Intro

This page explains how to connect an instance of Keycloak IAM with the eduTEAMS Service using the OpenID Connect protocol. In this setup, Keycloak acts as a Relying Party (RP), while the eduTEAMS 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 eduTEAMS Service.

Supported Keycloak versions

The integration description covers all versions of Keycloak starting from 13.0.0 up to the current version 24.0.2. 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 eduTEAMS Service. You can find more information about this process at Registering services on the eduTEAMS Service.

Filling in the service registration form does not automatically register the service on the eduTEAMS Service. The application will be processed and approved and a confirmation will be sent from the eduTEAMS Service support team that the service with its configuration is in place and connected. 
Any attempt to authenticate a user against the eduTEAMS Service in your Keycloak before the configuration on the eduTEAMS 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 eduTEAMS Service
    2. <realm> - the name of the realm at the Keycloak that you want to integrate with the eduTEAMS Service
    3. <alias> - the external IdP alias for the eduTEAMS integration in the Keycloak (see the configuration on the Keycloak side), e.g. eduteams







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 eduTEAMS Service

  1. Scroll down to the bottom of the page.
  2. Type the Discovery Endpoint of the OIDC Provider interface of the eduTEAMS Service, at the Import from URL text field.
    1. The URL of the Discovery Endpoint of the OIDC Provider interface of the eduTEAMS Service is:
      https://proxy.eduteams.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. "eduteams". Note that the alias is a part of the Redirect URL that you have defined when registering the RP with the eduTEAMS 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 eduTEAMS Service.
  7. Set value of the Client Secret text field to value provided during the registration of the PR at the eduTEAMS 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 eduTEAMS 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 eduperson_principal_name". 







Configure attribute mappers (optional)

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

Example mapper configuration for the eduperson_principal_name 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 eduperson_principal_name.
  5. Set value of the Claim text field to eduperson_principal_name.
  6. Set value of the User Attribute Name text field to eduperson_principal_name.
  7. Click the Save button.






The eduperson_principal_name claim from eduTEAMS Service will be mapped to the eduperson_principal_name attribute in the user's profile in Keycloak upon a user logs in using the eduTEAMS 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 eduTEAMS Service

  1. Set value of the Alias text field e.g. "eduteams". Note that the alias is a part of the Redirect URL that you have defined when registering the RP with the eduTEAMS Service.  
  2. Type the Discovery Endpoint of the OIDC Provider interface of the eduTEAMS Service, at the Discovery endpoint text field.
    1. The URL of the Discovery Endpoint of the OIDC Provider interface of the eduTEAMS Service is:
      https://proxy.eduteams.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 eduTEAMS Service.
  5. Set value of the Client Secret text field to value provided during the registration of the PR at the eduTEAMS 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 eduTEAMS Service side. Please wait for confirmation from the eduTEAMS Support Team that the configuration is in place. 
Any attempt to authenticate a user against the eduTEAMS Service in your Keycloak before the configuration on the eduTEAMS Service is in place will result in an error. Please do not create a ticket for the eduTEAMS 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 eduTEAMS 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 eduperson_principal_name".







Configure attribute mappers (optional)

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

Example mapper configuration for the eduperson_principal_name 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 eduperson_principal_name.
  5. Set value of the Claim text field to eduperson_principal_name.
  6. Set value of the User Attribute Name text field to eduperson_principal_name.
  7. Click the Save button.






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