SAML FAQ (Frequently Asked Questions)

This FAQ is based on my experience in working with SAML protocol. I will keep updating this FAQ.

What is SAML?

SAML (Security Assertion Markup Language) is one of the most widely used Identity Federation protocol. SAML standard defines an XML-based framework for describing and exchanging security information between on-line business partners. This security information is expressed in the form of portable SAML assertions that applications working across security domain boundaries can trust. The OASIS SAML standard defines precise syntax and rules for requesting, creating, communicating, and using these SAML assertions.

Where can I find the official SAML protocol documentation?

Acknowledgments

Who are the main actors in SAML?

There are two main actors in SAML — Identity Provider (IdP) and Service Provider (SP)

What is IdP?

Identity Provider (IdP) role is to assert the identity of the user i.e. authenticate the user and generate a SAML Assertion that will be posted to the Service Provider.

Examples of IdP :

• If an airline website allows sign-in using GMail account, GMail is the Identity Provider.
• Commercial identity products : Okta, AzureAD, ForgeRock OpenAM, PingFederate etc.

What is SP?

Service Provider (SP) will receive the assertion from an Identity Provider (IdP), perform certain validations and allow the user to access the resources that are hosted in the SP.

Examples:

• If an airline website allows sign-in using GMail account, airline website is the Service Provider and GMail is the Identity Provider.
• If a user logs into Airlines website and then launch a Hotel booking website from the airlines website, Airlines website is the Identity Provider and Hotel booking website is the Service Provider

What is SAML Metadata?

SAML Metadata defines a way to express and share configuration information between SAML parties. For instance, an entity’s supported SAML bindings, operational roles (IDP, SP, etc), identifier information, supporting identity attributes, and key information for encryption and signing can be expressed using SAML metadata XML documents.

What is the IdP metadata?

IdP metadata contains the configuration details related to the Identity Provider. This metadata file will be used by SP to setup the federation with IdP. Some of the key elements / attributes in IdP metadata are :

• entityID : This is the unique identifier for this IdP. A SP can have multiple IdP configurations and each IdP should have a unique entityID
• IDPSSODescriptor : The presence of this element in a metadata xml indicates it is a IdP metadata.
• KeyDescriptor : Public key in X509 format. This key will be used by the SP to verify the signature of the Assertion message posted by IdP.
• SingleSignOnService : This is the login URL for this IdP. SP will perform a browser redirect to his URL with a SAML Authentication Request when a user tries to access a protected resource.

Below are the key elements in a IdP Metadata. There are other optional elements which is not shown here.

<EntityDescriptor
    xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
    entityID="https://idp.example.com">
    <IDPSSODescriptor>
        <KeyDescriptor use="signing" />
        <SingleSignOnService />
    </IDPSSODescriptor>
</EntityDescriptor>

What is SP Metadata?

SP metadata contains the configuration details related to the Service Provider. This metadata file will be used by IdP to setup the federation with SP. Some of the key elements / attributes in IdP metadata are :

• entityID : This is the unique identifier for this SP. A IdP can have multiple SP configurations and each SP should have a unique entityID
• SPSSODescriptor : The presence of this element in a metadata xml indicates it is a SP metadata.
• AssertionConsumerService : This is the URL where IdP will post a SAML Assertion after successful user authentication.

<md:EntityDescriptor entityID="https://sp.example.com" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
    <md:SPSSODescriptor>
        <md:AssertionConsumerService />
    </md:SPSSODescriptor>
</md:EntityDescriptor>

What is entityID attribute in SAML Metadata?

entityID uniquely identifies a SP or IdP. A SP can have federation integrations with multiple IdP and vice-versa.

For ex: An employee in an organization can access a Timesheet app, Payroll app etc. The entityID of timesheet app can be timesheet.orga.com and payroll app can be payroll.orga.com. Depending on the app that user is trying to access, IdP will load the configurations related to that app and redirect the user to SP after authentication. SP will identify the IdP using IdP’s entity ID ex: idp.orga.com.

How is a federation established between SP and IdP?

When a SP and IdP wants to setup SAML federation, the metadata files will be exchanged between teams managing the SP and IdP. This can be done through emails or by exposing the metadata file in a publicly accessible URL. SP and IdP can then make the necessary configurations using the Metadata.

Many commercial identity products like Ping, Azure AD, Okta etc. might have a Admin UI to directly import the metadata xml file. That should automatically configure most of the basic things and an Administrator might have to perform some advanced configuration steps.

What is SP-Initiated SSO?

In a SP-Initiated SSO, the user attempts to access a resource on the SP, sp.example.com. If the user don’t have a current logon session on this site, SP will redirect the user to the IdP with a SAML Authentication Request. On successful authentication, IdP will post a SAML Assertion for the user’s identity back to the SP. SAML Authentication Request and Assertion are XML messages.

For ex: User tries to access SP https://airline.example.com. If there is no active session, SP will redirect to IdP https://idp.example.com which will then show the login page. Once the authentication is successful, IdP will post a SAML Assertion back to SP. SP will validate the SAML Assertion, create a session and allow the user to access the website.

