Использования последовательности операций неявного предоставления разрешений OAuth 2.0 в рамках портала

Эта функция позволяет клиенту осуществлять вызовы внешних API-интерфейсов со стороны клиента и обеспечивать их безопасность с помощью последовательности операций неявного предоставления разрешений OAuth. Это обеспечивает конечную точку для получения токенов безопасного доступа, которые будут содержать идентификационные данные пользователя для использования внешними API-интерфейсами для авторизации в соответствии с последовательностью операций неявного предоставления разрешений OAuth 2.0. Идентификационные данные вошедшего пользователя передаются безопасным образом во внешние вызовы AJAX. Это не только поможет разработчикам передавать контекст проверки подлинности, но также поможет пользователям защитить свои API-интерфейсы с помощью этого механизма.

Последовательность операций неявного предоставления разрешений OAuth 2.0 поддерживает конечные точки, которые клиент может вызывать для получения идентификационного токена. Две конечные точки используются для этой цели: авторизация и токен.

Сведения о конечной точке авторизации

URL-адрес конечной точки авторизации: <portal_url>/_services/auth/authorize. Конечная точка авторизации поддерживает следующие параметры:

Параметр Обязательный? Описание
client_id Да Строка, которая передается при выборе конечной точки авторизации. Необходимо обеспечить, чтобы этот идентификатор клиента был зарегистрирован на портале. В противном случае отображается ошибка. ИД клиента добавляется в заявках в токен как aud, а также как параметр appid и может использоваться клиентами, чтобы проверить, что возвращенный токен предназначен для их приложения.
Максимальная длина: 36 символов. Только алфавитно-цифровые знаки и дефисы поддерживаются.
redirect_uri Да URL-адрес портала, где могут отправлять и приниматься ответы проверки подлинности. Он должен быть зарегистрирован для конкретного client_id, используемого в вызове, и должен иметь точно такое же значение, что и зарегистрированное.
state Нет Значение, включенное в запрос, которое также возвращается в ответе токена. Это может быть строка любого содержания, которую вы хотите использовать. Обычно используется случайно созданное уникальное значение для предотвращения атак путем подложных межсайтовых запросов.
Максимальная длина: 20 символов.
nonce Нет Строковое значение, отправленное клиентом, которое включается в конечный токен идентификатора как заявка. Клиент может затем проверить это значение для исключения атак повторения токена. Максимальная длина: 20 символов.
response_type Нет Этот параметр поддерживает в качестве значения только token. Это позволяет вашему приложению немедленно получить токен доступа из конечной точки авторизации, не выполняя второй запрос в конечную точку авторизации.

Успешный ответ

Конечная точка авторизации возвращает следующие значения в URL-адресе отклика в качестве фрагмента:

  • token: токен возвращается как веб-токен JSON Web Token (JWT), подписанный цифровым частным ключом портала.
  • state: если параметр state включен в запрос, это же значение должно отображаться в отклике. Приложение должно убедиться, что значения параметра state в запросе и отклике идентичны.
  • expires_in: интервал времени действия токена доступа (в секундах).

Например, успешный отклик выглядит следующим образом:

GET https://aadb2cplayground.azurewebsites.net/#token=eyJ0eXAiOiJKV1QiLCJhbGciOI1NisIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q&expires_in=3599&state=arbitrary_data_you_sent_earlier

Отклик в случае ошибки

Ошибка в конечной точке авторизации возвращается в виде документа JSON со следующими значениями:

  • ИД ошибки: уникальный код ошибки.
  • Сообщение об ошибке: конкретное сообщение об ошибке, которое поможет определить первопричину ошибки проверки подлинности.
  • ИД корреляции: идентификатор GUID, используемый для целей отладки. Если включена диагностическая регистрация, ИД корреляции будет представлен в журналах ошибок сервера.
  • Отметка времени: дата и время создания ошибки.

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

{"ErrorId": "PortalSTS0001", "ErrorMessage": "Client Id provided in the request is not a valid client Id registered for this portal. Please check the parameter and try again.", "Timestamp": "4/5/2019 10:02:11 AM", "CorrelationId": "7464eb01-71ab-44bc-93a1-f221479be847" }

Сведения о конечной точке токена

Можно также получить токен, выполнив запрос в конечную точку /token. Она отличается от конечной точки авторизации в том отношении, что конечная точка авторизации обрабатывает логику токена на отдельной странице (redirect_uri), тогда как конечная точка токена обрабатывает логику токена на той же странице. URL-адрес конечной точки токена: <portal_url>/_services/auth/token. Конечная точка токена поддерживает следующие параметры:

Параметр Обязательный? Описание
client_id Нет Строка, которая передается при выборе конечной точки авторизации. Необходимо обеспечить, чтобы этот идентификатор клиента был зарегистрирован на портале. В противном случае отображается ошибка. ИД клиента добавляется в заявках в токен как aud, а также как параметр appid и может использоваться клиентами, чтобы проверить, что возвращенный токен предназначен для их приложения.
Максимальная длина: 36 символов. Только алфавитно-цифровые знаки и дефис поддерживаются.
redirect_uri Нет URL-адрес портала, где могут отправлять и приниматься ответы проверки подлинности. Он должен быть зарегистрирован для конкретного client_id, используемого в вызове, и должен иметь точно такое же значение, что и зарегистрированное.
state Нет Значение, включенное в запрос, которое также возвращается в ответе токена. Это может быть строка любого содержания, которую вы хотите использовать. Обычно используется случайно созданное уникальное значение для предотвращения атак путем подложных межсайтовых запросов.
Максимальная длина: 20 символов.
nonce Нет Строковое значение, отправленное клиентом, которое включается в конечный токен идентификатора как заявка. Клиент может затем проверить это значение для исключения атак повторения токена. Максимальная длина: 20 символов.
response_type Нет Этот параметр поддерживает в качестве значения только token. Это позволяет вашему приложению немедленно получить токен доступа из конечной точки авторизации, не выполняя второй запрос в конечную точку авторизации.

