Enable user attributes for SAML apps

Asgardeo can share user attributes with applications. The following guide shows how to share user attributes with SAML applications.

Prerequisite

To get started, you need to have an application registered in Asgardeo. If you don't have an app registered, go to Asgardeo to register a SAML application.

Configure user attributes to share

Follow the steps below to configure the user attributes from the Asgardeo Console and share them with the application.

Select user attributes

You need to first specify the user attributes required for an application. This ensures that when a user logs in, the application can only get access to the user information exposed through these attributes.

To add user attributes to the app:

1. On the Asgardeo, go to Applications.
2. Select your application, go to the Protocol tab and select Enable attribute profile.
3. Click Update and go to the User Attributes tab.

4. Click Add User Attribute if you don't have any attributes already added.

   

5. Select the required attributes from the list as shown below.

   

6. Click Save to return to the User Attributes tab and then click Update.

Map user attributes

In the user attribute configurations, you can either choose default attribute names or define application-specific user attribute names.

To configure application-specific attribute names, you need to map the selected user attributes to application-specific user attributes.

To perform mapping:

1. Click Enable Mapping in the User Attributes section.

2. Change the Mapped user attribute for the selected attribute.

   

This ensures that the application receives attributes based on the name that is configured.

Define mandatory user attributes

If your application needs certain attributes for the successful function of the application, you can make them mandatory attributes. Users logging into the application should then have the mandatory attributes either pre-filled in their profiles or provide the required information when prompted during the login flow.

To make an attribute mandatory:

1. On the Asgardeo console, go to Applications.

2. Select the application and go to its User attributes tab.

3. Expand the relevant scope and out of the selected attributes for the application, select the mandatory attributes by selecting the Mandatory checkbox next to them.

Select the subject attribute

The subject attribute is used for exchanging information about the user. The subject is represented by the subject attribute in the SAML assertion.

By default, Asgardeo shares User ID as the subject. You can define any user attribute as the subject.

To define a different attribute as the subject:

1. Select it as a user attribute.

2. Go to the Subject section under User Attributes.

   

3. Select an attribute as the subject from the Subject attribute list.

4. Click Update.

How it works

Let's see how this flow works in Asgardeo.

Once you have configured the user attributes that are required for your application, Asgardeo implements the following process when a user tries to log in to your app.

Asgardeo checks for mandatory attributes

Asgardeo verifies whether the user's profile has values for all the mandatory attributes that are requested by the application. If there are missing values, Asgardeo will prompt the user to enter the missing values.

Requests user consent

By default, Asgardeo requests the user's consent to share the user attributes with the application.

Note

Learn more about managing user consent.

Shares attributes with the app

Asgardeo will share these user attributes with an application, given the user has provided consent. User attributes, along with the subject attribute, are shared via SAML assertions.

Subject attribute

The subject attribute is shared via the <saml2:Subject> element based on the configured subject attribute.

A sample Subject element found in a SAML assertion is given below:

<saml2:Subject>
   <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">[email protected]</saml2:NameID>
   <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
         <saml2:SubjectConfirmationData InResponseTo="immfmmacmiaomepphphhlfokfggpffkleokajfbg"
                                 NotOnOrAfter="2021-07-13T06:09:33.594Z"
                                 Recipient="http://localhost:8081/sample-app/home.jsp"
                                 />
   </saml2:SubjectConfirmation>

</saml2:Subject>

Attribute statement

If the user gives consent to share attributes with the application, Asgardeo returns the requested user attributes via the <saml2:AttributeStatement> element.

A sample attribute statement element found in a SAML assertion is given below:

<saml2:AttributeStatement>
        <saml2:Attribute Name="http://wso2.org/claims/country"
                         NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
                         >
            <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                  xsi:type="xsd:string"
                                  >Sri Lanka</saml2:AttributeValue>
        </saml2:Attribute>
        <saml2:Attribute Name="http://wso2.org/claims/emailaddress"
                         NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
                         >
            <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                  xsi:type="xsd:string"
                                  >[email protected]</saml2:AttributeValue>
        </saml2:Attribute>
</saml2:AttributeStatement> 

Attribute statement with attribute mapping

If you have done any custom attribute mapping via the Enable mapping setting, the attributes will contain those application-specific names in the SAML assertion.

A sample attribute statement element with custom attribute mapping is given below:

<saml2:AttributeStatement>
            <saml2:Attribute Name="country"
                             NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
                             >
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                      xsi:type="xsd:string"
                                      >Sri Lanka</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="emailaddress"
                             NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
                             >
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                      xsi:type="xsd:string"
                                      >[email protected]</saml2:AttributeValue>
            </saml2:Attribute>
</saml2:AttributeStatement>