Adding Your Instance 'Integration'

A Platform 6 instance will, in most use cases, require access to the P6 Authentication and Authorization services (known as P6Auth) for User and Organisation data.

This is essential if using the Platform 6 workflow service; workflow steps are defined in terms of both user operations and their positions held within an organisational tree.

P6Auth is a secure services server and requires both authentication and authorization before an instance can access its data.

All P6Auth services require an access token that is issued to an instance when it authenticates itself. Technically this is achieved using OAuth2 and a grant_type of client_credentials.

To make authentication setup both straight forward and secure we have provided a configuration panel accessible via the Platform 6 Portal.

The panel is labeled Integrations and is accessed via the Administration menu option.

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/refresh_token pair This means these attributes are typically stored in an external systems 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.

Other attributes of an Integration are:

  • Name
  • Refresh token(s) valid until revoked
  • Enabled
  • Permission set list
Refresh token(s) valid until revoked

All access_token(s) expire and an external system must use a refresh_token to regenerate a valid access_token. A refresh_token will normally expire after 28 days. This attribute will stop the refresh_token expiring.

Permission set list

A list of permissions associated with the issued access_token/refresh 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 for a Platform 6 Instance

Each Platform 6 instance should be configured as an Integration. 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).

Example Platform 6 Integration

Note

Only two permissions are currently required by a Platform 6 instance orgs=read and 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

b2auth {
    client {
      id: "73705350-8de1-11e9-b4f3-5303f388dd00"
      secret: "74686ef0-8de1-11e9-b4f3-5303f388dd00"
      redirect.uri: "https://www.platform6.io"
    }
}

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