Table of Contents

SAML IDP

Note

In this section, configuration possibilities for the SAML identity provider are documented.

General configuration

Property name Description Allowed/default values Available for legacy IDPs?
id The internal ID of the SAML IdP String Yes
name The display name shown in the configuration gui String Yes
keystore The keystore id the IdP should use. For purposes of certificate rollover, can be several keystore ids in a row, comma-separated (no spaces). String Yes
entityID The entityID String Yes
requireSigned If signed SAMLRequests should be required by the IDP String Yes
authenticatorId Id or alias of the initial authenticator to use String No
postSSOURL The SingleSignOnService for POST binding the IDP as it appears in the metadata. NOTE: Should never be edited unless it is a legacy IDP String Yes
redirectSSOURL The SingleSignOnService for Redirect binding the IDP as it appears in the metadata. NOTE: Should never be edited unless it is a legacy IDP String Yes
postSLOURL The SingleLogoutService for POST binding the IDP as it appears in the metadata. NOTE: Should never be edited unless it is a legacy IDP String Yes
redirectSLOURL The SingleLogoutService for Redirect binding the IDP as it appears in the metadata. NOTE: Should never be edited unless it is a legacy IDP String Yes
pipeId Optional id of a pipe to run after successful authentication, but before SAMLResponse is returned. Pipe can access item as it was returned in authenticator pipe. String No
strictValidation Whether or not to put extra validation checks on incoming SAMLRequests. For legacy, this is configured at authenticator level. Default: false No
sendSAMLResponseOnError Whether or not to send a SAMLResponse containing error code if a fatal error occurs. For legacy, this is configured at authenticator level. Default: false No
allowUnsolicited Whether or not to allow unsolicited requests Default: true No
allowSSO Whether or not to allow SSO at this IDP Default: true No
assertionProfiles List of different assertion profiles at this IDP, see below. List of Json Objects No
postSSOURLHoK The SingleSignOnService for Holder-of-key POST binding the IDP as it appears in the metadata. Should be configured as the same value as postSSOURL but with /hok added to the end. If legacy, can have any value. String Yes
redirectSSOURLHoK The SingleSignOnService for Holder-of-key Redirect binding the IDP as it appears in the metadata. Should be configured as the same value as postSSOURL but with /hok added to the end. If legacy, can have any value. String Yes
appearanceProfiles List of different appearance profiles List of Json Objects No
requireSignedLogoutRequest Whether or not incoming SAML LogoutRequests need to be signed Default: true No
requireSignedLogoutResponse Whether or not incoming SAML LogoutResponses need to be signed Default: true No
entityIDAliases Other entityIDs this IDP can issue assertions as. Used to simplify upgrading from legacy configurations. List of Strings No

Assertion profiles configuration

assertionProfiles is a more complex configuration parameter, and is configured as a list of Json Objects (see examples below):

Property name Description Allowed/default values Mandatory
id The ID of the assertion profile String Yes
nameIDAttribute The attribute to take NameID from. If left blank, will use the user id returned from authenticator. String No
useForEntityIDs List of SP Entity IDs where this assertion profile should be used. Ignored if use_if_expr is set. List of strings Yes, unless use_if_expr is set
use_if_expr Expression to determine whether or not the assertion profile should be used. Available scopes are context, item, and session. See expressions for more. String Yes, unless useForEntityIDs is set
signResponse Whether or not to sign the SAML Response Default: true No
signAssertion Whether or not to sign the SAML Assertion Default: false No
encryptAssertion Whether or not to encrypt the SAML Assertion Default: false No
scope Scope added to scoped attributes. Must be one of the IDPs declared scopes. String No
enableScopedAttributes Whether or not to enable scoped attributes Default: false No
authMethod The authentication method used, will be used as AuthnContextClassRef value. Can be expanded with the item and session scopes. String (EXPANDABLE) No
comparePrincipal Whether or not to compare the principalSelection with the authenticated principal identity Default: false No
hokCertificate The certificate to use as SubjectConfirmationData when the holder-of-key binding is used String (base64 certificate without header) No
excludeSubjectNotBefore Whether to exclude subject not before Default: false No
nameIdFormat The nameIdFormat to use String No
audienceRestriction The audienceRestriction to use. If multiple, should be comma-separated. String No
additionalAttributes The attributes to add to the SAML Assertion. Detailed configuration description below. Json Object, see below No
defaultSPID For unsolicited requests (ie, when a SP has not initiated the authentication), send the SAML assertion towards this SP, see allowUnsolicited in the general section above String No
keystore Keystore ID to use for this assertion profile. Overrides the default keystore configured on the IDP object. For purposes of certificate rollover, can be several keystore ids in a row, comma-separated (no spaces) String No
signatureAlgorithm Signature algorithm to use for this assertion profile. Default is set at a global level. String No

additionalAttributes within assertionProfiles can be configured the following way:

