SecurityTokenService.GetScope Method

Article
10/05/2012

[Starting with the .NET Framework 4.5, Windows Identity Foundation (WIF) has been fully integrated into the .NET Framework. The version of WIF addressed by this topic, WIF 3.5, is deprecated and should only be used when developing against the .NET Framework 3.5 SP1 or the .NET Framework 4. For more information about WIF in the .NET Framework 4.5, also known as WIF 4.5, see the Windows Identity Foundation documentation in the .NET Framework 4.5 Development Guide.]

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: Microsoft.IdentityModel.SecurityTokenService
Assembly: Microsoft.IdentityModel (in Microsoft.IdentityModel.dll)

Usage

'Usage
Dim principal As IClaimsPrincipal
Dim request As RequestSecurityToken
Dim returnValue As Scope

returnValue = Me.GetScope(principal, request)

Syntax

'Declaration
Protected MustOverride Function GetScope ( _
    principal As IClaimsPrincipal, _
    request As RequestSecurityToken _
) As Scope

protected abstract Scope GetScope (
    IClaimsPrincipal principal,
    RequestSecurityToken request
)

protected:
virtual Scope^ GetScope (
    IClaimsPrincipal^ principal, 
    RequestSecurityToken^ request
) abstract

protected abstract Scope GetScope (
    IClaimsPrincipal principal, 
    RequestSecurityToken request
)

protected abstract function GetScope (
    principal : IClaimsPrincipal, 
    request : RequestSecurityToken
) : Scope

Parameters

principal
A Microsoft.IdentityModel.Claims.IClaimsPrincipal that represents the client making the request.

request
A RequestSecurityToken that represents the incoming request (RST).

Return Value

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

Example

The following code example shows an implementation of the GetScope method. This implementation verifies that the RP is recognized by the STS and sets the encrypting credentials to use with the RP based on the certificate of the AppliesTo identity in the request. The signing credentials are provided through configuration. The GetOutputClaimsIdentity method is is not shown in this example, but you would need to override this method as well in your STS.

using System;
using System.ServiceModel;

using Microsoft.IdentityModel.Claims;
using Microsoft.IdentityModel.Configuration;
using Microsoft.IdentityModel.Protocols.WSTrust;
using Microsoft.IdentityModel.SecurityTokenService;

namespace ClaimsAwareWebService
{
    public class MySecurityTokenService : SecurityTokenService
    {
        const string addressExpected = "https://localhost:6020/ClaimsAwareWebService";
        const string encryptingCertificateName = "CN=localhost";

        // NOTE: The GetOutputClaimsIdentity method is omitted from this example. You must override 
        // this method in your custom STS.


        /// <summary>
        /// Creates an instance of the MySecurityTokenService class.
        /// </summary>
        /// <param name="configuration">SecurityTokenServiceConfiguration element.</param>
 
        public MySecurityTokenService( SecurityTokenServiceConfiguration configuration )
            : base( configuration )
        {
        }

        /// <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 CN=localhost.
        /// </summary>
        /// <param name="principal">The caller's principal</param>
        /// <param name="request">The incoming RST</param>
        /// <returns>The configuration for the token issuance request.</returns>
        protected override Scope GetScope( IClaimsPrincipal principal, RequestSecurityToken request )
        {
            // Validate the AppliesTo on the incoming request
            ValidateAppliesTo( request.AppliesTo );

            // Normally the STS will have a trust relationship with the RP and can look up a trusted encrypting certficate 
            // using the AppliesTo endpoint. This is necessary to ensure that only the RP will be able to read the claims.
            //
            // In this sample the certificate of the AppliesTo Identity is used to encrypt the contents, so there is no
            // validation of any trust relationship with the RP. Since the certificate is not validated, 
            // a malicious client can provide a known certificate allowing it to read the returned claims.
            // For this reason, THIS APPROACH SHOULD NOT BE USED if the claims should be kept private. It may be reasonable,
            // though, if the STS is simply verifying public information such as the client's email address.

            // Get RP certificate
            X509CertificateEndpointIdentity appliesToIdentity = (X509CertificateEndpointIdentity)request.AppliesTo.Identity;

            X509EncryptingCredentials encryptingCredentials = new X509EncryptingCredentials( appliesToIdentity.Certificates[0] );
            // Create the scope using the request AppliesTo address and the STS signing certificate
            Scope scope = new Scope( request.AppliesTo.Uri.AbsoluteUri, SecurityTokenServiceConfiguration.SigningCredentials, encryptingCredentials );
            return scope;
        }

        /// <summary>
        /// Validates the appliesTo and throws an exception if the appliesTo is null or appliesTo contains some unexpected address.  
        /// </summary>
        void ValidateAppliesTo( EndpointAddress appliesTo )
        {
            if ( appliesTo == null )
            {
                throw new InvalidRequestException( "The appliesTo is null." );
            }

            if ( !appliesTo.Uri.Equals( new Uri( addressExpected ) ) )
            {
                Console.WriteLine( "The relying party address is not valid. " );
                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. The default Visual Studio template merely compares the appliesTo address in the request to an array that contains the URLs of recognized RPs. 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.

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.

For more information about the GetScope method, see Building an STS. For information specifically about the token (claims) issuance pipeline, see Claims Issuance Pipeline.

All of the Windows® Identity Foundation (WIF) samples contain custom STS implementations. For examples of simple STS implementations, see the samples in the Quick Start directory. For examples of more complicated STS implementations, including STSs used in delegation and federation scenarios, see the samples in the End-to-end and Extensibility directories.

Notes to Inheritors: You must override this method in your implementation of the SecurityTokenService class.

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Platforms

Target Platforms

Windows 7, Windows Server 2008 R2, Windows Vista SP2, Windows Server 2008 SP2, Windows Server 2003 SP2 (32-bit or 64-bit)

SecurityTokenService.GetScope Method

Usage

Syntax

Parameters

Return Value

Example

Remarks

Thread Safety

Platforms

Target Platforms

Change History

See Also

Reference

Other Resources

Additional resources