Skip to main content
Version: 19

SAML SSO providers

⚙️ Configuration​

Harmoney acts as a service provider using a Harmoney Provider.

Settings Configuration

🛠️ Technical documentation​

SSO_RESULT_MAPPING​

Customers map their data in their own specific way. This requires us to make the mapping configurable.

Fields​

  • fieldsMapping: Defines what claim should be used to map an 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 the 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 an exception if configured true but no registration prefill is available in the token.
    • 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. 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"
    ]
  }
}

SSO_ROLE_MAPPING​

The fspExtRef is used to define which Financial Service Provider (FSP) the role applies to, using the reference of the FSP itself.

If no fspExtRef is defined, the FSP is retrieved from the following attribute: .../claims/physicalDeliveryOfficeName

Warning: This fallback method resolves the FSP by searching for references on the link between a parent FSP and a child FSP (agency).

The idp_role key can be any string.

Example:

{
  "idp_role": [
    {
      "role": "PARTNER_ADVISOR",
      "fspExtRef": "__FSP_REF__"
    }
  ]
}

Encryption​

When the Identity Provider (IdP, e.g., Azure AD) sends a SAML response to the Service Provider (SP, Harmoney), the response can be encrypted for enhanced security.

The IdP encrypts the SAML response using a public certificate provided by Harmoney. Once received, Harmoney decrypts the response using the corresponding private key.

Creation of a Certificate & Private Key​

You can generate the required keys using OpenSSL.

  • Create a private key: 
    openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private-key.pem
  • Create public certificate (define the expiration days, because the default is 30 days!) 
    openssl req -new -x509 -key private-key.pem -out certificate.pem -days 365

Examples​

The EncryptedAssertion contains 2 encrypted parts:

  • Encrypted key: contains a symmetric key which can be used to decrypt the Encrypted Data.
  • Encrypted data : contains the Assertion
<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="_____ID_____" Version="2.0" IssueInstant="2023-07-17T01:01:48Z"
                Destination="https://sp.harmoney.eu/saml" InResponseTo="_____REQUEST_ID_____">
    <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">http://idp.example.com/metadata</saml:Issuer>
    <samlp:Status>
        <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
    </samlp:Status>
    <saml:EncryptedAssertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
        <xenc:EncryptedData xmlns:xenc="http://www.w3.org/2001/04/xmlenc#" Id="_____ASSERTION_ID_____">
            <xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/>
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <xenc:EncryptedKey>
                    <xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p"/>
                    <xenc:CipherData>
                        <xenc:CipherValue>_____ENCRYPTED_SYMMETRIC_KEY_____</xenc:CipherValue>
                    </xenc:CipherData>
                </xenc:EncryptedKey>
            </ds:KeyInfo>
            <xenc:CipherData>
                <xenc:CipherValue>_____ENCRYPTED_DATA_____</xenc:CipherValue>
            </xenc:CipherData>
        </xenc:EncryptedData>
    </saml:EncryptedAssertion>
</samlp:Response>

🔗 References​