SAML Architecture | Core Security Patterns: Best Practices and Strategies for J2EE, Web Services, and Identity Management

The original SAML specification introduced SAML using a domain model, which consists of Credential Collector, Authentication Authority, Session Authority, Attribute Authority, and Policy Decision Point. These are the key system entities in providing single sign-on service to service requesters.

Credential Collector: A system object that collects user credentials to authenticate with the associated Authentication Authority, Attribute Authority, and Policy Decision Point.
Authentication Authority: A system entity that produces authentication assertions.
Session Authority: A system entity (for example, identity provider) that plays the role of maintaining the state related to the session.
Attribute Authority: A system entity that produces attribute assertions.
Attribute Repository: A repository where attribute assertions are stored.
Policy Repository (or Policy) A repository where policies are stored.
Policy Decision Point: A system entity that makes authorization decisions for itself or for other system entities that request authorization.
Policy Enforcement Point: A system entity that enforces the security policy of granting or revoking the access of resources to the service requester.
Policy Administration Point: A system entity where policies (for example, access control rules about a resource) are defined and maintained.

SAML Assertions

A SAML assertion here resembles a piece of data produced by a SAML authority (for example, Authentication Authority) regarding either an authentication action performed on a subject (for example, service requester), attribute information about the subject, or an authorization request (for example, whether the service requester can access a resource).

There are three different SAML assertions:

Authentication Assertion: An assertion that carries business data about successful authentication performed on a subject (for example, a service requester).
Authorization Decision Assertion: An assertion that carries business data about an authorization decision. For example, the authorization decision may indicate that the subject is allowed to access a requested resource.
Attribute Assertion: An assertion that carries business data about the attributes of a subject.

SAML Domain Model

Figure 7-1 depicts a SAML domain model (refer to [SAML11Core] for details) where a system entity (client) wants to send an application request to access a system resource. The system entity presents its user credentials to the Credentials Collector, who will authenticate with the associated Authentication Authority (authentication assertion), the Attribute Authority (attribute assertion), and Policy Decision Point (authorization decision assertion), before the system entity can be granted access (Policy). The Policy Enforcement Point will process the application request based on the access rights granted in the Policy. All assertion requests are represented in SAML.

Figure 7-1. SAML domain model

Client requests for access (for example, credential or authentication assertion) come from a System Entry Point (refer to the System Entity in Figure 7-1) and are routed to different Authorities where authenticated and authorized requests will be routed to the relevant Policy Enforcement Point for execution.

These architectural entities resemble different instances of Certificate Authority, Registration Authority, and directory server in real life (within an enterprise, external Trust Service, or trading partners). For example, the Credential Collector is like a RADIUS protocol that front-ends the authentication process and passes to the directory server (or Authentication Authority) relevant user credentials for authentication.

Architecturally, SAML assertions are encoded in an XML package and consist of Basic Information (such as unique identifier of the assertion and issue date and time), Conditions (dependency or rule for the assertion), and Advice (specification of the assertion for policy decision).

SAML now supports a variety of protocol bindings when invoking different assertions. These include SOAP, reverse SOAP (multistage SOAP/HTTP exchange that allows an HTTP client to send an HTTP request containing a SOAP message), HTTP redirect (sending a SOAP message by HTTP 302 method), HTTP POST (sending a SOAP message in Base64-encoded HTML form control), HTTP artifact (way to transport an artifact using HTTP by a URI query string or by an HTML form control), and URI (retrieving a SAML message by resolving a URI).

Some architects and developers use the term "SAML architecture" to refer to the SAML entity model. This does not refer to the physical architecture. In the SAML architecture, the SAML domain model depicts the information entities (for example, System Entity) and their roles (for example, Policy Enforcement Point), but does not resemble any infrastructure-level component such as directory server or policy server. Thus, architects and developers need to map these domain entities into logical architecture components.

