Single Sign-On (SSO) setup

What does an SSO setup do?

An SSO setup lets users log in to Harmoney with the account they already have at their own identity provider (IdP), instead of a Harmoney username and password. Harmoney acts as the client (OAuth2/OpenID) or service provider (SAML) and the customer's IdP authenticates the user.

Which users are logged in, and with which roles, is decided by the mapping of the SSO result. See the SSO providers page for the functional behaviour, including automatic registration and the roles mapping.

There are two variants, depending on the protocol supported by the customer's IdP:

• SAML setup
• OAuth2 OpenID setup

Preconditions

• The customer has an identity provider that supports SAML 2.0 or OAuth2/OpenID Connect.
• The customer contact who administers the IdP is available to register Harmoney as an application and to test the login.

Information to request from the customer

Gather the following before configuring, so the setup can be completed in one go.

Input	SAML	OAuth2 OpenID
URL of the IdP where the user logs in (authorizeUri)	✅	✅
Client ID, or Entity ID for SAML	✅	✅
Client secret	❌ Only a private key if assertions are encrypted	✅
Token endpoint URL (tokenUri)	❌	✅
IdP metadata URL or signing key, if the signature of the response must be validated	✅	❌
Location of the user claims (ID token, access token or UserInfo endpoint)	❌	✅
Names of the attributes or claims for the user id, first name, last name, phone number, email, language and roles	✅	✅
The IdP groups or roles that must be mapped to Harmoney roles	✅	✅
The FSP each IdP group belongs to	✅	✅
Whether the IdP releases all these attributes to Harmoney	✅	✅

Harmoney in turn provides the customer with the redirect URL (redirectPath) to register at the IdP: the Assertion Consumer Service URL for SAML, the redirect URI for OAuth2 OpenID.

Instructions

The order below matters: the provider refers to the vault entries, and the white label refers to the provider.

Vault settings

1. Add the values received from the customer to the vault, for example:
   • SSO_clientId
   • SSO_clientSecret (if applicable)
   • SSO_tokenUri (OAuth2 OpenID only)
   • SSO_authorizeUri
   • SSO_redirectPath

SAML setup

Configure the following SAML SSO provider. The fields authentication, authorizeUri and redirectPath are described in the SSO providers page.

2. Create the provider, map the attributes sent by the IdP with SSO_RESULT_MAPPING and map the IdP groups to Harmoney roles with SSO_ROLE_MAPPING.

Settings Configuration

Examples

Example

{
  "identifier": "sso-provider",
  "state": "ACTIVE",
  "healthCheckLevel": 2,
  "implementationClass": "eu.myharmoney.app.providers.sso.saml.SamlSSOV2Provider",
  "settings": {
    "SSO_RESULT_MAPPING": {
      "fieldsMapping": {
        "uid": { "fieldName": "id" },
        "firstName": { "fieldName": "given_name" },
        "lastName": { "fieldName": "family_name" },
        "email": { "fieldName": "email" },
        "mobilePhone": { "fieldName": "phone_number" },
        "gender": { "fieldName": "gender" },
        "roles": { "fieldName": "role" }
      },
      "fallbackRoles": [],
      "initialRole": ""
    },
    "SSO_ROLE_MAPPING": {
       "idp-group-advisors": [
          {
             "role": "PARTNER_ADVISOR",
             "fspExtRef": "my-fsp"
          },
          {
             "role": "PARTNER_ADVISOR_RBAC",
             "fspExtRef": "my-fsp"
          }
       ],
       "idp-group-office-managers": [
          {
             "fspExtRef": "my-fsp",
             "role": "PARTNER_MANAGER"
          },
          {
             "role": "PARTNER_MANAGER_RBAC",
             "fspExtRef": "my-fsp"
          }
       ]
    },
    "authentication": {
      "clientId": "$vault{SSO_clientId}",
      "clientSecret": "$vault{SSO_clientSecret}"
    },
    "authorizeUri": "$vault{SSO_authorizeUri}",
    "redirectPath": "$vault{SSO_redirectPath}"
  }
}

