Microsoft kimlik platformu ve OAuth 2.0 Adına akışı

Adına (OBO) akışı, başka bir web API'sini çağırmak için kendi kimliği dışında bir kimlik kullanan bir web API'sinin senaryosunu açıklar. OAuth'da temsilci olarak adlandırılan amaç, istek zinciri aracılığıyla kullanıcının kimliğini ve izinlerini geçirmektir.

Orta katman hizmetinin aşağı akış hizmetine kimliği doğrulanmış isteklerde bulunabilmesi için Microsoft kimlik platformu bir erişim belirtecinin güvenliğini sağlaması gerekir. Uygulama rollerini değil yalnızca temsilci kapsamları kullanır. Roller sorumluya (kullanıcı) bağlı kalır ve hiçbir zaman kullanıcı adına çalışan uygulamaya eklenmez. Bu, kullanıcının erişmemesi gereken kaynaklara izin almasını önlemek için oluşur.

Bu makalede uygulamanızda doğrudan protokol için programlama işlemi açıklanır. Mümkün olduğunda, belirteçleri almak ve güvenli web API’lerini aramak yerine desteklenen Microsoft Kimlik Doğrulama Kitaplıklarını (MSAL) kullanmanızı öneririz. Örnekler için MSAL kullanan örnek uygulamalara da bakın.

İstemci sınırlamaları

Hizmet sorumlusu yalnızca uygulama belirteci istediyse ve bunu bir API'ye gönderdiyse, bu API özgün hizmet sorumlusunu temsil etmeyen bir belirteç değişimi yapar. Bunun nedeni OBO akışının yalnızca kullanıcı sorumluları için çalışmasıdır. Bunun yerine, yalnızca uygulama belirteci almak için istemci kimlik bilgileri akışını kullanması gerekir. Tek sayfalı uygulamalar (SPA' lar) söz konusu olduğunda, bunun yerine OBO akışlarını gerçekleştirmek için bir erişim belirtecini orta katman gizli istemcisine geçirmeleri gerekir.

İstemci, id_token almak için örtük akışı kullanıyorsa ve yanıt URL'sinde joker karakterler varsa, id_token OBO akışı için kullanılamaz. Joker karakter, karakterle biten bir * URL'dir. Örneğin, yanıt URL'si ise https://myapp.com/* istemciyi tanımlayacak kadar özel olmadığından id_token kullanılamaz. Bu, belirtecin verilmesini engeller. Ancak, örtük verme akışı aracılığıyla alınan erişim belirteçleri, başlatan istemcinin joker karakter yanıt URL'si kayıtlı olsa bile gizli bir istemci tarafından kullanılır. Bunun nedeni gizli istemcinin erişim belirtecini alan istemciyi tanımlayabilmesidir. Gizli istemci daha sonra erişim belirtecini kullanarak aşağı akış API'sine yönelik yeni bir erişim belirteci alabilir.

Ayrıca, özel imzalama anahtarları olan uygulamalar OBO akışında orta katman API'leri olarak kullanılamaz. Bu, çoklu oturum açma için yapılandırılmış kurumsal uygulamaları içerir. Orta katman API'sinde özel imzalama anahtarı kullanılıyorsa, aşağı akış API'si ona geçirilen erişim belirtecinin imzasını doğrulamaz. İstemci tarafından denetlenen bir anahtarla imzalanan belirteçler güvenli bir şekilde kabul edilemediğinden bu hatayla sonuçlanır.

Protokol diyagramı

Kullanıcının OAuth 2.0 yetkilendirme kodu verme akışını veya başka bir oturum açma akışını kullanarak bir uygulamanın kimliğini doğruladığını varsayalım. Bu noktada uygulama, kullanıcının talepleri ve orta katman web API'sine (API A) erişme onayıyla API A (belirteç A) için bir erişim belirtecine sahiptir. Şimdi API A'nın aşağı akış web API'sine (API B) kimliği doğrulanmış bir istekte bulunması gerekiyor.

İzleyen adımlar OBO akışını oluşturur ve aşağıdaki diyagram yardımıyla açıklanır.

1. İstemci uygulaması, A belirteci ile (API A talebiyle aud ) A API'sine bir istekte bulunur.
2. API A, Microsoft kimlik platformu belirteci verme uç noktasında kimlik doğrulaması yapar ve API B'ye erişmek için bir belirteç istemektedir.
3. Microsoft kimlik platformu belirteci verme uç noktası, A belirteci ile birlikte API A'nın kimlik bilgilerini doğrular ve API B (belirteç B) için erişim belirtecini API A'ya iletir.
4. B belirteci, API B'ye yapılan isteğin yetkilendirme üst bilgisinde API A tarafından ayarlanır.
5. Güvenli kaynaktan alınan veriler API B tarafından API A'ya ve ardından istemciye döndürülür.

