Example of authorization with WS-Trust and SAML
This article describes how to secure a Web Service using a central Token Server. The standards WS-Trust, WS-Policy, WS-SecurityPolicy and Web Services Security, formerly known WS-Security, are used. A simple scenerio with a consumer, a service and a Security Token Service (in short STS) would serve as an example.
The scenario used in this article roughly takes place as demonstrated in figure 1.
- The consumer contacts the service and is told that he needs a token for a request.
- To receive the token the consumer contacts the STS and identifies itself. The STS issues a token and return it to the consumer.
- Now the consumer is calling the desired operation of the service and commits the token in this process.
- The service accepts the token and runs the operation for the consumer.
Figure 1: WS-Trust scenerio
With gotton to know the roughly sequence, we will now have a detailed look on the single steps.
At first the consumer is retrieving the WSDL document of the service he wants to call. As demonstrated in figure 2 the service returns a WSDL document containing the metadata of the requirements which are assumed for invoking. Metadata describing the requirements of the service for the consumer are called policy. An interoperable description of the policies is giving the standards WS-PolicyFramework and WS-PolicyAttachment.
Figure 2: Retrieval of the WSDL document with embedded Policy
The policies embedded into the WSDL document are describing which part of a service call have to be encrypted and signed and what kind of token is expected. A token is containing one or more claims. Claims are assertions as for example:
- I am Thomas
- I am a authenticated user
- I am authorized to print to the printer
Tokens are often signed by an authority, so that nobody else can create a valid access token. In our example the STS represents the authority issuing a signed token to us.
Listing 1 is taken from the service's WSDL document. The service expects a SAML token for every call. The token can be obtained using WS-Trust.
<wssp:ProtectionToken>
<wsp:Policy>
<wsp:ExactlyOne>
<wsp:All>
<wssp:IssuedToken wssp:IncludeToken=".../IncludeToken/AlwaysToRecipient">
<wssp:RequestSecurityTokenTemplate>
<wst:TokenType>...#SAMLV1.1</wst:TokenType>
</wssp:RequestSecurityTokenTemplate>
</wssp:IssuedToken>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>
</wssp:ProtectionToken>Listing 1 Policy of a service secured with a SAML token (simplified)
Now the consumer can contact the STS to obtain the token. Therefore the consumer has to know the address of the STS. The address can be stored in the Sun Metro Stack in a configuration file for example. If the Sun Metro Stack is used the address is stored in a configuration file for example.
Figure 3: Request of the WSDL document of the STS
In the WSDL document of the STS, policies are embedded again describing how the STS has to be invoked. More precisely it describes which part of the message has to be singed and encrypted and how the consumer has to authenticate to the STS.
In our example the STS expects a singed username and also a signature for the whole call. With this information the consumer can send a inquiry to the STS including a request to issue a token.
Figure 4:
The invocation contains a Request Security Token (in short RST) element describing what kind of token the consumer needs. Listing 2 is showing the consumer's RST element.
<RequestSecurityToken>
<RequestType>
http://schemas.xmlsoap.org/ws/2005/02/trust/Issue
</RequestType>
<AppliesTo>
<EndpointReference>
<Address>http://localhost:2000/payment/PaymentServiceService</Address>
</EndpointReference>
</AppliesTo>
<TokenType>
http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1
</TokenType>
</RequestSecurityToken>
Listing 2: RST with requesting to issue a SAML token.
The STS validates the signature of the call, containing the public key, of the consumer. The signed username token is validated as well. If the validation has been finished successfully, the STS can be sure that the request originates from the consumer and haven't been changed. Now the STS can answer with a Request Security Token Response (in short RSTR) which is signed with his public key. The RSTR contains the requested SAML token as shown in listing 3. The token is for a single user thomas, who has authenticated himself with the private key he owns. Further, the token verifies it's user to be authenticated.
<saml:Assertion AssertionID="uuid-7bf" IssueInstant="2008-06-13T16:07:44.812Z"
Issuer="SunSTS" MajorVersion="1" MinorVersion="1">
<saml:Conditions NotBefore="2008-06-13T16:07:44.812Z"
NotOnOrAfter="2008-06-13T16:08:20.812Z"/>
<saml:AttributeStatement>
<saml:Subject>
<saml:NameIdentifier NameQualifier="http://sun.com">
thomas
</saml:NameIdentifier>
<saml:SubjectConfirmation>
<saml:ConfirmationMethod>...:holder-of-key</saml:ConfirmationMethod>
<ds:KeyInfo>...</ds:KeyInfo>
</saml:SubjectConfirmation>
</saml:Subject>
<saml:Attribute AttributeName="token-requestor"
AttributeNamespace="http://sun.com">
<saml:AttributeValue xsd:type="xsd:string">authenticated</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
</saml:Assertion>Listing 3: SAML Token
Now the consumer is holding the token, needed for the invocation of the target service. The token is send as a part of the invocation of the service.
Figure 5:The invocation of the target service.
In the SOAP header of the invocation the token, singed by the STS, as well as it's signatures are contained. The security information is embedded in elements which are described by the OASIS Web Services Security standard. The service can validate the token with the public signature of the STS and then process the inquiry as required and send a response to the client.
To avoid that externals are able to eavesdrop on the communication between the consumer and the STS, respectively the service, additional encryption is used. Therefore the possibility to spy out the token is avoided. To keep it simple, there is no encryption in our example.
I hope this article could clarify the interaction of the WS-* specification WS-Trust, WS-Policy and Web Services Security.
Thomas Bayer, July 2008
