Была ли эта страница полезной?
Ваш отзыв об этом контенте важен для нас. Расскажите нам о том, что вы думаете.
Дополнительный отзыв?
1500 символов осталось
Экспорт (0) Печать
Развернуть все
Развернуть Свернуть

Инструкции Запрос маркера от ACS с помощью протокола WRAP OAuth

Обновлено: Июнь 2015 г.

  • Microsoft Azure Active Directory Access Control (также называется Access Control Service или ACS)

Если веб-приложения и службы обработки проверки подлинности используют Служба управления доступом, клиент должен получить маркер безопасности, выданный службой Служба управления доступом для входа в приложение или службу. Для получения этого маркера (исходящего маркера), выданного Служба управления доступом, клиенту необходимо пройти проверку подлинности непосредственно с помощью Служба управления доступом или отправить в Служба управления доступом маркер безопасности, выданный его поставщиком удостоверений (входящий маркер). Служба управления доступом проверяет этот маркер безопасности ввода, обрабатывает идентификационные утверждения из этого маркера через обработчик правил Служба управления доступом, вычисляет исходящие идентификационные утверждения и выдает исходящий маркер безопасности.

В этом разделе описываются методы класса запроса маркера из Служба управления доступом по протоколу OAuth WRAP. Все запросы маркеров по протоколу OAuth WRAP передаются по протоколу SSL. Служба управления доступом всегда выдает простой веб-маркер (SWT) по протоколу OAuth WRAP в ответ на запрос маркера в правильном формате. Все запросы маркеров по протоколу OAuth WRAP отправляются в Служба управления доступом в HTTP POST. Можно запросить маркер Служба управления доступом по протоколу OAuth WRAP с любой платформы, которая поддерживает формы HTTPS POST: .NET Framework, Windows Communication Foundation (WCF), Silverlight, ASP.NET, Java, Python, Ruby, PHP, Flash и другие платформы.

В следующей таблице перечислены три поддерживаемых метода запроса маркера SWT, издаваемого Служба управления доступом по протоколу OAuth WRAP.

Три метода запроса маркера из ACS по протоколу OAuth WRAP

Метод запроса маркера Описание

Запросы маркеров паролей

Этот простейший способ требует, чтобы клиент отправлял имя пользователя и пароль из удостоверения службы непосредственно в Служба управления доступом по протоколу OAuth WRAP для проверки подлинности.

Запросы маркеров SWT

Этот метод требует, чтобы клиент отправлял маркер SWT, который может быть подписан симметричным ключом удостоверения службы или симметричным ключом поставщика удостоверений, в Служба управления доступом по протоколу OAuth WRAP для проверки подлинности.

Запросы маркеров SAML

Предназначенный главным образом для интеграции служб федерации Active Directory (AD FS) 2.0, метод Security Assertion Markup Language (SAML) требует, чтобы клиент отправлял подписанный маркер SAML в Служба управления доступом по протоколу OAuth WRAP для проверки подлинности. Такой подход позволяет клиенту использовать удостоверение предприятия для проверки подлинности с помощью Служба управления доступом.

Все запросы маркера Служба управления доступом по протоколу OAuth WRAP направляются на конечную точку Служба управления доступом, издающую маркеры. URI этой конечной точки зависит от Пространство имен Access Control. Пространство имен появляется в виде префикса имени DNS в URI запроса маркера. Остальная часть имени DNS фиксирована, как и путь. Например, если вы хотите запросить маркер от Пространство имен Access Control с названием «mysnservice», необходимо направить запрос маркера на следующий URI: https://mysnservice.accesscontrol.windows.net/WRAPv0.9.

С помощью запроса маркера пароля клиент может отправлять имя пользователя и пароль из удостоверения службы непосредственно в Служба управления доступом по протоколу OAuth WRAP для проверки подлинности. Это самый простой способ запросить маркер из Служба управления доступом по протоколу OAuth WRAP. Кроме установки соединения 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

В таблице ниже приведены имена, описания и требования к значениям параметров, которые должны присутствовать в запросе маркера пароля.

 

Имя параметра Описание Требования к значениям

wrap_scope

Сопоставляет запрос маркера с набором правил. Задайте значение этого параметра, равным значению области приложения проверяющей стороны. Это значение можно получить (в поле область) через портал управления Служба управления доступом, выбрав соответствующие приложения проверяющей стороны на странице Приложения проверяющей стороны.

  • URI HTTP или HTTP(s)

  • Без параметров запроса или привязок.

  • Сегменты пути < = 32.

  • Максимальная длина: 256 символов.

  • Требуется кодирование в виде URL-адреса.

wrap_name

Проверяет ключ следующего параметра. В качестве значения этого параметра задайте имя удостоверения службы в Пространство имен Access Control. Это значение можно получить (в поле Имя) через портал управления Служба управления доступом, выбрав соответствующую службу удостоверений на странице Удостоверения службы.

  • Минимальная длина: 1 символ.

  • Максимальная длина: 128 символов.

  • Требуется кодирование в виде URL-адреса.

wrap_password