To illustrate how the SAML domain model is mapped to the SAML logical architecture, Figure 7-2 shows a scenario where a client requests access to remote resources under a single sign-on environment. Both the source site and the destination site collaborate to provide single sign-on security using SAML. The destination site has a number of remote resources and an existing authentication infrastructure with a custom-built authentication module (Policy Enforcement Point). It has implemented a SAML Responder (SAML-enabled agent) that can intercept application requests for resources and initiate SAML assertion requests. The source site has built an authentication service (Authentication Authority), directory server (Attribute Authority that stores the policy attributes), and a policy server (Policy Decision Point that determines what the client is entitled to). The SAML server (or authority) processes requests for SAML assertions and responds to the SAML Responder. These domain entities can easily map to the security architecture components. These architecture components may take more than one role; for example, the authentication module may act as Authentication Authority and Policy Enforcement Point.

Figure 7-2. SAML logical architecture

The following describes the interaction between the system entities as per Figure 7-2:

The client has already authenticated with the authentication service offered by the source site (Step 1).
The client creates an application request (also called Application Request) to the remote sources at the destination site (Step 2). The destination site has a SAML responder (SAML-enabled agent) that uses an authentication module (for example, a JAAS authentication module using a local directory server) for generating authentication assertions.
The remote destination redirects the application request to the SAML responder (Step 3).
The SAML responder issues a SAML authentication assertion request to the source site (Step 4).
The SAML-enabled authentication service processes the SAML authentication assertion request and provides a response to the destination site (Step 5).

Now the authentication module of the destination site knows that the client is already authenticated. It will not require the client to re-login again. The destination site will initiate a SAML attribute assertion request and an authorization decision assertion request to the source site to determine whether the client is entitled to access the remote resources.

Policy Enforcement Point

Policy Enforcement Point (PEP) is a system entity that enforces security policies so that unauthorized service requesters are not able to access or utilize the target resources. Many applications or security infrastructures play the role of PEP. For example, a custom-built Java application verifies the user authentication result, retrieves the attributes and access rights of the service requester from the directory server, and grants access to the service requester.

SAML does not specify how to build a PEP or how to implement the processing logic for authorization decisions. A PEP is in effect a SAML responder that processes the resource access request and communicates with the SAML authority for SAML authorization decision assertions. It issues a SAML assertion request to the SAML authority, which may provide user attributes (SAML attribute assertion) and access control policy information (SAML authorization assertion). Architects and developers can customize processing logic to enforce the policy information from SAML assertions. Many security vendor products for PEP provide scripting languages to implement PEP functionality.

Policy Administration Point

Policy Administration Point (PAP) is a system entity that provides administrative functions such as defining new policy information and modifying or deleting existing policy information centrally or remotely. SAML does not require a PAP; XACML introduces the use of PAP for administering policy information. The policy information may include actions, conditions, or dependencies that are associated with the access of resources. They reside in a policy repository, which is usually implemented in a database or directory server. PAP does not necessarily denote a sophisticated system front-end, although many security vendor products provide a browser-based administrative front-end. Architects and developers can also use a text-based editor to administer security policy information.

SAML Request-Reply Model

SAML uses a request-reply model to implement interaction between the SAML Responder and the SAML authority. It typically uses a SOAP protocol binding. Figure 7-3 shows a SAML request sent from a relying party (for example, the destination site in Figure 7-2) that requests a SAML assertion (for example, password authentication) by the issuing party (for example, SAML Authority or the source site in Figure 7-2). The user credentials (for example, ID and password) are encapsulated in a security token together with a digital signature (using XML Signature), and the request data (for example, password authentication) are wrapped in a SOAP body and sent via HTTP. Once the SAML authority receives the SAML request, it will process the request and create the appropriate response, including the SAML assertion statements.

Figure 7-3. SAML request-reply model

The SAML request consists of a SOAP envelope and a SOAP body that contain the SAML request <samlp:Request>. The SAML request element may contain the elements AuthenticationQuery, AttributeQuery, or AuthorizationDecisionQuery. A digital signature <ds:Signature> may also be generated and attached to the SOAP message, though this is not discussed here. Refer to Example 7-1 for an example of the SOAP message skeleton for a SAML request.