Примечание

Хотя параметры client_id, redirect_uri, state и nonce необязательны, рекомендуется использовать их, чтобы гарантировать безопасность интеграций.

Успешный ответ

Конечная точка токена возвращает параметры state и expires_in как заголовки отклика, и токен в теле формы.

Отклик в случае ошибки

Ошибка в конечной точке токена возвращается в виде документа JSON со следующими значениями:

  • ИД ошибки: уникальный код ошибки.
  • Сообщение об ошибке: конкретное сообщение об ошибке, которое поможет определить первопричину ошибки проверки подлинности.
  • ИД корреляции: идентификатор GUID, используемый для целей отладки. Если включена диагностическая регистрация, ИД корреляции будет представлен в журналах ошибок сервера.
  • Отметка времени: дата и время создания ошибки.

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

{"ErrorId": "PortalSTS0001", "ErrorMessage": "Client Id provided in the request is not a valid client Id registered for this portal. Please check the parameter and try again.", "Timestamp": "4/5/2019 10:02:11 AM", "CorrelationId": "7464eb01-71ab-44bc-93a1-f221479be847" }

Проверка токена идентификации

Просто получить токен идентификации недостаточно для проверки подлинности пользователя; также следует проверить подпись токена и убедиться, что заявки в токене основаны на требованиях приложения. Общественная конечная точка токена предоставляет открытый ключ портала, который можно использовать для проверки подписи токена, предоставленного порталом. URL-адрес открытой конечной точки токена: <portal_url>/_services/auth/publickey.

Включение или выключение последовательности операций неявного предоставления разрешений

По умолчанию последовательность операций неявного предоставления разрешений включена. Если требуется выключить последовательность операций неявного предоставления разрешений, задайте для параметра сайта Connector/ImplicitGrantFlowEnabled значение False.

Если этот параметр сайта недоступен на вашем портале, необходимо создать новый параметр сайта с соответствующим значением.

Настройка действительности токена

По умолчанию токен действителен 15 минут. Если требуется изменить действительность токена, задайте для параметра сайта ImplicitGrantFlow/TokenExpirationTime требуемое значение. Значение должно быть задано в секундах. Максимальное значение может быть 1 час, а минимальное значение должно быть 1 минута. Если задано неправильное значение (например, алфавитно-цифровые символы), используется значение по умолчанию 15 минут. Если указать значение, большее максимального значения или меньшее минимального значения, используются максимальное и минимальные значения соответственно, по умолчанию.

Например, чтобы задать действительность токена 30 минут, задайте для параметра сайта ImplicitGrantFlow/TokenExpirationTime значение 1800. Чтобы задать действительность токена 1 час, задайте для параметра сайта ImplicitGrantFlow/TokenExpirationTime значение 3600.

Регистрация ИД клиента для последовательности операций неявного предоставления разрешений

Необходимо зарегистрировать ИД клиента на портале, для которого эта последовательность операций разрешена. Чтобы зарегистрировать ИД клиента, необходимо создать следующие параметры сайта:

Параметр сайта Value
ImplicitGrantFlow/RegisteredClientId Допустимые значения идентификатора клиента, которые разрешены для этого портала. Значения должны быть разделены точкой с запятой и могут содержать алфавитно-цифровые знаки и дефисы. Максимальная длина: 36 символов.
ImplicitGrantFlow/{ClientId}/RedirectUri Допустимые URI перенаправления, которые разрешены для конкретного идентификатора клиента. Значения должны быть разделены точкой с запятой. Указанный URL-адрес должен быть действительной веб-страницей портала.

Пример кода

Можно использовать следующий пример кода для начала работы с использованием неявного предоставления разрешений OAuth 2.0 с интерфейсами API порталов Power Apps.

Использование токена портала OAuth с внешним веб-API

Этот пример является проектом на основе ASP.NET, который используется для проверки токена идентификатора, выданного порталами Power Apps. Полный пример можно найти здесь: Использование токена портала OAuth с внешним веб-API.

Пример конечной точки авторизации

В этом примере показано, как конечные точки авторизации возвращают токен идентификатора как часть URL-адреса перенаправления. Также рассматривается проверка состояния, поддерживаемая в неявном предоставлении разрешений. Пример можно найти здесь: Пример конечной точки авторизации.

Пример конечной точки токена

В этом примере показано, как можно использовать функцию getAuthenticationToken для получения токена идентификатора с помощью конечной точки токена в порталах Power Apps. Пример можно найти здесь: Пример конечной точки токена.

Примечание

Каковы ваши предпочтения в отношении языка документации? Пройдите краткий опрос (обратите внимание, что этот опрос представлен на английском языке).

Опрос займет около семи минут. Личные данные не собираются (заявление о конфиденциальности).