Configuration Parameters to Add IdPs Using SAML Protocol

This article provides you a brief understanding of the SAML protocol and all the common configurations available to add an identity provider using the SAML protocol.

Overview

SAML stands for Security Assertion Markup Language. It is an XML-based open standard used for exchanging authentication and authorization data between identity providers (IdPs) and service providers (SPs). SAML enables single sign-on (SSO), allowing users to access multiple applications or services with a single set of login credentials. It is commonly used in enterprise environments and web-based applications to facilitate secure authentication and authorization processes. Learn more about the common configurations that are available to integrate identity providers over SAML protocol.

Refer to the below how-to guides to learn how to integrate the supported IdPs using the SAML protocol.

Common Configurations - SAML Protocol

The following are the common settings to integrate an IdP using the SAML Protocol.

Settings Term Description
General Redirect URL The redirect URL to use when configuring the identity provider.
Alias The alias uniquely identifies an identity provider and it is also used to build the redirect URL.
Domain Name Domain name of the organization.
SAML Settings Use Entity Descriptor Enabled: If this setting is enabled, the SAML Entity Descriptor will be used to fetch the identity provider configurations. The descriptor enables you to load the configuration from the endpoint and automatically update the configuration if the source has any updates. This setting is visible only once while adding a new IdP in the Unifyia platform. Once the endpoints are discovered, this option is hidden on the platform UI.
Disabled: If disabled, you need to manually provide the Identity Provider Entity ID, Single Sign-On Service URL, Single Logout Service URL, X509 Certificates, and other required parameters.
SAML Entity Descriptor If you have enabled the Use Entity Descriptor option, you need to provide the SAML Entity Descriptor URL. This is a URL for fetching the remote IdP metadata, which contains all the necessary configuration information (metadata) for the SAML protocol, such as endpoints and supported capabilities. It fetches the Identity Provider Entity ID, Single Sign-On Service URL, Single Logout Service URL, X509 Certificates, and other required parameters.
Service Provider Entity ID This is a unique identifier, typically a URL, for the Service Provider (SP) in the SAML federation. The remote IdP uses this ID to identify requests from a Service Provider.
Single Sign-On Service URL This is the SAML endpoint (URL) the user is redirected to when initiating an authentication process. The Service Provider sends the authentication requests (AuthnRequests) to this endpoint.
Identity Provider Entity ID If empty, no Issuer validation is performed. This is a unique identifier, typically a URL, that uniquely identifies the IdP in the SAML federation. The Entity ID is used to validate the Issuer for received SAML assertions.
Single Logout Service URL The SAML IdP endpoint (URL) on the IdP where the Service Provider sends logout requests. This is used to handle single logout (SLO) scenarios, ensuring that the user is logged out of all connected services.
Client Session Logout This typically refers to the mechanism or process by which a user’s session is terminated on the client side (e.g., web browser) when a logout request is initiated. The logout request and response messages are transmitted directly between the Identity Provider (IdP) and the Service Providers (SPs) via a server-to-server communication channel.
Enable: Enable this flag if your SAML IdP supports backchannel logout.
Disable: If backchannel logout is not supported, set this flag to false. The user will be logged out of the client side (web browser) only.
NameID Policy Format Refers to the format of the NameID element, a crucial part of the SAML assertion, representing the identity of the user being authenticated in the assertion. Common formats include email, persistent, and transient.
Email: Represents the user’s identity using their email address. This format is simple and human-readable, making it suitable for scenarios where the email address is a primary user identifier.
Persistent: Provides a persistent, opaque identifier for the user that remains the same across sessions. This format is ideal for scenarios where a long-term, stable identifier is needed, such as in federated identity management.
Transient: Provides a temporary identifier for the user that is unique for a single session or a short duration. This format is used when the identifier does not need to be persistent across sessions, enhancing privacy.
Principal Type Specifies which part of the SAML assertion will be used to uniquely identify and track external user identities. Can be either Subject NameID or SAML attributes such as username or user ID (either by name or by friendly name). Subject NameID value cannot be set together with the Transient NameID Policy Format value.
Principal Attribute If you have chosen the Principal type as either by name or by friendly name, specify the name ("Attribute [Name]") or the friendly name ("Attribute [Friendly Name]") values of the user-identifying attribute.
Allow Create A flag that indicates whether the IdP is allowed to create a new user account to represent the principal if the user does not already exist when an authentication request is received.
Enabled: Create a new user account
Disable: Omits creating a new user account
HTTP-POST Binding for AuthnRequest A flag that controls the SAML binding when requesting authentication from an external IdP.
Enabled: Indicates that the SAML authentication request will be sent to the IdP using the HTTP-POST method. This involves submitting a form that includes the SAML request in the body of the HTTP POST message.
Disabled: Redirect Binding method will be used.
HTTP-POST Binding Response A flat that controls the SAML binding in response to any SAML requests sent by an external IdP.
Enabled: Indicates that the SAML response from the IdP to the SP will be sent using the HTTP-POST method.
Disabled: Redirect Binding method will be used.
HTTP-POST Binding Logout A flag that indicates whether to respond to requests using HTTP-POST binding.
Enabled: Indicates that the SAML logout request will be sent using the HTTP-POST method.
Disabled: Redirect Binding method will be used.
Pass Subject A flag that controls if the Server forwards a login_hint query parameter to the IdP. The server adds this field’s value to the login_hint parameter in AuthnRequest’s Subject so destination providers can pre-fill their login form.
Enabled: Indicates whether the subject (the authenticated user) information should be included in the SAML assertion as a login-hint.
Disabled: Omits forwarding a login_hint query parameter to the IdP.
Sign Service Provider Metadata A flag indicating whether the SAML metadata provided by the SP should be signed for authenticity and integrity.
Enabled: Sign the SP metadata
Disabled: Omits signing the SP metadata
Want Assertions Signed A flag that indicates whether the SP requires the SAML assertions from the IdP to be digitally signed to ensure their authenticity and integrity.
Enabled: Indicates that the service provider expects a signed Assertion.
Disabled: Omits signed assertion.
Want Assertions Encrypted A flag that indicates whether the SP expects the SAML assertions it receives from the IdP to be encrypted.
Enabled: The service provider expects an encrypted assertion.
Disabled: Omits encrypted assertion.
Force Authentication A flag that, when set, requires the IdP to prompt the user for authentication credentials, even if the user already has a valid session.
Enabled: Mandates user authentication at the external IdP.
Disabled: Omits user authentication.
Want AuthnRequests Signed A flag that indicates whether the SP requires the SAML authentication requests it sends to the IdP to be signed.
Enabled: Sign the requests sent to the external SAML IdP. You must provide the Signature Algorithm, SAML Signature Key Name, and Encryption Algorithm.
Disabled: Omits signing the requests sent to the IdP.
Signature Algorithm If the Want AuthnRequests Signed flag is enabled, specify the signature algorithm that must be used to sign SAML messages.
Recommended: RSA-SHA256
Encryption Algorithm If the Want AuthnRequests Signed flag is enabled, specify the algorithm that must be used to encrypt. This algorithm will be used by the SAML IdP for encryption of SAML documents, assertions, or IDs. The corresponding decryption key for decrypting SAML document parts will be chosen based on this configured algorithm and should be available in realm keys for encryption (ENC) usage.
If the algorithm is not configured, any supported algorithm is allowed and a decryption key will be chosen based on the algorithm specified in the SAML document itself. Supported encryption algorithms are RSA1_5 or RSA-OAEP.
SAML Signature Key Name Specifies the name associated with the key used for signing SAML messages. Signed SAML documents sent via POST binding include the signing key's identification in the KeyName element, which, by default, contains the Server key ID. External SAML IdPs might require a different key name. This option controls whether KeyName contains:
KEY_ID: ID of the Key
CERT_SUBJECT: The subject from the certificate corresponding to the realm key. Microsoft Active Directory Federation Services expect CERT_SUBJECT.
NONE: The server omits the key name hint from the SAML message.
Validate Signatures A flag indicating whether the SP should validate the IdP signatures on SAML messages and assertions to ensure their authenticity.
Enabled: Indicates that the external IdP signatures must be validated. If the flag is set to true, enter the IdP X509 certificate in the base 64 format.
Disabled: Omits validation.
Validating X509 Certificates This is the X509 certificate of the IdP that will be used to validate the signatures of SAML requests and responses from the external IdP. This certificate is imported from the SAML Entity descriptor URL. If you are manually providing the certificate details, download this certificate on the IdP provider page and copy the certificate in the base64 format.

