Intro

This page explains how to connect an instance of Keycloak IAM with the MyAccessID Service using the OpenID Connect protocol. In this setup, Keycloak acts as a Relying Party (RP), while the MyAccessID Service is acting as the identity issuer or OIDC Provider (OP). In the following guide, "RP" is referring to Keycloak, and "OP" is referring to the MyAccessID Service.

Supported Keycloak versions

The integration description covers all versions of Keycloak starting from 13.0.0 up to the current version (26.0.0 at the time of updating this document). Integration of versions prior to 13.0.0 is possible but requires extra configuration and tweaks (e.g. removal of PKCE requirements, since it was not supported by Keycloak before version 13.0.0). Additionally, since version 21.0.0 the old admin console has been replaced with the new one. The new admin console is not available in versions prior to 15.1.0. Therefore, this page provides guidance for both:

Prerequisites

Before proceeding, the Keycloak RP instance needs to be registered with the MyAccessID Service. You can find more information about this process at Registering Relying Parties on the MyAccessID Service.

Filling in the service registration form does not automatically register the service on the MyAccessID Service. The application will be processed and approved and a confirmation will be sent from the MyAccessID Service support team that the service with its configuration is in place and connected. 
Any attempt to authenticate a user against the MyAccessID Service in your Keycloak before the configuration on the MyAccessID Service is in place will result in an error.

While registering the RP, make sure to choose the following options:

  1. In the SAML2 or OIDC field choose the OIDC option.
  2. In the Supported grants field choose only the Authorization Code Flow option.
  3. Leave the Client is public option unchecked.
  4. Check the Require PKCE (Proof Key for Code Exchange) option.
  5. Add the appropriate Redirect URLs. 
    Substitute tokens in the pattern for the Redirect URL which is https://<FQDN and port>/auth/realms/<realm>/broker/<alias>/endpoint with values specific to your Keycloak instance:
    1. <FQDN and port> - FQDN and port of the Keycloak instance you want to integrate with the MyAccessID Service
    2. <realm> - the name of the realm at the Keycloak that you want to integrate with the MyAccessID Service
    3. <alias> - the external IdP alias for the MyAccessID integration in the Keycloak (see the configuration on the Keycloak side), e.g. MyAccessID


Safely store the Client ID and Secret from the service-registration confirmation page. These credentials cannot be recovered. They will be used at a later stage.

The old Keycloak admin console

Login to the Keycloak admin console and then follow the steps below. 

Create a new OpenID Connect Identity Provider

  1. Choose the Identity Providers option from the left-side menu.
  2. Choose the OpenID Connect v1.0 option from the drop-down menu in the middle of the screen.  


Provide the discovery endpoint of the OIDC Provider interface of the MyAccessID Service

  1. Scroll down to the bottom of the page.
  2. Type the Discovery Endpoint of the OIDC Provider interface of the MyAccessID Service, at the Import from URL text field.
    1. The URL of the Discovery Endpoint of the OIDC Provider interface of the MyAccessID Service is:
      https://proxy.myaccessid.org/.well-known/openid-configuration
  3. Click the Import button.


After performing the above steps, the Identity Provider configuration fields (Authorization URL, Token URL, User Info URL, Issuer, etc.) must be pre-filled based on the information available through the discovery endpoint.

It is important to verify that this is the case. In case the configuration has not been pre-filled, please re-check that the URL you have provided to the Import from URL field is correct and reachable from the backend of your Keycloak instance.

Further configure the identity provider

  1. Scroll up to the top of the page.
  2. Set value of the Alias text field e.g. "MyAccessID". Note that the alias is a part of the Redirect URL that you have defined when registering the RP with the MyAccessID Service. 
  3. Switch the Trust Email option to On.
  4. You may consider changing the value of the Sync Mode option to the force value.
  5. Select the Client secret sent as basic auth option in the Client Authentication drop-down.
  6. Set value of the Client ID text field to the value provided during the registration of the RP at the MyAccessID Service.
  7. Set value of the Client Secret text field to value provided during the registration of the PR at the MyAccessID Service.
  8. Set value of the Default Scopes text field to email profile (see the Mappers configuration section for more options).
  9. Switch the Use PKCE option to On.
  10. Select the S256 option in the PKCE Method drop-down.
  11. Click the Save button.


The basic configuration is now ready.

