How-tos

7 mins read

Set Up SAML IDP for Authentication

Instructions on how to connect a SAML-compliant IDP to Cloudentity

About SAML

Security Assertion Markup Language (SAML) is an XML-based open standard that allows to transfer user’s identity data between the identity providers and the service providers.

SAML benefits include the following:

Improved user experience

SAML allows the users to use the Single Sign On (SSO). The user can authenticate with the IDP and then access the service protected by Cloudentity without additional authentication.
Reduced costs of administration for service providers

SAML reuses a single act of authentication for multiple times, which may reduce costs of maintaining account data.
Risk transfer

Using SAML shifts the responsibility for identity management and IAM-related risks from the service provider to the identity provider.

In order to connect a SAML IDP to Cloudentity, you need to perform the following high-level steps:

Get the following data from your SAML IDP:
- SSO certificate issued by the IDP
- SSO endpoint URL used by the IDP to receive SAML requests
Register the IDP in Cloudentity using the SAML connector.
Pass the Entity issuer and Redirect URL values generated by Cloudentity to your SAML IDP app.

Prerequisites

To configure the connector, you need to retrieve the metadata from your SAML IDP applicaiton.

SAML Service Povider app (SP) registered with your Identity Provider (IDP).

Connect SAML IDP

In your workspace, go to Identity Providers > Create Connection.

Result

A list of identity provider templates is displayed.
Select the SAML template and click Next.

Result

The Register SAML fill-in form opens with the redirect URL for registering your application.

Fill in the SAML connector form.

Field	Description
Name	Name of your connector. This name is displayed in the user authentication UI.
Sign-in URL	URL pointing to your SAML IDP application’s SSO endpoint. Enter an initial dummy value to pass form validation if you don’t have this app yet.
IDP certificate	Certificate of your SAML IDP application. You need to obtain it from the application itself.
Identifier source	Defines how the user identifier is extracted from the SAML assertion received from the IDP. If you select Subject as the identifier source, the identifier is retrieved from `SAMLResponse <Subject>`. If you choose Attribute, you need to enter a user attribute name into the Identifier attribute field. If you select the attribute as the identifier source, the identifier is retrieved from `SAMLResponse <AttributeStatement>`. Any attribute from `SAMLResponse <AttributeStatement>` can be used for that purpose.

Select Save.

Result

Your new SAML identity provider is created and listed in the Consumer Identity Providers view.

Entity issuer and Redirect URL (or Assertion Consumer Service (ACS)) are generated in Cloudentity. Use these values to finish the configuration on the SAML application side.

Advanced Configuration

Advanced settings contain optional features which may be necessary to use in specific cases. To configure your new IDP advanced settings

From the Identity Providers > YOUR_IDENTITY_PROVIDER > Configuration page, select Advanced settings at the bottom.
In the Authentication Method Reference you can select an authentication method to be written into the amr object returned by the IDP. The amr object is written if it doesn’t exist. If it exists, its values are replaced with the selected item.

Tip

You can also use an extension script to modify amr values. If you do, keep in mind that the script is executed after the amr injection from this field, so the values injected by the script are final.
Optionally, enable the Skip inResponseTo option. This is not recommended since it lowers the security level of your system, as the login is treated as IDP-initiated. You may need to turn this flag on when the InResponseTo parameter is not returned by the IDP.
Select Save.

Add SAML IDP attributes

Make sure to add attributes sent by your SAML IDP to the IDP connector so that they can be recognized and mapped to the authentication context.

Consider the example below. All attributes within <saml2:AttributeStatement> can be extracted and mapped to the authentication context.

<?xml version="1.0" encoding="UTF-8"?>
<saml2:Assertion ID="id12606633554344727301514261" IssueInstant="2022-01-12T17:04:07.362Z" Version="2.0"
    xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
    <saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://www.example.com/exk3ip7ehfTC30ReG5d7</saml2:Issuer>
    <saml2:Subject>
        <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">example@mail.com</saml2:NameID>
        <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
            <saml2:SubjectConfirmationData NotOnOrAfter="2022-01-12T17:09:07.362Z" Recipient="https://cloudentity-gkossobudzki.us.authz.stage.cloudentity.io/cloudentity-gkossobudzki/demo/login"/>
        </saml2:SubjectConfirmation>
    </saml2:Subject>
    <saml2:Conditions NotBefore="2022-01-12T16:59:07.362Z" NotOnOrAfter="2022-01-12T17:09:07.362Z">
        <saml2:AudienceRestriction>
            <saml2:Audience>c7bhamiqs3kro24r4peg</saml2:Audience>
        </saml2:AudienceRestriction>
    </saml2:Conditions>
    <saml2:AuthnStatement AuthnInstant="2022-01-12T17:04:07.362Z" SessionIndex="id1642007047361.940296625">
        <saml2:AuthnContext>
            <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef>
        </saml2:AuthnContext>
    </saml2:AuthnStatement>
    <saml2:AttributeStatement>
        <saml2:Attribute Name="employeeId" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
            <saml2:AttributeValue
                xmlns:xs="http://www.example.com/2001/XMLSchema"
                xmlns:xsi="http://www.example.com/2001/XMLSchema-instance" xsi:type="xs:string">JoeDoe123
            </saml2:AttributeValue>
        </saml2:Attribute>
        <saml2:Attribute Name="mail" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
            <saml2:AttributeValue
                xmlns:xs="http://www.example.com/2001/XMLSchema"
                xmlns:xsi="http://www.example.com/2001/XMLSchema-instance" xsi:type="xs:string">test@example.com
            </saml2:AttributeValue>
        </saml2:Attribute>
        <saml2:Attribute Name="https://example.com/groups" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
            <saml2:AttributeValue
                xmlns:xs="http://www.example.com/2001/XMLSchema"
                xmlns:xsi="http://www.example.com/2001/XMLSchema-instance" xsi:type="xs:string">administrators
            </saml2:AttributeValue>
            <saml2:AttributeValue
                xmlns:xs="http://www.example.com/2001/XMLSchema"
                xmlns:xsi="http://www.example.com/2001/XMLSchema-instance" xsi:type="xs:string">super_users
            </saml2:AttributeValue>
        </saml2:Attribute>
    </saml2:AttributeStatement>
