Използване на поток с косвено съгласие на 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
- Уеб сайт: Свързаният уеб сайт
- Стойност: Копирайте отпечатъка на качения персонализиран сертификат от екрана Управление на персонализиран сертификат и го поставете тук. Стойността ще посочи кой сертификат ще се използва за имплицитния поток на предоставяне.
Изберете Записване и затваряне.
Подробности за крайна точка на маркер
Можете да получите маркер и като публикувате заявка към /token крайна точка. URL адресът за крайна точка на маркер е: <portal_url>/_services/auth/token. Крайната точка на маркер поддържа следните параметри:
| Параметър | Необходимо? | Описание |
|---|---|---|
| client_id | Не | Низ, който се подава при осъществяване на повикване до крайната точка за удостоверяване. Вие трябва да гарантирате, че ИД на клиент е регистриран на портала. В противен случай се показва грешка. ИД на клиента се добавя в искания в маркера като aud и параметър appid и може да се използва от клиенти, за да потвърди, че върнатият маркер е за тяхното приложение.Максимална дължина е 36 знака. Поддържат се само буквено-цифрени знаци и тире. |
| redirect_uri | Не | URL адресът на портала, където отговорите на удостоверяване могат да бъдат изпратени и получени. Той трябва да бъде регистриран за конкретния client_id, използван в повикването и трябва да бъде точно същата стойност като регистрирана. |
| състояние | Не | Стойност, включена в заявката, която също се връща в отговора за маркер. Тя може да бъде низ с всякакво съдържание, което искате да използвате. Обикновено случайно генерирана, уникална стойност се използва за предотвратяване на атаки за фалшифициране на заявка през сайт. Максималната дължина е 20 знака. |
| nonce | Не | Низова стойност, изпратена от клиента, която е включена в получения ИД маркер като иск. Клиентът може след това да провери тази стойност, за да смекчи атаки за повторно изпълнение на маркер. Максималната дължина е 20 знака. |
| response_type | No | Този параметър се поддържа само token като стойност, което позволява на приложението ви незабавно да получи токен за достъп от крайната точка за оторизиране, без да прави втора заявка към крайната точка за оторизиране. |
Бележка
Въпреки че параметрите client_id, redirect_uri, state и nonce са незадължителни, се препоръчва да ги използвате, за да се уверете, че вашите интеграции са защитени.
Успешен отговор
Крайната точка на маркер връща състоянието и 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" }
Удостоверяване на подробности за крайна точка
Бележка
Крайната точка Authorize е изчерпана. Използвайте POST заявка за крайна точка на токен, за да получите ID токен.]
URL адресът за удостоверяване на крайна точка е: <portal_url>/_services/auth/authorize. Крайната точка на удостоверяване поддържа следните параметри:
| Параметър | Необходимо? | Описание |
|---|---|---|
| client_id | Да | Низ, който се подава при осъществяване на повикване до крайната точка за удостоверяване. Вие трябва да гарантирате, че ИД на клиент е регистриран на портала. В противен случай се показва грешка. ИД на клиента се добавя в искания в маркера като aud и параметър appid и може да се използва от клиенти, за да потвърди, че върнатият маркер е за тяхното приложение.Максимална дължина е 36 знака. Поддържат се само буквено-цифрени знаци и тирета. |
| redirect_uri | Да | URL адресът на портала, където отговорите на удостоверяване могат да бъдат изпратени и получени. Той трябва да бъде регистриран за конкретния client_id, използван в повикването и трябва да бъде точно същата стойност като регистрирана. |
| състояние | Не | Стойност, включена в заявката, която също се връща в отговора за маркер. Тя може да бъде низ с всякакво съдържание, което искате да използвате. Обикновено случайно генерирана, уникална стойност се използва за предотвратяване на атаки за фалшифициране на заявка през сайт. Максималната дължина е 20 знака. |
| nonce | Не | Низова стойност, изпратена от клиента, която е включена в получения ИД маркер като иск. Клиентът може след това да провери тази стойност, за да смекчи атаки за повторно изпълнение на маркер. Максималната дължина е 20 знака. |
| response_type | No | Този параметър се поддържа само token като стойност, което позволява на приложението ви незабавно да получи токен за достъп от крайната точка за оторизиране, без да прави втора заявка към крайната точка за оторизиране. |
Успешен отговор
Крайната точка на удостоверяване връща следните стойности в URL адрес на отговор като фрагмент:
- маркер: Маркер се връща като JSON уеб маркер (JWT), цифрово подписан от частния ключ на портала.
- състояние: Ако параметър за състояние е включен в искането, същата стойност трябва да се появи в отговора. Приложението трябва да се провери, че стойностите на състоянието в искането и отговора са идентични.
- 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. Извадката може да намерите тук: Извадка за крайна точка на маркер.
Бележка
Можете ли да ни споделите повече за езиковите си предпочитания за документацията? Попълнете кратко проучване. (имайте предвид, че това проучване е на английски език)
Проучването ще отнеме около седем минути. Не се събират лични данни (декларация за поверителност).