SecurityTokenService.Issue Method

  • Article

[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.]

Issues a security token.

Namespace: Microsoft.IdentityModel.SecurityTokenService
Assembly: Microsoft.IdentityModel (in Microsoft.IdentityModel.dll)

Usage

'Usage
Dim instance As SecurityTokenService
Dim principal As IClaimsPrincipal
Dim request As RequestSecurityToken
Dim returnValue As RequestSecurityTokenResponse

returnValue = instance.Issue(principal, request)

Syntax

'Declaration
Public Overridable Function Issue ( _
    principal As IClaimsPrincipal, _
    request As RequestSecurityToken _
) As RequestSecurityTokenResponse

public virtual RequestSecurityTokenResponse Issue (
    IClaimsPrincipal principal,
    RequestSecurityToken request
)

public:
virtual RequestSecurityTokenResponse^ Issue (
    IClaimsPrincipal^ principal, 
    RequestSecurityToken^ request
)

public RequestSecurityTokenResponse Issue (
    IClaimsPrincipal principal, 
    RequestSecurityToken request
)

public function Issue (
    principal : IClaimsPrincipal, 
    request : RequestSecurityToken
) : RequestSecurityTokenResponse

Parameters

  • principal
    An IClaimsPrincipal that represents the identity of the token requestor.
  • request
    A RequestSecurityToken that represents the security token request. This includes the request message as well as other client related information such as authorization context.

Return Value

A RequestSecurityTokenResponse that contains the issued security token.

Remarks

This method implements the Issue binding defined in the WS-Trust specification. The default implementation of the Issue method processes the incoming request (RST) through a token issuance (claims issuance) pipeline and returns either a response (RSTR) that contains a security token with the appropriate claims to authenticate the requestor with the RP or an appropriate exception. The token issuance pipeline in the default implementation consists of calls to the following methods (of the SecurityTokenService class).

  1. The ValidateRequest method to validate the request (RST).

  2. The GetScope method to get a Scope object that contains information about the relying party (RP) associated with the request. You must override this method.

  3. The CreateSecurityTokenDescriptor method to return a security token descriptor based on the RST. The security token descriptor (SecurityTokenDescriptor) contains information about the request in a form that can be used by a token handler.

  4. The GetSecurityTokenHandler method to get the appropriate token handler based on the kind of token requested.

  5. The GetIssuerName method to get the issuer name for the token.

  6. The GetTokenLifetime method to get the lifetime for the token.

  7. The GetProofToken method to get the proof token to include in the issued token.

  8. The GetOutputClaimsIdentity method to get the claims to include in the issued token. You must override this method.

  9. The GetDisplayToken method to get the display token for the issued token.

  10. The GetResponsemethod to create a response (RSTR) that contains the issued token.

You can override the Issue method to implement a custom token issuance pipeline; however this is typically not necessary in the development and test environments for which most custom implementations of the SecurityTokenService class are intended. In many of these cases you override the GetOutputClaimsIdentity and GetScope methods and optionally override the ValidateRequest method (as in the Visual Studio STS template) to provide a serviceable STS for your environment. If further customization is necessary you can often provide it by overriding the methods that implement each stage of the default token issuance pipeline listed above.

For more information about the token issuance pipeline, see the Claims Issuance Pipeline topic.

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)

See Also

Reference

SecurityTokenService Class
SecurityTokenService Members
Microsoft.IdentityModel.SecurityTokenService Namespace

Other Resources

Claims Provider - Security Token Service
Claims Issuance Pipeline

Copyright © 2008 by Microsoft Corporation. All rights reserved.