Bu senaryoda, orta katman hizmetinin aşağı akış API'sine erişmek için kullanıcının onayını almak için kullanıcı etkileşimi yoktur. Bu nedenle, aşağı akış API'sine erişim verme seçeneği, kimlik doğrulaması sırasında onay adımının bir parçası olarak önceden sunulur. Bunu uygulamanızda nasıl uygulayacağınızı öğrenmek için bkz . Orta katman uygulaması için onay alma.

Orta katman erişim belirteci isteği

Erişim belirteci istemek için kiracıya özgü Microsoft kimlik platformu belirteci uç noktasına aşağıdaki parametrelerle bir HTTP POST oluşturun.

https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token

İstemci uygulamasının paylaşılan gizli diziyle mi yoksa sertifikayla mı güvenli hale getirileceğini seçmesine bağlı olarak iki durum vardır.

İlk durum: Paylaşılan gizli diziyle belirteç isteğine erişme

Paylaşılan gizli dizi kullanılırken, hizmet-hizmet erişim belirteci isteği aşağıdaki parametreleri içerir:

Örnek

Aşağıdaki HTTP POST, web API'sinin kapsamına https://graph.microsoft.com sahip user.read bir erişim belirteci ve yenileme belirteci istemektedir. İstek, gizli diziyle imzalanır ve gizli bir istemci tarafından yapılır.

//line breaks for legibility only
    
POST /oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com/<tenant>
Content-Type: application/x-www-form-urlencoded
    
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&client_secret=sampleCredentia1s
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCJ9.eyJhdWQiOiIyO{a lot of characters here}
&scope=https://graph.microsoft.com/user.read+offline_access
&requested_token_use=on_behalf_of

İkinci durum: Sertifika ile erişim belirteci isteği

Bir sertifikaya sahip hizmetten hizmete erişim belirteci isteği, önceki örnekteki parametrelere ek olarak aşağıdaki parametreleri içerir:

Parametrelerin paylaşılan gizli dizi tarafından istek durumundakiyle hemen hemen aynı olduğuna dikkat edin, ancak parametresi iki client_secret parametreyle değiştirilir: a client_assertion_type ve client_assertion. client_assertion_type parametresi olarak urn:ietf:params:oauth:client-assertion-type:jwt-bearerclient_assertion, parametresi ise sertifikanın özel anahtarıyla imzalanan JWT belirtecine ayarlanır.

Örnek

Aşağıdaki HTTP POST, bir sertifikaya sahip user.read web API'sinin kapsamına https://graph.microsoft.com sahip bir erişim belirteci istemektedir. İstek, gizli diziyle imzalanır ve gizli bir istemci tarafından yapılır.

// line breaks for legibility only
    
POST /oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com/<tenant>
Content-Type: application/x-www-form-urlencoded
    
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCIsImtpZCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCJ9.eyJhdWQiO{a lot of characters here}
&requested_token_use=on_behalf_of
&scope=https://graph.microsoft.com/user.read+offline_access

Orta katman erişim belirteci yanıtı

Başarılı yanıt, aşağıdaki parametrelere sahip bir JSON OAuth 2.0 yanıtıdır.

Başarı yanıtı örneği

Aşağıdaki örnekte, web API'sine yönelik erişim belirteci isteğine verilen başarı yanıtı gösterilmektedir https://graph.microsoft.com . Yanıt bir erişim belirteci ve yenileme belirteci içerir ve sertifikanın özel anahtarıyla imzalanır.

