Reloading SAML: Web Browser SSO Profile

So far I have discussed key constructs of SAML 2.0 core standard and few supportive standards such as IDP Discovery and SAML Metadata too. Starting from this post, I’m planning to discuss SAML Profiles, if I recall our discussion about SAML profiles, profiles are practical use-cases defined in terms of basic SAML constructs such as Assertions, Bindings and Protocols. In this post, I will discuss ‘Web Browser SSO Profile’, which is one of the widely used SAML profile. In Web Browser SSO profile, a user access a SP via a web browser, the presence of a web browser is mandatory.

Before we discuss further, I would like to provide you the following fact sheet about Web Browser SSO Profile.

Depend on the direction of the message flows it’s possible to divide this profile as SP initiated SSO, and IdP initiated SSO.

SP-initiated SSO vs IdP-initiated SSO

SP-initiated SSO vs IdP-initiated SSO

In SP-initiated Web Browser SSO approach, the user first access the login page or restricted resource within the SP, this approach usually consists of the following 3 steps.

1. The user first access the login page or restricted resource within the SP.
2. The SP redirects the user to the IdP with a SAML authentication request.
3. IdP authenticates the user and returns the user with a valid SAML assertion or error message.

In IdP-initiated Web Browser SSO approach, the user first access the IdP and once the authentication is successful IdP redirects the user to the SP. This approach usually consists of the following 2 steps.

1. The user first access the login page within the IdP, the IdP authenticate the user.
2. User clicks a link within the IdP which redirect the user to the specific SP with a valid SAML assertion.

SP and IdP endpoints

SP and IdP endpoints

If we leave HTTP Artifact binding for a while, this profile mainly assumes the availability of two network endpoints, one at the IdP and another one at the SP.

Single Sign-on Service — This is a network endpoint exposed by the IdP, the SP suppose to send SAML authentication requests to this endpoint via HTTP GET or POST. According to SAML specification, this endpoint needed to be secured using the latest TLS security.

Assertion consumer Service — This is a network endpoint exposed by the SP, the IdP suppose to send SAML response messages to this endpoint via HTTP POST. According to SAML specification, this endpoint also needed to be secured using the latest TLS security.

SP-initiated Web Browser SSO

As we have seen in the above section SP-initiated approach consists with 3 steps, but the very first step that is the user access the SP via a browser is out of the scope of our discussion (however usually we can assume that the user type SP URL in the browser or click a bookmark to reach the SP) During the step 2 and 3 it’s required to transport SAML messages from SP to IdP and IdP to SP, to achieve that one of the following SAML binding combinations can be used.

This is according to the SAML conformance specification from here https://www.oasis-open.org/committees/download.php/8753/sstc-saml-conformance-2.0-draft-06-diff.pdf

During the next few sections we will look at some of the above combinations in detail.

SP-initiated Redirect — POST

The above diagram depicts SP-initiated Redirect — POST approach with exact message structures, however, I use the following sequence diagram to further explain this approach.

1. In the initial step the user tries to access a secure resource/page at the SP, usually through a HTTP GET request from the browser to the SP.
2. As the 2nd step, the SP determines the correct IdP associated with the current user. The mechanism used to determine the correct IdP is implementation-specific, one possible option is the IdP Discovery mechanism that we discussed in a previous post.
3. Once the SP decides the correct IdP it generates a SAML authentication request. To generate this request SP needs some level of information about the IdP such as unique identifiers, public certificates, supported binding and SSO service location etc. the SP should able to find these details using proprietary approach such as reading a configuration file or standard approach such as IdP Metadata specification.
4. Once the SP generate a proper SAML authentication request, it returns a HTTP redirect ( 302) message back to the browser with a URL of the SSO service endpoint of the IdP. URL encoded SAML request is appended to the above redirect URL as the value of “SAMLRequest” query string parameter, optionally it is possible to have “RelayState” query string parameter. You can read further details about this point from one of my previous post about SAML Bindings.
5. The browser follows the redirect message and issue a HTTP GET request to the SSO service endpoint of the IdP, note that this URL contains the encoded SAML request along with RelayState.
6. At the IdP once it receives the above SAML request, it checks whether an active authentication context exists for the current user or not, if not the IdP try to authenticate the current user based on its configuration, usually this can result into several back-and-forth interactions with the user. Once the IdP completed the authentication and creation of user session, it generates a SAML response which contains one or more SAML assertions about the authenticated user.
7. As the next step IdP generate a HTML form control with SAML response and return to the browser. You can read further details about this point from one of my previous post about SAML Binding.
8. At the browser, it submits the received HTML Form to the ACL URL of the SP.
9. At the SP, it read the SAML response message and decide to grant the access.

Note that the HTML form mentioned in the above step 7 consists of following HTML form controls.

• SAML Response — The encode SAML Response is set as the value of hidden HTML input control called “SAMLResponse”
• RelayState — The original value received as RelayState is set as the value of hidden HTML input control called “RelayState”
• SP’s ACL URL — ACL URL of the SP is set as the action of the HTML form control.
• A script (e.g — Javascript) that will auto-submit the above HTML Form at the browser to the SP.

