SAML Protocol
SAML defines a simple request response protocol that allows a Relying Party (a system entity that uses a security assertion) to request a SAML assertion from an asserting authority (a system entity that produces an assertion).
Figure 5SAML Simple Request Response Protocol
In the SAML protocol, SAML assertions are encapsulated in a SAML Response. The intention is that systems with minimal knowledge of each other can interact using the SAML protocol.
SAML Requests
There are different types of requests for different types of SAML information. Each request type asks specific types of SAML information. The different types of requests defined by SAML 1.0 are:
Authentication Query: Requests authentication information about a specified user.
Attribute Query: Requests a set of attributes associated with a specific object.
Authorization Decision Query: Requests a decision requiring access to a resource.
Artifact Query: Requests a specific SAML assertion.This is usually an authentication assertion used for single sign-on (SSO).
Authentication Query
Authentication queries are used to determine if the authentication authority has authentication information about the provided subject. A successful response is in the form of assertions containing authentication statements. The authentication query is not used as a request for new authentication; it is only used to get information about previous interaction between the subject and the authentication authority.
In the example below, the SAMLP request makes a request for authentication information about the user cn=joe,o=novell. For this example, optional SAML information has been omitted along with the SAML and SAMLP namespace declarations.
Figure 6Authentication Query
Attribute Query
An attribute query is used to get attributes about a given subject. A successful response contains assertions that contain attribute statements about the subject.
In the example below, the SAMLP request makes a request for the Email attribute in the urn:test:novell namespace for the subject cn=joe,o=novell. For this example, optional SAML information has been omitted along with the SAML and SAMLP namespace declarations.
Figure 7Attribute Query
Authorization Decision Query
Authorization decision queries are used to determine if a subject S is allowed to perform action A on resource R.
In the example below, a sample authorization decision query asks if user cn=joe,o=novell should be able to perform the Buy action on the urn:novell/buy_stuff resource. For this example, the optional SAML information has been removed along with the SAML and SAMLP namespace declarations.
Figure 8Authorization Decision Query
Artifact Query
An artifact request is a special type of SAMLP query used in the single sign-on (SSO) use case. The artifact query is used in the Browser/Artifact web SSO, which will be covered later. In the Browser/Artifact use case, a Relying Party is presented with an incoming request accompanied by a SAML Artifact. The SAML Artifact allows the Relying Party to determine who issued the user an Assertion and a unique identifier of that assertion. The Relying Party can then make an artifact query to the issuer that provides the assertion.
In the example below, a sample artifact query makes a request for an assertion with artifact SAMPLE_ARTIFACT. For this example, optional SAML data has been omitted along with the SAMLP and SAML namespace declarations.
Figure 9Artifact Query
SAML Responses
When a system receives a SAMLP request, a SAMLP response is returned. If the request can be successfully fulfilled then a SAMLP response is returned containing the requested assertions. If the SAMLP request cannot be fulfilled, a SAMLP response is returned containing an error message. The SAML 1.0 specification defines a number of static error codes that are associated with failed SAMLP requests.
The example below shows a sample of a successful SAMLP response:
Figure 10Successful SAMLP Response
A successful response contains at least one SAML assertion.
If there is an error fulfilling a SAMLP request, an error will be returned. The example below is a SAMLP response that describes an error condition. This example shows the error that is returned if the requester is using a request version that is too low.
Figure 11Example of an Error in Fulfilling a SAMLP Request
SAML 1.0 defines the following top-level status codes:
- Success
- VersionMismatch: Unable to fulfill the request because of an incorrect version.
- Requester: Unable to fulfill the request because of an error with the requester.
- Responder: Unable to fulfill the request because of an error with the responder.
SAML 1.0 also defines second-level status codes by providing additional information about why the SAMLP request failed:
- RequestVersionTooHigh
- RequestVersionTooLow
- RequestVersionDeprecated
- TooManyResponses: Fulfilling the request would require returning too much data.
- RequestDenied: The requester does not have sufficient rights to perform the request.
- ResourceNotRecognized: Unable to resolve the resource being referenced.
All of these error code values are QNames associated with the SAMLP namespace.
The StatusMessage and StatusDetail messages can contain any string data.