{
    "token_type": "Bearer",
    "scope": "https://graph.microsoft.com/user.read",
    "expires_in": 3269,
    "ext_expires_in": 0,
    "access_token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1tQTZOVGFlN0NkV1c3UWZkQ0NDYy0tY0hGa18wZE50MVEtc2loVzRMd2RwQVZISGpnTVdQZ0tQeVJIaGlDbUN2NkdyMEpmYmRfY1RmMUFxU21TcFJkVXVydVJqX3Nqd0JoN211eHlBQSIsImFsZyI6IlJTMjU2IiwieDV0IjoiejAzOXpkc0Z1aXpwQmZCVksxVG4yNVFIWU8wIiwia2lkIjoiejAzOXpkc0Z1aXpwQmZCVksxVG4yNVFIWU8wIn0.eyJhdWQiOiJodHRwczovL2dyYXBoLm1pY3Jvc29mdC5jb20iLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMWRiNDcvIiwiaWF0IjoxNDkzOTMwMzA1LCJuYmYiOjE0OTM5MzAzMDUsImV4cCI6MTQ5MzkzMzg3NSwiYWNyIjoiMCIsImFpbyI6IkFTUUEyLzhEQUFBQU9KYnFFWlRNTnEyZFcxYXpKN1RZMDlYeDdOT29EMkJEUlRWMXJ3b2ZRc1k9IiwiYW1yIjpbInB3ZCJdLCJhcHBfZGlzcGxheW5hbWUiOiJUb2RvRG90bmV0T2JvIiwiYXBwaWQiOiIyODQ2ZjcxYi1hN2E0LTQ5ODctYmFiMy03NjAwMzViMmYzODkiLCJhcHBpZGFjciI6IjEiLCJmYW1pbHlfbmFtZSI6IkNhbnVtYWxsYSIsImdpdmVuX25hbWUiOiJOYXZ5YSIsImlwYWRkciI6IjE2Ny4yMjAuMC4xOTkiLCJuYW1lIjoiTmF2eWEgQ2FudW1hbGxhIiwib2lkIjoiZDVlOTc5YzctM2QyZC00MmFmLThmMzAtNzI3ZGQ0YzJkMzgzIiwib25wcmVtX3NpZCI6IlMtMS01LTIxLTIxMjc1MjExODQtMTYwNDAxMjkyMC0xODg3OTI3NTI3LTI2MTE4NDg0IiwicGxhdGYiOiIxNCIsInB1aWQiOiIxMDAzM0ZGRkEwNkQxN0M5Iiwic2NwIjoiVXNlci5SZWFkIiwic3ViIjoibWtMMHBiLXlpMXQ1ckRGd2JTZ1JvTWxrZE52b3UzSjNWNm84UFE3alVCRSIsInRpZCI6IjcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0NyIsInVuaXF1ZV9uYW1lIjoibmFjYW51bWFAbWljcm9zb2Z0LmNvbSIsInVwbiI6Im5hY2FudW1hQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJWR1ItdmtEZlBFQ2M1dWFDaENRSkFBIiwidmVyIjoiMS4wIn0.cubh1L2VtruiiwF8ut1m9uNBmnUJeYx4x0G30F7CqSpzHj1Sv5DCgNZXyUz3pEiz77G8IfOF0_U5A_02k-xzwdYvtJUYGH3bFISzdqymiEGmdfCIRKl9KMeoo2llGv0ScCniIhr2U1yxTIkIpp092xcdaDt-2_2q_ql1Ha_HtjvTV1f9XR3t7_Id9bR5BqwVX5zPO7JMYDVhUZRx08eqZcC-F3wi0xd_5ND_mavMuxe2wrpF-EZviO3yg0QVRr59tE3AoWl8lSGpVc97vvRCnp4WVRk26jJhYXFPsdk4yWqOKZqzr3IFGyD08WizD_vPSrXcCPbZP3XWaoTUKZSNJg",
    "refresh_token": "OAQABAAAAAABnfiG-mA6NTae7CdWW7QfdAALzDWjw6qSn4GUDfxWzJDZ6lk9qRw4An{a lot of characters here}"
}

Bu erişim belirteci, Microsoft Graph için v1.0 biçimli bir belirteçtir. Bunun nedeni, belirteç biçiminin erişilen kaynağa dayalı olması ve istekte bulunmak için kullanılan uç noktalarla ilgisiz olmasıdır. Microsoft Graph, v1.0 belirteçlerini kabul etmek üzere ayarlanır, bu nedenle bir istemci Microsoft Graph için belirteç istediğinde Microsoft kimlik platformu v1.0 erişim belirteçleri üretir. Diğer uygulamalar v2.0 biçimli belirteçler, v1.0 biçimli belirteçler, hatta özel veya şifrelenmiş belirteç biçimleri istediklerini gösterebilir. Hem v1.0 hem de v2.0 uç noktaları iki belirteç biçimini de yayar. Bu şekilde, istemci tarafından belirtecin nasıl veya nerede istendiğine bakılmaksızın kaynak her zaman doğru belirteç biçimini alabilir.

Hata yanıtı örneği

