Web Services Architecture and Its Specifications [Electronic resources] : Essentials for Understanding WS-* نسخه متنی

Trust Based on Security Tokens

In our earlier examples, we used security tokens but did not explain how they were acquired by the various endpoints. One mechanism is for the School of Fine Art and Microsoft Press to exchange them out of band, such as in an email message or on a CD, but a more effective approach is for the systems to request security tokens from a mutually trusted authority. The WS-Trust specification describes how tokens are acquired and used in this way.

Security Token Services

In our example scenario, the School of Fine Art and Microsoft Press have selected a mutually trusted authority to distribute and verify security tokens. Figure 12-1 shows the sequence of messages that are transmitted between the two applications and the certificate authority in the course of sending a secure PurchaseOrder message. That sequence is as follows:

The procurement system transmits a RequestSecurityToken (RST) message [Message 1] to the agreed upon trusted security authority, and it responds with a RequestSecurityTokenResponse (RSTR) message [Message 2]. This response includes the security and proof tokens required for trusted communication with the Microsoft Press endpoint.

The proof token is then used to sign and/or encrypt the PurchaseOrder message [Message 3] sent to Microsoft Press. If applications require both signatures and encryption, use of two separate tokens is recommended. Messages should be signed first and then encrypted, each with different tokens.

When the PurchaseOrder message is received, the Order Mangement service at Microsoft Press sends the proof token back to the trusted authority for validation via another Request Security Token (RST) message [Message 4].

The trusted security authority responds to the request with a RequestSecurityTokenResponse message [Message 5] indicating whether the message is valid.

If the security token is valid and meets the Microsoft Press policy requirements, the PurchaseOrder message is processed.

RequestSecurityToken Messages

In our sample scenario, the RequestSecurityToken message is signed with the Username Token. The response returns a more secure X509 Certificate token that is then used for trusted communication with Microsoft Press.

Important

The SOAP message fragments shown in this chapter do not always show digital signatures or encryption. In a real implementation, it is important that each message and appropriate fragments be appropriately signed and encrypted.

RequestSecurityToken Message
(01) <env:Envelope ...>
(02)  <env:Header>
(03)   <wsse:Security>
(04)    <xenc:ReferenceList>...</xenc:ReferenceList>
(05)    <xenc:EncryptedData Id="MyToken">...</xenc:EncryptedData>
(06)    <ds:Signature>...</ds:Signature>
(07)   </wsse:Security>
(08)  </env:Header>
(09)  <env:Body>
(10)   <wst:RequestSecurityToken>
(11)    <wst:TokenType>http://education.org/mySpecialToken</wst:TokenType>
(12)    <wst:RequestType>
(13)        http://schemas.xmlsoap.org/ws/2004/04/security/trust/Issue
(14)    </wst:RequestType>
(15)   </wst:RequestSecurityToken>
(16)  </env:Body>
(17) </env:Envelope>

Lines 0406 The encrypted username token used as the basis for the request is included in the SOAP header block.

Line 11 The type of security token being requested is specified in the TokenType element. In this example, a custom security token type being requested.

Lines 1214 The type of request that is being made is specified here. In this case, the procurement system is requesting that a security token be issued.

RequestSecurityTokenResponse Messages

When the appropriate requirements and policies are met, the trust authority responds with a RequestSecurityTokenResponse message. This response contains the requested X509 certificate token that was requested by the procurement system.

RequestSecurityTokenResponse Message
(01) <env:Envelope ...>
(02)  <env:Header> ...</env:Header>
(03)  <env:Body>
(04)   <wst:RequestSecurityTokenResponse>
(05)    <wst:TokenType>http://education.org/mySpecialToken</wst:TokenType>
(06)    <wsp:AppliesTo>
(07)     <wsa:EndpointReference>
(08)      <wsa:Address>http://ex.mspress.microsoft.com/orders</wsa:Address>
(09)    </wsa:EndpointReference>
(10)   </wsp:AppliesTo>
(11)   <wst:RequestedSecurityToken>
(12)    <wsse:BinarySecurityToken>...</wsse:BinarySecurityToken>
(13)   </wst:RequestedSecurityToken>
(14)   <RequestedProofToken>
(15)     <xenc:EncryptedKey Id="ProofToken1">
(16)         ...
(17)     </xenc:EncryptedKey>
(18)    </RequestedProofToken>
(19)    <wst:Lifetime>PT30M</wst:Lifetime>
(20)   </wst:RequestSecurityTokenResponse>
(21)  </env:Body>
(22) </env:Envelope>

Lines 0420 The response information is returned in the SOAP message body.

Line 05 The TokenType element confirms that the returned security token is the custom token type, as requested.

Lines 0610 The AppliesTo element scopes the use of this security token to use with the Microsoft Press order management endpoint.

Lines 1113 The requested security token is returned.

Lines 1418 The requested proof of possession token is returned.

Line 19 The lifetime for the token in specified. In our example, the token may be used for no longer than 30 minutes. The application messages, such as the PurchaseOrder, then use the proof token to secure the messages between the procurement and order management services.

RequestSecurityToken Validation Messages

When a message carrying a security token is received by the order management system, it needs to be validated for authenticity. This is accomplished through a similar pair of Request-SecurityToken and RequestSecurityTokenResponse messages. In this case, the order management system simply asks the trust authority to confirm that the security token is valid.

Security Token Validation Request
(01)      <wst:RequestSecurityToken>
(02)       <wst:TokenType>
(03)           http://schemas.xmlsoap.org/ws/2004/04/security/trust/RSTR/Status
(04)       </wst:TokenType>
(05)       <wst:RequestType>
(06)           http://schemas.xmlsoap.org/ws/2004/04/security/trust/Validate
(07)       </wst:RequestType>
(08)       <wst:Base>
... token to be validated ...
(09)       </wst:Base>
(10)      </wst:RequestSecurityToken>

