Authentication federation

About authentication federation

ThingPark Enterprise can be configured to delegate authentication using OpenID Connect.

The federated identity provider where authentication is delegated to has the following mandatory requirements:

• Implement "Mandatory to Implement Features for All OpenID Providers" in OpenID Connect Core 1.0

• Implement the following features of the "Mandatory to Implement Features for Dynamic OpenID Providers" section from OpenID Connect Core 1.0:

  • "code" response type (The IDP must implement the Authorization Code Flow)
  • Discovery (The IDP must serve its configuration on the well-known URL ${issuer}/.well-known/openid-configuration as described in OpenID Connect Discovery 1.0)
  • Public Keys Published as Bare Keys

• Always return an access token in the responses of the token endpoint

and the following optional but highly recommended requirements:

• The IDP should return a refresh token in the responses from the token endpoint. This refresh token must not be an offline token: it must be bound to the user session.
• The IDP should implement a logout endpoint and provide its URL in the configuration (end_session_endpoint) 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 following identity providers are known to be compatible:

• Microsoft Azure Active Directory
• Microsoft Active Directory Federation Services (Windows Server 2022)
• Google
• Auth0
• Keycloak

The following identity provider is known to be incompatible:

• Microsoft Azure Active Directory B2C. The following specific behaviors are incompatible with ThingPark Enterprise:

  • Getting an access token is dependent on the presence of a specific scope. See Request an access token in Azure Active Directory B2C
  • The id token does not contain an email claim. It seems that a non-standard 'emails' claim is used.

Enabling authentication federation

Note

After being installed, the TPE administrator should log in with the <install@actility.com> account and do the first installation procedure. This procedure should be done before enabling authentication federation.

Prerequisite: all ThingPark Enterprise users should have a corresponding user on the federated identity provider with a matching email.

1. Create a client in the federated identity provider for ThingPark Enterprise with the following properties:

   • Redirection URI: https://<.Values.global.dnsHostname>/auth/federation-callback
   • Post logout redirect URI: https://<.Values.global.dnsHostname>/federation-post-logout
   • Response types: code
   • Token endpoint auth method: client_secret_basic
   • Scopes: The openid, email and profile scopes must be allowed

   Get the following properties of the created client:

   • Client ID
   • Client secret
   • OpenID Connect issuer

   See Creating the ThingPark Enterprise client for a detailed procedure by identity provider.

2. Set the global.oauthFederation.clientId, global.oauthFederation.clientSecret and global.oauthFederation.issuer, configuration parameters.

3. Apply the configuration by following the Update a configuration parameter procedure.

Disabling authentication federation

Note

After disabling authentication federation, all existing users must connect using their email and the password they had before authentication federation activation. If the user was created when federation was enabled, the user must use the lost password flow to set its password.

1. Clear the global.oauthFederation.*, configuration parameters.
2. Apply the configuration by following the Update a configuration parameter procedure.

Creating the ThingPark Enterprise client

Microsoft Azure Active Directory

Note

Microsoft Azure Active Directory does not issue refresh tokens. Therefore, ThingPark Enterprise session is not bound to the user session on Azure AD.

In your tenant, the ThingPark Enterprise application must be registered.

The ThingPark Enterprise client should be declared in Azure AD / App registrations / New registration.

A client secret must be created in Azure AD / App registrations / ThingPark Enterprise / Certificates & secrets / Client secrets / New client secret. Copy the created secret as it will be needed to configure TPE.

The client secret has an expiration date. It must be renewed before this date is reached. If ThingPark Enterprise is configured with an expired client ID, nobody will be able to login.

https://<.Values.global.dnsHostname>/auth/federation-post-logout must be added as redirect URI in Azure AD / App registrations / ThingPark Enterprise / Authentication / Redirect URIs.

To get the info required to enable authentication federation (in addition to the client secret), go to Azure AD / App registrations / ThingPark Enterprise / Overview:

• The client ID is in the Essentials section: Application (client) ID
• The issuer id has the form https://login.microsoftonline.com/<uuid>/v2.0. To get it, display the "endpoints" panel, go to the OpenID Connect metadata document URL and get the issuer property in the JSON document.

Google

Note

Google does not issue refresh tokens other than offline tokens nor implements the end_session_endpoint. Therefore, Google delegation works in degraded mode.

ThingPark Enterprise can be declared as an internal application of a Google Workspace. See OpenID Connect in the Google documentation to declare TingPark Enterprise in your google cloud console and get the client id and secret. The issuer ID is https://accounts.google.com.

Auth0

Note

Auth0 does not issue refresh tokens other than offline tokens nor implements the end_session_endpoint. Therefore, Auth0 delegation works in degraded mode.

In your Auth0 management dashboard, create a regular web application.

On the settings tab, set:

• Token Endpoint Authentication Method: Basic
• Allowed Callback URLs: https://<.Values.global.dnsHostname>/auth/federation-callback

To enable authentication federation, get the client ID and client secret on the settings tab of the application, in the basic information section. The issuer ID is visible in the "issuer" property of the OpenID Configuration JSON document. Go to Advanced settings / Endpoints of the application page to get the url of the OpenID Configuration JSON document. The issuer ID should be https://<tenant-hostname>/.

Microsoft Active Directory Federation Services

The following procedure applies to Windows Server 2022.

In the Active Directory Federation Service Manager:

1. Add an application group. The application group wizard opens.

2. Welcome step:

   Template: Server application accessing a web API

   

3. Server application step:

   • Redirect URI: https://<.Values.global.dnsHostname>/auth/federation-callback
   • Copy the client ID. It will be required to paste it in the global.oauthFederation.clientId parameter of TPE configuration.

   

4. Configure Application Credentials step:

   Check "Generate a shared secret" and copy it. It will be required to paste it in the global.oauthFederation.clientSecret parameter of TPE configuration.

   

5. Configure Web API step:

   Identifier: add the client id from the Server application step as an identifier

   

6. Configure Application Permissions step

   Permitted scoped: check allatclaims, email, openid and profile.

   

7. Create the application group

8. In the created application group, edit the Web API application, click Add rule in the Issuance Tranform Rules tab. The Add Transform Claim Rule Wizard opens.

   

9. Choose Rule Type step:

   Choose Send LDAP Attributes as Claims template.

   

10. Configure Claim Rule step:

    At least the email claim should be mapped.

    

11. Click Finish

Ensure the user that login has an email in its Active Directory profile.

The global.oauthFederation.issuer to configure in the TPE configuration should be https://<your-adfs-hostname>/adfs/.