Aşağı akış API'sinde Koşullu Erişim ilkesi (çok faktörlü kimlik doğrulaması gibi) kümesi varsa, aşağı akış API'sinin erişim belirteci alınmaya çalışılırken belirteç uç noktası tarafından bir hata yanıtı döndürülür. Orta katman hizmeti, istemci uygulamasının Koşullu Erişim ilkesini karşılamak için kullanıcı etkileşimi sağlayabilmesi için bu hatayı istemci uygulamasına sunmalıdır.

Bu hatayı istemciye geri döndürmek için, orta katman hizmeti HTTP 401 Yetkisiz ve hatayı ve talep sınamasını içeren bir WWW-Authenticate HTTP üst bilgisi ile yanıtlar. İstemci, varsa talep sınamasını sunarak bu üst bilgiyi ayrıştırmalı ve belirteç verenden yeni bir belirteç almalıdır. İstemciler, önbelleğe alınmış erişim belirteci kullanarak orta katman hizmetine erişmeyi yeniden denememelidir.

{
    "error":"interaction_required",
    "error_description":"AADSTS50079: Due to a configuration change made by your administrator, or because you moved to a new location, you must enroll in multifactor authentication to access 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2017-05-01 22:43:20Z",
    "error_codes":[50079],
    "timestamp":"2017-05-01 22:43:20Z",
    "trace_id":"0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id":"aaaa0000-bb11-2222-33cc-444444dddddd",
    "claims":"{\"access_token\":{\"polids\":{\"essential\":true,\"values\":[\"00aa00aa-bb11-cc22-dd33-44ee44ee44ee\"]}}}"
}

Güvenli kaynağa erişmek için erişim belirtecini kullanma

Artık orta katman hizmeti, üst bilgideki belirteci ayarlayarak aşağı akış web API'sine kimliği doğrulanmış istekler yapmak için daha önce alınan belirteci Authorization kullanabilir.

Örnek

    GET /v1.0/me HTTP/1.1
    Host: graph.microsoft.com
    Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw

OAuth2.0 OBO akışıyla alınan SAML onayları

Bazı OAuth tabanlı web hizmetlerinin etkileşimli olmayan akışlarda SAML onaylarını kabul eden diğer web hizmeti API'lerine erişmesi gerekir. Microsoft Entra Id, hedef kaynak olarak SAML tabanlı bir web hizmeti kullanan Bir Adına Akışına yanıt olarak bir SAML onaylaması sağlayabilir.

Bu, OAuth2 tabanlı bir uygulamanın SAML belirteçleri kullanan web hizmeti API'si uç noktalarına erişmesine olanak tanıyan OAuth 2.0 On-Behalf-Of akışının standart olmayan bir uzantısıdır.

Paylaşılan gizli dizi ile OBO isteği kullanarak SAML belirteci alma

SAML onayı için hizmet-hizmet isteği aşağıdaki parametreleri içerir:

Yanıt, UTF8 ve Base 64url'de kodlanmış bir SAML belirteci içerir.

• OBO çağrısından kaynaklanan bir SAML onaylama işlemi için SubjectConfirmationData: Hedef uygulama içinde SubjectConfirmationDatabir Recipient değer gerektiriyorsa, değerin kaynak uygulaması yapılandırmasındaki ilk anahtarsız Yanıt URL'si olarak yapılandırılması gerekir. Değeri belirlemek Recipient için varsayılan Yanıt URL'si kullanılmadığından, ilk döndürülmeyen Yanıt URL'sinin kullanıldığından emin olmak için uygulama yapılandırmasındaki Yanıt URL'lerini yeniden sıralamanız gerekebilir. Daha fazla bilgi için bkz . Yanıt URL'leri.
• SubjectConfirmationData düğümü: SamL yanıtının parçası InResponseTo olmadığından düğüm öznitelik içeremez. SAML belirtecini alan uygulamanın bir InResponseTo öznitelik olmadan SAML onayını kabul edebilmesi gerekir.
• API izinleri: SAML uygulamasına erişime izin vermek için, SAML uygulamasının kapsamı için belirteç isteyebilmesi için orta katman uygulamasına /.default gerekli API izinlerini eklemeniz gerekir.
• Onay: OAuth akışında kullanıcı verilerini içeren bir SAML belirteci almak için onay verilmelidir. Bilgi için bkz . Orta katman uygulaması için onay alma.

SAML onay ile yanıt

• token_type: Taşıyıcı
• expires_in: 3296
• ext_expires_in: 0
• expires_on: 1529627844
• Kaynak: https://api.contoso.com
• access_token: <SAML onayı>
• issued_token_type: urn:ietf:params:oauth:token-type:saml2
• refresh_token: <Belirteci yenileme>