SP-initiated POST — POST

The above diagrams illustrate the exact message flows under SP-initiated POST — POST approach.

1. In the very first step the user tries to access a secure resource/page at the SP, usually through a HTTP GET request from the browser to the SP.
2. As the 2nd step, the SP determines the correct IdP associated with the current user. The mechanism used to determine the correct IdP is implementation-specific, one possible option is the IdP Discovery mechanism that we discussed in a previous post.
3. Once the SP decides the correct IdP it generates a SAML authentication request. To generate this request message SP need some level of information about the IdP such as unique identifiers, public certificates, supported binding and SSO service location etc. the SP should able to find these details using a proprietary approach such as reading a configuration file or standard approach such as IdP Metadata specification.
4. Once the SP generates a proper SAML authentication request, it retunes a HTTP 200 message back to the browser with a HTML Form plus a script that can be used to submit this HTML form the SSO service endpoint of the IdP. Generated SAML request is encoded as the value of hidden input control named “SAMLRequest”, You can read further details about this point from one of my previous post about SAML Bindings.
5. Upon the receiving of above HTTP message from SP, IdP submits the HTML Form to the IdP by executing the script.
6. At the IdP once it receives the above SAML request, it checks whether an active authentication context exists for the current user or not, if not IdP try to authenticate the current user based on its configuration, usually this can result into several back-and-forth interactions with the user. Once the IdP completed the authentication and creation of user session, it generates a SAML response which contains one or more SAML assertions about the authenticated user.
7. As the next step IdP generate a HTML form control with SAML response and returns to the browser. You can read further details about this point from one of my previous post about SAML Binding.
8. At the browser, it submits the received HTML Form to the ACL URL of the SP.
9. At the SP, it read the SAML response message and decide to grant the access or not.

Note that the HTML form mentioned in the above step 7 consists of following HTML form controls.

• SAML Response — The encode SAML Response is set as the value of hidden HTML input control called “SAMLResponse”
• RelayState — The original value received as RelayState is set as the value of hidden HTML input control called “RelayState”
• SP’s ACL URL — ACL URL of the SP is set as the action of the HTML form control.
• A script (e.g — Javascript) that will auto-submit the above HTML Form at the browser to the SP.

IdP-initiated Web Browser SSO

Like in IdP-initiated case, the very first iteration, that is the very first user interaction with the IdP is out of the scope of our discussion, for the 2nd step, that is to transmit SAML response from IdP to SP one of the following binding option can be used.

This is according to the SAML conformance specification from here https://www.oasis-open.org/committees/download.php/8753/sstc-saml-conformance-2.0-draft-06-diff.pdf

Following diagrams illustrates exact message flows under this approach.

Anatomy of Authentication Request & Response

In this section let’s discuss the structure of authentication request and response, first, let’s start with the authentication request.

Generally <AuthnRequest> is a signed message and depended on requirements it is possible to encrypt as well. The following section, you can find short descriptions about each and every attribute and element supported by AuthRequest message.

Attributes

• ID — This is a mandatory attribute and represents a unique identifier of the current message. The value of this attribute is used as the value of “InResponseTo” attribute of the response message for the purpose of message correlating.
• Version — A mandatory attribute represents the version of SAML specification, the current value should be “2.0”
• IssueInstant — A mandatory attribute represents, the value should UTC value of the time instance.
• Destination — An optional attribute that represents the URI reference indicating the address to which this request has been sent.
• Consent — Indicate whether the consent is obtained from the user in order to send this request message, the following are possible URI values.

1. urn:oasis:names:tc:SAML:2.0:consent:unspecified — No claim as to principal consent is being made

2. urn:oasis:names:tc:SAML:2.0:consent:obtained — The consent has been obtained by the issuer.

3. urn:oasis:names:tc:SAML:2.0:consent:prior — The consent has been obtained by the issuer at some prior point.

4. urn:oasis:names:tc:SAML:2.0:consent:current-implicit — The consent has been implicitly obtained by the issuer during the action that initiated the message.

5. urn:oasis:names:tc:SAML:2.0:consent:current-explicit — The consent has been explicitly obtained by the issuer during the action that initiated the message.

6. urn:oasis:names:tc:SAML:2.0:consent:unavailable — The issuer did not obtain consent.

7. urn:oasis:names:tc:SAML:2.0:consent:inapplicable — The issuer does not believe that they need to obtain consent

• ForceAuthn — If the value is ‘true’ the IdP should authenticate the user directly rather than rely on a previous security context, the default value is ‘false’.
• IsPassive — If the value is ‘true’ then the IdP and the browser itself MUST NOT visibly take control of the user interface from the requester and interact with the user in a noticeable fashion.
• AssertionConsumerServiceURL — Specifies by value the location to which the <Response> message MUST be returned to the requester.
• AttributeConsumingServiceIndex — Indirectly identifies information associated with the requester describing the SAML attributes the requester desires or requires to be supplied by the identity provider in the <Response> message
• AssertionConsumerServiceIndex — Indirectly identifies the location to which the <Response> message should be returned to the requester.
• ProtocolBinding — A URI reference that identifies a SAML protocol binding to be used when returning the <Response> message.
• ProviderName — Specifies the human-readable name of the requester for use by the presenter’s user agent or the IdP.