Example 7-1. SAML request message skeleton sample

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap/envelope/"> <env:Body> <samlp:AuthnRequest    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"    ForceAuthn="true"    AssertionConsumerServiceURL       ="http://www.coresecuritypatterns.com/"    AttributeConsumingServiceIndex="0"    ProviderName="string"        Version="2.0"    IssueInstant="2005-06-01T01:00:00Z"    Destination="http://www.coresecuritypatterns.com/"    Consent="http://www.coresecuritypatterns.com/"> <saml:Subject    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" <saml:NameID    Format= "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">        maryj@namredips.com </saml:NameID> </saml:Subject> </samlp:AuthnRequest> </env:Body> </env:Envelope>

The SAML response will include the <Status> element with the SAML assertion statements, such as AuthenticationStatement, AttributeStatement, and AuthorizationDecisionStatement. Example 7-2 shows an example of the SOAP message skeleton for a SAML response.

Example 7-2. SAML response message skeleton sample

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body>    <samlp:Response xmlns:samlp="..." xmlns:saml="..."           xmlns:ds="...">       <Status>          <StatusCode      value="urn:oasis:names:tc:SAML:2.0:status:Success"/>       </Status>       <saml:Assertion>          <saml:AuthenticationStatement>            ...          </saml:AuthenticationStatement>       </saml:Assertion>    </samlp:Response> </SOAP-Env:Body> </SOAP-ENV:Envelope>

SAML Authentication Assertion

The SAML authority (in this case, the SAML server of the source site in Figure 7-2) creates an authentication assertion to assert that the subject was authenticated by a particular authentication mechanism at a certain time. An authentication assertion statement AuthenticationStatement consists of the elements of AuthenticationMethod (for example, password), AuthenticationInstant (for example, timestamp of the authentication action), and optionally, SubjectLocality (for example, DNS domain name, IP address from which the subject was authenticated). Example 7-3 shows an example of an authentication assertion statement request.

Example 7-3. SAML message to request password authentication

<samlp:AuthnQuery    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"    xmlns:ds="http://www.w3.org/2000/09/xmldsig#"    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"    xsi:schemaLocation=    "urn:oasis:names:tc:SAML:2.0:protocol" ... > <saml:Subject>    <saml:SubjectConfirmation Method=      "http://www.oasis-open.org/committees/security/docs/draft-sstc-core-25/ password">       <saml:SubjectConfirmationData>          cGFzc3dvcmQ=       <saml:SubjectConfirmationData/>      </saml:SubjectConfirmation> </saml:Subject> <samlp:RequestedAuthnContext Comparison="exact">   <saml:AuthnContextClassRef>      http://www.coresecuritypatterns.com   </saml:AuthnContextClassRef> </samlp:RequestedAuthnContext> </samlp:AuthnQuery>

The SAML authority (or Issuing Authority) asserts that the client request has been authenticated and thus returns with a SAML response, as shown in Example 7-4.