Orta katman uygulaması için onay alma

OBO akışının amacı, istemci uygulamasının orta katman uygulamasını çağırabilmesi ve orta katman uygulamasının arka uç kaynağını çağırma iznine sahip olması için uygun onayın verildiğinden emin olmaktır. Uygulamanızın mimarisine veya kullanımına bağlı olarak, OBO akışının başarılı olduğundan emin olmak için aşağıdakileri göz önünde bulundurmanız gerekir:

.default ve birleşik onay

Orta katman uygulaması, istemciyi bildirimindeki bilinen istemci uygulamaları listesine (knownClientApplications) ekler. İstemci tarafından bir onay istemi tetikleniyorsa, onay akışı hem kendisi hem de orta katman uygulaması içindir. Microsoft kimlik platformu, bu kapsam kullanılarak .default yapılır. Kapsam .default , uygulamanın izinlerine sahip olduğu tüm kapsamlara erişim izni istemek için kullanılan özel bir kapsamdır. Bu, uygulamanın birden çok kaynağa erişmesi gerektiğinde yararlıdır, ancak kullanıcıdan yalnızca bir kez onay istenmesi gerekir.

bilinen istemci uygulamalarını ve .defaultkullanarak bir onay ekranı tetiklerken, onay ekranı hem istemcinin orta katman API'sine yönelik izinleri gösterir hem de orta katman API'sinin gerektirdiği izinleri isteyebilir. Kullanıcı her iki uygulama için de onay sağlar ve ardından OBO akışı çalışır.

İstekte tanımlanan kaynak hizmeti (API), kullanıcının oturum açma işlemi sonucunda istemci uygulamasının erişim belirteci istediği API olmalıdır. Örneğin, scope=openid https://middle-tier-api.example.com/.default (orta katman API'sine erişim belirteci istemek için) veya scope=openid offline_access .default (bir kaynak tanımlanmadığında varsayılan olarak Microsoft Graph olur).

Yetkilendirme isteğinde hangi API'nin tanımlandığına bakılmaksızın, onay istemi istemci uygulaması için yapılandırılan tüm gerekli izinlerle birleştirilir. İstemciyi bilinen bir istemci uygulaması olarak tanımlayan istemcinin gerekli izinler listesinde listelenen her orta katman API'sine yönelik olarak yapılandırılan tüm gerekli izinler de eklenir.

Önceden yetkilendirilmiş uygulamalar

Kaynaklar, belirli bir uygulamanın her zaman belirli kapsamları alma iznine sahip olduğunu gösterebilir. Bu, ön uç istemcisiyle arka uç kaynağı arasındaki bağlantıları daha sorunsuz hale getirmek için kullanışlıdır. Bir kaynak, bildiriminde birden çok önceden doğrulanmış uygulama (preAuthorizedApplications) bildirebilir. Bu tür uygulamalar bir OBO akışında bu izinleri isteyebilir ve kullanıcı onay vermeden alabilir.

Yönetici onayı

Kiracı yöneticisi, orta katman uygulaması için yönetici onayı sağlayarak uygulamaların gerekli API'lerini çağırma iznine sahip olduğunu garanti edebilir. Bunu yapmak için yönetici, orta katman uygulamasını kiracısında bulabilir, gerekli izinler sayfasını açabilir ve uygulama için izin vermeyi seçebilir. Yönetici onayı hakkında daha fazla bilgi edinmek için onay ve izin belgelerine bakın.

Tek bir uygulamanın kullanımı

Bazı senaryolarda yalnızca orta katman ve ön uç istemci çifti olabilir. Bu senaryoda, orta katman uygulama gereksinimini tamamen ortadan kaldırarak bunu tek bir uygulama haline getirmenin daha kolay olduğunu fark edebilirsiniz. Ön uç ile web API'si arasında kimlik doğrulaması yapmak için tanımlama bilgilerini, id_token veya uygulamanın kendisi için istenen erişim belirtecini kullanabilirsiniz. Ardından, bu tek uygulamadan arka uç kaynağına onay isteyin.

Ayrıca bkz.

OAuth 2.0 protokolü ve istemci kimlik bilgilerini kullanarak hizmet kimlik doğrulaması gerçekleştirmenin başka bir yolu hakkında daha fazla bilgi edinin.

• Microsoft kimlik platformu'de OAuth 2.0 istemci kimlik bilgileri verme
• Microsoft kimlik platformu'da OAuth 2.0 kod akışı
• /.default Kapsamı kullanma