作法：建立安全性權杖服務

發行項
03/03/2024

安全性權杖服務實作於 WS-Trust 規格定義的通訊協定。此通訊協定定義用來核發、更新、取消及驗證安全性權杖的訊息格式以及訊息交換模式。指定的安全性權杖服務提供一個或一個以上的這些功能。此主題檢視最常見的狀況：實作權杖核發。

核發權杖

WS-Trust 根據 RequestSecurityToken XML Schema 定義語言 (XSD) 結構描述項目以及執行權杖核發的 RequestSecurityTokenResponse XSD 結構描述項目，定義訊息的格式。除此之外，它還定義關聯的動作統一資源識別源 (URI)。與 RequestSecurityToken 訊息相關聯的動作 URI 為 http://schemas.xmlsoap.org/ws/2005/02/trust/RST/Issue。與 RequestSecurityTokenResponse 訊息相關聯的動作 URI 為 http://schemas.xmlsoap.org/ws/2005/02/trust/RSTR/Issue。

要求訊息結構

發出要求訊息結構通常包括下列項目：

值為 http://schemas.xmlsoap.org/ws/2005/02/trust/Issue 的要求類型 URI。
語彙基元型別 URI。若是安全性聲明標記語言 (SAML) 1.1 權杖，此 URI 的值為 http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1。
此金鑰大小值表示關聯於核發之權杖的金鑰位元數。
金鑰型別 URI。若是對稱金鑰，此 URI 的值為 http://schemas.xmlsoap.org/ws/2005/02/trust/SymmetricKey。

此外，也許存在一些其他項目：

用戶端提供的金錀資料。
表示將使用已發行權杖之目標服務的範圍資訊。

安全性權杖服務在建構發出回應 (Issue Response) 訊息時，使用發出要求訊息內的資訊。

回應訊息結構

發出回應訊息結構通常包括下列項目：

例如，核發的安全性權杖為 SAML 1.1 判斷提示。
與安全性權杖相關聯的證明權杖。就對稱金鑰而言，這經常是金鑰資料的加密格式。
核發的安全性權杖的參照。一般而言，安全性權杖服務會於已核發權杖出現於用戶端發出的後續訊息時，傳回可使用的參照，以及另一個當後續訊息無權杖時可使用的參照。

此外，也許存在一些其他項目：

安全性權杖服務提供的金錀資料。
要計算共用金鑰所需的演算法。
核發權杖的存留期資訊。

處理要求訊息

安全性權杖服務檢查各個要求訊息以處理核發要求，並且確保能核發滿足要求的權杖。在建構要核發的權杖前，安全性權杖服務必須決定下列項目：

所謂要求其實是核發權杖的要求。
安全性權杖服務支援要求的權杖類型。
要求者獲得授權提出要求。
安全性權杖服務可滿足要求者對金鑰資料的期望。

建構權杖的兩個重要部分為決定要使用什麼金鑰簽署權杖，以及共用金鑰要用什麼金鑰加密。權杖需要簽署，這樣當用戶端對目標服務提出權杖時，該服務才能判斷此權杖是否為自己信賴之安全性權杖服務所核發的權杖。金鑰資料需要以目標服務能解密金鑰資料的方式進行加密。

簽署 SAML 判斷提示包括建立 SigningCredentials 執行個體。此類別的建構函式接受下列項目：

SecurityKey 用於金鑰簽署 SAML 判斷提示。
識別要使用之簽署演算法的字串。
識別要使用之摘要演算法的字串。
或者，SecurityKeyIdentifier 識別要用來簽署判斷提示的金鑰。

void AddSigningCredentials(SamlAssertion assertion, SecurityKey signingKey)
{
    SigningCredentials sc = new SigningCredentials(signingKey,
        SecurityAlgorithms.RsaSha1Signature, SecurityAlgorithms.Sha1Digest);
    assertion.SigningCredentials = sc;
}

Sub AddSigningCredentials(ByVal assertion As SamlAssertion, _
    ByVal signingKey As SecurityKey)
    Dim sc As New SigningCredentials(signingKey, _
    SecurityAlgorithms.RsaSha1Signature, SecurityAlgorithms.Sha1Digest)
    assertion.SigningCredentials = sc

End Sub

加密共用金鑰包含將金鑰資料以金鑰加密，目標服務能使用此金鑰解密共用金鑰。一般而言，會使用目標服務的公開金鑰。