Example 7-4. SAML responsepassword authenticated

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"    xmlns:ds="http://www.w3.org/2000/09/xmldsig#"    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"    IssueInstant="2005-06-01T09:30:47.0Z" Version="2.0"    InResponseTo="NCName"    Destination="http://www.coresecuritypatterns.com"    >         ...    <samlp:Status>       <samlp:StatusCode          Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>       <samlp:StatusMessage>status is successful</samlp:StatusMessage>    </samlp:Status>    <saml:Assertion       IssueInstant="2005-06-01T09:30:47.0Z" Version="2.0" >       <saml:Issuer NameQualifier="String" Format="http:// www.coresecuritypatterns.com"           SPProvided SPNameQualifier="String">CSP</ saml:Issuer>       <saml:Subject>       <saml:SubjectConfirmation          Method="http://www.oasis-open.org/committees/security/docs/draft- sstc-core-25/password">          <saml:NameID NameQualifier="card:SQLDatabase">              CoreSecurityPatterns          <saml:NameID/>       <saml:SubjectConfirmationData NotBefore="2005-06-01T09:30:47.0Z"           InResponseTo="NCName"           Recipient="http://www.coresecuritypatterns.com"           NotOnOrAfter="2005-06-01T09:30:47.0Z"           Address="String"/>       </saml:SubjectConfirmation>          </saml:Subject>             <saml:Conditions NotBefore="2005-06-01T09:30:47.0Z"                NotOnOrAfter="2005-06-01T09:30:47.0Z">                <saml:Condition xsi:type="a type derived from ConditionAbstractType"/>             </saml:Conditions>             <saml:Advice>                <saml:AssertionIDRef>NCName</saml:AssertionIDRef>             </saml:Advice>       <saml:AuthnStatement>           AuthnInstant="2005-06-0131T12:00:00Z"           SessionIndex="67775277772">           <saml:AuthnContext>                <saml:AuthnContextClassRef> urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport                </saml:AuthnContextClassRef>           </saml:AuthnContext>       </saml:AuthnStatement>    </saml:Assertion> </samlp:Response>

SAML Attribute Assertion

The SAML authority (in this case, the SAML server of the source site in Figure 7-2) creates an attribute assertion to assert that the subject was associated with the specified attributes. Typically, the attributes are stored in the policy data store or a directory server. An attribute assertion statement AttributeStatement consists of the elements of Attribute, AttributeName, AttributeNamespace, and AttributeValue. For example, the SAML relying party is inquiring about the list of organization and user role attributes of the subject. It generates a SAML attribute assertion statement request to the SAML authority to retrieve a list of attributes. Example 7-5 shows an example of an attribute assertion statement request.

Example 7-5. SAML attribute assertion statement request

<samlp:AttributeQuery xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"    xmlns:ds="http://www.w3.org/2000/09/xmldsig#"    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"    IssueInstant="2005-06-01T09:30:47.0Z" Version="2.0"    InResponseTo="NCName"    Destination="http://www.coresecuritypatterns.com"    >         ...      <saml:Subject>             ...      </saml:Subject>      <saml:Attribute Name="userRole">         <saml:AttributeValue/>      </saml:Attribute> </samlp:AttributeQuery>

Example 7-6 shows the corresponding response. The list of attribute names and the associated values vary in customer implementations. They may resemble local resource names or policy mnemonics that may not be easily understandable to users.

Example 7-6. SAML attribute assertion statement response

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"    xmlns:ds="http://www.w3.org/2000/09/xmldsig#"    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"    IssueInstant="2005-06-01T09:30:47.0Z" Version="2.0"    InResponseTo="NCName"    Destination="http://www.coresecuritypatterns.com"    >         ...      <samlp:Status>        <samlp:StatusCode                Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>        <samlp:StatusMessage>status is successful</samlp:StatusMessage>      </samlp:Status>      <saml:Assertion IssueInstant="2005-06-01T09:30:47.0Z" Version="2.0" >                 ...         <saml:Subject>                    ...         </saml:Subject>         <saml:Conditions NotBefore="2005-06-01T09:30:47.0Z"                     NotOnOrAfter="2005-06-01T09:30:47.0Z">            <saml:Condition xsi:type="a type derived from ConditionAbstractType"/>         </saml:Conditions>         <saml:Advice>            <saml:AssertionIDRef>NCName</saml:AssertionIDRef>         </saml:Advice>                 <saml:AttributeStatement>                    <saml:Attribute                        NameFormat="http://www.coresecuritypatterns.com">                        Name="PaymentStatus"                        <saml:AttributeValue>                            JustPaid                        </saml:AttributeValue>                    </saml:Attribute>                    <saml:Attribute                        NameFormat="http://coresecuritypatterns.com">                        Name="CreditLimit"                        <saml:AttributeValue xsi:type="coresecuritypatterns:type">                           <coresecuritypatterns:amount currency="USD">                              1000.00                           </coresecuritypatterns:amount>                        </saml:AttributeValue>                    </saml:Attribute>                 </saml:AttributeStatement>      </saml:Assertion> </samlp:Response>

