Versions Compared

Old Version 1

changes.mady.by.user Christos Kanellopoulos

Saved on

compared with

New Version Current

changes.mady.by.user Tomasz Kuczyński

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


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 24(26.0.20 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.

Note

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:

Section


Column
width30%
  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



Column
width10%



Column
width60%



Note

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
Anchor
old_admin_console
old_admin_console

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

Section

Create a new OpenID Connect Identity Provider

Column
width30%
  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.  


Column
width10%



Column
width60%

Image Modified




Section

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

Column
width30%
  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.


Column
width10%




Column
width60%
Image Removed

Image Added



Info

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.


Section

Further configure the identity provider


Column
width30%
  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.


Column
width10%



Column
width60%
Image Removed

Image Added




Info

The basic configuration is now ready.




Section

Configure attributes, claims and scopes (optional)

Column
width30%
  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 edupersonvoperson_principalexternal_nameaffiliation". 


Column
width10%



Column
width60%

Image RemovedImage Added




Section

Configure attribute mappers (optional)

Column
width30%

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 edupersonvoperson_principalexternal_name claimaffiliation 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 edupersonvoperson_principalexternal_nameaffiliation.
  5. Set value of the Claim text field to edupersonvoperson_principalexternal_nameaffiliation.
  6. Set value of the User Attribute Name text text field to edupersonvoperson_principalexternal_nameaffiliation.
  7. Click the Save button.


Column
width10%



Column
width60%

Image RemovedImage AddedImage Removed

Image Added



Info

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


The new Keycloak admin console
Anchor
new_admin_console
new_admin_console

Section

Create a new OpenID Connect Identity Provider

Column
width30%
  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.  


Column
width10%



Column
width60%

Image Modified




Section

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

Column
width30%
  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.


Column
width10%



Column
width60%

Image RemovedImage Added




Section

Further configure the identity provider

Column
width30%
  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 theScopes text field to email profile (see the Mappers configuration section for more options).
  8. Click the Save button.


Column
width10%



Column
width60%

Image RemovedImage AddedImage Removed

Image Added



Info

The basic configuration is now ready.


Note

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.



Section

Configure attributes, claims and scopes (optional)

Column
width30%
  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 theScopes text field of the identity provider configuration of your Keycloak. Please note  that all values need to be space separated, e.g. "email profile edupersonvoperson_principalexternal_nameaffiliation".


Column
width10%



Column
width60%




Section

Configure attribute mappers (optional)

Column
width30%

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 edupersonvoperson_principalexternal_name claimaffiliation 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 edupersonvoperson_principalexternal_nameaffiliation.
  5. Set value of the Claim text field to edupersonvoperson_principalexternal_nameaffiliation.
  6. Set value of the User Attribute Name text text field to edupersonvoperson_principalexternal_nameaffiliation.
  7. Click the Save button.


Column
width10%



Column
width60%

Image RemovedImage Added



Info

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