3. Only if the signature of the SAML response must be validated, also configure digitalSignatureValidation together with metadataUrl or idpSsoProviderSigningKey. Only if the IdP encrypts its assertions, also configure SSO_X509_CERTIFICATE and the private key in clientSecret.

OAuth2 OpenID setup

Configure the following OAuth2 OpenID SSO provider. The fields authentication, authorizeUri and redirectPath are described in the SSO providers page.

2. Create the provider, tell it where to find the user claims with SSO_USER_INFO_CLAIMS_SOURCE, map the claims with SSO_RESULT_MAPPING and map the IdP groups to Harmoney roles with SSO_ROLE_MAPPING.

3. Enable PKCE with PKCE_MAPPING if the IdP requires it. See PKCE_MAPPING.

Settings Configuration

Examples

Example

{
  "identifier": "sso-provider",
  "state": "ACTIVE",
  "healthCheckLevel": 2,
  "implementationClass": "eu.myharmoney.app.providers.sso.OAuth2OpenIdSSOProvider",
  "settings": {
    "SSO_USER_INFO_CLAIMS_SOURCE": "ID_TOKEN",
    "PKCE_MAPPING": {
      "codeChallengeTransformationType": "S256"
    },
    "SSO_RESULT_MAPPING": {
      "fieldsMapping": {
        "uid": { "fieldName": "sub" },
        "firstName": { "fieldName": "firstName", "setUndefinedIfNull": true },
        "lastName": { "fieldName": "lastName", "setUndefinedIfNull": true },
        "email": { "fieldName": "email", "setUndefinedIfNull": true },
        "languageIsoCode": { "fieldName": "language" },
        "roles": { "fieldName": "groups" }
      }
    },
    "SSO_ROLE_MAPPING": {
      "idp-group-advisors": [
        {
          "role": "PARTNER_ADVISOR",
          "fspExtRef": "my-fsp"
        },
         {
            "role": "PARTNER_ADVISOR_RBAC",
            "fspExtRef": "my-fsp"
         }
      ],
       "idp-group-office-managers": [
          {
             "fspExtRef": "my-fsp",
             "role": "PARTNER_MANAGER"
          },
          {
             "role": "PARTNER_MANAGER_RBAC",
             "fspExtRef": "my-fsp"
          }
       ]
    },
    "authentication": {
      "clientId": "$vault{SSO_clientId}",
      "clientSecret": "$vault{SSO_clientSecret}",
      "tokenUri": "$vault{SSO_tokenUri}"
    },
    "authorizeUri": "$vault{SSO_authorizeUri}",
    "redirectPath": "$vault{SSO_redirectPath}"
  }
}

White label settings

4. Add the provider to the authentication methods of the white label, as described on the authentication page. Until this is done, the provider has no effect.

[
  {
    "providerIdentifier": "sso-provider",
    "type": "PROVIDER"
  },
  {
    "type": "BUILT_IN"
  }
]

warning

Keep the BUILT_IN method, so nobody is locked out if the SSO login does not work yet.

Disabling manual registration

Once users log in through SSO, the white label experimental feature disableManualRegistration can be enabled to remove the possibility to register manually with an email or phone number and a password. The registration option is hidden on the login page and the registration itself is refused by the back-end. Registration through SSO is not affected.

:::warning Do not enable disableManualRegistration straight away Once manual registration is disabled, nobody can create a Harmoney user by registering. Before enabling it, make sure the Harmoney users who need access for support are able to provide themselves access, for example through the roles mapped in SSO_ROLE_MAPPING or an account that already exists. Otherwise support cannot get into the environment. :::

✅ To test

Ask the customer to test the login and confirm each of the following:

1. The white label login page shows the SSO login option.
2. Clicking it redirects to the login page of their IdP.
3. After logging in at the IdP, the user is returned to Harmoney and is logged in.
4. If first name, last name and mobile phone are provided by the IdP, the user is registered automatically. Otherwise the registration page opens, prefilled with the data received.
5. The user has the Harmoney roles and the FSP that are expected for their IdP group.