Elements

• <saml:Issuer> — Identifies the entity that generated the request message.
• <ds:Signature> — An XML Signature that authenticates the requester and provides message integrity.
• <saml:Subject> — Specifies the requested subject of the resulting assertion.
• <NameIDPolicy> — Specifies constraints on the name identifier to be used to represent the requested subject. If omitted, then any type of identifier supported by the identity provider for the requested subject can be used.
• <saml:Conditions> — Specifies the SAML conditions the requester expects to limit the validity and/or use of the resulting assertion.
• <RequestedAuthnContext> — Specifies the requirements, if any, that the requester places on the authentication context that applies to the responding provider’s authentication of the user, I will discuss this matter in a separate post.

Here is the structure of a typical SAML authentication request message.

Generally, the Response message is a signed message and depended on the requirements it is possible to encrypt the whole message or part of the message as well. In the next section, you can find short descriptions about each and every attribute and element available on AuthRequest message.

Attributes

• ID — This is a mandatory attribute and represents a unique identifier of the current message.
• InResponseTo — The value of the ‘ID’ attribute of the associated <AuthnRequest> message.
• Version — A mandatory attribute represents the version of SAML specification, the current value should be “2.0”
• IssueInstant — A mandatory attribute represents, the value should UTC value of the time instance.
• Destination — An optional attribute that represents the URI reference indicating the address to which this request has been sent.
• Consent — Indicate whether the consent is obtained from the user in order to send this request message, the following are possible URI values.

1. urn:oasis:names:tc:SAML:2.0:consent:unspecified — No claim as to principal consent is being made

2. urn:oasis:names:tc:SAML:2.0:consent:obtained — The consent has been obtained by the issuer.

3. urn:oasis:names:tc:SAML:2.0:consent:prior — The consent has been obtained by the issuer at some prior point.

4. urn:oasis:names:tc:SAML:2.0:consent:current-implicit — The consent has been implicitly obtained by the issuer during the action that initiated the message.

5. urn:oasis:names:tc:SAML:2.0:consent:current-explicit — The consent has been explicitly obtained by the issuer during the action that initiated the message.

6. urn:oasis:names:tc:SAML:2.0:consent:unavailable — The issuer did not obtain consent.

7. urn:oasis:names:tc:SAML:2.0:consent:inapplicable — The issuer does not believe that they need to obtain consent

Elements

• <saml:Issuer> — Identifies the entity that generated the request message.
• <ds:Signature> — An XML Signature that authenticates the requester and provides message integrity.
• <Status> — A code representing the status of the corresponding request.
• <saml:Assertion> OR <saml:EncryptedAssertion> — Specifies an assertion by value, or optionally an encrypted assertion by value.

SP and IdP configuration

Up to now, you have a better understanding about message formats, exact interactions among various roles etc. but in order to make it possible these interactions there should be an understanding between the SP and the IdP about each other, basically each party should know some kind of knowledge about the other party. Generally following configuration details needed to be shared by one party with the other.

1. Entity Id
2. Issuer
3. Assertion consumer service URL/ SSO service URL
4. Public certificate
5. Message level security options such as singing, encryption
6. Supported SAML profiles such as SLO, attribute profiles etc.
7. Signing and encryption algorithm details

There are two widely used options available to provide the above information.

1. Using a proprietary UI or API

Provide configuration data related to the other party using a proprietary UI or API provided by the IdP/the SP. As this is not a standard-based approach an identity administrator is supposed to go through the SP/IdP configuration guide to figure out exact procedure, additionally manually proving each and every input value can be error-prone as well.

Proprietary configuration UI from Salesforce SP

Proprietary configuration UI from WSO2 IS IdP

2. Using SAML Metadata

Provide configuration data related to the other party as a SAML Metadata is the other option, compared to the previous approach this is a more easiest and efficient approach. An identity administrator can download metadata specification from other party and can use with own configuration, this metadata specification consists of all the required configuration data about a SAML entity. Today almost all the IdP vendors and providers are supported for SAML Metadata.

Following diagram illustrate sample SAML metadata description generated by Salesforce SP.

Following diagram illustrate sample SAML metadata description generated by WSO2IS IdP.

RealyState

First, consider the following two practical scenarios,

• The user requests a specific secured page/video/resource at the SP, in order to provide better user experience the SP suppose to return the originally requested page/video/resource back to the user after successful SAML message exchange with the IdP.
• The SP can decide to re-authenticate the user via the IdP at the middle of a transaction, in such cases, it’s required to restore the original transaction context after successful authentication.

In both of the above cases, the SP suppose to persist current state before it contacts the IdP, and it should restore the state after receiving the SAML assertion from the IdP. SAML provides a special parameter called “RealyState” to fulfil this requirement, SP can persist its local state and pass an opaque reference token to the IdP along with SAML authentication request either as a query string parameter or as a HTML has hidden input control deepening on underline SAML Binding. In both cases, the name of the parameter/HTML control should be RealyState. Once the IdP receives this RealyState it must return this original value back to the SP along with SAML response.