Özel talep sağlayıcı başvurusu

Makale
07/27/2024

Bu başvuru makalesinde, özel talep sağlayıcısı olayları için REST API şeması ve talep eşleme ilkesi yapısı hakkında bilgi edinebilirsiniz.

Belirteç verme başlangıç olayı

Özel talep sağlayıcı belirteci verme olayı, uygulama belirteçlerini dış sistemlerden alınan bilgilerle zenginleştirmenize veya özelleştirmenize olanak tanır. Bu bilgiler, Microsoft Entra dizinindeki kullanıcı profilinin bir parçası olarak depolanamaz.

Bileşene genel bakış

Özel bir uzantıyı ayarlamak ve ayarlamak için uygulamanızla tümleştirmek için birden çok bileşenin bağlanması gerekir. Aşağıdaki diyagramda yapılandırma noktalarının ve özel uzantı uygulamak için oluşturulan ilişkilerin üst düzey bir görünümü gösterilmektedir.

Genel kullanıma açık bir REST API uç noktanız olmalıdır. Bu diyagramda Azure İşlevi tarafından temsil edilir. REST API, özel talepleri oluşturur ve özel uzantıya döndürür. Microsoft Entra uygulama kaydıyla ilişkilidir.
API'nize bağlanacak şekilde yapılandırılmış Microsoft Entra Id'de özel bir uzantı yapılandırmanız gerekir.
Özelleştirilmiş belirteçleri alan bir uygulamaya ihtiyacınız vardır. Örneğin https://jwt.ms , bir belirtecin kodu çözülen içeriğini görüntüleyen Microsoft'a ait bir web uygulaması.
Gibi https://jwt.ms uygulama, uygulama kaydı kullanılarak Microsoft Entra Id'ye kaydedilmelidir.
Uygulamanızla özel uzantınız arasında bir ilişki oluşturmanız gerekir.
Azure İşlevi'nin güvenliğini isteğe bağlı olarak bir kimlik doğrulama sağlayıcısıyla sağlayabilirsiniz. Bu makalede Microsoft Entra Kimliğinizi kullanırız.

REST API

REST API uç noktanız aşağı akış hizmetleriyle birlikte çalışmaktan sorumludur. Örneğin, veritabanları, diğer REST API'leri, LDAP dizinleri veya belirteç yapılandırmasına eklemek istediğiniz öznitelikleri içeren diğer depolar.

REST API, öznitelikleri içeren Microsoft Entra Kimliğine bir HTTP yanıtı döndürür. REST API'niz tarafından döndürülen öznitelikler otomatik olarak bir belirteçe eklenmez. Bunun yerine, bir uygulamanın talep eşleme ilkesinin belirteci içermesi için herhangi bir özniteliğin yapılandırılması gerekir. Microsoft Entra Id'de, talep eşleme ilkesi belirli uygulamalar için verilen belirteçlerde yayılan talepleri değiştirir.

REST API şeması

Belirteç verme başlangıç olayı için kendi REST API'nizi geliştirmek için aşağıdaki REST API veri sözleşmesini kullanın. Şema, istek ve yanıt işleyicisini tasarlamaya yönelik sözleşmeyi açıklar.

Microsoft Entra ID'deki özel uzantınız, JSON yüküyle REST API'nize bir HTTP çağrısı yapar. JSON yükü kullanıcı profili verilerini, kimlik doğrulama bağlamı özniteliklerini ve kullanıcının oturum açmak istediği uygulama hakkındaki bilgileri içerir. id Aşağıdaki JSON'daki değer, Microsoft Entra kimlik doğrulama olayları hizmetini temsil eden bir Microsoft uygulamasıdır. JSON öznitelikleri, API'niz tarafından ek mantık gerçekleştirmek için kullanılabilir. API'nize gönderilen istek aşağıdaki biçimdedir:

POST https://your-api.com/endpoint

{
    "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 extension ID>",
        "authenticationContext": {
            "correlationId": "<GUID>",
            "client": {
                "ip": "30.51.176.110",
                "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": "2016-03-01T15:23:40Z",
                "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": "caseyjensen",
                "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                "onPremisesUserPrincipalName": "Casey Jensen",
                "preferredLanguage": "en-us",
                "surname": "Jensen",
                "userPrincipalName": "casey@contoso.com",
                "userType": "Member"
            }
        }
    }
}

