Single Sign-On (SSO)

🎯 Functional documentation

SSO Providers can be used to automatically log in a user.

In Harmoney, there are 3 places to use SSO:

• By navigating to the login page
• By clicking an invitation link to provide details (information exchange)
• By authenticating on the API gateway using a bearer token (Not really SSO, but needed here because functionally it is similar)
  • Make sure the user has GATEWAY role assigned or add it to the SSO_ROLE_MAPPING configuration
  • To activate this, the authentication.gateway property must be set in the whitelabel settings

The result from the SSO provider is used to authenticate the user in the Harmoney application

• Look for an existing user based on the sso result uid and the sso provider id
• If no user is found, register a new user in Harmoney using the sso result
  • Automatic registration (skip Harmoney registration page) possible when SSO result contains: first name, last name, and mobile phone
  • Manual registration if automatic registration is not possible (not possible in the gateway -> endpoint will return an unauthorized error)
    • Redirects to the Harmoney registration page and prefill with available data from SSO result

⚙️ Configuration

Adding an SSO provider in the libraries does not have any functional effect without additional configuration. See whitelabel authentication settings for more information.

Key	Mandatory
SSO_ROLES	❌	Can be used to define which roles should be assigned to a user after registering or logging in using an SSO provider.
SSO_ROLE_MAPPING	❌	Can be used to define which roles should be assigned to a user after registering or logging in using an SSO provider.
jwtSettings	❌
jwksUri		The URI used to retrieve the JSON web key sets when processing the JWT.
jwksCacheDuration		The time period (in seconds) to cache the JWKs from the endpoint, if the cache directive headers of the response are not present or indicate that the content should not be cached. The default value is 3600 seconds (1 hour).
jwksRetainCacheOnErrorDuration		Sets the length of time in seconds, before trying again, to keep using the cache when an error occurs making the request to the JWKS URI or parsing the response. The default value is 0
jwsAlgorithm		Configure the JWS algorithm constraints to be applied when processing the JWT.
expectedJwtIssuer		Specify the expected issuer to be validated when processing the JWT.
expectedJwtAudience		Specify the expected audience to be validated when processing the JWT.
requireJwtSubject		Require that a subject ("sub") claim be present in the JWT.
skipJwtSignatureVerification		Set to true to skip signature verification when processing the JWT.
skipJwtDefaultAudienceVerification		Set to true to skip default audience verification when processing the JWT.

Mocking an SSO provider

Mocking an SSO provider does not work in non-local environments unless specific settings are configured.

• mockIPAllowList: A list of IP addresses that are allowed to use the mock SSO provider in non-local environments.
• mockAllowedUntil: A UTC timestamp (2014-02-19T15:42:00.000Z) indicating until when the mock SSO provider is allowed to be used in non-local environments.

Both of these settings prevent accidental usage of the mock SSO provider in production environments.

SSO_ROLE_MAPPING

Configure the roles that should be assigned to a user after registering or logging in using an SSO provider.

Setting fields

• The provider implementation (e.g. OAuth2 OpenID SSO provider) will provide a list roles linked to the user that is being logged in.
• The structure is a Map (dictionary) of String keys and a List of FspRole as value.
  • The keys correspond with the value mentioned above.
  • For each key we can define a list of FSP roles. An FSP role consists of a Harmoney role and an external reference to the FSP that the role should belong (fspExtRef)

Example

A client provides the list ['custom_company_role_name', 'another_company_role_name']`. This list would then be combined with the setting which might look like:

{
  "SSO_ROLE_MAPPING": {
    "custom_company_role_name": [
      {
        "role": "PARTNER_ADVISOR",
        "fspExtRef": "external_fsp_ref"
      }
    ],
    "another_company_role_name": [
      {
        "role": "PARTNER_MANAGER",
        "fspExtRef": "other_fsp_ref"
      }
    ]
  }
}

This means that PARTNER_ADVISOR on external_fsp_ref would be selected as default.