SAML Authorization Decision Assertion

An authorization decision assertion statement describes a resource access request for the specified subject. The requested resource is typically identified by a URI reference. The response to the resource request reflects the authorization decision (using the element <Decision>), which may be Permit, Deny, or Indeterminate. It usually includes the resulting actions (using the element <Action>) and a set of assertions (using the element <Evidence>) that the SAML authority relied on while making the decision.

Example 7-7 shows an authorization decision assertion statement request. For example, a user wants to access a remote printer resource. The authorization decision assertion statement request will describe a request about accessing the resource "Printer."

Example 7-7. SAML authorization decision assertion statement request

<samlp:AuthzDecisionQuery xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"    xmlns:ds="http://www.w3.org/2000/09/xmldsig#"    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"    IssueInstant="2005-06-01T09:30:47.0Z" Version="2.0"    InResponseTo="NCName"    Destination="http://www.coresecuritypatterns.com"    >      <saml:Subject>         <saml:BaseID xsi:type="a type derived from BaseIDAbstractType"/>         <saml:SubjectConfirmation Method="http:// www.coresecuritypatterns.com">                    ...         </saml:SubjectConfirmation>      </saml:Subject>      <saml:Action Namespace="http:// www.coresecuritypatterns.com">SomeAction</saml:Action>      <saml:Evidence>             ...      </saml:Evidence> </samlp:AuthzDecisionQuery>

Example 7-8 shows the corresponding response.

Example 7-8. SAML authorization decision assertion response

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"    xmlns:ds="http://www.w3.org/2000/09/xmldsig#"    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"    IssueInstant="2005-06-01T09:30:47.0Z" Version="2.0"    InResponseTo="NCName"    Destination="http://www.coresecuritypatterns.com"    >      <saml:Issuer>IssuerName</saml:Issuer>      <samlp:Status>         <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>         <samlp:StatusMessage>status is successful</samlp:StatusMessage>      </samlp:Status>      <saml:Assertion IssueInstant="2005-06-01T09:30:47.0Z" Version="2.0"                 >                 ...         <saml:Subject>                    ...         </saml:Subject>         <saml:Conditions NotBefore="2005-06-01T09:30:47.0Z"                     NotOnOrAfter="2005-06-01T09:30:47.0Z">            ...         </saml:Conditions>         <saml:Advice>            <saml:AssertionIDRef>NCName</saml:AssertionIDRef>         </saml:Advice>             <saml:AuthzDecisionStatement Resource="Printer" Decision="Deny">                <saml:Action Namespace="http://www.coresecuritypatterns.com">                    SomeAction</saml:Action>                <saml:Evidence>                   ...             </saml:Evidence>             </saml:AuthzDecisionStatement>      </saml:Assertion> </samlp:Response>

The SAML core specification for assertions and protocols (refer to [SAML2Core], p. 25) indicates that the <AuthorizationDecisionStatement> feature has been frozen in version 2.0. Thus, architects and developers should consider using XACML for enhanced authorization decision features.

XML Signatures in SAML

The XML Signature defines mechanisms for embedding signatures in XML documents including SAML. XML Digital Signatures provide integrity and non-repudiation of SAML-based transactions. In SAML, XML Signature element is used to represent its authority who signs the message. The XML signature can be placed within the SAML assertion, request and response elements. The XML signature contains the X.509 certificate with a public key and also the signature value generated. When a signed message is received by a relying party, it verifies the message using the authority's public key. The verification process checks that the message has not been tampered during transmission, authenticity of the signer and identifies the content and portions of message signed.

For more information on XML signature and how to represent XML signature in XML messages, refer to Chapter 6, "Web Services SecurityStandards and Technologies."