Mappers

Mappers are commonly used to translate and configure user attributes, roles, and group memberships between the Unifyia platform and identity providers (IdPs) during integration. They offer flexibility in accommodating different user data structures and requirements when integrating multiple IdPs. The following are the supported mapper types for the IdPs being integrated using the OIDC protocol:

NOTE
  • You can add multiple hardcoded role mappers if you want the users to be given multiple roles. For each role mapper that you add, you need to select a different role.
  • For users from the integrated IdP, you can assign groups in two ways - by using the Hardcoded Group Mapper or the Advanced Claim to Group Mapper.
  • You can add as many Hardcoded Group or Advanced Claim to Group mappers as you need but each time ensure that you are mapping it to a different Unifyia group.
  • Once a Unifyia group is assigned to a group mapper, the same cannot be assigned to another group mapper.
  • There are 3 possible combinations of the group mapping using theAdvanced Claim to Group
    • Map specific group of IdP to a specific group on the Unifyia platform
    • Map multiple groups of IdP to a single group on the Unifyia Platform
    • Map multiple groups of IdP to multiple groups on the Unifyia Platform
  • If there is no group or role mapping, all the IdP users will be assigned to the default workflow present in the Unifyia platform and the policies defined in the workflow will apply to all the IdP users. The default workflow also needs to be defined by the organization before adding the IdP.
  • The mappings also rely on the mappers supported by the identity providers. For instance, Okta does not support the Advanced Claim to Group mapper, so you would need to use a hardcoded group for group mappings in this scenario.
