Keycloak

Keycloak client

For a successful Keycloak integration, there needs to be an authClient created on the Keycloak server side.

Expected client specifications

• Client Protocol should be set to openid-connect
• Access type should be set to confidential
• Credentials should be the Client ID and Client Secret

Required OIDC scopes

The following scopes must be configured on the Keycloak server side. If you need different scopes, please get in touch with your SCAYLE account manager.

• openid
• profile
• email
• offline_access

Whitelisted URLs

Whitelisted URLs should be formatted as follows:

{{auth_service_hostname}}/v1/auth/external/callback

Keycloak instance base URL

This is the root URL used for the entire integration. For example: https://sso-general-auth.tenant.cloud/auth/realms/Tenant

Reference key mapping key

When fetching data from Keycloak using the protocol/openid-connect/userinfo endpoint, we need to load and store the external id (id of the given customer on Keycloak) on Auth service. As the user data response structure might vary across different implementations, we need to know what is the name of the attribute in the customer's object that holds the external id as dot notation. This attribute name will be stored later as reference_key_mapping_key.

Example of a call to Keycloak to get user data

Copy

curl 
--location 'https://sso-general-auth.tenant.cloud/auth/realms/Tenant/protocol/openid-connect/userinfo' \
--header 'Authorization: Bearer {{access_token}}'

Expected attributes

In the response, we look for the following attributes:

• preferred_username: user email used as an username
• name: customer's full name
• email: customer's email address
• sub: used as reference_key_mapping_key. It can be configured later by changing the dot notation.

Example response

Copy

{

    "sub": "317521a5-8d64-4efd-b1aa-546f45894b04",
    "email_verified": false,
    "name": "John Doe",
    "preferred_username": [email protected]",
    "given_name": "John",
    "family_name": "Doe",
    "email": "[email protected]"

}

reference_key_mapping_key = sub

Example response

Copy

{
    "email_verified": false,
    "name": "John Doe",
    "preferred_username": "[email protected]",
    "given_name": "John",
    "family_name": "Doe",
    "email": "[email protected]",
    “metaData”: {
        “details” {
            “customerId”: "317521a5-8d64-4efd-b1aa-546f45894b05"
}
    }
}

reference_key_mapping_key = metaData.deails.customerId

Keycloak endpoints

/protocol/openid-connect/token

This endpoint is used to exchange the token with the code obtained when the user logs in to /protocol/openid-connect/auth.

/protocol/openid-connect/auth

The customer will be redirected to this endpoint to complete the logging in process.

/protocol/openid-connect/userinfo

This endpoint is used to load user data.

protocol/openid-connect/token/introspect

This endpoint is used to validate the existing token.