System Authentication

Prior to integrating any external system to P6 via its API, an integration must be created to generate API credentials and assign permissions to that system. To make authentication setup both straightforward and secure, we have provided a configuration panel accessible via P6 Portal. The panel is labeled Integrations and is accessed via the User Administration menu entry.

A Platform 6 instance also requires access to the P6 Authentication and Authorization services (known as P6 Auth) for user and organisation data. This is essential if using the Platform 6 workflow service; workflow steps are defined in terms of both user permissions and their positions held within an organisational tree.

P6 Auth is a secure services server and requires both authentication and authorization before an instance or external system can access its data.

All P6 Auth services require an access token that is issued to an instance or external system when it authenticates itself. Technically this is achieved using OAuth 2.0 and a grant type of client_credentials.

Integrations

Integrations are configurations allowing authentication of external systems without user interaction (i.e. no username/password exchange via a login screen).

While a Platform 6 instance is the most common and obvious external system requiring authentication, integrations may also be required for other external systems that use Platform 6 services such as an IOT server pushing notifications.

In summary, an integration configuration is required for each and every external system that requires an access token and the external system connects in an automated and unattended manner.

The Integration credentials used by external systems are:

• Application ID
• App Secret
• Redirect URI

Warning

These three credential attributes are used by an external system to generate an access_token. This means these attributes are typically stored in an external system application configuration. It is therefore essential that the attribute values are protected and also that the permissions assigned to a system acquiring an access_token using this method are restricted.

Note

Unlike user authentication, refresh tokens are not required when using the OAuth 2 client_credentials grant type.

Other attributes of an Integration are:

• Name
• Enabled
• Permission set list

Permission set list

A list of permissions associated with the issued access_token. For security reasons, it is advised that the permissions granted are a minimal set only - i.e. fine grained permissions, sufficient only for a small number of operations performed by an external system.

Integration Configuration of an External System

To generate credentials and assign permissions to an external system, please create a new integration configuration as seen below:

You can name it however you like, but most importantly use the generate button on the UI to fill the client and secret ID.

Once done, you can get an access token with curl to test the connection as follows:

curl --insecure -v -d \
    "redirect_uri=$REDIRECT_URI&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&grant_type=client_credentials" \
    https://login.amalto.io/oauth2/token

You should get an HTTP 200 OK answer with a JSON object containing the access token.

Integration Configuration of a Platform 6 Instance

Each Platform 6 instance should be configured as an Integration.

This is automatically handled when you create your instance in your P6 Console account, then install it following the P6 Install Guide. So you don’t need to read the rest of this section.

Otherwise, it is strongly recommended that the attributes:

• Application ID
• App Secret

are complex, long and unique identifiers. (use the generate button on the UI to help with this).

Note

Only two permissions are currently required by a typical Platform 6 instance :orgs=read and [instance]:users=read(“./”)

Once the Integration is created, the Application ID, App Secret and Redirect URI values need to be added to the instance configuration file: application.conf

p6auth {
    client {
      id: "73705350-8de1-11e9-b4f3-5303f388dd00"
      secret: "74686ef0-8de1-11e9-b4f3-5303f388dd00"
    }
}

Once this file has been updated, the instance will need to be restarted.