GetScope Method

SecurityTokenService.GetScope Method (ClaimsPrincipal, RequestSecurityToken)

.NET Framework 4.6 and 4.5

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.

Namespace:   System.IdentityModel
Assembly:  System.IdentityModel (in System.IdentityModel.dll)

protected abstract Scope GetScope(
	ClaimsPrincipal principal,
	RequestSecurityToken request


Type: System.Security.Claims.ClaimsPrincipal

A ClaimsPrincipal that represents the client making the request.

Type: System.IdentityModel.Protocols.WSTrust.RequestSecurityToken

A RequestSecurityToken that represents the incoming request (RST).

Return Value

Type: System.IdentityModel.Scope

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

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.

    System_CAPS_security Security Note

    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 Inheritors:

You must override this method in your implementation of the SecurityTokenServiceclass.

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;
            scope.ReplyToAddress = request.ReplyTo;
        Uri resultUri = null;
        if (Uri.TryCreate(request.AppliesTo.Uri, request.ReplyTo, out resultUri))
            scope.ReplyToAddress = resultUri.AbsoluteUri;
            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));

.NET Framework
Available since 4.5
Return to top
© 2015 Microsoft