Request Security Token (RST) Needs
Let's look at a token template from the MS CRM Discovery Service WSDL for an on-premise IFD deployment. The WSDL is the document uses that client's access to determine how to authenticate. Obviously, it must be coordinated with the requirements that the ADFS server advertises. The token template describes the return type of the token once a token is issued. The fragment below comes from the IssuedToken policy section and indicates the format of the issued token. Hence, this fragment describes what the response (RSTR) will look like once you issue a Request Security Token (RST) message. The "sp" namespace maps to http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702 which indicates that it maps to the WS-SecurityPolicy specification. If you read WS_SecurityPolicy, it states that the contents inside of a RequestSecurityTokenTemplate element are governed by the WS-Trust specification.
The fragment is:
We can break this down fairly directly by looking at the WS-Trust specification and converting most of the markup into a table and dropping some of the verbose namespacing:
We first notice that much of the policy is related to encryption and signing which are, of course, important aspects of WSS. The "xmlenc" and "xmldsig" in the configuration values indicate that the configuration parameters belongs to the java XML encryption and digital signatures standards. These are allowed parameters and values because the WS-Trust specification says they are valid values. The actual token type is going to be SAML, but that information is not specified here. The information describes how the SAML token will be communicated e.g. its encrypted and signed. The SAML token will contain a key as indicated by KeyType, in this case a symmetric key.
EncryptWith/SignWith indicate that the issued security token is to be encrypted and signed. Because signing and encrypting are two distinct processing steps (which need to happen in a specific order) and that there are many different signing and encrypting approaches, the specific approaches need to be specified. Most of the remaining parameters provide these details. As a side note, the canonicalization algorithm is needed because signing is highly sensitive to the specific byte layout of the data to be signed. A single character difference leads to different signature values. XML is not sensitive to whitespace between elements so depending on how a system might output an XML string for the body of an HTML request, the signature could be different on the sending and receiving ends. The canonicalization method specified a very specific approach to formatting the XML so that the signature will be the same assuming the same signature algorithm is used. The "xml-enc-c14n" is a specific algorithm that you can read about in the XML encryption specification: https://www.w3.org/TR/xmlenc-core/#sec-Algorithms.
EncryptWith indicates that encryption that is used to encrypt the actual response. EncryptionAlgorithm refers to the encryption used inside the token itself e.g. if the token returns a key, that key could be encrypted. EncryptWith is all about the actual response message. In this case, the encryption for the response is the same as the encryption request inside the actual token—a bit confusing but an artifact of using this as an example. The parameter value is "http://www.w3.org/2001/04/xmlenc#aes256-cbc" which says to use the AES encryption with a 256 bit key.
The encrypted contents will be included in the RSTR that holds the token using a XML encryption standard specified set of XML elements that look roughly like:
The actual content itself is contained in the CipherValue element. The KeyInfo is included because decryption requires a key. At first it seems strange that the Key is included along with the actual encrypted content, but the KeyInfo may not be the actual key itself but a description of how to find the actual key. Key information could be a name and public key which forms a digital certificate. The decryption key may itself be encrypted is is the case with MS CRM SOAP messages. The algorithm used to decrypt the decryption key is specified in KeyWrapAlgorithm which in this case is "http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p." A KeyWrap uses symettric encryption to encapsulate cryptographic key material (from Wikipedia) when communicated over untrusted communication networks. To decrypt this type of key in MS CRM, the algorithm requires a specific digest method which will be specified in the token response and the CipherValue. For MS CRM this turns out to be SHA1.
Signature occurs using the HMAC-SHA1 algorithm which is described in the XML signature specification: https://www.w3.org/TR/xmldsig-core with algorithm details in RFCs referenced in the xmldsig specification. As mentioned above, a signature algorithm requires a hash function and a key so in the following sections, we need to identify which hash function (SHA1 in this case) and what key is used to be part of the HMAC-SHA1 calculation.
The Claims parameter specifies the type of claims that are required for authentication. The focus should be on ClaimType as the dialect indicates what syntax the ClaimType takes—in this case a URI indicating the claim type. The ClaimType says that a UPN mast be provided. However, as other sections of this document have pointed out, MS CRM typically passes in a username (username plus domain similar to an email address) and a password, not a UPN. Strictly, we should pass in a UPN to be authenticated but because the ADFS server can take a "claim" and transform it into another "claim" we can actually configure ADFS to receive a username-domain/password combination and have that automatically translated into a UPN claim. That's when you setup ADFS for on-premise IFD deployment you setup a few critical claims transform rules. Knowing that those that transformation rules exist allows us to provide a different claim for the identity when we send the RST (Request Security Token) message.
From the WSDL, we know the following about the returned token information:
The actual key will be a symmetric key.
The key itself will be encrypted and signed.
The message will also have encrypted and signatures.
The key for decrypting the message level security will be wrapped.
Last updated