Share via

How to: Create a Security Token Service

  • Article

A security token service implements the protocol defined in the WS-Trust specification. This protocol defines message formats and message exchange patterns for issuing, renewing, canceling, and validating security tokens. A given security token service provides one or more of these capabilities. This topic looks at the most common scenario: implementing token issuance.

Issuing Tokens

WS-Trust defines message formats, based on the RequestSecurityToken XML Schema definition language (XSD) schema element, and RequestSecurityTokenResponse XSD schema element for performing token issuance. In addition, it defines the associated Action Uniform Resource Identifiers (URIs). The action URI associated with the RequestSecurityToken message is https://schemas.xmlsoap.org/ws/2005/02/trust/RST/Issue. The action URI associated with the RequestSecurityTokenResponse message is https://schemas.xmlsoap.org/ws/2005/02/trust/RSTR/Issue.

Request Message Structure

The issue request message structure typically consists of the following items:

In addition, a couple of other items might be present:

  • Key material provided by the client.

  • Scope information that indicates the target service that the issued token will be used with.

The security token service uses the information in the issue request message when it constructs the Issue Response message.

Response Message Structure

The issue response message structure typically consists of the following items;

  • The issued security token, for example, a SAML 1.1 assertion.

  • A proof token associated with the security token. For symmetric keys, this is often an encrypted form of the key material.

  • References to the issued security token. Typically, the security token service returns a reference that can be used when the issued token appears in a subsequent message sent by the client and another that can be used when the token is not present in subsequent messages.

In addition, a couple of other items might be present:

  • Key material provided by the security token service.

  • The algorithm needed to compute the shared key.

  • Lifetime information for the issued token.

Processing Request Messages

The security token service processes the issue request by examining the various pieces of the request message and ensuring that it can issue a token that satisfies the request. The security token service must determine the following before it constructs the token to be issued:

  • The request really is a request for a token to be issued.

  • The security token service supports the requested token type.

  • The requester is authorized to make the request.

  • The security token service can meet the requester's expectations with respect to key material.

Two vital parts of constructing a token are determining what key to sign the token with and what key to encrypt the shared key with. The token needs to be signed so that when the client presents the token to the target service, that service can determine that the token was issued by a security token service that it trusts. The key material needs to be encrypted in such a way that the target service can decrypt that key material.

Signing a SAML assertion involves creating a SigningCredentials instance. The constructor for this class takes the following:

  • A SecurityKey for the key to use to sign the SAML assertion.

  • A string identifying the signature algorithm to use.

  • A string identifying the digest algorithm to use.

  • Optionally, a SecurityKeyIdentifier that identifies the key to use to sign the assertion.

Sub AddSigningCredentials(ByVal assertion As SamlAssertion, _
    ByVal signingKey As SecurityKey)
    Dim sc As New SigningCredentials(signingKey, _
    SecurityAlgorithms.RsaSha1Signature, SecurityAlgorithms.Sha1Digest)
    assertion.SigningCredentials = sc

End Sub

void AddSigningCredentials(SamlAssertion assertion, SecurityKey signingKey)
{
    SigningCredentials sc = new SigningCredentials(signingKey,
        SecurityAlgorithms.RsaSha1Signature, SecurityAlgorithms.Sha1Digest);
    assertion.SigningCredentials = sc;
}

Encrypting the shared key involves taking the key material and encrypting it with a key that the target service can use to decrypt the shared key. Typically, the public key of the target service is used.

Function EncryptKey(ByVal plainTextKey() As Byte, _
        ByVal encryptingKey As SecurityKey) As Byte()
    Return encryptingKey.EncryptKey(SecurityAlgorithms.RsaOaepKeyWrap, plainTextKey)
End Function

byte[] EncryptKey(byte[] plainTextKey, SecurityKey encryptingKey)
{
    return encryptingKey.EncryptKey(SecurityAlgorithms.RsaOaepKeyWrap, plainTextKey);
}

In addition, a SecurityKeyIdentifier for the encrypted key is needed.

