An assertion is a package of information that supplies zero or more statements made by a SAML authority. SAML assertions are usually made about a subject, represented by the <Subject> element. The SAML 2.0 specification defines three different kinds of assertion statements that can be created by a SAML authority. All SAML-defined statements are associated with a subject. The three kinds of assertion statements defined are as follows:
An important type of SAML assertion is the so-called "bearer" assertion used to facilitate Web Browser SSO. Here is an example of a short-lived bearer assertion issued by an identity provider (https://idp.example.org/SAML2) to a service provider (https://sp.example.com/SAML2). The assertion includes both an Authentication Assertion <saml:AuthnStatement> and an Attribute Assertion <saml:AttributeStatement>, which presumably the service provider uses to make an access control decision. The prefix saml: represents the SAML V2.0 assertion namespace.
Note that in the above example the <saml:Assertion> element contains the following child elements:
In words, the assertion encodes the following information:
The assertion ("b07b804c-7c29-ea16-7300-4f3d6f7928ac") was issued at time "2004-12-05T09:22:05Z" by identity provider (https://idp.example.org/SAML2) regarding subject (3f7b3dcf-1674-4ecd-92c8-1544f346baf8) exclusively for service provider (https://sp.example.com/SAML2).
The authentication statement, in particular, asserts the following:
The principal identified in the <saml:Subject> element was authenticated at time "2004-12-05T09:22:00Z" by means of a password sent over a protected channel.
Likewise the attribute statement asserts that:
The principal identified in the <saml:Subject> element has the 'staff' and 'member' attributes at this institution.
The following protocols are specified in SAMLCore:5
The most important of these protocols—the Authentication Request Protocol—is discussed in detail below.
In SAML 1.1 Web Browser SSO Profiles are initiated by the Identity Provider (IDP), that is, an unsolicited <samlp:Response> element is transmitted from the identity provider to the service provider (via the browser). (The prefix samlp: denotes the SAML protocol namespace.)
In SAML 2.0, however, the flow begins at the service provider who issues an explicit authentication request to the identity provider. The resulting Authentication Request Protocol is a significant new feature of SAML 2.0.
When a principal (or an entity acting on the principal's behalf) wishes to obtain an assertion containing an authentication statement, a <samlp:AuthnRequest> element is transmitted to the identity provider:
The above <samlp:AuthnRequest> element, which implicitly requests an assertion containing an authentication statement, was evidently issued by a service provider (https://sp.example.com/SAML2) and subsequently presented to the identity provider (via the browser). The identity provider authenticates the principal (if necessary) and issues an authentication response, which is transmitted back to the service provider (again via the browser).
A SAML message is transmitted from one entity to another either by value or by reference. A reference to a SAML message is called an artifact. The receiver of an artifact resolves the reference by sending a <samlp:ArtifactResolve> request directly to the issuer of the artifact, who then responds with the actual message referenced by the artifact.
Suppose, for example, that an identity provider sends the following <samlp:ArtifactResolve> request directly to a service provider (via a back channel):
In response, the service provider returns the SAML element referenced by the enclosed artifact. This protocol forms the basis of the HTTP Artifact Binding.
The bindings supported by SAML 2.0 are outlined in the Bindings specification (SAMLBind6):
For Web Browser SSO, the HTTP Redirect Binding and the HTTP POST Binding are commonly used. For example, the service provider may use HTTP Redirect to send a request while the identity provider uses HTTP POST to transmit the response. This example illustrates that an entity's choice of binding is independent of its partner's choice of binding.
SAML protocol messages can be carried directly in the URL query string of an HTTP GET request. Since the length of URLs is limited in practice, the HTTP Redirect binding is suitable for short messages, such as the <samlp:AuthnRequest> message. Longer messages (e.g. those containing signed or encrypted SAML assertions, such as SAML Responses) are usually transmitted via other bindings such as the HTTP POST Binding.
SAML requests or responses transmitted via HTTP Redirect have a SAMLRequest or SAMLResponse query string parameter, respectively. Before it's sent, the message is deflated (without header and checksum), base64-encoded, and URL-encoded, in that order. Upon receipt, the process is reversed to recover the original message.
For example, encoding the <samlp:AuthnRequest> message above yields:
The above message (formatted for readability) may be signed for additional security. In practice, all the data contained in a <samlp:AuthnRequest>, such as Issuer which contains the SP ID, and NameIDPolicy, has been agreed between IdP and SP beforehand (via manual information exchange or via SAML metadata). In that case signing the request is not a security constraint. When the <samlp:AuthnRequest> contains information not known by the IdP beforehand, such as Assertion Consumer Service URL, signing the request is recommended for security purposes.
In the following example, both the service provider and the identity provider use an HTTP POST binding. Initially, the service provider responds to a request from the user agent with a document containing an XHTML form:
The value of the SAMLRequest parameter is the base64-encoding of a <samlp:AuthnRequest> element, which is transmitted to the identity provider via the browser. The SSO service at the identity provider validates the request and responds with a document containing another XHTML form:
The value of the SAMLResponse parameter is the base64 encoding of a <samlp:Response> element, which likewise is transmitted to the service provider via the browser.
To automate the submission of the form, the following line of JavaScript may appear anywhere on the XHTML page:
This assumes, of course, that the first form element in the page contains the above SAMLResponse containing form element (forms[0]).
The HTTP Artifact Binding uses the Artifact Resolution Protocol and the SAML SOAP Binding (over HTTP) to resolve a SAML message by reference. Consider the following specific example. Suppose a service provider wants to send a <samlp:AuthnRequest> message to an identity provider. Initially, the service provider transmits an artifact to the identity provider via an HTTP redirect:
Next the identity provider sends a <samlp:ArtifactResolve> request (such as the ArtifactResolveRequest shown earlier) directly to the service provider via a back channel. Finally, the service provider returns a <samlp:ArtifactResponse> element containing the referenced <samlp:AuthnRequest> message:
Of course the flow can go in the other direction as well, that is, the identity provider may issue an artifact, and in fact this is more common. See, for example, the "double artifact" profile example later in this topic.
In general, a SAML 2.0 artifact is defined as follows (SAMLBind7):
Thus a SAML 2.0 artifact consists of three components: a two-byte TypeCode, a two-byte EndpointIndex, and an arbitrary sequence of bytes called the RemainingArtifact. These three pieces of information are concatenated and base64-encoded to yield the complete artifact.
The TypeCode uniquely identifies the artifact format. SAML 2.0 predefines just one such artifact, of type 0x0004. The EndpointIndex is a reference to a particular artifact resolution endpoint managed by the artifact issuer (which may be either the IdP or the SP, as mentioned earlier). The RemainingArtifact, which is determined by the type definition, is the "meat" of the artifact.
The format of a type 0x0004 artifact is further defined as follows:
Thus a type 0x0004 artifact is of size 44 bytes (unencoded). The SourceId is an arbitrary sequence of bytes, although in practice, the SourceId is the SHA-1 hash of the issuer's entityID. The MessageHandle is a random sequence of bytes that references a SAML message that the artifact issuer is willing to produce on-demand.
For example, consider this hex-encoded type 0x0004 artifact:
If you look closely, you can see the TypeCode (0x0004) and the EndpointIndex (0x0000) at the front of the artifact. The next 20 bytes are the SHA-1 hash of the issuer's entityID (https://idp.example.org/SAML2) followed by 20 random bytes. The base64-encoding of these 44 bytes is what you see in the ArtifactResolveRequest example above.
In SAML 2.0, as in SAML 1.1, the primary use case is still Web Browser SSO, but the scope of SAML 2.0 is broader than previous versions of SAML, as suggested in the following exhaustive list of profiles:
Although the number of supported profiles is quite large, the Profiles specification (SAMLProf8) is simplified since the binding aspects of each profile have been factored out into a separate Bindings specification (SAMLBind9).
SAML 2.0 specifies a Web Browser SSO Profile involving an identity provider (IdP), a service provider (SP), and a principal wielding an HTTP user agent. The service provider has four bindings from which to choose while the identity provider has three, which leads to twelve possible deployment scenarios. We outline three of those deployment scenarios below.
This is one of the most common scenarios. The service provider sends a SAML Request to the IdP SSO Service using the HTTP-Redirect Binding. The identity provider returns the SAML Response to the SP Assertion Consumer Service using the HTTP-POST Binding.
The message flow begins with a request for a secured resource at the service provider.
1. Request the target resource at the SP
The principal (via an HTTP user agent) requests a target resource at the service provider:
The service provider performs a security check on behalf of the target resource. If a valid security context at the service provider already exists, skip steps 2–7.
The service provider may use any kind of mechanism to discover the identity provider that will be used, e.g., ask the user, use a preconfigured IdP, etc.
2. Redirect to IdP SSO Service
The service provider generates an appropriate SAMLRequest (and RelayState, if any), then redirects the browser to the IdP SSO Service using a standard HTTP 302 redirect.
The RelayState token is an opaque reference to state information maintained at the service provider. The value of the SAMLRequest parameter is a deflated, base64-encoded and URL-encoded value of an <samlp:AuthnRequest> element:
The SAMLRequest may be signed using the SP signing key. Typically, however, this is not necessary.
3. Request the SSO Service at the IdP
The user agent issues a GET request to the SSO service at the identity provider:
where the values of the SAMLRequest and RelayState parameters are the same as those provided in the redirect. The SSO Service at the identity provider processes the <samlp:AuthnRequest> element (by URL-decoding, base64-decoding and inflating the request, in that order) and performs a security check. If the user does not have a valid security context, the identity provider identifies the user with any mechanism (details omitted).
4. Respond with an XHTML form
The SSO Service validates the request and responds with a document containing an XHTML form:
The value of the RelayState parameter has been preserved from step 3. The value of the SAMLResponse parameter is the base64 encoding of the following <samlp:Response> element:
5. Request the Assertion Consumer Service at the SP
The user agent issues a POST request to the Assertion Consumer Service at the service provider:
where the values of the SAMLResponse and RelayState parameters are taken from the XHTML form at step 4.
6. Redirect to the target resource
The assertion consumer service processes the response, creates a security context at the service provider and redirects the user agent to the target resource.
7. Request the target resource at the SP again
The user agent requests the target resource at the service provider (again):
8. Respond with requested resource
Since a security context exists, the service provider returns the resource to the user agent.
This is a relatively simple deployment of the SAML 2.0 Web Browser SSO Profile (SAMLProf10) where both the service provider (SP) and the identity provider (IdP) use the HTTP POST binding.
The message flow begins with a request for a secured resource at the SP.
2. Respond with an XHTML form
The service provider responds with a document containing an XHTML form:
The RelayState token is an opaque reference to state information maintained at the service provider. The value of the SAMLRequest parameter is the base64 encoding of the following <samlp:AuthnRequest> element:
Before the <samlp:AuthnRequest> element is inserted into the XHTML form, it is first base64-encoded.
The user agent issues a POST request to the SSO service at the identity provider:
where the values of the SAMLRequest and RelayState parameters are taken from the XHTML form at step 2. The SSO service processes the <samlp:AuthnRequest> element (by URL-decoding, base64-decoding and inflating the request, in that order) and performs a security check. If the user does not have a valid security context, the identity provider identifies the user (details omitted).
The SSO service validates the request and responds with a document containing an XHTML form:
The user agent issues a POST request to the assertion consumer service at the service provider:
This is a complex deployment of the SAML 2.0 Web Browser SSO Profile (SAMLProf11) where both the service provider (SP) and the identity provider (IdP) use the HTTP Artifact binding. Both artifacts are delivered to their respective endpoints via HTTP GET.
The message flow begins with a request for a secured resource at the SP:
The service provider performs a security check on behalf of the target resource. If a valid security context at the service provider already exists, skip steps 2–11.
2. Redirect to the Single Sign-on (SSO) Service at the IdP
The service provider redirects the user agent to the single sign-on (SSO) service at the identity provider. A RelayState parameter and a SAMLart parameter are appended to the redirect URL.
The user agent requests the SSO service at the identity provider:
where token is an opaque reference to state information maintained at the service provider and artifact_1 is a SAML artifact, both issued at step 2.
4. Request the Artifact Resolution Service at the SP
The SSO service dereferences the artifact by sending a <samlp:ArtifactResolve> element bound to a SAML SOAP message to the artifact resolution service at the service provider:
where the value of the <samlp:Artifact> element is the SAML artifact transmitted at step 3.
5. Respond with a SAML AuthnRequest
The artifact resolution service at the service provider returns a <samlp:ArtifactResponse> element (containing an <samlp:AuthnRequest> element) bound to a SAML SOAP message to the SSO service at the identity provider:
The SSO service processes the <samlp:AuthnRequest> element and performs a security check. If the user does not have a valid security context, the identity provider identifies the user (details omitted).
6. Redirect to the Assertion Consumer Service
The SSO service at the identity provider redirects the user agent to the assertion consumer service at the service provider. The previous RelayState parameter and a new SAMLart parameter are appended to the redirect URL.
7. Request the Assertion Consumer Service at the SP
The user agent requests the assertion consumer service at the service provider:
where token is the token value from step 3 and artifact_2 is the SAML artifact issued at step 6.
8. Request the Artifact Resolution Service at the IdP
The assertion consumer service dereferences the artifact by sending a <samlp:ArtifactResolve> element bound to a SAML SOAP message to the artifact resolution service at the identity provider:
where the value of the <samlp:Artifact> element is the SAML artifact transmitted at step 7.
9. Respond with a SAML Assertion
The artifact resolution service at the identity provider returns a <samlp:ArtifactResponse> element (containing an <samlp:Response> element) bound to a SAML SOAP message to the assertion consumer service at the service provider:
10. Redirect to the target resource
11. Request the target resource at the SP again
12. Respond with the requested resource
The SAML 2.0 Identity Provider Discovery Profile introduces the following concepts:
As a hypothetical example of a Common Domain, let's suppose Example UK (example.co.uk) and Example Deutschland (example.de) belong to the virtual organization Example Global Alliance (example.com). In this example, the domain example.com is the common domain. Both Example UK and Example Deutschland have a presence in this domain (uk.example.com and de.example.com, resp.).
The Common Domain Cookie is a secure browser cookie scoped to the common domain. For each browser user, this cookie stores a history list of recently visited IdPs. The name and value of the cookie are specified in the IdP Discovery Profile (SAMLProf12).
After a successful act of authentication, the IdP requests the Common Domain Cookie Writing Service. This service appends the IdP's unique identifier to the common domain cookie. The SP, when it receives an unauthenticated request for a protected resource, requests the Common Domain Cookie Reading Service to discover the browser user's most recently used IdP.
The Assertion Query/Request Profile is a general profile that accommodates numerous types of so-called queries using the following SAML 2.0 elements:
The SAML SOAP binding is often used in conjunction with queries.
The Attribute Query is perhaps the most important type of SAML query. Often a requester, acting on behalf of the principal, queries an identity provider for attributes. Below we give an example of a query issued by a principal directly:
Note that the Issuer is the Subject in this case. This is sometimes called an attribute self-query. An identity provider might return the following assertion, wrapped in a <samlp:Response> element (not shown):
In contrast to the BearerAssertion shown earlier, this assertion has a longer lifetime corresponding to the lifetime of the X.509 certificate that the principal used to authenticate to the identity provider. Moreover, since the assertion is signed, the user can push this assertion to a relying party, and as long as the user can prove possession of the corresponding private key (hence the name "holder-of-key"), the relying party can be assured that the assertion is authentic.
Quite literally, metadata is what makes SAML work (or work well). Some important uses of metadata include:
Metadata ensures a secure transaction between an identity provider and a service provider. Before metadata, trust information was encoded into the implementation in a proprietary manner. Now the sharing of trust information is facilitated by standard metadata. SAML 2.0 provides a well-defined, interoperable metadata format that entities can leverage to bootstrap the trust process.
An identity provider publishes data about itself in an <md:EntityDescriptor> element:
Note the following details about this entity descriptor:
By definition, an identity provider manages an SSO service that supports the SAML Web Browser SSO profile specified in SAMLProf.15 See, for example, the identity provider described in the <md:IDPSSODescriptor> element shown in the next section.
The SSO service at the identity provider is described in an <md:IDPSSODescriptor> element:
The previous metadata element describes the SSO service at the identity provider. Note the following details about this element:
As noted at the beginning of this section, the values of the Location attributes are used by a service provider to route SAML messages, which minimizes the possibility of a rogue identity provider orchestrating a man-in-the-middle attack.
Like the identity provider, a service provider publishes data about itself in an <md:EntityDescriptor> element:
By definition, a service provider manages an assertion consumer service that supports the SAML Web Browser SSO profile specified in SAMLProf.21 See, for example, the service provider described in the <md:SPSSODescriptor> element shown in the next section.
The assertion consumer service is contained in an <md:SPSSODescriptor> element:
Note the following details about the <md:SPSSODescriptor> metadata element:
As noted at the beginning of this section, the values of the Location attributes are used by an identity provider to route SAML messages, which minimizes the possibility of a rogue service provider orchestrating a man-in-the-middle attack.
In the previous examples, each <md:EntityDescriptor> element is shown to be digitally signed. In practice, however, multiple <md:EntityDescriptor> elements are grouped together under an <md:EntitiesDescriptor> element with a single digital signature over the entire aggregate:
Note the following details about the above <md:EntitiesDescriptor> element:
Typically metadata aggregates are published by trusted third parties called federations who vouch for the integrity of all the metadata in the aggregate. Note that metadata aggregates can be very large, composed of hundreds or even thousands of entities per aggregate.
Primary references:
Secondary references:
Deprecated references:
S. Cantor et al. Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0 – Errata Composite. Working Draft 07, 8 September 2015. Document ID sstc-saml-core-errata-2.0-wd-07 http://www.oasis-open.org/committees/download.php/56776/sstc-saml-core-errata-2.0-wd-07.pdf http://www.oasis-open.org/committees/download.php/56776/sstc-saml-core-errata-2.0-wd-07.pdf ↩
S. Cantor et al. Bindings for the OASIS Security Assertion Markup Language (SAML) V2.0 – Errata Composite. Working Draft 06, 8 September 2015. Document ID sstc-saml-bindings-errata-2.0-wd-06 https://www.oasis-open.org/committees/download.php/56779/sstc-saml-bindings-errata-2.0-wd-06.pdf https://www.oasis-open.org/committees/download.php/56779/sstc-saml-bindings-errata-2.0-wd-06.pdf ↩
J. Hughes et al. Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0 – Errata Composite. Working Draft 07, 8 September 2015. Document ID sstc-saml-profiles-errata-2.0-wd-07 https://www.oasis-open.org/committees/download.php/56782/sstc-saml-profiles-errata-2.0-wd-07.pdf https://www.oasis-open.org/committees/download.php/56782/sstc-saml-profiles-errata-2.0-wd-07.pdf ↩
S. Cantor et al. Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0 – Errata Composite. Working Draft 05, 8 September 2015. Document ID sstc-saml-metadata-errata-2.0-wd-05 https://www.oasis-open.org/committees/download.php/56785/sstc-saml-metadata-errata-2.0-wd-05.pdf https://www.oasis-open.org/committees/download.php/56785/sstc-saml-metadata-errata-2.0-wd-05.pdf ↩