Mapper Type AVailable Configurations Description
Hardcoded Role
  • Name: Display name for the mapper.
  • Role: Select the role that must be automatically assigned to the user imported fromthe IdP to the Unifyia platform.
 A hardcoded role mapper allows you to define which hardcoded role must be automatically assigned to the user imported to the Unifyia platform fromthe IdP rather than being dynamically mapped from user attributes or claims provided by the IdP. It means that any user will automatically receive this role regardless of their actual identity or attributes from the IdP. For example, all users may be given the User role by default, regardless of their role attribute in the IdP. This can be useful for creating a baseline level of access for all users.
Hardcoded Group
  • Name: Display name for the mapper.
  • Sync Mode Override: Overrides the default sync mode of the IdP for this mapper. Available values are:
    • Legacy: To keep the behaviour before this option was introduced.
    • Import: To only import the user once during first login of the user with this identity provide.
    • Force: To always update the user during every login with this identity provider.
    • Inherit: To use the sync mode defined in the identity provider for this mapper.
 A hardcoded group refers to a group that is statically assigned to users without any dynamic mapping or condition based on the IdP’s claims. The group is predetermined on the Unifyia platform and doesn't change based on the user’s actual attributes. For example, a group like Admins might be hardcoded for all users who are part of an administrative team, regardless of the user's attributes provided by the IdP.
Advanced Claim to Group
  • Name: Display name for the mapper.
  • Sync Mode Override: Overrides the default sync mode of the IdP for this mapper. Available values are:
    • Legacy: To keep the behaviour before this option was introduced.
    • Import: To only import the user once during first login of the user with this identity provide.
    • Force: To always update the user during every login with this identity provider.
    • Inherit: To use the sync mode defined in the identity provider for this mapper.
  • Claims: Key and value of the claim to search for in the token. You can reference nested claims using a '.', i.e. 'address.locality'. To use dot (.) literally, escape it with backslash (\.). You have the option to add multiple key and value of the claims to search for in the token.
    • Key: The key to search in the token.
    • Value: The assigned value (ID) for the Key in the IdP system.
  • Regex Claim Values: To apply regular expressions (regex) to validate and filter claim values received from an external identity provider (IdP).
  • Group: Group to assign the user to in the Unifyia platform if claim is present.