What is IdP-Initiated SSO?

In an IdP-initiated SSO, the identity provider is configured with special links that refer to SPs that user has access to. So instead of visiting the SP directly, the user accesses the IdP site and clicks on one of the links to gain access to the remote SP. This triggers the creation of a SAML Assertion that will be transported to the service provider using the browser.

An IdP-Initiated SSO won’t have a Authentication Request since the flow starts from the IdP side. It is also called as “Unsolicited SSO” and considered less secure as per OWASP.

What is a SAML Authentication Request?

When a user tries to access the Service Provider, SP performs a browser redirect to the Identity Provider by posting a SAML Authentication request. SAML Authentication request is a XML message.

IdP recognizes the SP using the <saml:Issuer> value which is same as SP entityID.

Example :

<samlp:AuthnRequest
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"    ID="YeFm4BTYEW7I0YO" Version="2.0" IssueInstant="2021-08-05T09:21:59Z"
AssertionConsumerServiceIndex="1">
    <saml:Issuer>https://sp.example.com/SAML2</saml:Issuer>
    <samlp:NameIDPolicy AllowCreate="true" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient"/>
</samlp:AuthnRequest>

What is SAML Assertion?

If user authentication is successful, IdP will perform a browser redirect to SP and post a SAML Assertion. A SAML Assertion is a XML message that contains some common information about the identity provider, a signature and authenticated user attributes like first name, last name, email etc.

Basic structure of a SAML XML :

<samlp:Response>
    <saml:Issuer />
    <Signature
        xmlns="http://www.w3.org/2000/09/xmldsig#" />
        <samlp:Status />
        <saml:Assertion
            xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
            <saml:Subject />
            <saml:Conditions/>
            <saml:AttributeStatement>
                <saml:Attribute />
                <saml:Attribute />
            </saml:AttributeStatement>
        </saml:Assertion>
</samlp:Response>

What is <saml:Issuer> element in SAML Assertion?

The value of <saml:Issuer> element is the IdP “Entity ID” and it is a unique identifier for the IdP. A SP can have multiple IdP configurations. When a SAML Assertion is posted by the IdP, SP can validate the assertion using the settings configured for that particular IdP “Entity ID”.

For ex: A Gmail login using SAML Federation can have a <saml:Issuer>www.google.com</saml:Issuer>. If the SP supports GMail login, it should have a configuration specific to “www.google.com” entityID.

What is <signature> element in SAML Assertion?

IdP will sign the assertion using a private key and add this value in <signature> element of SAML Assertion. SP can verify the signature using the corresponding public key. Signature validation makes sure that the message is not tampered. It also confirms the fact that this message is signed by a trusted IdP.

Sometimes a signature element can be present inside the <saml:Assertion> element rather than the <samlp:Response> element. It depends on what was agreed between the SP and IdP during the federation setup process.

• Signed response: In this case, the entire authentication response is signed.
• Signed assertions: In this case, the attribute statement within the response is signed.

What is <saml:Subject> element?

This element holds the unique identifier of the authenticated user. This can be a GUID, employee ID or some other value that doesn’t change. Since SP uses this identifier to associate a IdP user with a SP profile, it is always recommended to use a immutable value. Some IdPs send email address in this element. The problem with email address is that it can change.

Example:

<saml:Subject>
     <saml:NameID
       Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">
       3f7b3dcf-1674-4ecd-92c8-1544f346baf8
     </saml:NameID>
 </saml:Subject>

What is <saml:Conditions> element?

This element contains certain attributes for validating the SAML Assertion.

• NotBefore & NotOnOrAfter : This is a DateTime value. SP should compare the current time with these values to make sure Assertion is still valid. If the current time falls outside this range, SP should reject that Assertion and fail the transaction.
• Audience : This is a child element of <saml:Conditions> / <saml:AudienceRestriction element. The value of this element should match with the SP entityID. What it means is that this Assertion is meant for a specific SP. SP should make sure this value matches with its own entityID. Otherwise, it should fail the transaction.

Example:

<saml:Conditions NotBefore="2021-10-29T20:29:23.888Z"
                         NotOnOrAfter="2021-10-29T20:39:23.888Z"
                         >
            <saml:AudienceRestriction>
                <saml:Audience>sp.example.com</saml:Audience>
            </saml:AudienceRestriction>
</saml:Conditions>

What is <saml:AttributeStatement> and <saml:Attribute>?

These elements contain different attribute values like name, first name, last name, email etc. When a federation is setup between SP and IdP, both teams should agree on the list of attributes that SP needs from the IdP. Whenever any user is authenticated, IdP will include all those attributes in the SAML Assertion posted to the SP. It is recommended to not send any sensitive attributes like passwords, keys, mfa factors etc. as part of SAML Assertion because a SAML Assertion is posted through a browser and there is always a risk of someone stealing the data.

Example:

<saml:AttributeStatement>
      <saml:Attribute Name="name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">John</saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name="mail" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">jdoe@example.com</saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name="department" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">DEP1</saml:AttributeValue>
      </saml:Attribute>
</saml:AttributeStatement>