Add login with a SAML identity provider


# Add login with a SAML identity provider

You can add standard SAML login (opens new window) to your applications using an external SAML identity provider (IdP) and enable users to log in to your applications while maintaining their accounts in the external identity providers.

Configure SAML Enterprise IDP login in Asgardeo

Follow this guide to register a SAML IdP in Asgardeo and add it to the login flow of your application.

# Register Asgardeo in the IdP

You need to register Asgardeo as a SAML application in the external identity provider. Follow the identity provider's documentation to know how to register a SAML application.

You can use the following URL as the Assertion Consumer Service URL (also known as callback URL/ redirect URL/ ACS URL) in the application that represents Asgardeo.

https://api.asgardeo.io/t/<organization_name>/commonauth
1

After you register the app, you should get the required configurations as explained below.

  • If you are manually applying the IdP configurations to Asgardeo, you need the following configurations:

    • Issuer (also known as entityId)
    • Single sign on URL of the identity provider (also known as login URL)
    • Identity Provider Certificate
  • If you are using metadata to apply the IdP configurations to Asgardeo, you need the following:

    • SAML IdP metadata file of the identity provider
    • Identity Provider Certificate

# Register the SAML IdP

Now, let's register the SAML IdP in Asgardeo.

  1. On the Asgardeo Console, click Connections.

  2. Click New Connections and select Standard-Based IdP.

  3. Provide a unique identity provider name, select SAML, and click Next.

    Create SAML Enterprise IDP in Asgardeo
  4. Select one of the following methods and add the SAML configurations:

    File Based Configuration

    Upload a SAML metadata file with the required configurations.

    See Use a SAML metadata file.
    Manual Configuration

    Use this option to manually specify the required SAML configurations.

    See Add SAML configs manually.

# Add SAML configs manually

If you selected Manual Configuration in the previous step, follow the steps given below.

  1. Enter the following details and click Next.

    Create SAML Enterprise IDP with manual configurations
    Parameter Description
    Service provider entity ID This value will be used as the saml2:Issuer in the SAML requests initiated from Asgardeo to the external identity provider (IdP).
    Identity provider Single Sign-On URL This vlaue specifies the single sign-on URL of the external IdP. This is where Asgardeo will send its authentication requests. You need to get this value from the external IdP.
    Identity provider entity ID This is the saml2:Issuer value specified in the SAML responses issued by the external IdP. You need to get this value from the external IdP.
  2. (Optional) Upload the public certificate of the identity provider.

  3. Click Finish to complete the registration.

# Use a SAML metadata file

If you selected File Based Configuration in the previous step, follow the steps given below.

A SAML IdP metadata file contains the following:

  • IdP identifiers (entityID or Issuer)
  • Endpoints (single sign-on URLs, single logout URLs, etc)
  • Supported bindings
  1. Specify the service provider entity ID.

    This value will be used as the saml2:Issuer in the SAML requests initiated from Asgardeo to the external identity provider (IdP).

  2. Upload the IdP metadata file and click Next.

    Create SAML Enterprise IDP with Metadata file
  3. (Opional) Upload the public certificate of the identity provider.

  4. Click Finish to complete the registration.

Once the SAML identity provider is created, you can configure additional SAML settings from the Settings tab.

# Enable the SAML IdP for login

Before you begin

You need to register an application with Asgardeo. You can register your own application or use one of the sample applications provided.

  1. On the Asgardeo Console, go to Applications.

  2. Select your application, go to its Login Flow tab and add SAML identity provider from your preferred editor:

    Recommendations

    Asgardeo recommends adding your social and enterprise connections to the first authentication step as they are used for identifying the user.

    Using the Classic Editor

    To add SAML identity provider login using the classic editor:

    1. If you haven't already defined a sign-in flow, click Start with Default configuration to get started.
    2. Click Add Authentication on the step, select your SAML identity provider, and click Add. Add SAML IdP login in Asgardeo
    Using the Visual Editor

    To add SAML identity provider login using the Visual Editor:

    1. Switch to the Visual Editor tab, by default the Username & Password login flow will be added onto the Visual Editor's workspace.

    2. Click on + Add Sign In Option to add a new authenticator to the same step and select your SAML identity provider connection.

      Add SAML IdP login in Asgardeo with visual editor
  3. Click Update to save your changes.