Name Description Expandable Mandatory
name The name of the attribute No Yes
friendlyName The friendlyName of the attribute No No
itemAttribute The item attribute that the value should be taken from No Yes
nameFormat NameFormat for this attribute No No
scoped Whether or not the attribute should be scoped No No

Additional notes on AssertionProfiles

If you wish to use a default profile, configure use_if_expr as true. You may configure useForEntityIDs if you want to use a specific profile for certain SP EntityIDs. Profiles will be iterated in order and the first profile matching the expression or entity ID will be used. One of use_if_expr and useForEntityIDs must be configured, but if both are configured use_if_expr takes precedence. The parameter authMethod is expandable (and the only parameter here which is expandable) and may use the item from the authenticator or IDP pipe. So if you want the authMethod value to be dynamic based on which authenticator was used, you can add a property in the authenticator pipe with your desired value.

If you wish to set up a SAML holder-of-key flow, you may do so using the "hokCertificate" parameter in your assertion profiles. If a holder-of-key binding is used, the certificate will be used as subject confirmation data. At the identity provider, you should include a configuration parameter called "postSSOURLHoK" (and/or "redirectSSOURLHoK") and it should have the value  <base-url>/authentication/saml/<internal-idp-id>/login/hok. You can also direct the authentication flow via AgnosticDispatcher and "context.bindingIsHok".

Example AssertionProfiles

Example of an assertionProfile configuration:

Simple example that uses mostly default settings:

[{
      "id" : "my-default-profile",
      "use_if_expr": "true",
      "additionalAttributes" : [ {
        "name" : "urn:oid:2.5.4.42",
        "friendlyName": "givenName",
        "itemAttribute" : "givenName"
      }]
}]

A more advanced example:

[{
      "id" : "some-custom-profile",
      "nameIDAttribute": "uid",
      "useForEntityIDs" : [ "someSPEntityID", "someOtherSPEntityID" ],
      "use_if_expr": "context.requestedAuthenticationContext.contains('myacrvalue1')",
      "signResponse": "true",
      "signAssertion" : "false",
      "encryptAssertion": "true",
      "scope": "mydomain.com",
      "enableScopedAttributes": "false",
      "authMethod": "{{item.authMethod}}",
      "comparePrincipal": "false",
      "hokCertificate": "some-certificate-value",
      "excludeSubjectNotBefore": "false",
      "nameIdFormat": "some-value",
      "audienceRestriction": "someSPEntityID",
      "additionalAttributes" : [ {
        "name" : "urn:oid:2.5.4.42",
        "friendlyName": "givenName",
        "itemAttribute" : "givenName"
      }, {
        "name" : "urn:oid:2.5.4.4",
        "friendlyName": "sn",
        "itemAttribute" : "sn"
      } ]
}]

Unsolicited requests

An example of an assertion profile for an unsolicited request:

{
  "id": "my-default-assertion-profile",
  "defaultSPID": "myapps",
  "use_if_expr": "true",
  "nameIDAttribute": "sAMAccountName",
  "additionalAttributes": [
    {
      "name": "mail",
      "itemAttribute": "mail"
    }
  ]
}

Please note, the order of the profiles is important - the first one to match will be applied, so you might want to place your "defaultSPID" profile last

Complete SAML IDP configuration example

{
    "assertionProfiles" : [ {
      "id" : "default",
      "use_if_expr" : "true",
      "additionalAttributes" : [{
              "name": "urn:oid:2.5.4.42",
              "friendlyName": "givenName",
              "itemAttribute": "givenName"
      }],
      "signResponse" : "true",
      "signAssertion" : "true",
      "encryptAssertion" : "false",
      "defaultSPID" : "myapps"
    } ],
    "id" : "my_internal_idp_id",
    "name" : "Saml IDP",
    "keystore" : "5f615cf9-7868-4c73-87e4-f0cceea45ac9",
    "entityID" : "https://mydomain.com/authentication/saml/my_internal_idp_id",
    "requireSigned" : "false",
    "authenticatorId" : "my-authenticator-alias",
    "postSSOURL" : "https://mydomain.com/authentication/saml/my_internal_idp_id/login",
    "redirectSSOURL" : "https://mydomain.com/authentication/saml/my_internal_idp_id/login",
    "postSLOURL" : "https://mydomain.com/authentication/saml/my_internal_idp_id/logout",
    "redirectSLOURL" : "https://mydomain.com/authentication/saml/my_internal_idp_id/logout",
    "strictValidation" : "false",
    "allowUnsolicited" : "true",
    "sendSAMLResponseOnError" : "true",
    "clock_skew_minutes" : "5",
    "allowSSO" : "true",
    "created" : "2024-06-12T09:16:53.489Z",
    "modified" : "2024-09-05T07:02:12.164Z"
}
Configuration Files SAML 2 Identity Provider