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 Develop > 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 Protocol tab.

# Enable the SAML IdP for login

Before you begin

You need to have an application registered in Asgardeo. If you don't already have one, register one of the following application types:

  1. On the Asgardeo console, click Develop > Applications.

  2. Open your application from the list and go to the Sign-in Method tab.

  3. If you haven't already defined a sign-in flow, click Start with Default configuration to get started.

  4. Click Add Authentication on the step, select your SAML identity provider, and click Add.

    Add SAML IdP login in Asgardeo

# 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 Develop > 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

    To configure a different attribute as the subject, first you need to enable the Find user ID from requests setting for SAML IdP. If this setting is not enabled, Asgardeo uses the subject attribute that is sent by the external 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