Özel talep sağlayıcı API'nizin sorunlarını giderme

Kimlik doğrulama olayları ve özel talep sağlayıcıları , dış sistemlerle tümleştirerek Microsoft Entra kimlik doğrulama deneyimini özelleştirmenize olanak tanır. Örneğin, bir özel talep sağlayıcısı API'si oluşturabilir ve bir OpenID Bağlan uygulaması veya SAML uygulaması yapılandırarak dış depodan talep içeren belirteçler alabilirsiniz.

Hata davranışı

API çağrısı başarısız olduğunda hata davranışı aşağıdaki gibidir:

• OpenId Bağlan uygulamaları için - Microsoft Entra Id kullanıcıyı bir hatayla istemci uygulamasına geri yönlendirir. Belirteç basılamaz.
• SAML uygulamaları için - Microsoft Entra Id, kullanıcıya kimlik doğrulama deneyiminde bir hata ekranı gösterir. Kullanıcı istemci uygulamasına geri yönlendirilmiyor.

Uygulamaya veya kullanıcıya geri gönderilen hata kodu geneldir. Sorun gidermek için hata kodları için oturum açma günlüklerine bakın.

Günlük Kaydı

Özel talep sağlayıcı REST API uç noktanızla ilgili sorunları gidermek için REST API'nin günlüğü işlemesi gerekir. Azure İşlevleri ve diğer API geliştirme platformları ayrıntılı günlüğe kaydetme çözümleri sağlar. API'lerinizin davranışı hakkında ayrıntılı bilgi almak ve API mantığınızın sorunlarını gidermek için bu çözümleri kullanın.

Microsoft Entra oturum açma günlükleri

İpucu

Bu makaledeki adımlar, başladığınız portala göre biraz değişiklik gösterebilir.

REST API günlüklerinize ve barındırma ortamı tanılama çözümlerinize ek olarak Microsoft Entra oturum açma günlüklerini de kullanabilirsiniz. Microsoft Entra oturum açma günlüklerini kullanarak, kullanıcıların oturum açmalarını etkileyebilecek hatalar bulabilirsiniz. Microsoft Entra oturum açma günlükleri HTTP durumu, hata kodu, yürütme süresi ve API'nin Microsoft Entra Id tarafından çağrıldığı yeniden deneme sayısı hakkında bilgi sağlar.

Microsoft Entra oturum açma günlükleri, Azure İzleyici ile de tümleşir. Uyarılar ve izleme ayarlayabilir, verileri görselleştirebilir ve güvenlik bilgileri ve olay yönetimi (SIEM) araçlarıyla tümleştirebilirsiniz. Örneğin, hata sayısı seçtiğiniz belirli bir eşiği aşarsa bildirimleri ayarlayabilirsiniz.

Microsoft Entra oturum açma günlüklerine erişmek için:

1. Microsoft Entra yönetim merkezinde en azından bir Bulut Uygulaması Yönetici istrator olarak oturum açın.

2. Kimlik>Uygulamaları>Kurumsal uygulamaları'na göz atın.

3. Oturum açma günlükleri'ni ve ardından en son oturum açma günlüğünü seçin.

4. Daha fazla ayrıntı için Kimlik Doğrulama Olayları sekmesini seçin. Hata kodları dahil olmak üzere özel kimlik doğrulama uzantısı REST API çağrısıyla ilgili bilgiler görüntülenir.

   

Hata kodları başvurusu

Hata kodunu tanılamak için aşağıdaki tabloyu kullanın.