An advanced claim to group mapping involves mapping a claim (such as a user attribute or identity provider-specific information) to a specific group or groups in the Unifyia platform. This may include custom logic for transforming claims, combining multiple claims, or using conditions to assign a user to a particular group based on certain attributes.
Claims (Key and Value) Example: For example,
  • if you provide the key as group and provide the ID of the group for the value parameter, then it means that the group with the given ID (claim) must be searched for in the token sent from the IdP and must be assigned to the selected Group in the Unifyia platform.
  • if you provide the key as 'address.locality' and provide the value as Santa Cruz for the value parameter, then it means that the users with the locality in the address as Santa Cruz must be searched for in the token sent from the IdP and must be assigned to the selected Group (for example group_admins) in the Unifyia platform.
Hardcoded Attribute
  • Name: Display name for the mapper.
  • User Attribute: User attribute you want to hardcode
  • User Attribute Value: User attribute value you want to hardcode.
A hardcoded attribute mapper type allows you to map a single user attribute from the IdP to User Model attribute in the Unifyia platform’s database. This attribute is fixed and manually configured (default/static value), without being dynamically derived from the user's identity or claims from the IdP. It ensures that a specific attribute is always assigned the same value regardless of the data in the IdP. For example, every user might be assigned a specific department code (e.g., HR) even though the IdP doesn't provide this information in the user’s attributes.
Attribute Importer
  • Name: Display name for the mapper.
  • Sync Mode Override: Overrides the default sync mode of the IdP for this mapper. Available values are:
    • Legacy: To keep the behaviour before this option was introduced.
    • Import: To only import the user once during first login of the user with this identity provide.
    • Force: To always update the user during every login with this identity provider.
    • Inherit: To use the sync mode defined in the identity provider for this mapper.
  • Attribute Name: Name of the attribute to search for in the assertion (token).
  • User Attribute Name: User attribute name to store claim. Use username, email, lastName, and firstName to map to those predefined user properties.
 An attribute importer is a configuration that allows for the importing and mapping of attributes from the IdP into the Unifyia platform. This could involve mapping a claim (like email or lastName) from the IdP to a field in the Unifyia’s user profile. For example, if the IdP provides a attribute like email=user@abc.com, an attribute importer might map this claim to a field like email in the platform. You can add a single attribute at a time. If you need to import more attributes, add a new attribute importer mapper for each attribute that you wish to import.
Username Template Importer
  • Name: Display name for the mapper.
  • Sync Mode Override: Overrides the default sync mode of the IdP for this mapper. Available values are:
    • Legacy: To keep the behaviour before this option was introduced.
    • Import: To only import the user once during first login of the user with this identity provide.
    • Force: To always update the user during every login with this identity provider.
    • Inherit: To use the sync mode defined in the identity provider for this mapper.
  • Template: Provide a template or pattern to use to format the username being imported from the IdP in the token and store it on the Unifyia platform. This particularly is useful when the users with the similar username are being imported. Substitutions are enclosed in ${}.
  • Target: Destination field for the mapper.
    • LOCAL: Means that the changes are applied to the username stored in local database upon user import.
    • BROKER_ID: This means the changes are stored into the ID used for federation user lookup.
    • BROKER_USERNAME: This means that the changes are stored into the username used for federation user lookup.
 A username template importer allows for the creation or transformation of a user’s username based on data sent in the token from the IdP. It often involves using predefined templates or patterns to generate the username in the Unifyia platform. The template can use information such as first name, last name, email, or other attributes from the IdP. For example, '${ALIAS}.${CLAIM.sub}'. ALIAS is the provider alias. CLAIM.sub references a subject ID or Access token claim. The substitution can be converted to upper or lower case by appending |uppercase or |lowercase to the substituted value, e.g. '${CLAIM.sub | lowercase}

Back Next
On this page
Related Links
How-To-Guides