Azure'ın beklediği REST API yanıt biçimi, taleplerin DateOfBirth CustomRoles ve Azure'a döndürüldüğü şu biçimdedir:

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                "claims": {
                    "DateOfBirth": "01/01/2000",
                    "CustomRoles": [
                        "Writer",
                        "Editor"
                    ]
                }
            }
        ]
    }
}

Fabrikam kuruluşundan bir B2B kullanıcısı Contoso'nun kuruluşunda kimlik doğrulaması yaparken, REST API'ye gönderilen istek yükü aşağıdaki biçimde öğesine sahiptir user :

"user": {
    "companyName": "Fabrikam",
    "createdDateTime": "2022-07-15T00:00:00Z",
    "displayName": "John Wright",
    "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "mail": "johnwright@fabrikam.com",
    "preferredDataLocation": "EUR",
    "userPrincipalName": "johnwright_fabrikam.com#EXT#@contoso.onmicrosoft.com",
    "userType": "Guest"
}

Desteklenen veri türleri

Aşağıdaki tabloda, belirteç verme başlangıç olayı için Özel talep sağlayıcıları tarafından desteklenen veri türleri gösterilmektedir:

Veri türü	Desteklenir
String	True
Dize dizisi	True
Boolean	False
JSON	False

Talep boyutu sınırlamaları

Bir talep sağlayıcısının döndürebileceği maksimum talep boyutu 3 KB ile sınırlıdır. Bu, REST API tarafından döndürülen tüm anahtar ve değer çiftlerinin toplamıdır.

Talep eşleme ilkesi

Microsoft Entra Id'de, talep eşleme ilkesi belirli uygulamalar için verilen belirteçlerde yayılan talepleri değiştirir. Özel talep sağlayıcınızdan gelen talepleri içerir ve bunları belirtecin içine aktarır.

{
    "ClaimsMappingPolicy": {
        "Version": 1,
        "IncludeBasicClaimSet": "true",
        "ClaimsSchema": [{
            "Source": "CustomClaimsProvider",
            "ID": "dateOfBirth",
            "JwtClaimType": "birthdate"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "customRoles",
            "JwtClaimType": "my_roles"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "correlationId",
            "JwtClaimType": "correlation_Id"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "apiVersion",
            "JwtClaimType": "apiVersion"
        },
        {
            "Value": "tokenaug_V2",
            "JwtClaimType": "policy_version"
        }]
    }
}

ClaimsSchema öğesi aşağıdaki özniteliklerle eşlenecek taleplerin listesini içerir:

Kaynak özniteliğinin CustomClaimsProviderkaynağı olan öğesini açıklar. Son öğenin test amacıyla ilke sürümüyle sabit bir değer içerdiğini unutmayın. Bu nedenle, source özniteliği atlanır.
Kimlik , oluşturduğunuz Azure İşlevi'nden döndürdüğü taleplerin adıdır.

Önemli

ID özniteliğinin değeri büyük/küçük harfe duyarlıdır. Talep adını Tam olarak Azure İşlevi tarafından döndürülen şekilde yazdığınızdan emin olun.
JwtClaimType , OpenID Connect uygulaması için yayılan belirteçte isteğe bağlı bir talep adıdır. JWT belirtecinde döndüren farklı bir ad sağlamanıza olanak tanır. Örneğin, API yanıtının ID dateOfBirthdeğeri varsa, belirteçte olduğu gibi birthdate yayılabilir.

Talep eşleme ilkenizi oluşturduktan sonra, sonraki adım bunu Microsoft Entra kiracınıza yüklemektir. Kiracınızda aşağıdaki claimsMappingPolicy Graph API'sini kullanın.

Önemli

Tanım öğesi, tek bir dize değerine sahip bir dizi olmalıdır. Dize, talep eşleme ilkenizin dizeleştirilmiş ve kaçış sürümü olmalıdır. Talep eşleme ilkenizi dizeleştirmek için gibi https://jsontostring.com/ araçları kullanabilirsiniz.

Ayrıca bkz.

Belirteç verme başlangıç olayıyla REST API oluşturma
Belirteç verme olayı için özel talep sağlayıcısı yapılandırın.
Nasıl yapılır: Kiracıdaki belirli bir uygulama için belirteçlerde yayılan talepleri özelleştirme
Nasıl yapılır: Kurumsal uygulamalar için SAML belirtecinde verilen talepleri özelleştirme
Taleplerde dizin uzantısı özniteliklerini kullanma.

Aracılığıyla paylaş