Hata kodu	Hata Adı	Açıklama
1003000	EventHandlerUnexpectedError	Olay işleyicisi işlenirken beklenmeyen bir hata oluştu.
1003001	CustomExtenstionUnexpectedError	Özel uzantı API'si çağrılırken beklenmeyen bir hata oluştu.
1003002	CustomExtensionInvalidHTTPStatus	Özel uzantı API'si geçersiz bir HTTP durum kodu döndürdü. API'nin bu özel uzantı türü için tanımlanmış kabul edilen bir durum kodu döndürdüğünü denetleyin.
1003003	CustomExtensionInvalidResponseBody	Özel uzantının yanıt gövdesi ayrıştırmada bir sorun oluştu. API yanıt gövdesinin bu özel uzantı türü için kabul edilebilir bir şemada olup olmadığını denetleyin.
1003004	CustomExtensionThrottlingError	Çok fazla özel uzantı isteği var. Azaltma sınırlarına ulaşıldığında özel uzantı API'leri çağrıları için bu özel durum oluşturulur.
1003005	CustomExtensionTimedOut	Özel uzantı izin verilen zaman aşımı içinde yanıt vermedi. API'nizin özel uzantı için yapılandırılmış zaman aşımı içinde yanıt verdiğini denetleyin. Erişim belirtecinin geçersiz olduğunu da gösterebilir. REST API'nizi doğrudan çağırmak için adımları izleyin.
1003006	CustomExtensionInvalidResponseContentType	Özel uzantının yanıt içerik türü 'application/json' değil.
1003007	CustomExtensionNullClaimsResponse	Özel uzantı API'si null talep paketiyle yanıt verdi.
1003008	CustomExtensionInvalidResponseApiSchemaVersion	Özel uzantı API'si çağrıldığı apiSchemaVersion ile yanıt vermedi.
1003009	CustomExtensionEmptyResponse	Bu beklenmiyorsa özel uzantı API'sinin yanıt gövdesi null idi.
1003010	CustomExtensionInvalidNumberOfActions	Özel uzantı API'sinin yanıtı, bu özel uzantı türü için desteklenenlerden farklı sayıda eylem içeriyor.
1003011	CustomExtensionNotFound	Olay dinleyicisiyle ilişkilendirilmiş özel uzantı bulunamadı.
1003012	CustomExtensionInvalidActionType	Özel uzantı, bu özel uzantı türü için tanımlanan geçersiz bir eylem türü döndürdü.
1003014	CustomExtensionIncorrectResourceIdFormat	Özel uzantının uygulama kaydının bildirimindeki identifierUris özelliği "api://{tam etki alanı adı}/{appid} biçiminde olmalıdır.
1003015	CustomExtensionDomainNameDoesNotMatch	Özel uzantının targetUrl ve resourceId değeri aynı tam etki alanı adına sahip olmalıdır.
1003016	CustomExtensionResourceServicePrincipalNotFound	Özel uzantı resourceId'sinin appId değeri kiracıdaki gerçek bir hizmet sorumlusuna karşılık gelir.
1003017	CustomExtensionClientServicePrincipalNotFound	Özel uzantı kaynak hizmet sorumlusu kiracıda bulunamadı.
1003018	CustomExtensionClientServiceDisabled	Özel uzantı kaynak hizmet sorumlusu bu kiracıda devre dışı bırakıldı.
1003019	CustomExtensionResourceServicePrincipalDisabled	Özel uzantı kaynak hizmet sorumlusu bu kiracıda devre dışı bırakıldı.
1003020	CustomExtensionIncorrectTargetUrlFormat	Hedef URL yanlış biçimde. Https ile başlayan geçerli bir URL olmalıdır.
1003021	CustomExtensionPermissionNotGrantedToServicePrincipal	Hizmet sorumlusu, uygulamanın özel kimlik doğrulama uzantısı HTTP istekleri alması için gereken Microsoft Graph CustomAuthenticationExtensions.Receive.Payload uygulama rolü (uygulama izni olarak da bilinir) için yönetici onayına sahip değildir.
1003022	CustomExtensionMsGraphServicePrincipalDisabledOrNotFound	MS Graph hizmet sorumlusu devre dışı bırakıldı veya bu kiracıda bulunamadı.
1003023	CustomExtensionBlocked	Özel uzantı için kullanılan uç nokta hizmet tarafından engellenir.
1003024	CustomExtensionResponseSizeExceededed	Özel uzantı yanıt boyutu üst sınırı aştı.
1003025	CustomExtensionResponseClaimsSizeExceeded	Özel uzantı yanıtında taleplerin toplam boyutu üst sınırı aştı.
1003026	CustomExtensionNullOrEmptyClaimKeyNotSupported	Özel uzantı API'si null veya boş anahtar içeren taleplerle yanıt verdi'
1003027	CustomExtension Bağlan ionError	Özel uzantı API'sine bağlanırken hata oluştu.

