SecurityTokenService.Issue(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.

Issues a security token.

public:
 virtual System::IdentityModel::Protocols::WSTrust::RequestSecurityTokenResponse ^ Issue(System::Security::Claims::ClaimsPrincipal ^ principal, System::IdentityModel::Protocols::WSTrust::RequestSecurityToken ^ request);

public virtual System.IdentityModel.Protocols.WSTrust.RequestSecurityTokenResponse Issue (System.Security.Claims.ClaimsPrincipal principal, System.IdentityModel.Protocols.WSTrust.RequestSecurityToken request);

abstract member Issue : System.Security.Claims.ClaimsPrincipal * System.IdentityModel.Protocols.WSTrust.RequestSecurityToken -> System.IdentityModel.Protocols.WSTrust.RequestSecurityTokenResponse
override this.Issue : System.Security.Claims.ClaimsPrincipal * System.IdentityModel.Protocols.WSTrust.RequestSecurityToken -> System.IdentityModel.Protocols.WSTrust.RequestSecurityTokenResponse

Public Overridable Function Issue (principal As ClaimsPrincipal, request As RequestSecurityToken) As RequestSecurityTokenResponse

Parameters

principal: ClaimsPrincipal

A ClaimsPrincipal that represents the identity of the token requestor.

request: RequestSecurityToken

A RequestSecurityToken that represents the security token request. This includes the request message as well as other client related information such as authorization context.

Returns

RequestSecurityTokenResponse

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).

The ValidateRequest method to validate the request (RST).
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. If GetScope returns null, a InvalidOperationException is thrown.
The CreateSecurityTokenDescriptor method to return a security token descriptor based on the RST and the Scope object returned in the previous step. The security token descriptor (SecurityTokenDescriptor) contains information about the request in a form that can be used by a token handler. The SecurityTokenService.SecurityTokenDescriptor property is set to the descriptor returned by the call. If null is returned or if the SigningCredentials property of the descriptor is null, an InvalidOperationException is thrown. The exception is also thrown if the Scope.TokenEncryptionRequired property is true but the EncryptingCredentials property on the returned descriptor is null.
The GetSecurityTokenHandler method to get the appropriate token handler based on the kind of token requested. If null is returned, a NotImplementedException is thrown.
The GetIssuerName method to get the issuer name for the token. Throws an InvalidOperationException if the name is null or empty; otherwise sets the TokenIssuerName property on the descriptor.
The GetTokenLifetime method to get the lifetime for the token and sets the Lifetime property on the descriptor.
The GetProofToken method to get the proof token to include in the issued token and sets the Proof property on the descriptor.
The GetOutputClaimsIdentity method to get the claims to include in the issued token and sets the Subject property on the descriptor. You must override this method.
The GetResponse method 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 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.

Applies to

Share via