Share via

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

  • Makale

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.

Özel talep sağlayıcısını ayarlamak ve tümleştirmek için Microsoft Entra Id'de yapılandırılan bileşenleri gösteren ekran görüntüsü.

  • 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 DateOfBirthCustomRoles 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 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 Bağlan 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 IDdateOfBirthdeğ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.