# Request Security Token Response (RTRS)

Once a request for security token (RST) has been made, a client should expect the response (RSTR) to include a security token. The security token should ideally be treated, according to WS-Trust as an opaque structure that does not need to be parsed. An critical information that a client may need, such as the token lifetime, should be communicated in additional elements. While the response could be contained in the header, it is often in the body.

An example response is shown below:

```markup
<s:Envelope 
xmlns:a="http://www.w3.org/2005/08/addressing" 
xmlns:s="http://www.w3.org/2003/05/soap-envelope" 
xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
  <s:Header>
    <a:Action s:mustUnderstand="1">http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTRC/IssueFinal</a:Action>
    <a:RelatesTo>urn:uuid:f2d2bda8-b82a-4e0f-b8f2-2b15205822d7</a:RelatesTo>
    <o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
      <u:Timestamp u:Id="_0">
        <u:Created>2016-12-14T18:09:37.160Z</u:Created>
        <u:Expires>2016-12-14T18:14:37.160Z</u:Expires>
      </u:Timestamp>
    </o:Security>
  </s:Header>
  <s:Body>
    <trust:RequestSecurityTokenResponseCollection xmlns:trust="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
      <trust:RequestSecurityTokenResponse>
        <trust:Lifetime>
          <wsu:Created xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">2016-12-14T18:09:37.156Z</wsu:Created>
          <wsu:Expires xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">2016-12-14T19:09:37.156Z</wsu:Expires>
        </trust:Lifetime>
        <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
          <wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/08/addressing">
            <wsa:Address>https://crmdemo.demo.local:444/</wsa:Address>
          </wsa:EndpointReference>
        </wsp:AppliesTo>
        <trust:RequestedSecurityToken>
          <xenc:EncryptedData Type="http://www.w3.org/2001/04/xmlenc#Element" xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">
            <xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"/>
            <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
              <e:EncryptedKey xmlns:e="http://www.w3.org/2001/04/xmlenc#">
                <e:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p">
                  <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                </e:EncryptionMethod>
                <KeyInfo>
                  <o:SecurityTokenReference xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
                    <X509Data>
                      <X509IssuerSerial>
                        <X509IssuerName>CN=DemoCrmServer, DC=Demo, DC=Local</X509IssuerName>
                        <X509SerialNumber>825127572376036501802804159644169187033612293</X509SerialNumber>
                      </X509IssuerSerial>
                    </X509Data>
                  </o:SecurityTokenReference>
                </KeyInfo>
                <e:CipherData>
                  <e:CipherValue>...</e:CipherValue>
                </e:CipherData>
              </e:EncryptedKey>
            </KeyInfo>
            <xenc:CipherData>
              <xenc:CipherValue>...</xenc:CipherValue>
            </xenc:CipherData>
          </xenc:EncryptedData>
        </trust:RequestedSecurityToken>
        <trust:RequestedProofToken>
          <trust:BinarySecret>Y5nHZ23McFNLVYKi4yUy1PB1IZ4FH1osfnFX0mhusqg=</trust:BinarySecret>
        </trust:RequestedProofToken>
        <trust:RequestedAttachedReference>
          <o:SecurityTokenReference 
          k:TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1" 
          xmlns:k="http://docs.oasis-open.org/wss/oasis-wss-wssecurity-secext-1.1.xsd" 
          xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
            <o:KeyIdentifier ValueType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.0#SAMLAssertionID">_aef152ff-f14b-4df5-bda8-bea51ad77d28</o:KeyIdentifier>
          </o:SecurityTokenReference>
        </trust:RequestedAttachedReference>
        <trust:RequestedUnattachedReference>
          <o:SecurityTokenReference 
          k:TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1" 
          xmlns:k="http://docs.oasis-open.org/wss/oasis-wss-wssecurity-secext-1.1.xsd" 
          xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
            <o:KeyIdentifier 
            ValueType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.0#SAMLAssertionID">_aef152ff-f14b-4df5-bda8-bea51ad77d28</o:KeyIdentifier>
          </o:SecurityTokenReference>
        </trust:RequestedUnattachedReference>
        <trust:TokenType>urn:oasis:names:tc:SAML:1.0:assertion</trust:TokenType>
        <trust:RequestType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue</trust:RequestType>
        <trust:KeyType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey</trust:KeyType>
      </trust:RequestSecurityTokenResponse>
    </trust:RequestSecurityTokenResponseCollection>
  </s:Body>
</s:Envelope>
```

The actual cipher values were remove from the listing above for brevity.

The individual sections need to be expanded but the basic outline is helpful to understand. The actual token is included in the RequestedSecurityToken and we expect that to be signed and encrypted. Hence, we expected the key element child to be "EncryptedData" as described in a previous section. The actual token response is wrapped in a RequestSecurityTokenResponseCollection as an STS could return multiple tokens. For MS CRM, we receive a single token response.

There are a few key parts of the message that come from WS-Trust:

* Lifetime: A Timestamp in the header is provided with an Id of "\_0". This is the Timestamp mentioned in previous section that is required when using Transport level security. The Timestamp helps prevent replay attacks.
* AppliesTo: The token can only be used with a specific endpoint. Although the child element appears to include a URL, it is really a URI of a resource on the server. The token is only good for that URI. In MS CRM, you need a different token for each service, Discovery or Organization.
* TokenType: The token type is SAML. If we were to decrypt the token, it would have a SAML XML structure. The SAML version is 1.0. This is a slighly older version as SAML 1.1 is available.
* RequestType: The RST requested a token, so the request type is one of "issued."
* KeyType: The key inside the SAML token is symmetric.

The next few parts are fairly interesting:

* RequestedProofToken: This element contains a base64 encoded key. It is a "proof of possession" token that is used to sign the signature. It is unencrypted but does not need to be decoded from it's base64 format. This token is included as a \* BinarySecret which should only be used when Transport level security is available, which it is since HTTPS is being used.&#x20;
* RequestedAttachedReference/RequestedUnattachedReference: A token reference provides a "pointer" to the actual token. Embedding the actual token in the response message is optional in which case a token reference would provided that contains an Id to the token. The Id is issued by the server and is only valid on the server. In the case of MS CRM, the token is returned and a token references are provided. The Ids in each section are identical.