Configure attributes, claims and scopes (optional)

  1. Please read Attributes available to Relying Parties for the claims and scopes that the MyAccessID Service supports and releases, and which you may need to configure and import to your Keycloak instance.
  2. Add all values of the OIDC scope from the Attributes available to Relying Parties page for the chosen attributes to the Default Scopes text field of the identity provider configuration of your Keycloak. Please note that all values need to be space separated, e.g. "email profile voperson_external_affiliation". 


Configure attribute mappers (optional)

Configure mapper/mappers for the every attribute identified in the previous stage. Attributes will be released by the MyAccessID Service as OIDC claims.

Example mapper configuration for the voperson_external_affiliation claim: 

  1. Open the Mapper tab of the identity provider configuration of your Keycloak.
  2. Click the Create button.
  3. Select Attribute Importer option in the Mapper Type drop-down.
  4. Set value of the Name text field to voperson_external_affiliation.
  5. Set value of the Claim text field to voperson_external_affiliation.
  6. Set value of the User Attribute Name text field to voperson_external_affiliation.
  7. Click the Save button.


The voperson_external_affiliation claim from MyAccessID Service will be mapped to the voperson_external_affiliation attribute in the user's profile in Keycloak upon a user logs in using the MyAccessID Service.

The new Keycloak admin console

Create a new OpenID Connect Identity Provider

  1. Choose the Identity Providers option from the left-side menu.
  2. Choose the OpenID Connect v1.0 option from options in the middle of the screen.  



Set basic properties and provide the discovery endpoint of the OIDC Provider interface of the MyAccessID Service

  1. Set value of the Alias text field e.g. "MyAccessID". Note that the alias is a part of the Redirect URL that you have defined when registering the RP with the MyAccessID Service.  
  2. Type the Discovery Endpoint of the OIDC Provider interface of the MyAccessID Service, at the Discovery endpoint text field.
    1. The URL of the Discovery Endpoint of the OIDC Provider interface of the MyAccessID Service is:
      https://proxy.myaccessid.org/.well-known/openid-configuration
  3. Select the Client secret sent as basic auth option in the Client Authentication drop-down.
  4. Set value of the Client ID text field to the value provided during the registration of the RP at the MyAccessID Service.
  5. Set value of the Client Secret text field to value provided during the registration of the PR at the MyAccessID Service.
  6. Click the Add button.




Further configure the identity provider

  1. Scroll down to the OpenID Connect settings section.
  2. Switch the Use PKCE option to On.
  3. Select the S256 option in the PKCE Method drop-down.
  4. Switch the Trust Email option to On.
  5. You may consider changing the value of the Sync mode option to the Force value.
  6. Click on > Advanced link.
  7. Set value of the Scopes text field to email profile (see the Mappers configuration section for more options).
  8. Click the Save button.


The basic configuration is now ready.

Please take into account that filling in the RP registration form does not automatically configure the RP on the MyAccessID Service side. Please wait for confirmation from the MyAccessID Support Team that the configuration is in place. 
Any attempt to authenticate a user against the MyAccessID Service in your Keycloak before the configuration on the MyAccessID Service is in place will result in an error. Please do not create a ticket for the MyAccessID Support Team in such a situation.


Configure attributes, claims and scopes (optional)

  1. Please read Attributes available to Relying Parties for the claims and scopes that the MyAccessID Service supports and releases, and which you may need to configure and import to your Keycloak instance.
  2. Add all values of the OIDC scope from the Attributes available to Relying Parties page for the choosen attributes to the Scopes text field of the identity provider configuration of your Keycloak. Please note  that all values need to be space separated, e.g. "email profile voperson_external_affiliation".




Configure attribute mappers (optional)

Configure mapper/mappers for the every attribute identified in the previous stage. Attributes will be released by the MyAccessID Service as OIDC claims.

Example mapper configuration for the voperson_external_affiliation claim: 

  1. Open the Mapper tab of the identity provider configuration of your Keycloak.
  2. Click the Add mapper button.
  3. Select Attribute Importer option in the Mapper type drop-down.
  4. Set value of the Name text field to voperson_external_affiliation.
  5. Set value of the Claim text field to voperson_external_affiliation.
  6. Set value of the User Attribute Name text field to voperson_external_affiliation.
  7. Click the Save button.


The voperson_external_affiliation claim from MyAccessID Service will be mapped to the voperson_external_affiliation attribute in the user's profile in Keycloak upon a user logs in using the MyAccessID Service.

  • No labels