Выполняет проверку подлинности входящего запроса. В качестве значения этого параметра задайте пароль удостоверения службы в Пространство имен Access Control. Это значение можно получить (в поле Пароль на странице Изменение учетных данных) через портал управления Служба управления доступом, сначала выбрав соответствующее удостоверение службы на странице Удостоверения службы, а затем выбрав соответствующий пароль в таблице Учетные данные на странице Изменение удостоверения службы.

  • Строка, минимум 1 символ и максимум 64 символа.

  • Требуется кодирование в виде URL-адреса.

Значения этих параметров должны быть закодированы как URL-адрес перед отправкой запроса на Служба управления доступом. Веб-приложение или служба может предоставить значение wrap_scope клиенту, или клиент может задать значение параметра wrap_scope URI цели веб-приложения или ресурса службы.

Запросы маркеров пароля по протоколу OAuth WRAP могут также содержать дополнительные параметры, которые Служба управления доступом может использовать в процессе вычисления исходящего утверждения. Эти имена и значения дополнительных параметров должны быть закодированы как 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);

Сведения о том, как распаковать исходящий маркер из Служба управления доступом и отправить его в веб-приложение или службу см. в разделе Unwrapping and sending the token to a web application or service.

Можно также запросить маркер от Служба управления доступом по протоколу OAuth WRAP с помощью маркера SWT, подписанного симметричным ключом. Все запросы маркеров SWT выполняются через формы HTTPS POST. Значения параметров в этом методе запроса маркера зашифрованы в форме.

Ниже приведен пример трассировки сети запроса маркера SWT пространству имен «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_assertion_format=SWT&
wrap_assertion=Issuer%3dmysncustomer1%26HMACSHA256%3db%252f%252bJFwbngGdufECFjQb8qhb9YH0e32Cf9ABMDZFiPPA%253d

Запрос маркера SWT должен иметь следующие параметры и значения.

 

Имя параметра Описание Требования к значениям

wrap_scope

Сопоставляет запрос маркера с набором правил.

  • Задайте значение этого параметра, равным значению области приложения проверяющей стороны. Это значение можно получить (в поле область) через портал управления Служба управления доступом, выбрав соответствующие приложения проверяющей стороны на странице Приложения проверяющей стороны.

  • URI HTTP или HTTP(s)

  • Без параметров запроса или привязок.

  • Сегменты пути < = 32.

  • Максимальная длина: 256 символов.

  • Требуется кодирование в виде URL-адреса.

wrap_assertion

Это входящий маркер, который отправляется в Служба управления доступом.

  • Подписанный маркер SWT с входящими утверждениями, включающий издателя и параметры HMACSHA256.

  • Максимальная длина: 2048 символов.

  • Требуется кодирование в виде URL-адреса.

wrap_assertion_format

Формат входящего маркера, который отправляется в Служба управления доступом.

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

Сведения о том, как распаковать ответ из Служба управления доступом и отправить его в веб-приложение или службу, см. в разделе Unwrapping and sending the token to a web application or service.

Маркер SWT — это набор пар «ключ-значение», подписанных с помощью ключа издателя (симметричного ключа). Маркер SWT, отправляемый Служба управления доступом в запросе маркера SWT, должен содержать издателя и параметры HMACSHA256, а также дополнительные параметры, например ExpiresOn, Audience и другие утверждения для конкретного клиента. В следующей таблице приведены имена и описания параметров маркера SWT.

 

Имя параметра Описание

Issuer

В Служба управления доступом ищет ключ, который использовался для подписи маркера. Если подпись является допустимой, это значение используется для выполнения вычисления исходящего утверждения.

Этому параметру может быть присвоено значение области поставщика удостоверений в вашем Пространство имен Access Control или имя удостоверения службы в вашем Пространство имен Access Control. Это значение можно получить (в поле Область на странице Изменение поставщика удостоверений) через портал управления Служба управления доступом, выбрав соответствующего поставщика удостоверений на странице «Поставщики удостоверений». Или можно получить это значение с помощью службы управления Служба управления доступом — это имя свойства записи «Издатель», которая создается для каждого поставщика удостоверений.

HMACSHA256

В Служба управления доступом проверяет подпись SWT и ищет ключ издателя с именем в параметре Издатель.

Подпись SWT создается с использованием симметричного ключа подписи, присоединенного к удостоверению службы или поставщику удостоверений в вашем Пространство имен Access Control.

Аудитория

Если он присутствует, Служба управления доступом использует это значение, чтобы убедиться в том, что Служба управления доступом предназначается для маркера SWT. Это URL-адрес вашего Пространство имен Access Control, например https://contoso.accesscontrol.windows.net/.

ExpiresOn

Если имеется (во время эпохи), указывает, истек ли срок действия маркера. Например, значение этого параметра может быть 1324300962.

Дополнительные утверждения

Если присутствуют, Служба управления доступом использует эти параметры для выполнения вычислений исходящего утверждения. Каждый тип утверждения должен появляться только один раз. Несколько значений утверждения того же типа утверждения должны быть объединены с помощью символа «,» (запятая). Подробнее о подтверждении утверждений в Служба управления доступом см. в разделе Подтверждение утверждений по протоколу OAuth WRAP.