Lines 0204 This value for the TokenType element simply requests that the trust authority provide status information for the security token. There is no request for additional tokens or other information about the token.

Lines 0507 This value for the RequestType element specifies that the token is to be validated by the trust authority.

Lines 0809 The security token to be validated is sent to the trust authority. The omitted content is the binary security token that was carried in the PurchaseOrder message from the procurement service.

RequestSecurityTokenResponse Validation Messages

In response to the request, the trust authority returns a message with a status element value indicating whether the security token is valid. If the token is valid, the value of the Status element is as shown here:

Security Token Validation Response
(01)    <wst:RequestSecurityTokenResponse>
(02)     <wst:TokenType>
(03)         http://schemas.xmlsoap.org/ws/2004/04/security/trust/RSTR/Status
(04)     </wst:TokenType>
(05)     <wst:Status>
(06)         http://schemas.xmlsoap.org/ws/2004/04/security/trust/status/valid
(07)     </wst:Status>
(08)    </wst:RequestSecurityTokenResponse>

Lines 0507 The security token is valid.

Secure Conversations

In terms of network latency time and processing resources, requesting and issuing a new security token is relatively expensive. Many applications, such as our procurement service, transmit many messages to another endpoint in a short period of time. The WS-SecureConversation specification provides mechanisms for a security token to be issued and used for a series of messages between the endpoints, instead of establishing new security credentials for each message. This facility leverages the approach used in WS-Trust and removes the overhead of requiring new tokens to be issued for each message exchange without compromising message security.

In our sample solution, multiple PurchaseOrders and OrderAcknowledgements are sent between the School of Fine Art and Microsoft Press each the day. In the example, a security context is established between the two endpoints to support a day's communication.

Security Context Token Request
(01) <env:Envelope ...>
(02)  <env:Header>...</env:Header>
(03)  <env:Body>
(04)   <wst:RequestSecurityToken>
(05)    <wst:TokenType>
(06)        http://schemas.xmlsoap.org/ws/2004/04/security/sc/sct
(07)    </wst:TokenType>
(08)    <wst:RequestType>
(09)        http://schemas.xmlsoap.org/ws/2004/04/security/trust/Issue
(10)    </wst:RequestType>
(11)   </wst:RequestSecurityToken>
(12)  </env:Body>
(13) </env:Envelope>

Lines 0507 The RequestSecurityToken message requests a security context token Token-Type.

In response to the security token request, the trust authority issues a SecurityContextToken that is used to secure the messages sent between endpoints throughout the day:

Security Context Token Response
(01) <env:Envelope ...>
(02)  <env:Header> ...</env:Header>
(03)  <env:Body>
(04)   <wst:RequestSecurityTokenResponse>
(05)    <wst:RequestedSecurityToken>
(06)     <wsc:SecurityContextToken>...</wsc:SecurityContextToken>
(07)    </wst:RequestedSecurityToken>
(08)   </wst:RequestSecurityTokenResponse>
(09)  </env:Body>
(10) </env:Envelope>

Line 06 The security context token is returned in the body of the response message.

Once a security context token is received, it can be used to secure the application-level messages sent between the endpoints. Similar to any other token type, it is included within the Security SOAP header block.

Messages using Security Context Tokens
(01) <env:Envelope>
(02)  <env:Header>
...
(03)   <wsse:Security>
(04)    <wsc:SecurityContextToken wsu:Id="sct1">
(05)        ...
(06)    </wsc:SecurityContextToken>
(07)    <wsc:DerivedKeyToken wsu:Id="dkey1">
(08)     <wsse:SecurityTokenReference>
(09)      <wsse:Reference URI="#sct1"/>
(10)     </wsse:SecurityTokenReference>
(11)     <wsc:Nonce>KJHREF...</Nonce>
(12)    </wsc:DerivedKeyToken>
(13)    <xenc:ReferenceList>
(14)     <xenc:DataReference URI="#Body" />
(15)    </xenc:ReferenceList>
(16)     <ds:KeyInfo>
(17)      <wsse:SecurityTokenReference>
(18)       <wsse:Reference URI="#dkey1"/>
(19)      </wsse:SecurityTokenReference>
(20)     </ds:KeyInfo>
(21)    </xenc:ReferenceList>
(22)    <wsc:SecurityContextToken wsu:Id="sct2">
(23)        ...
(24)    </wsc:SecurityContextToken>
(25)    <wsc:DerivedKeyToken wsu:Id="dkey2">...</wsc:DerivedKeyToken>
(26)    <xenc:ReferenceList>...</xenc:ReferenceList>
(27)   </wsse:Security>
(28)  </env:Header>
(29)  <env:Body>
(30)   <xenc:EncryptedData Id="Body">
(31)    <ds:KeyInfo>...<ds:KeyInfo>
(32)    <xenc:CipherData>...</xenc:CipherData>
(33)   </xenc:EncryptedData>
(34)  </env:Body>
(35) </env:Envelope>

Lines 0406 The security context token is carried in the Security SOAP header block as another type of security token. The message is encrypted using this token as described in the WS-Security discussion earlier.

Lines 0721 As recommended in the WS-SecureConversation, a derived key is used to encrypt the message.

Lines 2226 A second security context token and derived keys are used to sign the message.

Lines 3033 The signed and encrypted message payload is carried in the SOAP Body.

System Federations

On the wire, WS-Federation is a specific application of WS-Trust. In our example scenario, the same mechanisms as described above can be used to federate instructor identities and account information across the School of Fine Art procurement system and Microsoft Press's order management system.