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 SSO set-up for more information.

Provider fields

Every SSO provider uses the following provider-level fields.

Field	Mandatory	Description
authentication.clientId	✅	The identifier of Harmoney at the identity provider. For OAuth2 OpenID this is the OAuth client ID. For SAML this is the issuer, also referred to as the Entity ID, and it must match the configuration at the identity provider.
authentication.clientSecret	❌	For OAuth2 OpenID this is the OAuth client secret used to exchange the authorization code for a token. For SAML it is not a shared secret: it holds the Base64 private key used to decrypt encrypted assertions, and can be left empty when the identity provider sends unencrypted assertions.
authentication.tokenUri	❌	The token endpoint of the identity provider. Only used by OAuth2 OpenID, where it is required.
authorizeUri	✅	The URL of the identity provider where Harmoney sends the user to log in. For OAuth2 OpenID the placeholders <client-id> and <redirect-uri> are replaced with the client ID and the redirect URI; Harmoney adds the state and PKCE parameters. For SAML Harmoney adds the SAMLRequest and RelayState parameters.
redirectPath	✅	The URL the identity provider sends the user back to after logging in, which must be registered at the identity provider. For OAuth2 OpenID a value starting with / is prefixed with the URL of the white label. For SAML this is the Assertion Consumer Service URL.

tip

These values need to be stored the vault (for example $vault{SSO_authorizeUri}) instead of writing them in the provider settings, to ensure this information cannot be easily exported.

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 optional reference to the FSP that the role should belong (fspExtRef), in whichever field SSO_FSP_REFERENCE_SOURCE names.
  • fspExtRef should be omitted for global roles such as HARMONEY_ADMINISTRATOR, which are not scoped to a specific FSP.

:::warning Mapping HARMONEY_ADMINISTRATOR delegates admin rights to the identity provider Mapping an external role to HARMONEY_ADMINISTRATOR grants full Harmoney administrator rights to every user the identity provider places in that external role. From that point, control over who becomes a Harmoney administrator effectively moves to whoever manages membership of that group in the IdP. Only map it to a tightly controlled external role. :::

Example

A client provides the list ['custom_company_role_name', 'another_company_role_name', 'admin_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"
      }
    ],
    "admin_role_name": [
      {
        "role": "HARMONEY_ADMINISTRATOR"
      }
    ]
  }
}

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

SSO_FSP_REFERENCE_SOURCE

Which field of the FSP a reference names — both the fspExtRef entries of SSO_ROLE_MAPPING and whatever reference the provider reads out of the token (the Keycloak organization alias, for instance).

Value	Matches against	Use when the FSP naming is
FSP_EXTERNAL_REFERENCE (default)	externalReference	externally managed — the other system decides what the FSP is called and may change it
FSP_IDENTIFIER	identifier	self-managed — ours to define and keep stable

Either way the lookup is scoped to the white label the login was made on. It does not cover the agency references a SAML response can carry: those name the reference on the link between two FSPs, not a field of the FSP itself.