В следующем примере кода показано, как создать маркер SWT с помощью . Он содержит тип, который создает маркеры SWT, содержащие параметры издателя и HMACSHA256.

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 предназначен главным образом для интеграции AD FS 2.0 и позволяет клиенту использовать удостоверение предприятия (Active Directory) для проверки подлинности с помощью Служба управления доступом. С помощью метода запроса маркера SAML можно отправлять подписанный маркер SAML 1.1 или маркер SAML 2.0, выданный AD FS 2.0 (входящий маркер), в Служба управления доступом по протоколу OAuth WRAP.

ACS использует его правила для вычисления исходящих утверждений, группирует их в маркер SWT (исходящий маркер), подписывает его и возвращает клиенту по протоколу OAuth WRAP.

Запрос маркера SWT должен иметь следующие параметры и значения.

 

Имя параметра Описание Требования к значениям

wrap_scope

Сопоставляет запрос маркера с набором правил.

  • Задайте значение этого параметра, равным значению области приложения проверяющей стороны. Это значение можно получить (в поле область) через портал управления Служба управления доступом, выбрав соответствующие приложения проверяющей стороны на странице Приложения проверяющей стороны.

  • URI HTTP или HTTP(s)

  • Без параметров запроса или привязок.

  • Сегменты пути < = 32.

  • Максимальная длина: 256 символов.

  • Требуется кодирование в виде URL-адреса.

wrap_assertion

Это входящий маркер, который отправляется в Служба управления доступом.

  • Подписанный маркер SAML 1.1 или 2.0 с входящими утверждениями. Маркеры SAML 1.1 в качестве ограничения маркера требуют по крайней мере одно входящее утверждение. Это означает, что необходимо использовать поставщика удостоверений или удостоверения службы с поддержкой утверждений для проверки подлинности маркера SAML 1.1. Маркеры SAML 2.0 не требуют входящих утверждений для проверки подлинности по удостоверению службы, помимо неявного утверждения NameIdentifier. Поэтому маркеры SAML 2.0 можно использовать для проверки подлинности по удостоверению обычной службы, не поддерживающему утверждений.

  • Требуется кодирование в виде URL-адреса.

wrap_assertion_format

Формат входящего маркера, который отправляется в Служба управления доступом.

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 и отправить его в веб-приложение или службу, см. в разделе Распаковывание и отправка маркера для веб-приложения или службы.

Чтобы обеспечить обратную совместимость с поведением запроса маркера ACS 1.0, Служба управления доступом поддерживает возможность подтверждения утверждений как части запросов маркеров.

Для этого рекомендуется зарегистрировать в качестве поставщика удостоверений ACS приложение или службу подтверждения. Приложение или служба запрашивает маркер от Служба управления доступом, предоставляя маркер SAML или SWT, содержащий утверждения, которые необходимо подтвердить, и этот маркер подписывается с помощью ключа поставщика удостоверений в Служба управления доступом. Например, можно отправить запрос маркера SAML с подтвержденными утверждениями в Служба управления доступом по протоколу OAuth WRAP из AD FS 2.0 или любой пользовательской службы маркеров безопасности (STS), построенной с помощью Windows Identity Foundation (WIF) и зарегистрированной в Служба управления доступом в качестве поставщика удостоверений WS-Federation.

Можно использовать портал управления Служба управления доступом, чтобы зарегистрировать поставщика удостоверений с помощью метаданных WS-Federation, или службу управления Служба управления доступом, чтобы задавать свойства, адреса и ключи поставщика удостоверений по отдельности. (Например, см. раздел Инструкции по использованию службы управления ACS для настройки AD FS 2.0 в качестве поставщика удостоверений организации.) В этом методе подтверждения утверждений в запросе маркера удостоверения службы не требуются. Этот метод действует через все протоколы, поддерживаемые Служба управления доступом.

Если запрос маркера успешно прошел проверку подлинности, Служба управления доступом возвращает два параметра, зашифрованные в форме wrap_token и wrap_token_expires_in. Значения этих параметров фактически представляют собой маркер SWT, который клиент может использовать для получения доступа к веб-приложению или службе, и приблизительное оставшееся время существования маркера (в секундах) соответственно.

Перед отправкой маркера SWT для веб-приложения или службы клиент должен извлечь его и декодировать в 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));

Служба управления доступом возвращает ошибки, если ему не удается удовлетворить запрос маркера. В соответствии с разработкой REST ошибка содержит код ответа HTTP. Во многих случаях ошибки Служба управления доступом также содержат SubCode и Detail, которые предоставляют контекст для изучения причины сбоя. Формат ошибки: ошибка:код ошибки:<httpStatus>:вложенный код:<код>:подробности:<сообщение>. Content-Type ошибки всегда «text/plain».

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.

При отладке или восстановлении после ошибки, возвращаемой из Служба управления доступом, часто приходится считывать текст ответа. В следующем примере кода показано, как прочитать сообщение об ошибке из объекта 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

Добавления сообщества

ДОБАВИТЬ
Показ:
© 2015 Microsoft