Skip to main content
Version: 19

OAuth2 OpenID SSO provider

⚙️ Configuration​

Additional to the base [SSO Provider configuration](sso-providers.md#⚙️ Configuration), extra settings are available:

KeyMandatory
SSO_RESULT_MAPPING✅Defines how the SSO result should be mapped to user information.
SSO_USER_INFO_CLAIMS_SOURCE✅Defines where the find the claims for the user info.
SSO_USER_INFO_URI❌The URI to perform an additional request on to fetch user info.
PKCE_MAPPING❌Configuration to enable PKCE.

SSO_USER_INFO_CLAIMS_SOURCE && SSO_USER_INFO_URI​

The property SSO_USER_INFO_CLAIMS_SOURCE defines where the SSO provider should look for the user information claims. The user information claims could be included

  • in the id_token of the received SSO token
  • in the access_token of the received SSO token
  • in the result of an additional request to the UserInfo endpoint (in this case the SSO_USER_INFO_URI becomes required)

Example:

Perform an additional request to the UserInfo endpoint
{
  "SSO_USER_INFO_CLAIMS_SOURCE": "USER_INFO_REQUEST",
  "SSO_USER_INFO_URI": "https://example.com/userinfo"
}

SSO_RESULT_MAPPING​

We need to know how the external data (in the form of an OpenID UserInfo or an OpenID IDToken) should be mapped on our own SSO result. Use setting SSO_RESULT_MAPPING to configure this.

Fields​

  • fieldsMapping: Defines what claim should be used to map a SSO result field.
    • The SSO result fields to map are:
      • uid
      • firstName (TriState)
      • lastName (TriState)
      • mobilePhone (TriState)
      • email (TriState)
      • languageIsoCode (TriState)
      • gender (TriState)
      • roles (In combination with SSO_ROLE_MAPPING setting)
    • For each TriState field mapping you can specify the tristate behavior with the setUndefinedIfNull flag. (default false)
      • true: Don’t update field if value is not provided in claims
      • false: Remove current value if claim is null
    • Note: There is one special field prefix that is used by certain customers to get a custom value into the mobile phone field to allow automatic registration. This should be avoided as it might break in future updates.
  • usePrefillFields: When the SSO provider is used to start the flow, we have some prefilled user data in our own token that can be used in the SSO result. This behavior can be configured with this flag.
    Note: will throw exception if configured true but no registration prefill is available in the token warning
    • The fields that can be prefilled are firstName, lastName, gender and languageIsoCode
  • fallbackRoles: A list of String values that correspond to the keys configured in the SSO_ROLE_MAPPING. If a field mapping for the “roles” is configured BUT the claims don’t contain a value for this mapping, then we fall back on this value list to map the user roles.
  • initialRole: A single Role value. If configured, this defines the role that will be active when the user starts their session.

Note on automatic registration: In order to register with SSO without being redirected to the registration form, the firstName, lastName and mobilePhone fields MUST have a value. So take this into account when configuring the fields mapping if you want automatic registration!

Example:

{
  "SSO_RESULT_MAPPING": {
    "fieldsMapping": {
      "email": {
        "fieldName": "email",
        "setUndefinedIfNull": true
      },
      "firstName": {
        "fieldName": "given_name"
      },
      "gender": {
        "fieldName": "gender"
      },
      "languageIsoCode": {
        "fieldName": "language"
      },
      "lastName": {
        "fieldName": "family_name"
      },
      "mobilePhone": {
        "fieldName": "telephone"
      },
      "roles": {
        "fieldName": "groups"
      },
      "uid": {
        "fieldName": "sub"
      }
    },
    "fallbackRoles": [
      "agent"
    ]
  }
}

PKCE_MAPPING​

Configure the SSO provider to follow the Proof of Key Exchange (PKCE, pronounced pixy) flow. Only if the PKCE mapping is configured, will the PKCE flow be executed during OAuth authorization.

Some OAuth authorization servers require PKCE to be configured and will throw an error if PKCE is not provided by the client.

The PKCE mapping setting contains a PKCESettings object containing a required field codeChallengeTransformationType.

The code challenge transformation type is an enum with values:

  • PLAIN: Used for compatibility with existing deployments and for constrained environments that can't use the S256 transformation.
  • S256: SHA-256

Example:

{
  "PKCE_MAPPING": {
    "codeChallengeTransformationType": "S256"
  }
}

Note: starting from version OAuth 2.1 the PKCE will be required for all OAuth clients using the authorization code flow! More information: RFC7636

Test the provider​

The setting MOCKED_RESPONSE can be configured in order to define a specific claims map that will be used in the SSO provider.

Example of claims sent by a customer:

{
  "aud": "microsoft:identityserver:008e1c40-88fa-4f53-961b-0f7a44a7c70d",
  "iss": "http://logon.xyz.com/adfs/services/trust",
  "iat": 1629367344,
  "exp": 1629370944,
  "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups": [
    "MyHarmoney - Partner",
    "MyHarmoney-Broker"
  ],
  "language": "FR",
  "unique_name": "[email protected]",
  "given_name": "Sirius",
  "family_name": "Socks",
  "email": "[email protected]",
  "apptype": "Public",
  "appid": "008e9c40-88fa-4f52-961b-0f7a44a7a70d",
  "authmethod": "urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified",
  "auth_time": "2021-08-19T10:02:23.698Z",
  "ver": "1.0",
  "scp": "openid"
}

🔗 References​

Useful info: