方法: OAuth WRAP プロトコルを使用して ACS からトークンを要求する

適用対象

• Microsoft Azure Active Directory アクセス制御 (アクセス制御サービスまたは ACS)

概要

Web アプリケーションとサービスが ACS を使用して認証を処理する場合、クライアントは ACS によって発行されたセキュリティ トークンを取得して、アプリケーションまたはサービスにログインする必要があります。 この ACS 発行トークン (出力トークン) を取得するには、クライアントは ACS で直接認証するか、ID プロバイダーによって発行されたセキュリティ トークン (入力トークン) を ACS に送信する必要があります。 ACS は、この入力セキュリティ トークンを検証し、ACS ルール エンジンを介してこのトークン内の ID 要求を処理し、出力 ID 要求を計算し、出力セキュリティ トークンを発行します。

このトピックでは、OAuth WRAP プロトコルを使用して ACS からトークンを要求する方法について説明します。 OAuth WRAP プロトコル経由のすべてのトークン要求は、SSL 経由で送信されます。 ACS は、正しく書式設定されたトークン要求に応答して、OAuth WRAP プロトコルを介して常に簡易 Web トークン (SWT) を発行します。 OAuth WRAP プロトコル経由のすべてのトークン要求は、HTTP POST で ACS に送信されます。 HTTPS FORM POST を作成できる任意のプラットフォーム (.NET Framework、Windows Communication Foundation (WCF)、Silverlight、ASP.NET、Java、Python、Ruby、PHP、Flash などのプラットフォームから、OAuth WRAP プロトコルを介して ACS トークンを要求できます。

次の表に、OAuth WRAP プロトコルを介して ACS によって発行された SWT トークンを要求する 3 つのサポートされる方法を示します。

OAuth WRAP プロトコル経由で ACS からトークンを要求する 3 つの方法

トークン発行エンドポイント

OAuth WRAP プロトコルを介するすべての ACS トークン要求は、ACS トークン発行エンドポイントに送信されます。 このエンドポイントの URI は、Access Control名前空間によって異なります。 名前空間はトークン要求 URI に DNS 名のプレフィックスとして表示されます。 DNS 名の残りの部分はパスと同様に固定となります。 たとえば、"mysnservice" という名前のAccess Control名前空間からトークンを要求する場合は、トークン要求を次の URI https://mysnservice.accesscontrol.windows.net/WRAPv0.9に送信できます。

パスワード トークン要求

パスワード トークン要求を使用すると、クライアントは、認証のために OAuth WRAP プロトコルを使用して、サービス ID からユーザー名とパスワードを ACS に直接送信できます。 これは、OAuth WRAP プロトコルを使用して ACS からトークンを要求する最も簡単な方法です。 SSL 接続を確立する以外、この手法は暗号化機能を必要としません。 実際には、REST Web サービスで一般的なユーザー名/パスワードのモデルに似ています。 この種類のトークン要求は実際には HTTPS FORM POST です。 パスワード トークン要求のパラメーターはフォーム エンコードです。

「Mysnservice」という名前の名前空間にプレーン テキストを要求した例を次に示します。

POST /WRAPv0.9/ HTTP/1.1
Host: mysnservice.accesscontrol.windows.net
Content-Type: application/x-www-form-urlencoded

wrap_scope=http%3A%2F%2Fmysnservice.com%2Fservices%2F&
wrap_name=mysncustomer1&
wrap_password=5znwNTZDYC39dqhFOTDtnaikd1hiuRa4XaAj3Y9kJhQ%3D

次の表は、パスワード トークン要求に必要なパラメーターの名前、説明、値要件をまとめたものです。

これらのパラメーターの値は、ACS に要求を送信する前に URL エンコードする必要があります。 Web アプリケーションまたはサービスは 、wrap_scope の値をクライアントに提供できます。または、クライアントは 、wrap_scope パラメーターの値を Web アプリケーションまたはサービス リソース ターゲットの URI に設定することを決定できます。

OAuth WRAP プロトコルを介したパスワード トークン要求には、出力要求の計算プロセス中に ACS が使用できる追加のパラメーターを含めることもできます。 これらの追加のパラメーターの名前と値は URL エンコードする必要があり、値を引用符で囲むことは禁止されます。

パスワード トークン要求方法は を利用し、非常に簡単です。

WebClient client = new WebClient();
client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");

NameValueCollection values = new NameValueCollection();
values.Add("wrap_name", "mysncustomer1");
values.Add("wrap_password", "5znwNTZDYC39dqhFOTDtnaikd1hiuRa4XaAj3Y9kJhQ=");
values.Add("wrap_scope", "http://mysnservice.com/services");

// WebClient takes care of the URL Encoding
byte[] responseBytes = client.UploadValues("WRAPv0.9", "POST", values);

// the raw response from ACS
string response = Encoding.UTF8.GetString(responseBytes);

ACS から出力トークンをアンパックして Web アプリケーションまたはサービスに送信する方法については、「Web アプリケーションまたはサービスへのトークンのラップ解除と送信」を参照してください。

SWT トークン要求

対称キーによって署名された SWT トークンを使用して、OAuth WRAP プロトコルを介して ACS からトークンを要求することもできます。 すべての SWT トークン要求は HTTPS FORM POST 経由で行われます。 このトークン要求メソッドのパラメーター値はフォーム エンコードです。

「Mysnservice」という名前空間に SWT トークンを要求する例を次に示します。

POST /WRAPv0.9/ HTTP/1.1
Host: mysnservice.accesscontrol.windows.net
Content-Type: application/x-www-form-urlencoded

wrap_scope=http%3A%2F%2Fmysnservice.com%2Fservices%2F&
wrap_assertion_format=SWT&
wrap_assertion=Issuer%3dmysncustomer1%26HMACSHA256%3db%252f%252bJFwbngGdufECFjQb8qhb9YH0e32Cf9ABMDZFiPPA%253d

SWT トークン要求には次のパラメーターと値が必要です。

次の例のように、SWT トークン要求を行うために必要なコードは、パスワード トークン要求を行うために必要なコードに似ています。

WebClient client = new WebClient();
client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");

NameValueCollection values = new NameValueCollection();
// add the wrap_scope
values.Add("wrap_scope", "http://mysnservice.com/services");
// add the format
values.Add("wrap_assertion_format", "SWT");
// add the SWT
values.Add("wrap_assertion", "Issuer=mysncustomer1&HMACSHA256=b%2f%2bJFwbngGdufECFjQb8qhb9YH0e32Cf9ABMDZFiPPA%3d");
// WebClient takes care of the remaining URL Encoding
byte[] responseBytes = client.UploadValues("WRAPv0.9", "POST", values);

// the raw response from ACS
string response = Encoding.UTF8.GetString(responseBytes);

ACS からの応答をアンパックして Web アプリケーションまたはサービスに送信する方法については、「Web アプリケーションまたはサービスへのトークンのラップ解除と送信」を参照してください。

SWT トークンの作成

SWT トークンは、発行者キー (対称キー) で署名されているキー/値ペアのセットです。 SWT トークン要求で ACS に送信される SWT トークンには、 発行者 と HMACSHA256 パラメーターのほか、 ExpiresOn、 Audience、その他のクライアント固有の要求などの追加パラメーターが含まれている必要があります。 SWT トークン パラメーターの名前と説明を次の表に示します。

次のコード サンプルは、 を利用して SWT トークンを生成する方法を示しています。 発行者パラメーターと HMACSHA256 パラメーターを含む SWT トークンを構築するタイプを含みます。

using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;
using System.Web;

public class TokenFactory
{
    string signingKey;   
    string issuer;
    
    public TokenFactory(string issuer, string signingKey)
    {
        this.issuer = issuer;
        this.signingKey = signingKey;
    }

    public string CreateToken()
    {
        StringBuilder builder = new StringBuilder();

        // add the issuer name
        builder.Append("Issuer=");
        builder.Append(HttpUtility.UrlEncode(this.issuer));

        string signature = this.GenerateSignature(builder.ToString(), this.signingKey);
        builder.Append("&HMACSHA256=");
        builder.Append(signature);

        return builder.ToString();
    }

   
    private string GenerateSignature(string unsignedToken, string signingKey)
    {
        HMACSHA256 hmac = new HMACSHA256(Convert.FromBase64String(signingKey));

        byte[] locallyGeneratedSignatureInBytes = hmac.ComputeHash(Encoding.ASCII.GetBytes(unsignedToken));

        string locallyGeneratedSignature = HttpUtility.UrlEncode(Convert.ToBase64String(locallyGeneratedSignatureInBytes));

        return locallyGeneratedSignature;
    }
}

SAML トークン要求

SAML トークン要求方法は主に AD FS 2.0 統合を目的としており、クライアントがエンタープライズ ID (Active Directory) を使用して ACS で認証できるようにします。 SAML トークン要求メソッドを使用すると、OAuth WRAP プロトコルを使用して、署名された SAML 1.1 または AD FS 2.0 によって発行された SAML 2.0 トークン (入力トークン) を ACS に送信できます。

ACS はそのルールを使用して出力要求を計算したり、SWT トークン (出力トークン) にグループ化したり、署名したり、OAuth WRAP プロトコル経由でクライアントに返したりします。

SAML トークン要求には次のパラメーターと値が必要です。

次は SAML トークンを要求するために必要なコードの例です。

private static string SendSAMLTokenToACS(string samlToken)
{
 try
 {
  WebClient client = new WebClient();
  client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");
  NameValueCollection parameters = new NameValueCollection();
  parameters.Add("wrap_assertion_format", "SAML");
  parameters.Add("wrap_assertion", samlToken);
  parameters.Add("wrap_scope", "http://mysnservice.com/services");

  byte[] responseBytes = client.UploadValues("WRAPv0.9", parameters);
  string response = Encoding.UTF8.GetString(responseBytes);

  return response
   .Split('&')
   .Single(value => value.StartsWith("wrap_access_token=", StringComparison.OrdinalIgnoreCase))
   .Split('=')[1];
 }
 catch (WebException wex)
 {
  string value = new StreamReader(wex.Response.GetResponseStream()).ReadToEnd();
  throw;
 }
}  

ACS からの応答をアンパックして Web アプリケーションまたはサービスに送信する方法については、「Web アプリケーションまたはサービスへのトークンのラップ解除と送信」を参照してください。

OAuth WRAP プロトコルによる要求のアサーション

ACS 1.0 トークン要求動作との下位互換性を有効にするために、ACS はトークン要求の一部として要求をアサートする機能をサポートしています。

アサートするアプリケーションまたはサービスを ACS ID プロバイダーとして登録します。

推奨される方法は、アサートするアプリケーションまたはサービスを ACS の ID プロバイダーとして登録することです。 次に、アプリケーションまたはサービスは、アサートする要求を含む SAML または SWT トークンを提示して ACS からトークンを要求し、このトークンは ACS に格納されている ID プロバイダー キーを使用して署名されます。 たとえば、AD FS 2.0 から OAuth WRAP プロトコルを使用して、アサートされた要求を含む SAML トークン要求を ACS に送信したり、WINDOWS Identity Foundation (WIF) を使用して構築され、WS-Federation ID プロバイダーとして ACS に登録されているカスタム セキュリティ トークン サービス (STS) を送信したりすることができます。

ACS 管理ポータルを使用して、WS-Federation メタデータを使用して ID プロバイダーを登録することも、ACS 管理サービスを使用して ID プロバイダーのプロパティ、アドレス、キーを個別に設定することもできます。 (たとえば、「方法: ACS 管理サービスを使用して AD FS 2.0 を Enterprise ID プロバイダーとして構成する」を参照してください)。 トークン要求で要求をアサートするこのメソッドではサービス ID は必要ありません。 この方法は、ACS でサポートされているすべてのプロトコルを介して機能します。

ラップの解除と Web アプリケーションまたはサービスへのトークン送信

トークン要求が正常に認証された場合、ACS は 2 つの形式でエンコードされたパラメーター (wrap_token と wrap_token_expires_in) を返します。 これらのパラメーターの値は実際の SWT トークンです。クライアントはそれを利用し、Web アプリケーションまたはサービスとこのトークンの残り有効時間概算 (秒) にそれぞれアクセスできます。

SWT トークンを Web アプリケーションまたはサービスに送信する前に、クライアントは ACS 応答から SWT トークンを抽出して URL デコードする必要があります。 Web アプリケーションまたはサービスで、HTTP Authorization ヘッダーにトークンを表示する必要がある場合、トークンの前にスキーム WRAPv0.9 を付ける必要があります。

次のコード例は、トークンをアンパックし、Authorization ヘッダーを書式設定する方法を示しています。

WebClient client = new WebClient();
client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");

NameValueCollection values = new NameValueCollection();
values.Add("wrap_name", "mysncustomer1");
values.Add("wrap_password", "5znwNTZDYC39dqhFOTDtnaikd1hiuRa4XaAj3Y9kJhQ=");
values.Add("wrap_scope", "http://mysnservice.com/services");

// WebClient takes care of the URL Encoding
byte[] responseBytes = client.UploadValues("WRAPv0.9", "POST", values);

// the raw response from ACS
string response = Encoding.UTF8.GetString(responseBytes);

string token = response
    .Split('&')
    .Single(value => value.StartsWith("wrap_token=", StringComparison.OrdinalIgnoreCase))
    .Split('=')[1];

string.Format("WRAP access_token=\"{0}\"", HttpUtility.UrlDecode(token));

ACS エラー コードと説明

ACS は、トークン要求を満たすことができない場合にエラーを返します。 REST の設計に合わせて、エラーには HTTP 応答コードが含まれます。 多くの場合、ACS エラーには失敗した内容に関するコンテキストも含まれていますSubCodeDetail。 エラー形式は、Error:Code:<httpStatus>:Sub-Code:<code>:D etail:<message> です。 エラーの Content-Type は常にテキスト/プレーンです。

HTTP/1.1 401 Access Forbidden
Content-Type: text/plain; charset=us-ascii

Error:Code:401:SubCode:T0:Detail:ACS50009: SWT token is invalid. :TraceID:<trace id value>:TimeStamp:<timestamp value>

ACS エラー コードの詳細については、「 ACS エラー コード」を参照してください。

ACS から返されたエラーからデバッグまたは回復する場合、多くの場合、応答本文を読み取る必要があります。 次のコード例は、 WebException オブジェクトからエラー メッセージを読み取る方法を示しています。

try
{
    WebClient client = new WebClient();
    client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");

    NameValueCollection values = new NameValueCollection();
    values.Add("wrap_name", "mysncustomer1");
    values.Add("wrap_password", "5znwNTZDYC39dqhFOTDtnaikd1hiuRa4XaAj3Y9kJhQ=");
    values.Add("wrap_scope", "http://mysnservice.com/services");

    // WebClient takes care of the URL Encoding
    byte[] responseBytes = client.UploadValues("WRAPv0.9", "POST", values);

    // the raw response from ACS
    string response = Encoding.UTF8.GetString(responseBytes);

    string token = response
        .Split('&')
        .Single(value => value.StartsWith("wrap_access_token=",       StringComparison.OrdinalIgnoreCase))
        .Split('=')[1];
}
catch (WebException wex)
{
    if (wex.Response != null)
    {
        // the response Stream contains the error message
        StreamReader reader = new StreamReader(wex.Response.GetResponseStream());
        string message = reader.ReadToEnd();
    }
    // Throw as appropriate
}

参照

概念

ACS の利用方法