Set up External Authentication Method (Digital Access part)

This article is new for Digital Access 6.9.0.

This article describes how to set up an External Authentication Method (EAM).

Prerequisites

Signing Certificate

• Install an OIDC Signing cert. Signing certificate is used for communication between the OpenID provider and the relying party. See section "Add server certificate" in Add certificates for more information.

CA certificate

• CA certificates are used to make Digital Access trust external parties. This is required when setting the Discovery Endpoint later. See section "Add certificate authority" in Add certificates in Digital Access for more information.

Authentication method

• At least one authentication method must have been configured. See Set up authentication method in Digital Access for more information. In addition, OpenId Authentication Method Reference (amr) extended property need to be specified. This should be specified according to Entra’s requirements, See amr claims in https://learn.microsoft.com/en-us/entra/identity/authentication/concept-authentication-external-method-provider#microsoft-entra-id-interaction-with-provider.

Step-by-step instructions

Log in to Digital Access Admin

1. Log in to Digital Access Admin with an administrator account.

Enable OpenID Connect

1. In Digital Access Admin, go to Manage System.

2. Click OpenID Connect (OAuth2) Configuration > Manage Global OpenID Connect (OAuth2) Configuration Settings.

3. Check Enable OAuth2 and check Enable OpenID Connect Provider.

4. Select OIDC Signing Certificate. 

5. Select the Digest Method.

6. Click Save.

Configure scopes (optional)

Scopes are the permissions a client is allowed to ask for. The scope name is mapped to a description that will be shown to the user on the consent page.

To configure scopes in the Digital Access component:

1. In Digital Access Admin, go to Manage System.

2. Click OpenID Connect (OAuth2) Configuration.

3. Click Add scope.

4. Enter the name of the scope in Name.

When the end-user is asked for consent to share the piece of information related to the scope, the end-user will see an explaining text. To add this text:

1. Enter a name of the description in Key. 

2. Enter a describing text for that scope in Value.

The description of a scope defines what will be shown to the resource owner when asked to grant a client permission to use this scope. If no branding has been applied, the default description to be shown will be the first one added. Click Add description and further click Save.

Configure attribute groups

Scopes are not directly related to a piece of information from the user. They are only describing one or more pieces of information requested by the relying party. To connect the scopes with user information (claims), you configure Attribute Groups. 

1. In Digital Access Admin, go to Manage System.

2. Click OpenID Connect (OAuth2) Configuration > Manage Global OpenID Connect (OAuth2) Configuration Settings.

3. Click Add Attribute Group.

4. Define a Group Name.

5. Register one or several attributes that should be part of the attribute group. 

   1. Enter a Friendly Name. The friendly name is used as a name of the claim. 

   2. Define the Source the user information is taken from. 
      When using the option "User Storage, Custom", the User Storage is first searched. If no value is found, the Digital Access component's Account's "Custom Attributes" are searched. See 'help' for further explanation.

   3. Specify the Value. 
      If this field is left empty, then the Friendly Name is used when reading value from the Source. If Source is set to "Static Value" then the content of this field is used as the value.

   4. Click Add Attribute.

6. After all attributes have been added, click Save.

Add a client

1. In Digital Access Admin, go to Manage System.

2. Click OpenID Connect (OAuth2) Configuration.

3. Click Add client.

4. Provide a readable name as Display Name.

5. Issue Refresh Tokens (optional)

6. Require Consent (optional)

7. Enable Openid connect

8. If consent is required, the template to the consent page has to be provided. The default value is /wa/oauth2/consent.html.
   You can create your own template per client and refer to it. Together with the key/value pair of the scope, each client may have its own (multi-language) scope description.

9. Construct the OpenId Issuer as: https://<dns>/https/api/rest/v3.0/oauth/<clientid>(use clientId generated in the next step)

9. Provide the Client ID or click on Generate, it is suggested to use Client ID in DA set to same as APP ID in Entra or generate one to avoid identity conflicts.

10. Select Client Authentication, that Entra will use to authenticate for OpenID Connect requests towards Digital Access. 

11. Select the Source of subject as well as the Encoding method. 

12. Redirect URI will be provided by Entra, it is callback URL that the Digital Access component will send the response to. During the authentication request, the client will send the redirect URI as a parameter. This value must match one of the configured URIs, otherwise the authentication request will fail, see redirect URI in https://learn.microsoft.com/en-us/entra/identity/authentication/concept-authentication-external-method-provider#microsoft-entra-id-interaction-with-provider

13. On the Privileges tab, you can configure the supported Grant Types(by default Entra use implicit). Select scopes(if required).

14. On the Access Rules tab, select the access rules that should be applied for the client when using the /authorize endpoint. Reusable access rule is recommended. For more information about access rules, see Access rules in Digital Access.

15. Configure Scopes. For each Selected Scope, on the Scope Mapping tab, you will find a drop-down menu to select the corresponding Attribute Group.
    The user information configured in the selected Attribute Group will be returned as claims if the relying party requests access to the corresponding scope. An Attribute Group can have one or several claims configured.

16. Enable Return acr from request

17. Enable Return sub from id_token_hint

18. Put the Discovery Endpoint of the external issuer of id_token_hint. Example value: https://login.microsoftonline.com/5dd150a6-02c5-4bbd-8414-10d790efcd37/v2.0/.well-known/openid-configuration.

19. User Mapping Claim is value of a claim received in id_token_hint and will be resolved for a given authenticated user. The selected value must also exists as an attribute in the selected User Mapping Group Example value oid.

20. User Mapping Group defines the Attribute Group to use when performing user mapping. The selected User Mapping Claim is looked up in the selected group, matching Friendly Name. This enables flexible source lookup and transformations. Select a group that defines the appropriate source, e.g. “User Storage”. When adding an attribute to a new global OpenID Connect Attribute to be used in this context, it is recommended to uncheck Include in Token, to make it clear it's not used in token. This setting is required when Return sub from id_token_hint is enabled.

21. Save and Publish.

For configuration at Entra, see https://learn.microsoft.com/en-us/entra/identity/authentication/how-to-authentication-external-method-manage

Add DA authorize endpoint: https://<da>/https/api/rest/v3.0/oauth/authorize to the Entra application for selected APP ID.

Related information

• Access rules in Digital Access

• Add certificates in Digital Access

• Global resource settings in Digital Access

• Set up authentication method in Digital Access