# Configure user attributes

Configuring attributes for an identity provider involves mapping the attributes available in the external SAML IdP to attributes that are local to Asgardeo. This is done so that Asgardeo can identify the user attributes in the response sent from the external SAML IdP.

  1. On the Asgardeo Console, click Connections.

  2. Select the SAML IdP connection from the list and click Set up.

  3. Go to the Attributes tab and click Add IdP Attributes. Go to attributes section in SAML IdP

  4. Provide the following values and click Add Attribute Mapping.

    Map SAML IdP attributes
    Parameter Description
    External IdP Attribute The attribute from the external IdP that should be mapped to the local attribute.
    Maps to The local attribute to which the external IdP attribute is mapped.
  5. Select one of the mapped attributes as the subject attribute for your application and click Update.

    select a subject attribute

    By default, Asgardeo uses the subject attribute sent by the external SAML IdP as the subject identifier. To configure a different attribute as the subject, enable the Find user ID from requests from the Settings tab of the SAML IdP.

# How it works

Consider a scenario where a SAML IdP returns the authenticated user's nickname and profile updated time to Asgardeo in the SAML authentication response as follows:

  • http://schemas.idp.com/nickname : nickname
  • http://schemas.idp.com/updated_at : profile updated time

You may want to convert them to the local attribute URI so that the application can receive them in the local attribute URI. If you don't do that mapping, the application will receive the attributes as sent by the external IdP.

A sample IdP attribute mapping done from the Asgardeo Console:

Sample IdP attribute mapping

Sample attributes in the SAML assertion of the integrated SAML app:

<saml2:AttributeStatement>
    <saml2:Attribute Name="http://wso2.org/claims/modified"
                        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"
                                >Mon Aug 30 2021 07:26:40 GMT+0000 (Coordinated Universal Time)</saml2:AttributeValue>
    </saml2:Attribute>
    <saml2:Attribute Name="http://wso2.org/claims/nickname"
                        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"
                                >John</saml2:AttributeValue>
    </saml2:Attribute>
</saml2:AttributeStatement>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Sample subject attribute in the assertion looks as shown below:

<saml2:Subject>
    <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">John</saml2:NameID>
    <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <saml2:SubjectConfirmationData InResponseTo="jimhbeljflkppacldhnjcfjkhoobkddhngnkamom"
                                        NotOnOrAfter="2021-08-30T09:49:21.336Z"
                                        Recipient="http://localhost:8081/sample-app/home.jsp"
                                        />
    </saml2:SubjectConfirmation>
</saml2:Subject>
1
2
3
4
5
6
7
8
9

# Map groups with Asgardeo

# Configure External Connection's Group attribute

Follow the steps below to map the groups attribute of your connection with Asgardeo:

  1. On the Asgardeo Console, go to Connections.
  2. Select your connection and go to its Attributes tab.
  3. Click Add Attribute Mapping to add a new attribute mapping. Add attribute mappings
  4. Enter the External IdP Attribute of the connection and map it to the Groups attribute of Asgardeo. Add new group attribute mapping
  5. Click Add Attribute Mapping and then click Save. Stage new group attribute mapping
  6. Click Update to save the changes. Submit attribute mappings

# Add groups to connections

Follow the steps below to add the groups from your connection to Asgardeo:

  1. On the Asgardeo Console, go to Connections.
  2. Select your connection and go to its Groups tab.
  3. Click New Group and enter the group name. Be sure to enter the exact group name that will be returned from the connection. Add group
  4. Click Finish to add the group information.

# Delete a connection

Before you begin

If your connection has applications associated with it, you will not be able to delete the connection.


Before deleting such connections:
  1. Check the associated applications from the Connected Apps tab of the connection.
  2. Click on an application that uses the connection and you will be redirected to the Sign-in Method tab of the respective application.
  3. Remove the connection from the sign-in flow of the associated applications.
  4. Repeat steps 2 and 3 for all listed applications.
  5. Proceed to delete the connection.

To delete a connection that does not have any applications using it:

  1. On the Asgardeo Console, go to Connections.

  2. Click Set up and navigate to the General tab.

  3. At the bottom of the page, click the button in the Delete connection.

    You cannot delete connections that are available by default.

  4. Select the checkbox and confirm your action.

    Delete connection