</saml2:Assertion>

Go to Identity Providers and select an IDP from the list.
Open the Attributes page. A standard list of attributes returned by this IDP appears.
Select Add attribute.

Fill in the attribute form.

Source	Description
SAML assertion attribute name	Attribute received within the SAML assertion sent by the IDP, for example `employeeId`, `mail` or `groups` from the above sample.
Display name	Name representing this attribute in Cloudentity
Data type	Data type of the incoming SAML attribute

Claim names with a . character

If the incoming attribute has a . character in the name, the dot must be explicitly escaped using \. when defining the IDP attribute. For example, claim name https://example.com/groups must be entered as https://example\.com/groups.

Save your changes and proceed to mapping the attributes to the authentication context.

Attributes of your IDP correspond to the contents of the assertion (the XML received from the IDP).

Example

Here’s a SAML Response containing the <saml2:AttributeStatement> tag and attributes issued by IDP (in this case, a single username attribute with the value Joe):

<?xml version="1.0" encoding="UTF-8"?>
<saml2:Assertion ID="id1214053367877977596315632" IssueInstant="2022-01-07T09:14:27.545Z" Version="2.0"
    xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
    <saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://www.okta.com/exk3ip7ehfTC60ReG5d7</saml2:Issuer>
    <saml2:Subject>
        <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">test@mail.com</saml2:NameID>
        <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
            <saml2:SubjectConfirmationData NotOnOrAfter="2022-01-07T09:19:27.545Z" Recipient="https://example.com/login">
        </saml2:SubjectConfirmation>
    </saml2:Subject>
    <saml2:Conditions NotBefore="2022-01-07T09:09:27.545Z" NotOnOrAfter="2022-01-07T09:19:27.545Z">
        <saml2:AudienceRestriction>
            <saml2:Audience>c7bhamiqs5kro24r4peg</saml2:Audience>
        </saml2:AudienceRestriction>
    </saml2:Conditions>
    <saml2:AuthnStatement AuthnInstant="2022-01-07T09:14:27.545Z" SessionIndex="id1641546867544.1585510482">
        <saml2:AuthnContext>
            <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef>
        </saml2:AuthnContext>
    </saml2:AuthnStatement>
    <saml2:AttributeStatement>
        <saml2:Attribute Name="username" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
            <saml2:AttributeValue
                xmlns:xs="http://www.w3.org/2001/XMLSchema"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Joe
            </saml2:AttributeValue>
        </saml2:Attribute>
    </saml2:AttributeStatement>
</saml2:Assertion>

Map IDP attributes to authentication context

If you’ve added custom attributes for an IDP, you need to make sure they are mapped to the authentication context. You can do it either from the IDP configuration page (as explained here) or use Data Lineage instead.

Default OIDC/SAML attributes are mapped out of the box.

Go to Identity Providers and select an IDP from the list.
Open the Mappings page. A standard attribute mapping for this IDP appears.
Select Add mapping and map any custom IDP attributes to an existing authentication context attribute.

Note

If you need to create new authentication context attributes, read Setting up authentication context.
Optionally, assign a post-authentication extension to modify your authentication context before issuing the token to the client. Attributes returned by the script do not need to be separately mapped to the authentication context.
Save your changes. Your mapped custom attributes should now be shared in the ID token issued to your client application, given that the target application requests them (you can check this in Data Lineage).

Connect Extensions to your IDP

Go to Identity Providers > YOUR_IDP > Extensions.
Assign a Post Authentication script to the IDP. This script will be executed upon user authentication via this IDP.
Connect your application to the IDP in the Post Authentication application field. Users will be redirected to this application upon authentication via this IDP.

Feature flag

Post Authentication applications must be explicitly enabled in your tenant using the custom_apps feature flag.

Bind SAML Service Provider

Configure your SP with Entity issuer and Redirect URL generated for your new identity provider in the Cloudentity administrator portal.

Result

After user authentication, IDP should send back the POST request to the specified redirect URL.

Test IDP

Prerequisites

Your IDP is enabled for user authentication.
Demo workspace is created with the Demo Portal connected.

Test

Open the Demo Portal (Data lineage -> Demo Portal -> Launch).
Select LOGIN TO DEMO APP.
Select your configured IDP and, next, authenticate in IDP.

Result

Cloudentity displays the consent page that lists data scopes to be shared with the application. When you proceed to the application (ALLOW ACCESS), the PII data coming from Azure AD is delivered through the access token and the ID token generated by Cloudentity.

Read More

For information on granting and managing Cloudentity consents, see Cloudentity OAuth consents.

Updated: Feb 14, 2023

How-tos

Set Up SAML IDP for Authentication

About SAML

Prerequisites

Connect SAML IDP

Result

Result

Result

Advanced Configuration

Tip

Add SAML IDP attributes

Claim names with a . character

Example

Map IDP attributes to authentication context

Note

Connect Extensions to your IDP

Feature flag

Bind SAML Service Provider

Result

Test IDP

Prerequisites

Test

Result

Read More

Related Articles