SecurityToken 類別
定義
重要
部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。
表示用來實作所有安全性權杖的基底類別。
public ref class SecurityToken abstractpublic abstract class SecurityTokentype SecurityToken = classPublic MustInherit Class SecurityToken- 繼承
-
SecurityToken
- 衍生
範例
主題中使用的 SecurityToken 程式代碼範例取自 Custom Token 範例。 此範例提供自定義類別，可讓您處理簡單 Web 令牌 (SWT) 。 它包含類別和SimpleWebTokenHandler類別的實作SimpleWebToken，以及支援 SWT 令牌的其他類別。 如需此範例和其他可供 WIF 使用之範例以及下載位置的相關信息，請參閱 WIF 程式代碼範例索引。 下列程式代碼顯示 類別的實作 SimpleWebToken 。 這個類別會 SecurityToken擴充 。
/// <summary>
/// Defines the set of constants for the Simple Web Token.
/// </summary>
public static class SimpleWebTokenConstants
{
public const string Audience = "Audience";
public const string ExpiresOn = "ExpiresOn";
public const string Id = "Id";
public const string Issuer = "Issuer";
public const string Signature = "HMACSHA256";
public const string ValidFrom = "ValidFrom";
public const string ValueTypeUri = "http://schemas.xmlsoap.org/ws/2009/11/swt-token-profile-1.0";
}
using System;
using System.Collections.Generic;
using System.Collections.ObjectModel;
using System.Collections.Specialized;
using System.IdentityModel.Tokens;
namespace SimpleWebToken
{
/// <summary>
/// This class represents the token format for the SimpleWebToken.
/// </summary>
public class SimpleWebToken : SecurityToken
{
public static DateTime SwtBaseTime = new DateTime( 1970, 1, 1, 0, 0, 0, 0 ); // per SWT psec
NameValueCollection _properties;
string _serializedToken;
/// <summary>
/// Initializes a new instance of the <see cref="SimpleWebToken"/> class.
/// This is an internal constructor that is only called from the <see cref="SimpleWebTokenHandler"/> when reading a token received from the wire.
/// </summary>
/// <param name="properties">The collection representing all the key value pairs in the token.</param>
/// <param name="serializedToken">The serialized form of the token.</param>
internal SimpleWebToken( NameValueCollection properties, string serializedToken )
: this(properties)
{
_serializedToken = serializedToken;
}
/// <summary>
/// Initializes a new instance of the <see cref="SimpleWebToken"/> class.
/// </summary>
/// <param name="properties">The collection representing all the key value pairs in the token.</param>
public SimpleWebToken( NameValueCollection properties )
{
if ( properties == null )
{
throw new ArgumentNullException( "properties" );
}
_properties = properties;
}
/// <summary>
/// Gets the Id of the token.
/// </summary>
/// <value>The Id of the token.</value>
public override string Id
{
get
{
return _properties[SimpleWebTokenConstants.Id];
}
}
/// <summary>
/// Gets the keys associated with this token.
/// </summary>
/// <value>The keys associated with this token.</value>
public override ReadOnlyCollection<SecurityKey> SecurityKeys
{
get
{
return new ReadOnlyCollection<SecurityKey>( new List<SecurityKey>() );
}
}
/// <summary>
/// Gets the time from when the token is valid.
/// </summary>
/// <value>The time from when the token is valid.</value>
public override DateTime ValidFrom
{
get
{
string validFrom = _properties[SimpleWebTokenConstants.ValidFrom];
return GetTimeAsDateTime( String.IsNullOrEmpty( validFrom ) ? "0" : validFrom );
}
}
/// <summary>
/// Gets the time when the token expires.
/// </summary>
/// <value>The time up to which the token is valid.</value>
public override DateTime ValidTo
{
get
{
string expiryTime = _properties[SimpleWebTokenConstants.ExpiresOn];
return GetTimeAsDateTime( String.IsNullOrEmpty( expiryTime ) ? "0" : expiryTime );
}
}
/// <summary>
/// Gets the Audience for the token.
/// </summary>
/// <value>The audience of the token.</value>
public string Audience
{
get
{
return _properties[SimpleWebTokenConstants.Audience];
}
}
/// <summary>
/// Gets the Issuer for the token.
/// </summary>
/// <value>The issuer for the token.</value>
public string Issuer
{
get
{
return _properties[SimpleWebTokenConstants.Issuer];
}
}
/// <summary>
/// Gets the signature for the token.
/// </summary>
/// <value>The signature for the token.</value>
public string Signature
{
get
{
return _properties[SimpleWebTokenConstants.Signature];
}
}
/// <summary>
/// Gets the serialized form of the token if the token was created from its serialized form by the token handler.
/// </summary>
/// <value>The serialized form of the token.</value>
public string SerializedToken
{
get
{
return _serializedToken;
}
}
/// <summary>
/// Creates a copy of all key value pairs of the token.
/// </summary>
/// <returns>A copy of all the key value pairs in the token.</returns>
public NameValueCollection GetAllProperties()
{
return new NameValueCollection( _properties );
}
/// <summary>
/// Converts the time in seconds to a <see cref="DateTime"/> object based on the base time
/// defined by the Simple Web Token.
/// </summary>
/// <param name="expiryTime">The time in seconds.</param>
/// <returns>The time as a <see cref="DateTime"/> object.</returns>
protected virtual DateTime GetTimeAsDateTime( string expiryTime )
{
long totalSeconds = 0;
if ( !long.TryParse( expiryTime, out totalSeconds ) )
{
throw new SecurityTokenException("Invalid expiry time. Expected the time to be in seconds passed from 1 January 1970.");
}
long maxSeconds = (long)( DateTime.MaxValue - SwtBaseTime ).TotalSeconds - 1;
if ( totalSeconds > maxSeconds )
{
totalSeconds = maxSeconds;
}
return SwtBaseTime.AddSeconds( totalSeconds );
}
}
}
備註
使用安全性權杖，提供驗證認證或保護訊息。
安全性令牌可用來提供驗證認證、密碼編譯密鑰數據，或在安全性令牌服務所發行的安全性令牌的情況下， (STS) ，這是關於主體的宣告集合。 所有安全性令牌都衍生自 SecurityToken 類別。
從 .NET 4.5 開始，Windows Identity Foundation (WIF) 已完全整合到 .NET Framework，而且 WIF 公開的類別是處理程式代碼中安全性令牌的慣用方法。 在 WIF 中，安全性令牌會串行化及還原串行化為其 XML 表示法，並使用衍生自基類的類別進行 SecurityTokenHandler 驗證。 驗證令牌不僅牽涉到確保令牌有效，也會從可用於進行驗證和授權決策的令牌傳回 ClaimsIdentity 實例。 是由 ClaimsIdentity 令牌處理程式的方法實 ValidateToken 作所建構，這些宣告來自令牌中包含的宣告，以及令牌類型本身內建的宣告。
WIF 隨附下列安全性令牌類型的支援：
Saml2SecurityToken：表示以 SAML 2.0 判斷提示為基礎的安全性令牌。 此令牌類型通常是由安全性令牌服務發出，以回應 WS-Trust 或 WS-Federation 安全性令牌要求 (RST) 。
SamlSecurityToken：表示以 SAML 1.1 判斷提示為基礎的安全性令牌。 此令牌類型通常是由安全性令牌服務發出，以回應 WS-Trust 或 WS-Federation 安全性令牌要求 (RST) 。
KerberosRequestorSecurityToken 和 KerberosReceiverSecurityToken：代表以 SOAP 訊息中接收或傳送的 Kerberos 票證為基礎的安全性令牌
RsaSecurityToken：表示以使用 RSA 演算法建立之金鑰為基礎的安全性令牌。
SessionSecurityToken：表示包含會話相關信息的安全性令牌。
UserNameSecurityToken：表示以使用者名稱和密碼為基礎的安全性令牌。
WindowsSecurityToken：表示以 Windows 網域或用戶帳戶身分識別為基礎的安全性令牌。
X509SecurityToken：表示以 X.509 憑證為基礎的安全性令牌。
X509WindowsSecurityToken：表示以對應至 Windows 網域使用者或本機計算機用戶帳戶之 X.509 憑證為基礎的安全性令牌。
另外兩個安全性令牌類別 GenericXmlSecurityToken 和 EncryptedSecurityToken可用來協助處理一般案例。
大致來說，安全性令牌分為三個主要類別：
包含或參考密碼編譯金鑰數據的令牌。 例如， RsaSecurityToken 和 X509SecurityToken 型別通常用於此用途。
代表已驗證之用戶的認證令牌。 例如，在 UserNameSecurityToken使用憑證驗證的使用者案例中，、 WindowsSecurityToken和 是型別 X509SecurityToken 。
安全性令牌服務所發行的令牌 (STS) ，以回應使用 WS-Trust 或 WS-Federation 通訊協定的安全性令牌要求。 這些通常會在 XML 片段中
wst:RequestSecurityTokenResponse傳回。 Saml2SecurityToken和 SamlSecurityToken 類型最常用來表示這些令牌。
特殊令牌類型 ， SessionSecurityToken包含在使用主動或被動案例中的會話時，重新建立主體所需的資訊。
若要將功能新增至現有的令牌類型，您可以衍生自特定類型及其相關聯的令牌處理程式，以支援您新增至令牌的任何新元素。 若要新增對新令牌類型的支援，您可以直接從 SecurityToken 類別衍生。 當您這樣做時，您也需要從 類別衍生來 SecurityTokenHandler 建立令牌處理程序類別。 根據令牌的使用方式，您可能也需要藉由衍生自 IssuerTokenResolver 類別，以及衍生 SecurityKeyIdentifierClause 自 類別的一或多個自定義密鑰標識子句類型來建立自定義令牌解析程式。
給實施者的注意事項
您必須覆寫 Id、 SecurityKeys、 ValidFrom和 ValidTo 屬性。 CanCreateKeyIdentifierClause<T>()、 CreateKeyIdentifierClause<T>()、 MatchesKeyIdentifierClause(SecurityKeyIdentifierClause)以及 ResolveKeyIdentifierClause(SecurityKeyIdentifierClause) 方法全都支援 類型的LocalIdKeyIdentifierClause金鑰識別碼。 您必須覆寫這些方法，以支援衍生類別中的其他密鑰標識碼類型。
建構函式
| SecurityToken() |
由衍生類別的建構函式呼叫，以初始化 SecurityToken 類別。 |
屬性
| Id |
取得安全性權杖的唯一識別碼。 |
| SecurityKeys |
取得與安全性權杖相關聯的密碼編譯金鑰。 |
| ValidFrom |
取得這個安全性權杖有效的第一個瞬間。 |
| ValidTo |
取得這個安全性權杖有效的最後一個瞬間。 |
方法
| CanCreateKeyIdentifierClause<T>() |
取得值，這個值會指出這個安全性權杖是否能夠建立指定的金鑰識別碼。 |
| CreateKeyIdentifierClause<T>() |
建立指定的金鑰識別碼子句。 |
| Equals(Object) |
判斷指定的物件是否等於目前的物件。 (繼承來源 Object) |
| GetHashCode() |
做為預設雜湊函式。 (繼承來源 Object) |
| GetType() |
取得目前執行個體的 Type。 (繼承來源 Object) |
| MatchesKeyIdentifierClause(SecurityKeyIdentifierClause) |
傳回值，這個值會指出這個執行個體的金鑰識別碼是否能夠解析為指定的金鑰識別碼。 |
| MemberwiseClone() |
建立目前 Object 的淺層複製。 (繼承來源 Object) |
| ResolveKeyIdentifierClause(SecurityKeyIdentifierClause) |
取得指定之金鑰識別碼子句的金鑰。 |
| ToString() |
傳回代表目前物件的字串。 (繼承來源 Object) |