REST API'nizi doğrudan çağırma

REST API'niz bir Microsoft Entra erişim belirteci ile korunur. API'nizi şu şekilde test edebilirsiniz:

• Özel kimlik doğrulama uzantılarıyla ilişkilendirilmiş bir uygulama kaydıyla erişim belirteci alma
• API test aracını kullanarak API'nizi yerel olarak test edin.

Erişim belirteci alma

Erişim belirtecini aldıktan sonra HTTP Authorization üst bilgisini geçirin. Erişim belirteci almak için şu adımları izleyin:

1. Microsoft Entra yönetim merkezinde en azından bir Bulut Uygulaması Yönetici istrator olarak oturum açın.

2. Kimlik>Uygulamaları>Uygulama kayıtları'na göz atın.

3. Daha önce belirteç verme olayı için özel talep sağlayıcısı yapılandırma bölümünde yapılandırılan Azure İşlevleri kimlik doğrulama olayları API'sinin uygulama kaydını seçin.

4. Uygulama kimliğini kopyalayın.

5. Uygulama gizli dizisi oluşturmadıysanız şu adımları izleyin:

   1. Sertifikalar ve gizli diziler İstemci gizli>dizileri>Yeni istemci gizli dizisi'ni seçin.
   2. İstemci gizli diziniz için bir açıklama ekleyin.
   3. Gizli dizi için bir süre sonu seçin veya özel bir yaşam süresi belirtin.
   4. Ekle'yi seçin.
   5. Gizli anahtarın değerini istemci uygulama kodunuzda kullanmak üzere kaydedin. Bu sayfadan ayrıldıktan sonra bu gizli anahtar değeri hiçbir zaman görüntülenmez.

6. Menüden Bir API'yi kullanıma sunma'yı seçin ve Uygulama Kimliği URI'sinin değerini kopyalayın. Örneğin, api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444.

7. Tercih ettiğiniz API test aracını açın ve yeni bir HTTP sorgusu oluşturun.

8. HTTP yöntemini olarak POSTdeğiştirin.

9. Aşağıdaki URL'yi girin. değerini {tenantID} kiracı kimliğiniz ile değiştirin.

   https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token
   

10. Gövde'nin altında form-data'yı seçin ve aşağıdaki anahtarları ekleyin:

    Anahtar	Değer
    grant_type	client_credentials
    client_id	Uygulamanızın İstemci Kimliği.
    client_secret	Uygulamanızın İstemci Gizli Anahtarı.
    scope	Uygulamanızın Uygulama Kimliği URI'si , ardından ekleyin .default. Örneğin api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444/.default

11. HTTP sorgusunu çalıştırın ve web uygulamasına https://jwt.ms kopyalayınaccess_token.

12. değerini iss API'nizde yapılandırdığınız veren adıyla karşılaştırın.

13. öğesini aud API'nizde yapılandırdığınız istemci kimliğiyle karşılaştırın.

API test araçları

Tercih ettiğiniz API test aracını kullanarak API'nizi doğrudan test etmek için şu adımları izleyin:

Not

Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents NuGet paketini kullandıysanız, test amacıyla belirteç doğrulamayı kapatın. local.settings.json açın ve aşağıdaki parametreyi ekleyin

"AuthenticationEvents__BypassTokenValidation": true

Testi tamamladıktan sonra kaldırdığınızdan emin olun.

1. REST API'nizde veya azptalep doğrulamasını appiddevre dışı bırakın. Daha önce oluşturduğunuz işlev API'sini düzenlemeyi öğrenin.

2. Yeni HTTP isteği oluşturun ve HTTP yöntemini olarak POSTayarlayın.

3. Gövde'de Ham'ıve ardından JSON'ı seçin.

