SecurityTokenService.GetScope(ClaimsPrincipal, RequestSecurityToken) Method

Reference

Definition

Namespace:: System.IdentityModel

Assembly:: System.IdentityModel.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Gets a Scope object that contains information about the relying party (RP) associated with the specified request (RST). You must override this method in your implementation of the SecurityTokenService class.

protected:
 abstract System::IdentityModel::Scope ^ GetScope(System::Security::Claims::ClaimsPrincipal ^ principal, System::IdentityModel::Protocols::WSTrust::RequestSecurityToken ^ request);

protected abstract System.IdentityModel.Scope GetScope (System.Security.Claims.ClaimsPrincipal principal, System.IdentityModel.Protocols.WSTrust.RequestSecurityToken request);

abstract member GetScope : System.Security.Claims.ClaimsPrincipal * System.IdentityModel.Protocols.WSTrust.RequestSecurityToken -> System.IdentityModel.Scope

Protected MustOverride Function GetScope (principal As ClaimsPrincipal, request As RequestSecurityToken) As Scope

Parameters

principal: ClaimsPrincipal

A ClaimsPrincipal that represents the client making the request.

request: RequestSecurityToken

A RequestSecurityToken that represents the incoming request (RST).

Returns

Scope

A Scope that encapsulates the RP information associated with the request.

Examples

The code example that is used in this topic is taken from the Custom Token sample. This sample provides custom classes that enable processing of Simple Web Tokens (SWT) and it includes an implementation of a passive STS that is capable of serving an SWT token. For an example of how to implement an active STS, you can see the Federation Metadata sample. For information about these samples and other samples available for WIF and about where to download them, see WIF Code Sample Index.

The following code example shows an implementation of the GetScope method. This implementation verifies that the RP is recognized by the STS, validates the ReplyTo address in the request and sets the Scope.ReplyToAddress property accordingly, and sets the signing and encrypting credentials to use with the RP based on certificates that are hard-coded in the file.

// Certificate Constants
private const string SIGNING_CERTIFICATE_NAME = "CN=localhost";
private const string ENCRYPTING_CERTIFICATE_NAME = "CN=localhost";

private SigningCredentials _signingCreds;
private EncryptingCredentials _encryptingCreds;
// Used for validating applies to address, set to URI used in RP app of application, could also have been done via config
private string _addressExpected = "http://localhost:19851/";

/// <summary>
/// This method returns the configuration for the token issuance request. The configuration
/// is represented by the Scope class. In our case, we are only capable of issuing a token to a
/// single RP identity represented by the _encryptingCreds field.
/// </summary>
/// <param name="principal">The caller's principal</param>
/// <param name="request">The incoming RST</param>
/// <returns></returns>
protected override Scope GetScope(ClaimsPrincipal principal, RequestSecurityToken request)
{
    // Validate the AppliesTo address
    ValidateAppliesTo( request.AppliesTo );

    // Create the scope using the request AppliesTo address and the RP identity
    Scope scope = new Scope( request.AppliesTo.Uri.AbsoluteUri, _signingCreds );

    if (Uri.IsWellFormedUriString(request.ReplyTo, UriKind.Absolute))
    {
        if (request.AppliesTo.Uri.Host != new Uri(request.ReplyTo).Host)
            scope.ReplyToAddress = request.AppliesTo.Uri.AbsoluteUri;
        else
            scope.ReplyToAddress = request.ReplyTo;
    }
    else
    {
        Uri resultUri = null;
        if (Uri.TryCreate(request.AppliesTo.Uri, request.ReplyTo, out resultUri))
            scope.ReplyToAddress = resultUri.AbsoluteUri;
        else
            scope.ReplyToAddress = request.AppliesTo.Uri.ToString() ;
    }

    // Note: In this sample app only a single RP identity is shown, which is localhost, and the certificate of that RP is 
    // populated as _encryptingCreds
    // If you have multiple RPs for the STS you would select the certificate that is specific to 
    // the RP that requests the token and then use that for _encryptingCreds
    scope.EncryptingCredentials = _encryptingCreds;

    return scope;
}

/// <summary>
/// Validates the appliesTo and throws an exception if the appliesTo is null or appliesTo contains some unexpected address.
/// </summary>
/// <param name="appliesTo">The AppliesTo parameter in the request that came in (RST)</param>
/// <returns></returns>
void ValidateAppliesTo(EndpointReference appliesTo)
{
    if (appliesTo == null)
    {
        throw new InvalidRequestException("The appliesTo is null.");
    }

    if (!appliesTo.Uri.Equals(new Uri(_addressExpected)))
    {
        throw new InvalidRequestException(String.Format("The relying party address is not valid. Expected value is {0}, the actual value is {1}.", _addressExpected, appliesTo.Uri.AbsoluteUri));
    }
}

Remarks

The GetScope method is called from the token issuance pipeline after the ValidateRequest method and should return a Scope object configured for the incoming request. (The token issuance pipeline is implemented in the Issue method.) The Scope object encapsulates information about the RP associated with the security token request (RST). This includes information about the encrypting and signing credentials to be used with the RP and whether or not to encrypt any issued tokens and/or symmetric keys in the response. Some typical tasks performed in the GetScope method are:

Determine whether the RP for which the token is intended is a recognized RP. How this is accomplished depends on your implementation. If the intended RP is not a valid RP for this STS, then the method should throw an InvalidRequestException.
Determine the signing credentials to be used in the response (RSTR) and set the SigningCredentials property accordingly.
Determine whether the response and/or any included symmetrical keys should be encrypted and the credentials to be used for encryption. Set the TokenEncryptionRequired, SymmetricKeyEncryptionRequired, and EncryptingCredentials properties accordingly.

Important

By default, the TokenEncryptionRequired and SymmetricKeyEncryptionRequired properties are set true to prevent the STS from issuing tokens that are not secure. It is recommended that these properties never be set to false in a production environment.
Determine the address to which the response should be returned. Set either the AppliesToAddress or ReplyToAddress property accordingly.

Notes to Implementers

You must override this method in your implementation of the SecurityTokenService class.

Applies to