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. Go to the TPE Configuration Cockpit module, in the Authentication federation section. Set "Authentication federation" to "Enabled". Don't save the configuration for the moment.

2. Create a client in the federated identity provider for the ThingPark Enterprise using instructions displayed in the Authentication federation section.

   Eventually, use the client definition in the OpenID Connect Client Metadata Description.

   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.

3. Fill in the client ID, client secret and OpenID Connect issuer fields with the info retrieved in step 2.

4. Save the configuration

Disabling authentication federation

Note

After disabling the 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 the federation was enabled, the user must use the lost password flow to set its password.

1. Go to the TPE Configuration Cockpit module, in the Authentication federation section. Set "Authentication federation" to "Disabled"
2. Save the configuration

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 log in.

https://<hostname>/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://<hostname>/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://<tpe-hostname>/auth/federation-callback (copy/paste from the TPE Configuration Cockpit module)
   • Copy the client ID. It will be required to paste it on the TPE Configuration Cockpit module in the Configure Web API step

   

4. Configure Application Credentials step:

   Check "Generate a shared secret" and copy it. It will be required to paste it on the TPE Configuration Cockpit module (client secret)

   

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, and 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 issuer ID to set in the TPE Configuration Cockpit module should be https://<your-adfs-hostname>/adfs/.