OAuth 2.0 örtülü izin akışını portalınız içinde kullanın
Bu özellik, bir müşterinin harici API'lere istemci taraflı çağrıda bulunmasını ve bunları OAuth örtülü izin akış kullanarak güvence altına almasını sağlar. Harici API'ler tarafından kimlik doğrulama için OAuth 2.0 örtülü izin akışını izleyerek kullanıcı kimlik bilgisini içeren erişim belirteçlerini almak üzere bir uç nokta sağlar. Oturum açmış bir kullanıcının kimlik bilgisi, harici AJAX çağrılarına güvenli bir biçimde aktarılır. Bu yalnızca, geliştiricilerin kimlik doğrulama bağlamında aktarma yapmasına yardımcı olmak kalmaz, aynı zamanda kullanıcıların bu mekanizmayı kullanarak API'lerini güvence altına almalarına yardımcı olur.
Not
En iyi güvenlik uygulamaları için, OAuth 2.0 örtük onay akışı için özel sertifikaların kullanılması önerilir. Özel bir sertifika olmadan örtülü onay akışının kullanılması desteklenmeyecektir.
OAuth 2.0 örtülü izin akışı, bir istemcinin bir kimlik kodu belirteci almak üzere çağırabileceği uç noktaları destekler. Bu amaç için kullanılan iki uç nokta şunlardır: yetkilendir ve belirteç.
Uç nokta ayrıntılarını yetkilendir
Uç noktayı yetkilendirmek için URL: <portal_url>/_services/auth/authorize. Yetkilendir uç noktası aşağıdaki parametreleri destekler:
| Parametre | Gerekli mi? | Açıklama |
|---|---|---|
| client_id | Evet | Uç noktayı yetkilendirmek amacıyla bir çağrı yaparken aktarılan bir dize. İstemci kimlik kodunun portal ile kayıtlı olduğundan emin olmalısınız. Aksi takdirde, bir hata görüntülenir. İstemci kimlik kodu, belirteçteki istemlere aud ve appid parametresi olarak eklenir ve istemciler tarafından belirtecin uygulamaları için döndürüldüğünü doğrulamak için kullanılabilir.Maksimum uzunluk 36 karakterdir. Yalnızca alfasayısal karakterler ve tire desteklenir. |
| redirect_uri | Evet | Kimlik doğrulama yanıtlarının gönderilebileceği ve alınabileceği portalın URL'si. Çağrıda kullanılan bu belirli client_id için kayıtlı olmalıdır ve kayıtlı ile tam olarak aynı değere sahip olmalıdır. |
| semt | Hayır | Talep içine dahil olan bir değer de belirteç yanıtında döndürülür. Kullanmak istediğiniz herhangi bir içerikte bir dize olabilir. Genel olarak, rastgele oluşturulan benzersiz bir değer siteler arası sahte imza isteğini önlemek için kullanılır. Maksimum uzunluk 20 karakterdir. |
| nonce | Hayır | İstemci tarafından gönderilen bir dize değeri, kimlik kodu belirtecinde bir istem olarak sonuçlanan içine dahildir. İstemci daha sonra bu değeri, belirteç yeniden yürütme saldırılarını azaltmak için doğrulayabilir. Maksimum uzunluk 20 karakterdir. |
| response_type | Hayır | Bu parametre değer olarak yalnızca token destekler. Bu, uygulamanızın bir adres belirtecini yetkilendirme uç noktasından anında almasına izin verir, yetkilendirme uç noktasına ikinci bir talepte bulunmadan. |
Başarılı yanıt
Yetkilendirme uç noktası, aşağıdaki yanıt URL'sini bir parça olarak döndürür:
- belirteç: Belirteç, bir JSON Web Belirteci (JWT) olarak, portalın özel anahtarı tarafından dijital biçimde imzalanmış şekilde döndürülür.
- durum: Bir durum parametresi talebe dahilse, aynı değer yanıtta da belirmelidir. Uygulama, talepteki ve yanıttaki durum değerlerinin aynı olduğunu doğrulamalıdır.
- expires_in: Erişim belirtecinin geçerli olduğu zaman uzunluğu (saniye cinsinden).
Örneğin, başarılı bir yanıt şu şekilde görünür:
GET https://aadb2cplayground.azurewebsites.net/#token=eyJ0eXAiOiJKV1QiLCJhbGciOI1NisIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q&expires_in=3599&state=arbitrary_data_you_sent_earlier
Hata yanıtı
Yetkilendirme uç noktasındaki hata, JSON belgesi olarak aşağıdaki değerlerle döndürülür:
- Hata Kimlik Kodu: Hatanın benzersiz kimlik belirleyicisi.
- Hata iletisi: Bir kimlik doğrulama hatasının temel nedenini tanımlamanıza yardımcı olan belirli bir hata iletisi.
- Korelasyon Kimlik Kodu: Hata ayıklama amacıyla kullanılacak bir GUID. Tanılama günlüklerini etkinleştirmişseniz, korelasyon kimlik kodu sunucu hata günlüklerinde mevcut olacaktır.
- Zaman Damgası: Hatanın oluşturulduğu tarih ve saat.
Hata iletisi, oturum açmış kullanıcının varsayılan dilinde görüntülenir. Kullanıcı oturum açmazsa, oturum açma sayfası kullanıcının oturum açması için görüntülenir. Örneğin, bir hata yanıtı şu şekilde görünür:
{"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" }
Belirteç uç noktası ayrıntıları
/token uç noktasına bir talepte bulunarak da bir belirteç alabilirsiniz. Yetkilendirme uç noktasının belirteç mantığını ayrı bir sayfada (redirect_uri) içinde işliyor olmasıyla, yetkilendirme uç noktasından farklıdır; belirteç uç noktası, belirteç mantığını aynı sayfa üzerinde işler. Belirteç uç noktası için URL: <portal_url>/_services/auth/token. Belirteç uç noktası aşağıdaki parametreleri destekler:
| Parametre | Gerekli mi? | Açıklama |
|---|---|---|
| client_id | Hayır | Uç noktayı yetkilendirmek amacıyla bir çağrı yaparken aktarılan bir dize. İstemci kimlik kodunun portal ile kayıtlı olduğundan emin olmalısınız. Aksi takdirde, bir hata görüntülenir. İstemci kimlik kodu, belirteçteki istemlere aud ve appid parametresi olarak eklenir ve istemciler tarafından belirtecin uygulamaları için döndürüldüğünü doğrulamak için kullanılabilir.Maksimum uzunluk 36 karakterdir. Yalnızca alfasayısal karakterler ve tire desteklenir. |
| redirect_uri | Hayır | Kimlik doğrulama yanıtlarının gönderilebileceği ve alınabileceği portalın URL'si. Çağrıda kullanılan bu belirli client_id için kayıtlı olmalıdır ve kayıtlı ile tam olarak aynı değere sahip olmalıdır. |
| semt | Hayır | Talep içine dahil olan bir değer de belirteç yanıtında döndürülür. Kullanmak istediğiniz herhangi bir içerikte bir dize olabilir. Genel olarak, rastgele oluşturulan benzersiz bir değer siteler arası sahte imza isteğini önlemek için kullanılır. Maksimum uzunluk 20 karakterdir. |
| nonce | Hayır | İstemci tarafından gönderilen bir dize değeri, kimlik kodu belirtecinde bir istem olarak sonuçlanan içine dahildir. İstemci daha sonra bu değeri, belirteç yeniden yürütme saldırılarını azaltmak için doğrulayabilir. Maksimum uzunluk 20 karakterdir. |
| response_type | Hayır | Bu parametre değer olarak yalnızca token destekler. Bu, uygulamanızın bir adres belirtecini yetkilendirme uç noktasından anında almasına izin verir, yetkilendirme uç noktasına ikinci bir talepte bulunmadan. |
Not
client_id, redirect_uri, state ve nonce parametreleri isteğe bağlı olsa da, tümleştirmelerinizin güvenli olduğundan emin olmak için bunların kullanılması önerilmektedir.
Başarılı yanıt
Belirteç uç noktası durumu ve expires_in'i yanıt başlıkları olarak, belirteci de form gövdesinde döndürür.
Hata yanıtı
Bir belirteç uç noktasındaki hata, JSON belgesi olarak aşağıdaki değerlerle döndürülür:
- Hata Kimlik Kodu: Hatanın benzersiz kimlik belirleyicisi.
- Hata iletisi: Bir kimlik doğrulama hatasının temel nedenini tanımlamanıza yardımcı olan belirli bir hata iletisi.
- Korelasyon Kimlik Kodu: Hata ayıklama amacıyla kullanılacak bir GUID. Tanılama günlüklerini etkinleştirmişseniz, korelasyon kimlik kodu sunucu hata günlüklerinde mevcut olacaktır.
- Zaman Damgası: Hatanın oluşturulduğu tarih ve saat.
Hata iletisi, oturum açmış kullanıcının varsayılan dilinde görüntülenir. Kullanıcı oturum açmazsa, oturum açma sayfası kullanıcının oturum açması için görüntülenir. Örneğin, bir hata yanıtı şu şekilde görünür:
{"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" }
Kimlik kodu belirtecini doğrula
Bir kimlik kodu belirtecini almak, son kullanıcıyı yetkilendirmek için yeterli değildir; belirtecin imzasını doğrulamanız ve belirteç içindeki iddiaları uygulamanızın gereksinimlerine dayanarak doğrulamanız gerekir. Genel belirteç uç noktası, portalın genel anahtarını sağlar, bu da portal tarafından sağlanan belirtecin imzasını doğrulamakta kullanılabilir. Genel belirteç uç noktası için URL: <portal_url>/_services/auth/publickey.
Örtülü izin akışını aç veya kapat
Varsayılan olarak örtülü izin akışı etkindir. Örtülü izin akışını kapatmak istiyorsanız, Bağlayıcı/ImplicitGrantFlowEnabled site ayarını Yanlış olarak ayarlayın.
Bu site ayarı portalnızda kullanılabilir değilse, uygun değer ile yeni bir site ayarı oluşturmanız gerekir.
Belirteç geçerliliğini yapılandırma
Varsayılan olarak, belirteç 15 dakika süreyle geçerlidir. Bir belirtecin geçerliliğini değiştirmek istiyorsanız, ImplicitGrantFlow/TokenExpirationTime site yarının değerini gerekli değere ayarlayın. Değer saniye cinsinden belirtilmelidir. Maksimum değer 1 saat olabilir ve minimum değer 1 dakika olmalıdır. Hatalı bir değer belirtilirse (örneğin, alfasayısal karakterler), varsayılan değer olan 15 dakika kullanılır. Maksimum değerden fazla veya minimum değerden az bir değer belirtirseniz, maksimum ve minimum değerler varsayılan olarak kullanılır.
Örneğin, belirteç geçerliliğini 30 dakika olarak ayarlamak için ImplicitGrantFlow/TokenExpirationTime site ayarının değerini 1800 olarak ayarlayın. Belirteç geçerliliğini 1 saat olarak ayarlamak için ImplicitGrantFlow/TokenExpirationTime site ayarının değerini 3600 olarak ayarlayın.
Örtülü izin akışı için istemci kimlik kodunu kaydetmek
Bu akışa izin verilmesi için istemci kimlik kodunu portal ile kaydetmeniz gerekir. Bir istemciyi kaydetmek için aşağıdaki site ayarlarını oluşturmanız gerekir:
| Site ayarı | Value |
|---|---|
| ImplicitGrantFlow/RegisteredClientId | Geçerli istemci kimlik kodu değerlerine bu portal için izin verilir. Değerler bir noktalı virgül ile ayrılmalıdır ve alfasayısal karakterler ve tireler içerebilir. Maksimum uzunluk 36 karakterdir. |
| ImplicitGrantFlow/{ClientId}/RedirectUri | Geçerli yönlendirme URI'lerine belirli istemci kimlik kodları için izin verilir. Değerlerin noktalı virgül ile ayrılması gerekir. Sağlanan URL, portalın geçerli web sayfasının olmalıdır. |
Örnek kod
Power Apps portalları API'leriyle OAuth 2.0 Örtük Onay kullanmaya başlamak için aşağıdaki örnek kodu kullanabilirsiniz.
Harici Web API'si ile Portal OAuth belirteci kullanma
ASP.NET tabanlı bir proje olan bu örnek, Power Apps portalları tarafından verilen kimlik belirtecini doğrulamak için kullanılır. Tam örnek burada bulunabilir: Harici bir Web API'si ile Portal OAuth belirteci kullanma.
Uç Nokta Yetkilendirme örneği
Bu örnekte, yetkilendirmede uç noktasın kimlik belirtecini yeniden yönlendirilen URL'deki bir parça olarak nasıl döndürdüğü gösterilmektedir. Ayrıca Örtülü İzin'de desteklemem durum doğrulamayı da içerir. Örnek burada bulunabilir: Uç Nokta Yetkilendirme örneği.
Belirteç Uç Noktası örneği
Bu örnekte, Power Apps portallarında Belirteç uç noktası kullanılan bir kimlik belirteci getirmek için getAuthenticationToken işlevini nasıl kullanacağınız gösterilmektedir. Örnek burada bulunabilir: Belirteç Uç Noktası örneği.