4. Microsoft Entra Id'nin REST API'nize gönderdiği isteği taklit eden aşağıdaki JSON'u yapıştırın.

   {
       "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
       "source": "/tenants/<Your tenant GUID>/applications/<Your Test Application App Id>",
       "data": {
           "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
           "tenantId": "<Your tenant GUID>",
           "authenticationEventListenerId": "<GUID>",
           "customAuthenticationExtensionId": "<Your custom authentication extension ID>",
           "authenticationContext": {
               "correlationId": "<Enter correlation ID here>",
               "client": {
                   "ip": "127.0.0.1",
                   "locale": "en-us",
                   "market": "en-us"
               },
               "protocol": "OAUTH2.0",
               "clientServicePrincipal": {
                   "id": "<Your Test Applications servicePrincipal objectId>",
                   "appId": "<Your Test Application App Id>",
                   "appDisplayName": "My Test application",
                   "displayName": "My Test application"
               },
               "resourceServicePrincipal": {
                   "id": "<Your Test Applications servicePrincipal objectId>",
                   "appId": "<Your Test Application App Id>",
                   "appDisplayName": "My Test application",
                   "displayName": "My Test application"
               },
               "user": {
                   "companyName": "Casey Jensen",
                   "createdDateTime": "2023-08-16T00:00:00Z",
                   "displayName": "Casey Jensen",
                   "givenName": "Casey",
                   "id": "90847c2a-e29d-4d2f-9f54-c5b4d3f26471", // Client ID representing the Microsoft Entra authentication events service
                   "mail": "casey@contoso.com",
                   "onPremisesSamAccountName": "Casey Jensen",
                   "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                   "onPremisesUserPrincipalName": "Casey Jensen",
                   "preferredLanguage": "en-us",
                   "surname": "Jensen",
                   "userPrincipalName": "casey@contoso.com",
                   "userType": "Member"
               }
           }
       }
   }
   

   İpucu

   Microsoft Entra Id'den alınan bir erişim belirteci kullanıyorsanız Yetkilendirme'yi seçin ve taşıyıcı belirteci'ni seçin, ardından Microsoft Entra Id'den aldığınız erişim belirtecini yapıştırın.

5. Gönder'i seçtiğinizde aşağıdakine benzer bir JSON yanıtı almanız gerekir:

   {
       "data": {
           "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
           "actions": [
               {
                   "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                   "claims": {
                       "customClaim1": "customClaimValue1",
                       "customClaim2": [
                           "customClaimString1",
                           "customClaimString2" 
                       ]
                   }
               }
   
           ]
       }
   }
   

Yaygın performans geliştirmeleri

En yaygın sorunlardan biri, özel talep sağlayıcı API'nizin iki saniyelik zaman aşımı içinde yanıt vermemesidir. REST API'niz sonraki yeniden denemelerde yanıt vermezse kimlik doğrulaması başarısız olur. REST API'nizin performansını geliştirmek için aşağıdaki önerileri izleyin:

1. API'niz herhangi bir aşağı akış API'sine erişiyorsa, bu API'leri çağırmak için kullanılan erişim belirtecini önbelleğe alarak her yürütmede yeni bir belirtecin alınması gerekmez.
2. Performans sorunları genellikle aşağı akış hizmetleriyle ilgilidir. Herhangi bir aşağı akış hizmetini çağırmak için işlem süresini kaydeden günlük kaydı ekleyin.
3. API'nizi barındırmak için bir bulut sağlayıcısı kullanıyorsanız, API'yi her zaman "sıcak" tutan bir barındırma planı kullanın. Azure İşlevleri için Premium plan veya Ayrılmış plan olabilir.
4. Kimlik doğrulamalarınız için otomatik tümleştirme testleri çalıştırın. Yalnızca API performansınızı test etmek için API test araçlarını da kullanabilirsiniz.

Ayrıca bkz.

• Belirteç verme başlangıç olayıyla REST API oluşturma
• SamL uygulamasını dış depodan talepler içeren belirteçleri alacak şekilde yapılandırma
• Özel talep sağlayıcısı başvuru makalesi.