방법: OAuth WRAP 프로토콜을 통해 ACS에서 토큰 요청

적용 대상

• Microsoft Azure Active Directory 액세스 제어(액세스 제어 서비스 또는 ACS라고도 함)

개요

웹 애플리케이션 및 서비스가 ACS를 사용하여 인증을 처리하는 경우 클라이언트는 애플리케이션 또는 서비스에 로그인하기 위해 ACS에서 발급한 보안 토큰을 가져와야 합니다. 이 ACS 발급 토큰(출력 토큰)을 가져오려면 클라이언트가 ACS를 사용하여 직접 인증하거나 ID 공급자(입력 토큰)에서 발급한 보안 토큰을 ACS에 보내야 합니다. ACS는 이 입력 보안 토큰의 유효성을 검사하고, ACS 규칙 엔진을 통해 이 토큰의 ID 클레임을 처리하고, 출력 ID 클레임을 계산하고, 출력 보안 토큰을 발급합니다.

이 항목에서는 OAuth WRAP 프로토콜을 통해 ACS에서 토큰을 요청하는 방법에 대해 설명합니다. OAuth WRAP 프로토콜을 통한 모든 토큰 요청은 SSL을 통해 전송됩니다. ACS는 올바른 형식의 토큰 요청에 대한 응답으로 항상 OAuth WRAP 프로토콜을 통해 SWT(단순 웹 토큰)를 발급합니다. OAuth WRAP 프로토콜을 통한 모든 토큰 요청은 HTTP POST에서 ACS로 전송됩니다. HTTPS FORM POST(.NET Framework, WCF(Windows Communication Foundation), Silverlight, ASP.NET, Java, Python, Ruby, PHP, Flash 및 기타 플랫폼 등 HTTPS FORM POST를 만들 수 있는 모든 플랫폼에서 OAuth WRAP 프로토콜을 통해 ACS 토큰을 요청할 수 있습니다.

다음 표에는 OAuth WRAP 프로토콜을 통해 ACS에서 발급한 SWT 토큰을 요청하는 지원되는 세 가지 방법이 나와 있습니다.

OAuth WRAP 프로토콜을 통해 ACS에서 토큰을 요청하는 세 가지 방법

토큰 발급 엔드포인트

OAuth WRAP 프로토콜을 통한 모든 ACS 토큰 요청은 ACS 토큰 발급 엔드포인트로 전달됩니다. 이 엔드포인트의 URI는 Access Control 네임스페이스에 따라 달라집니다. 이 네임스페이스는 토큰 요청 URI에 DNS 이름 접두사로 표시됩니다. DNS 이름의 나머지는 고정된 경로입니다. 예를 들어 "mysnservice"라는 Access Control 네임스페이스에서 토큰을 요청하려는 경우 토큰 요청을 다음 URIhttps://mysnservice.accesscontrol.windows.net/WRAPv0.9로 보낼 수 있습니다.

암호 토큰 요청

암호 토큰 요청을 사용하면 클라이언트가 인증을 위해 OAuth WRAP 프로토콜을 통해 서비스 ID에서 ACS로 직접 사용자 이름과 암호를 보낼 수 있습니다. OAuth WRAP 프로토콜을 사용하여 ACS에서 토큰을 요청하는 가장 쉬운 방법입니다. 이 접근 방식에는 SSL 연결 설정 외에 필요한 암호화 기능은 없습니다. 실제로는 REST 웹 서비스에서 널리 사용되는 사용자 이름/암호 모델과 유사합니다. 이 유형의 토큰 요청은 실제로 HTTPS 양식 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로 인코딩되어야 합니다. 웹 애플리케이션 또는 서비스는 클라이언트에 wrap_scope 값을 제공하거나 클라이언트가 wrap_scope 매개 변수의 값을 웹 애플리케이션 또는 서비스 리소스 대상의 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에서 출력 토큰의 압축을 풀고 웹 애플리케이션 또는 서비스로 보내는 방법에 대한 자세한 내용은 래핑 해제 및 웹 애플리케이션 또는 서비스에 토큰 보내기를 참조하세요.

SWT 토큰 요청

대칭 키로 서명된 SWT 토큰을 사용하여 OAuth WRAP 프로토콜을 통해 ACS에서 토큰을 요청할 수도 있습니다. 모든 SWT 토큰 요청은 HTTPS 양식 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에서 응답을 압축을 풀고 웹 애플리케이션 또는 서비스로 보내는 방법에 대한 자세한 내용은 래핑 해제 및 토큰을 웹 애플리케이션 또는 서비스로 보내는 방법을 참조하세요.

SWT 토큰 만들기

SWT 토큰은 발급자 키(대칭 키)로 서명된 키/값 쌍 집합입니다. SWT 토큰 요청에서 ACS로 전송된 SWT 토큰에는 발급자 및 HMACSHA256 매개 변수와 추가 매개 변수(예: ExpiresOn, Audience 및 기타 클라이언트 관련 클레임)가 포함되어야 합니다. 다음 표에는 SWT 토큰 매개 변수의 이름 및 설명이 나와 있습니다.

다음 코드 예제에서는 를 사용하여 SWT 토큰을 생성하는 방법을 보여 줍니다. 여기에는 Issuer 및 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 프로토콜을 통해 AD FS 2.0(입력 토큰)에서 발급한 서명된 SAML 1.1 또는 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에서 응답의 압축을 풀고 웹 애플리케이션 또는 서비스로 보내는 방법에 대한 자세한 내용은 래핑 해제 및 웹 애플리케이션 또는 서비스에 토큰 보내기를 참조하세요.

OAuth WRAP 프로토콜을 통한 클레임 어설션

ACS 1.0 토큰 요청 동작과 이전 버전과의 호환성을 사용하도록 설정하기 위해 ACS는 토큰 요청의 일부로 클레임을 어설션하는 기능을 지원합니다.

어설션 응용 프로그램 또는 서비스를 ACS ID 공급자로 등록

클레임을 어설션하는 데 권장되는 방법은 어설션 응용 프로그램 또는 서비스를 ACS ID 공급자로 등록하는 것입니다. 그런 다음 애플리케이션 또는 서비스는 어설션하려는 클레임이 포함된 SAML 또는 SWT 토큰을 제공하여 ACS에서 토큰을 요청하고, 이 토큰은 ACS에 저장된 ID 공급자 키를 사용하여 서명됩니다. 예를 들어 AD FS 2.0에서 OAuth WRAP 프로토콜을 통해 어설션된 클레임이 있는 SAML 토큰 요청을 보내거나 WIF(Windows Identity Foundation)를 사용하여 빌드되고 ACS에 WS-Federation ID 공급자로 등록된 STS(사용자 지정 보안 토큰 서비스)를 보낼 수 있습니다.

ACS 관리 포털을 사용하여 WS-Federation 메타데이터를 사용하여 ID 공급자를 등록하거나 ACS 관리 서비스를 사용하여 ID 공급자 속성, 주소 및 키를 개별적으로 설정할 수 있습니다. (예: 방법 참조: ACS 관리 서비스를 사용하여 AD FS 2.0을 Enterprise ID 공급자로 구성). 토큰 요청에서 클레임을 어설션하는 이 방법에는 서비스 ID가 필요 없습니다. 이 메서드는 모든 ACS 지원 프로토콜을 통해 작동합니다.

토큰의 압축을 풀고 웹 응용 프로그램 또는 서비스로 보내기

토큰 요청이 성공적으로 인증되면 ACS는 양식으로 인코딩된 두 매개 변수인 wrap_token 및 wrap_token_expires_in 반환합니다. 이러한 매개 변수의 값은 각각 클라이언트에서 웹 응용 프로그램 또는 서비스에 대한 액세스 권한을 얻는 데 사용할 수 있는 실제 SWT 토큰과 이 토큰의 남은 수명(초)입니다.

웹 애플리케이션 또는 서비스에 SWT 토큰을 보내기 전에 클라이언트는 ACS 응답에서 토큰을 추출하고 URL 디코딩해야 합니다. 웹 응용 프로그램 또는 서비스에서 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 제공하는 ACS 오류도 포함됩니다. 오류 형식은 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 사용 방법