New features specific to self-hosted ThingPark Enterprise

Delegation of end-user authentication to third-party Identity Providers RDTP-17071

Starting self-hosted TPE 7.1.1, the TPE administrator may configure the platform to delegate the end-user's authentication to an external Identity Provider (IDP) that supports the OpenID Connect authorization code flow.

With this delegation, the end-user authentication rules (password storage and enforcement rules, use of multifactor authentication, user logout...) are directly managed by the third-party IDP, not by ThingPark.

More details

User management in TPE

When authentication federation is enabled, users must still be created in the TPE GUI to have access to TPE services. In this case, the user creation form is limited to an email and roles.

The email provided when the user is created must match the user email provided by the customer's IDP in the ID Token when the user accesses TPE for the first time. This matching constraint is not required for the following login attempts of the same user, as the subject identifier claim (sub) of the Id Token is used to find the corresponding TPE user.

Notes

The content of the activation email is also adapted when federated authentication is activated.
When delegated authentication is activated, TPE do not manage user passwords anymore, hence there is no way to change/reset the user password from TPE GUI.
a user authenticated on customer's IDP but not declared in TPE cannot access TPE services.

Service accounts

To allow using the DX-API when delegated authentication is enabled, a service account must be created by the TPE administrator. To learn more, see Simplified integration with DX-API through Service Accounts RDTP-17071.

note

Using services accounts when delegated authentication is not enabled is allowed.

Key customer benefits

This feature allows easier integration of ThingPark Enterprise with the enterprise's IT services to offer a federated authentication with Single Sign On (SSO) user experience across all the enterprise services managed by their Identity Provider, including TPE services.

Additionally, with the delegated authentication, the platform administrator may freely define the end-user authentication policy without any dependency on TPE.

Feature activation

Integrating with third-party IDP

The Identity Provider (IDP) where authentication is delegated must fulfill the following requirements:

The IDP must implement OpenID Connect Core 1.0, and more specifically the Authorization Code Flow.
The IDP must serve its configuration on the well-known URL ${issuer}/.well-known/openid-configuration as described in OpenID Connect Discovery 1.0.
The IDP must implement a logout endpoint and provide its URL in the configuration as described in OpenID Connect RP-Initiated Logout 1.0.
The following signing algorithms are supported to sign the ID Token:
- RS256
- RS384
- RS512
- ES256
- ES384
- ES512
- PS256
- PS384
- PS512
The self-hosted TPE platform must be declared in the IDP as a client with the following properties:
- Confidential client: client id and secret will be provided in the HTTP Authorization header when invoking the token endpoint as described in the OAuth2 RFC 6749 section 2.3.1.
- Redirect-uri: https://{tpe-ocp-hostname}/auth/federation-callback
- The openid, email and profile scopes are allowed.
- Authorization code flow is allowed (Response types: code, Grant types: authorization_code, refresh_token).

To help creating the TPE client in the IDP, the client definition in the OpenID Connect Client Metadata Description format can be downloaded in Cockpit.

Once the TPE client is created in the IDP, authentication federation should be enabled on Cockpit.

Activating delegation in TPE

During initial installation of the self-hosted TPE platform, the administrator should login with the 'install@actility.com' account and do the first installation procedure. This procedure should be done before enabling authentication delegation.

Here is the overall procedure to enable delegated authentication just after TPE installation:

Login using the install@actility.com account.
In the first installation procedure, configure the first TPE user account with the email of an existing user in the external IDP.
Configure authentication federation in Cockpit.
Login to TPE with the same email account used in step #2.

On an existing self-hosted TPE platform: enable the authentication federation on Cockpit.

note

Once the feature is activated, end-users directly login in the IDP. To successfully associate the end-user identity on TPE and IDP sides, the user email must match on both sides during the first login after feature activation.

Deactivating delegation in TPE

Delegated authentication (also known as authentication federation) may be deactivated at any time by the TPE administrator, through TPE Cockpit GUI. In this case:

All the existing users may connect using their email and the password they had before activating the delegation feature.
If the user was created while the delegation feature was already enabled, or if the user cannot remember their old password, the user should use the password recovery option (Forgotten password) to reset their password.

Network flows

When delegated authentication is enabled, the following flow must be open:

From	To	Protocol	Port	Description
TPE	IDP	HTTPS	443	OpenId Connect authentication flow

note

When a proxy is configured, this flow goes through the proxy.

Feature limitations

This feature only works with Identity Providers supporting OpenID Connect protocol. SAML authorization code flow is not covered by this feature.
Remote support: no user is created when the remote support session is open. Hence, the rescue user feature on cockpit is not available when delegation is activated.
If the user logs out from the TPE GUI, the logout is immediately propagated to the IDP. But if the user logs out from another application delegating its authentication to the same IDP, a TPE GUI associated to the closed session (in another browser tab for example) may remain active up to 5 minutes, which is the lifetime of the refresh token.

Simplified integration with DX-API through Service Accounts RDTP-17071

Starting release 7.1.1, the self-hosted TPE administrator may create Service Accounts.

Service accounts are a special type of accounts associated with applications.

Services accounts authenticate on the DX-API with their credentials:

Client ID: unique identifier of the service account
Client Secret: strong password generated by ThingPark Enterprise

More details

Creating Service Accounts on self-hosted TPE GUI

Service accounts are managed in the Manage > Service Accounts menu in TPE GUI:

The administrator shall fill the creation form and set a client ID and role(s) to each Service Account.

note

The client secret is displayed only during the initial creation of the Service Account, the administrator must copy it at this step as it will not display again on the GUI for security reasons. In case the initial client secret is lost, the administrator may regenerate a new secret (also displayed only once by the GUI, during the regeneration step).

Using the Service Account to authenticate with DX-API

To use DX-API, an OAuth access token must be issued using the DX-Admin authentication endpoint. The client ID and client secret of the service account must be used. For example, if the service account client ID is "tpe-api/my-service-account" and the client secret is "my-secret", the following request should be made to DX Admin to obtain a token:

curl -X POST
-H 'Content-Type: application/x-www-form-urlencoded'
-H 'Accept: application/json'
-d 'grant_type=client_credentials&client_id=tpe-api%2Fmy-service-account&client_secret=my-secret' https://enterprise.thingpark.com/thingpark/dx/admin/latest/api/oauth/token