CA API Management: Implementing a Security Assertion Markup Language (SAML) Security Token Service

Document ID : KB000010908
Last Modified Date : 14/02/2018
Show Technical Document Details

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 SOA or API 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 gateway from your STS, the benefits are legitimate and compelling. The flexibility of the CA API Gateway policy language gives administrators the ability to simply build an STS. 


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.




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.




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




Specify the type of SAML assertion to be created:




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.




Specify the Subject Confirmation method:




Add any restrictions or conditions that may apply:




Lastly, specify how the assertion should be signed:




By default the private key used to sign the assertion will be that of the CA API 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.




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 is just one example of what a CA STS policy could look like. It can be modified in a number of ways to suit different use cases. Note also that the CA API Gateway supports the exchange and/or validation of credential information with third-party Security Token Services using either WS-Trust or WS-Federation.