Использования последовательности операций неявного предоставления разрешений OAuth 2.0 в рамках портала
Примечание
Действует с 12 октября 2022 г, в качестве порталов для Power Apps используется Power Pages. Дополнительная информация: Microsoft Power Pages теперь доступен для всех (блог)
Скоро мы мигрируем и объединим документацию порталов Power Apps с документацией Power Pages.
Эта функция позволяет клиенту осуществлять вызовы внешних API-интерфейсов со стороны клиента и обеспечивать их безопасность с помощью последовательности операций неявного предоставления разрешений OAuth. Она предоставляет конечную точку для получения маркеров безопасного доступа. Эти маркеры будут содержать идентификационные данные пользователя, доступные для использования внешними API-интерфейсами для авторизации в соответствии с последовательностью операций неявного предоставления разрешений OAuth 2.0. Идентификационные данные вошедшего в систему пользователя безопасным образом передаются внешним вызовам AJAX, что позволяет разработчикам передавать контекст аутентификации, а также помогает пользователям защитить свои API.
Последовательность операций неявного предоставления разрешений OAuth 2.0 поддерживает конечные точки маркеров , которые клиент может вызывать для получения идентификационного маркера.
Пользовательские сертификаты
Использование сертификата по умолчанию для потока неявного предоставления разрешений OAuth 2.0 не рекомендуется. Вам потребуется пользовательский сертификат при использовании конечной точки OAuth 2.0. Воспользуйтесь центром администрирования Power Platform для загрузки пользовательского сертификата. После загрузки пользовательского сертификата необходимо обновить настройки сайта, как показано ниже:
Перейдите в параметры портала и выберите Параметры сайта.
Чтобы создать новый параметр, выберите Создать.
Чтобы отредактировать существующий параметр, выберите параметр сайта, перечисленный в сетке.
Укажите значения:
- Имя: CustomCertificates/ImplicitGrantflow
- Веб-сайт: связанный веб-сайт
- Значение: скопируйте отпечаток отправленного настраиваемого сертификата на экране «Управление настраиваемыми сертификатами» и вставьте сюда. Значение будет указывать, какой сертификат будет использоваться в последовательности действий неявного предоставления разрешения.
Выберите Сохранить и закрыть.
Сведения о конечной точке маркера
Можно также получить маркер, выполнив post-запрос к конечной точке /token. 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" }
Сведения о конечной точке авторизации
Примечание
Конечная точка авторизации устарела. Используйте POST-запрос к конечной точке маркера, чтобы получить маркер идентификатора.]
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" }
Проверка маркера идентификации
Просто получить маркер идентификации недостаточно для проверки подлинности пользователя; также следует проверить подпись маркера и убедиться, что заявки в маркере основаны на требованиях приложения. Общественная конечная точка токена предоставляет открытый ключ портала, который можно использовать для проверки подписи токена, предоставленного порталом. 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.
Пример конечной точки маркера
В этом примере показано, как можно использовать функцию getAuthenticationToken для получения маркера идентификатора с помощью конечной точки маркера в порталах Power Apps. Пример можно найти здесь: Пример конечной точки токена.
Примечание
Каковы ваши предпочтения в отношении языка документации? Пройдите краткий опрос (обратите внимание, что этот опрос представлен на английском языке).
Опрос займет около семи минут. Личные данные не собираются (заявление о конфиденциальности).
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по