byte[] EncryptKey(byte[] plainTextKey, SecurityKey encryptingKey)
{
    return encryptingKey.EncryptKey(SecurityAlgorithms.RsaOaepKeyWrap, plainTextKey);
}

Function EncryptKey(ByVal plainTextKey() As Byte, _
        ByVal encryptingKey As SecurityKey) As Byte()
    Return encryptingKey.EncryptKey(SecurityAlgorithms.RsaOaepKeyWrap, plainTextKey)
End Function

除此之外，加密金鑰還需要 SecurityKeyIdentifier。

SecurityKeyIdentifier GetKeyIdentifierForEncryptedKey(byte[] encryptedKey,
    SecurityToken encryptingToken)
{
    SecurityKeyIdentifier encryptingKeyIdentifier = new SecurityKeyIdentifier(encryptingToken.CreateKeyIdentifierClause<X509ThumbprintKeyIdentifierClause>());
    return new SecurityKeyIdentifier(new EncryptedKeyIdentifierClause(encryptedKey, SecurityAlgorithms.RsaOaepKeyWrap, encryptingKeyIdentifier));
}

Function GetKeyIdentifierForEncryptedKey(ByVal encryptedKey() _
 As Byte, ByVal encryptingToken As SecurityToken) _
    As SecurityKeyIdentifier
    Dim encryptingKeyIdentifier As New SecurityKeyIdentifier( _
        encryptingToken.CreateKeyIdentifierClause(Of X509ThumbprintKeyIdentifierClause)())
    Return New SecurityKeyIdentifier(New EncryptedKeyIdentifierClause( _
        encryptedKey, SecurityAlgorithms.RsaOaepKeyWrap, encryptingKeyIdentifier))
End Function

然後使用 SecurityKeyIdentifier 建立 SamlSubject 做為 SamlToken 的一部分。

SamlSubject CreateSamlSubjectForProofKey(SecurityKeyIdentifier proofKeyIdentifier)
{
    List<string> confirmations = new List<string>();

    confirmations.Add("urn:oasis:names:tc:SAML:1.0:cm:holder-of-key");

    return new SamlSubject(null, null, "IssuerName", confirmations, null, proofKeyIdentifier);
}

Function CreateSamlSubjectForProofKey( _
    ByVal proofKeyIdentifier As SecurityKeyIdentifier) As SamlSubject
    Dim confirmations As List(Of String) = New List(Of String)()
    confirmations.Add("urn:oasis:names:tc:SAML:1.0:cm:holder-of-key")
    Return New SamlSubject(Nothing, Nothing, "IssuerName", _
        confirmations, Nothing, proofKeyIdentifier)
End Function

如需詳細資訊，請參閱同盟範例。

建立回應訊息

一旦安全性權杖服務處理發出的要求，並且建構出要核發之權杖以及證明金鑰後，就需要建構回應訊息，至少包括要求的權杖、證明權杖以及核發的權杖參照。此核發的權杖一般而言是 SamlSecurityToken 自 SamlAssertion所建造，如以下範例所示。

SecurityToken CreateIssuedToken(SamlAssertion assertion)
{
    return new SamlSecurityToken(assertion);
}

Function CreateIssuedToken(ByVal assertion As SamlAssertion) As SecurityToken
    Return New SamlSecurityToken(assertion)
End Function

當安全性權杖服務提供共用金鑰資料時，證明權杖就是由建立 BinarySecretSecurityToken 加以建構。

BinarySecretSecurityToken CreateProofToken(byte[] proofKey)
{
    return new BinarySecretSecurityToken(proofKey);
}

Function CreateProofToken(ByVal proofKey() As Byte) As BinarySecretSecurityToken
    Return New BinarySecretSecurityToken(proofKey)

End Function

如需如何在用戶端和安全性權杖服務都提供共用金鑰的金鑰資料時建構證明權杖的詳細資訊，請參閱同盟範例。

核發的權杖參照以建立 SecurityKeyIdentifierClause 類別執行個體而建構。

SecurityKeyIdentifierClause CreateTokenReference(SamlSecurityToken token)
{
    return token.CreateKeyIdentifierClause<SamlAssertionKeyIdentifierClause>();
}

Function CreateTokenReference(ByVal token As SamlSecurityToken) _
    As SecurityKeyIdentifierClause
    Return token.CreateKeyIdentifierClause( _
    Of SamlAssertionKeyIdentifierClause)()
End Function

然後將這些不同的值序列化成回應訊息傳回用戶端。

範例

如需安全性權杖服務的完整程式碼，請參閱同盟範例。

共用方式為