Header Image

Implementing a SAML Security Token Service

In an attempt to reduce costs and maintenance overhead, requests are often seen for features that cross typical product boundaries.  Examples of this include a Web & Web Services gateway or a SOA gateway that doubles as a SAML 1.1 / 2.0 Security Token Service (STS).  While it may be desirable to separate the concerns of your SOA gateway from your STS, the benefits are legitimate and compelling.  The flexibility of the SecureSpan gateway policy language gives administrators the ability to simply build an STS.  This tutorial will demonstrate how to do just that using either Layer 7’s SecureSpan SOA Gateway or XML Firewall.

Security Token Service capabilities for SAML, such as those shown here, are useful for many federation scenarios.  Whether this involves connecting to partner sites or connecting to Cloud applications, any situation that requires the propagation of authorization/authentication information from one domain to another will benefit.

The first step is to publish a new service endpoint on the gateway using an appropriate WS-Trust WSDL.  At this point, this new service is just like any other service on the gateway.  The only difference here is that instead of proxying requests for back-end services, the gateway endpoint is the (STS) service.  All that is required is to define a policy which issues a token based on supplied credentials.  In this example we'll build a policy that requires inbound credentials in the form of a WS-Security Username Token and issues a SAML assertion that contains both authentication & attribute statements. 

Using an appropriate WS-Trust WSDL - Layer 7 Technologies

 

The policy authenticates the inbound credentials, and ensures that the user is a member of the “partners” group. LDAP attributes for the user are extracted and saved to context variables (authenticatedUser.department & authenticatedUser.expiration) to be used when building the attribute statement of the SAML assertion. 

Identity Attribute Properties - Layer 7 Technologies

 

The Create SAML Token Wizard is used to build the required SAML assertion. Specify the version:

The Create SAML Token Wizard used to build the SAML assertion - Layer 7 Technologies

 

Specify the type of SAML assertion to be created: 

Specify the type of SAML assertion to be created - Layer 7 Technologies

 

When building the attribute statement of the SAML assertion, the context variables created above (authenticatedUser.*) can be referenced. This allows the dynamic population of attribute values depending on the credentials making the request.

Edit SAML Assertion Properties - Layer 7 Technologies

Specify the Subject Confirmation method:

Specify the Subject Confirmation method - Layer 7 Technologies

 

Add any restrictions or conditions that may apply:

Add any restrictions or conditions that may apply - Layer 7 Technologies

 

Lastly, specify how the assertion should be signed:

Specify how the assertion should be signed - Layer 7 Technologies

 

By default the private key used to sign the assertion will be that of the SecureSpan gateway. However, any private key loaded into the gateway can be used by selecting Select Private Key option from the context menu of the Create SAML Token assertion.

The final step requires the construction of the response. For your policy to act as an STS, it must respond to the Request Security Token (RST) request with an Request Security Token Response (RSTR) response. An easy way to achieve this is to create a response message using the Template Response assertion. The skeleton of the RSTR message is added to the Template Response assertion, and its content references a context variable called issuedSamlAssertion whose value is the actual token issued. This context variable is set by the SAML issuing assertion. 

Template Response Properties - Layer 7 Technologies

The Create SAML Token assertion allows the administrator to specify authorization, authentication & attribute statements. In our example attribute values were obtained from an LDAP using the Identity Attributes assertion, but they could just have easily been obtained using the LDAP Query assertion or by some other means entirely.

You are now finished building a Security Token Service, which should typically take less than an hour. This tutorial presents just one example of what a Layer 7 STS policy could look like. It can be modified in a number of ways to suit different use cases. Note also that SecureSpan supports the exchange and/or validation of credential information with third-party Security Token Services using either WS-Trust or WS-Federation.

Implementing a SAML Security Token Service