Function GetKeyIdentifierForEncryptedKey(ByVal encryptedKey() _
 As Byte, ByVal encryptingToken As SecurityToken) _
    As SecurityKeyIdentifier
    Dim encryptingKeyIdentifier As New SecurityKeyIdentifier( _
        encryptingToken.CreateKeyIdentifierClause(Of X509ThumbprintKeyIdentifierClause)())
    Return New SecurityKeyIdentifier(New EncryptedKeyIdentifierClause( _
        encryptedKey, SecurityAlgorithms.RsaOaepKeyWrap, encryptingKeyIdentifier))
End Function

SecurityKeyIdentifier GetKeyIdentifierForEncryptedKey(byte[] encryptedKey,
    SecurityToken encryptingToken)
{
    SecurityKeyIdentifier encryptingKeyIdentifier = new SecurityKeyIdentifier(encryptingToken.CreateKeyIdentifierClause<X509ThumbprintKeyIdentifierClause>());
    return new SecurityKeyIdentifier(new EncryptedKeyIdentifierClause(encryptedKey, SecurityAlgorithms.RsaOaepKeyWrap, encryptingKeyIdentifier));

}

This SecurityKeyIdentifier is then used to create a SamlSubject as part of the SamlToken.

Function CreateSamlSubjectForProofKey( _
    ByVal proofKeyIdentifier As SecurityKeyIdentifier) As SamlSubject
    Dim confirmations As List(Of String) = New List(Of String)()
    confirmations.Add("urn:oasis:names:tc:SAML:1.0:cm:holder-of-key")
    Return New SamlSubject(Nothing, Nothing, "IssuerName", _
        confirmations, Nothing, proofKeyIdentifier)
End Function

SamlSubject CreateSamlSubjectForProofKey(SecurityKeyIdentifier proofKeyIdentifier)
{
    List<string> confirmations = new List<string>();

    confirmations.Add("urn:oasis:names:tc:SAML:1.0:cm:holder-of-key");

    return new SamlSubject(null, null, "IssuerName", confirmations, null, proofKeyIdentifier);
}

For more information, see Federation Sample.

Creating Response Messages

Once the security token service processes the issue request and constructs the token to be issued along with the proof key, the response message needs to be constructed, including at least the requested token, the proof token, and the issued token references. The issued token is typically a SamlSecurityToken created from the SamlAssertion, as shown in the following example.

Function CreateIssuedToken(ByVal assertion As SamlAssertion) As SecurityToken
    Return New SamlSecurityToken(assertion)
End Function

SecurityToken CreateIssuedToken(SamlAssertion assertion)
{
    return new SamlSecurityToken(assertion);
}

In the case where the security token service provides the shared key material, the proof token is constructed by creating a BinarySecretSecurityToken.

Function CreateProofToken(ByVal proofKey() As Byte) As BinarySecretSecurityToken
    Return New BinarySecretSecurityToken(proofKey)

End Function

BinarySecretSecurityToken CreateProofToken(byte[] proofKey)
{
    return new BinarySecretSecurityToken(proofKey);
}

For more information about how to construct the proof token when the client and the security token service both provide key material for the shared key, see Federation Sample.

The issued token references are constructed by creating instances of the SecurityKeyIdentifierClause class.

Function CreateTokenReference(ByVal token As SamlSecurityToken) _
    As SecurityKeyIdentifierClause
    Return token.CreateKeyIdentifierClause( _
    Of SamlAssertionKeyIdentifierClause)()
End Function

SecurityKeyIdentifierClause CreateTokenReference(SamlSecurityToken token)
{
    return token.CreateKeyIdentifierClause<SamlAssertionKeyIdentifierClause>();
}

These various values are then serialized into the response message returned to the client.

Example

For full code for a security token service, see Federation Sample.

See Also

Reference

SigningCredentials
SecurityKey
SecurityKeyIdentifier
SamlSecurityToken
SamlAssertion
BinarySecretSecurityToken
SecurityKeyIdentifierClause

Other Resources

Federation Sample