Microsoft Graph API'lerini kullanarak sağlamayı yapılandırma

Makale
04/06/2024

Microsoft Entra yönetim merkezi, tek tek uygulamalar için sağlamayı birer birer yapılandırmanın kullanışlı bir yoludur. Ancak bir uygulamanın birkaç örneğini (hatta yüzlercesini) oluşturuyorsanız veya uygulama yapılandırmasını bir ortamdan diğerine geçiriyorsanız, Microsoft Graph API'leriyle uygulama oluşturmayı ve yapılandırmayı otomatikleştirmek daha kolay olabilir. Bu makalede, API'ler aracılığıyla sağlama yapılandırmasının nasıl otomatikleştirilmesi özetlenmiştir. Bu yöntem, Amazon Web Services gibi uygulamalar için yaygın olarak kullanılır.

Bu makalede, Microsoft Graph beta uç noktası ve Microsoft Graph Gezgini'ndeki API'lerle ilgili işlemler gösterilmektedir; benzer API'ler Microsoft Graph v1.0 uç noktasında da kullanılabilir. Graph v1.0 ve PowerShell ile sağlamayı yapılandırma örneği için Bkz. PowerShell veya Microsoft Graph API kullanarak kiracılar arası eşitlemeyi yapılandırma makalesinin 6-13 arası adımları.

Sağlama yapılandırmasını otomatikleştirmek için Microsoft Graph API'lerini kullanma adımlarına genel bakış

Adım	Ayrıntılar
1. Adım. Galeri uygulamasını oluşturma	API istemcisinde oturum açma Galeri uygulaması şablonunu alma Galeri uygulamasını oluşturma
2. Adım. Şablona göre sağlama işi oluşturma	Sağlama bağlayıcısı için şablonu alma Sağlama işini oluşturma
3. Adım. Erişimi yetkilendirme	Uygulama bağlantısını test etme Kimlik bilgilerini kaydetme
4. Adım. Sağlama işini başlatma	İşi başlatma
Adım 5. Sağlamayı izleme	Sağlama işinin durumunu denetleme Sağlama günlüklerini alma

Şirket içi bir uygulamaya sağlamayı kullanıyorsanız, sağlama aracısını yükleyip yapılandırmanız ve sağlama aracısını uygulamaya atamanız gerekir.

1. Adım: Galeri uygulamasını oluşturma

Microsoft Graph Gezgini'ni başlatın.
"Microsoft ile Oturum Aç" düğmesini seçin ve Microsoft Entra Global Yönetici istrator veya Uygulama Yönetici kimlik bilgilerini kullanarak oturum açın.
Oturum başarıyla açıldıktan sonra, sol bölmede kullanıcı hesabı ayrıntılarını görürsünüz.

Galeri uygulaması şablon tanımlayıcısını alma

Microsoft Entra uygulama galerisindeki uygulamaların her birinin, bu uygulamanın meta verilerini açıklayan bir uygulama şablonu vardır. Bu şablonu kullanarak, yönetim için kiracınızda uygulama ve hizmet sorumlusunun bir örneğini oluşturabilirsiniz. AWS Tek Hesap Erişimi için uygulama şablonunun tanımlayıcısını alın ve yanıttan bu öğreticinin devamında kullanılacak id özelliğinin değerini kaydedin.

İste

GET https://graph.microsoft.com/beta/applicationTemplates?$filter=displayName eq 'AWS Single-Account Access'

Response

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
  {
    "id": "8b1025e4-1dd2-430b-a150-2ef79cd700f5",
        "displayName": "AWS Single-Account Access",
        "homePageUrl": "http://aws.amazon.com/",
        "supportedSingleSignOnModes": [
             "password",
             "saml",
             "external"
         ],
         "supportedProvisioningTypes": [
             "sync"
         ],
         "logoUrl": "https://az495088.vo.msecnd.net/app-logo/aws_215.png",
         "categories": [
             "developerServices"
         ],
         "publisher": "Amazon",
         "description": "Federate to a single AWS account and use SAML claims to authorize access to AWS IAM roles. If you have many AWS accounts, consider using the AWS Single Sign-On gallery application instead."    

}

Galeri uygulamasını oluşturma

Kiracınızda uygulama ve hizmet sorumlusu örneği oluşturmak için son adımda uygulamanız için alınan şablon kimliğini kullanın.

İste

POST https://graph.microsoft.com/beta/applicationTemplates/{applicationTemplateId}/instantiate
Content-type: application/json

{
  "displayName": "AWS Contoso"
}

Response

HTTP/1.1 201 OK
Content-type: application/json

{
    "application": {
        "objectId": "cbc071a6-0fa5-4859-8g55-e983ef63df63",
        "appId": "92653dd4-aa3a-3323-80cf-e8cfefcc8d5d",
        "applicationTemplateId": "8b1025e4-1dd2-430b-a150-2ef79cd700f5",
        "displayName": "AWS Contoso",
        "homepage": "https://signin.aws.amazon.com/saml?metadata=aws|ISV9.1|primary|z",
        "replyUrls": [
            "https://signin.aws.amazon.com/saml"
        ],
        "logoutUrl": null,
        "samlMetadataUrl": null,
    },
    "servicePrincipal": {
        "objectId": "f47a6776-bca7-4f2e-bc6c-eec59d058e3e",
        "appDisplayName": "AWS Contoso",
        "applicationTemplateId": "8b1025e4-1dd2-430b-a150-2ef79cd700f5",
        "appRoleAssignmentRequired": true,
        "displayName": "My custom name",
        "homepage": "https://signin.aws.amazon.com/saml?metadata=aws|ISV9.1|primary|z",
        "replyUrls": [
            "https://signin.aws.amazon.com/saml"
        ],
        "servicePrincipalNames": [
            "93653dd4-aa3a-4323-80cf-e8cfefcc8d7d"
        ],
        "tags": [
            "WindowsAzureActiveDirectoryIntegratedApp"
        ],
    }
}

2. Adım: Şablona göre sağlama işini oluşturma

Sağlama bağlayıcısı için şablonu alma

Sağlama için etkinleştirilen galerideki uygulamaların yapılandırmayı kolaylaştıracak şablonları vardır. Sağlama yapılandırmasının şablonunu almak için aşağıdaki isteği kullanın. Kimliği sağlamanız gerektiğini unutmayın. Kimlik, önceki adımda oluşturulan servicePrincipal kaynağının kimliğidir.

İste

GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/templates

Response

HTTP/1.1 200 OK

{
    "value": [
        {
            "id": "aws",
            "factoryTag": "aws",
            "schema": {
                    "directories": [],
                    "synchronizationRules": []
                    }
        }
    ]
}

Sağlama işini oluşturma

Sağlamayı etkinleştirmek için önce bir iş oluşturmanız gerekir. Sağlama işi oluşturmak için aşağıdaki isteği kullanın. İş için kullanılacak şablonu belirtirken önceki adımdaki templateId değerini kullanın.

İste

POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs
Content-type: application/json

{ 
    "templateId": "aws"
}

Response

HTTP/1.1 201 OK
Content-type: application/json

{
    "id": "{jobId}",
    "templateId": "aws",
    "schedule": {
        "expiration": null,
        "interval": "P10675199DT2H48M5.4775807S",
        "state": "Disabled"
    },
    "status": {
        "countSuccessiveCompleteFailures": 0,
        "escrowsPruned": false,
        "synchronizedEntryCountByType": [],
        "code": "NotConfigured",
        "lastExecution": null,
        "lastSuccessfulExecution": null,
        "lastSuccessfulExecutionWithExports": null,
        "steadyStateFirstAchievedTime": "0001-01-01T00:00:00Z",
        "steadyStateLastAchievedTime": "0001-01-01T00:00:00Z",
        "quarantine": null,
        "troubleshootingUrl": null
    }
}

3. Adım: Erişimi yetkilendirme

Uygulama bağlantısını test etme

Üçüncü taraf uygulamayla bağlantıyı test edin. Aşağıdaki örnek, istemci gizli dizisi ve gizli dizi belirteci gerektiren bir uygulamaya yöneliktir. Her uygulamanın kendi gereksinimleri vardır. Uygulamalar genellikle istemci gizli dizisi yerine bir temel adres kullanır. Uygulamanızın hangi kimlik bilgilerini gerektirdiğini belirlemek için uygulamanızın sağlama yapılandırma sayfasına gidin ve geliştirici modunda bağlantıyı test et'e tıklayın. Ağ trafiği kimlik bilgileri için kullanılan parametreleri gösterir. Kimlik bilgilerinin tam listesi için bkz . synchronizationJob: validateCredentials. Azure Databricks gibi uygulamaların çoğu BaseAddress ve SecretToken'a dayanır. BaseAddress, Microsoft Entra yönetim merkezinde kiracı URL'si olarak adlandırılır.

İste

POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}/validateCredentials

{ 
    "credentials": [ 
        { 
            "key": "ClientSecret", "value": "xxxxxxxxxxxxxxxxxxxxx" 
        },
        {
            "key": "SecretToken", "value": "xxxxxxxxxxxxxxxxxxxxx"
        }
    ]
}

Response

HTTP/1.1 204 No Content

Kimlik bilgilerinizi kaydetme

Sağlamayı yapılandırmak için Microsoft Entra Kimliği ile uygulama arasında güven oluşturulması ve Microsoft Entra'nın üçüncü taraf uygulamayı çağırma yetkisine sahip olması gerekir. Aşağıdaki örnek, istemci gizli dizisi ve gizli dizi belirteci gerektiren bir uygulamaya özgüdür. Her uygulamanın kendi gereksinimleri vardır. Kullanılabilir seçenekleri görmek için API belgelerini gözden geçirin.

İste

PUT https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/secrets 

{ 
    "value": [ 
        { 
            "key": "ClientSecret", "value": "xxxxxxxxxxxxxxxxxxxxx"
        },
        {
            "key": "SecretToken", "value": "xxxxxxxxxxxxxxxxxxxxx"
        }
    ]
}

Response

HTTP/1.1 204 No Content

4. Adım: Sağlama işini başlatma

Sağlama işi yapılandırıldığına göre, işi başlatmak için aşağıdaki komutu kullanın.

İste

POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}/start

Response

HTTP/1.1 204 No Content

5. Adım: Sağlamayı izleme

Sağlama işi durumunu izleme

Sağlama işi çalışmaya başladıktan sonra ilerleme durumunu izlemek için aşağıdaki komutu kullanın. Yanıttaki her eşitleme işi, geçerli sağlama döngüsünün durumunun yanı sıra hedef sistemde oluşturulan kullanıcı ve grup sayısı gibi bugüne kadarki istatistikleri içerir.

İste

GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs

Response

HTTP/1.1 200 OK
Content-type: application/json

{ "value": [
{
    "id": "{jobId}",
    "templateId": "aws",
    "schedule": {
        "expiration": null,
        "interval": "P10675199DT2H48M5.4775807S",
        "state": "Disabled"
    },
    "status": {
        "countSuccessiveCompleteFailures": 0,
        "escrowsPruned": false,
        "synchronizedEntryCountByType": [],
        "code": "Paused",
        "lastExecution": null,
        "lastSuccessfulExecution": null,
        "progress": [],
        "lastSuccessfulExecutionWithExports": null,
        "steadyStateFirstAchievedTime": "0001-01-01T00:00:00Z",
        "steadyStateLastAchievedTime": "0001-01-01T00:00:00Z",
        "quarantine": null,
        "troubleshootingUrl": null
    },
    "synchronizationJobSettings": [
      {
          "name": "QuarantineTooManyDeletesThreshold",
          "value": "500"
      }
    ]
}
]
}

Sağlama günlüklerini kullanarak sağlama olaylarını izleme

Sağlama işinin durumunu izlemeye ek olarak, gerçekleşen tüm olayları sorgulamak için sağlama günlüklerini kullanabilirsiniz. Örneğin, belirli bir kullanıcıyı sorgulayıp başarıyla sağlanıp sağlanmadığını belirleyin.

İste

GET https://graph.microsoft.com/beta/auditLogs/provisioning

Response

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#auditLogs/provisioning",
    "value": [
        {
            "id": "gc532ff9-r265-ec76-861e-42e2970a8218",
            "activityDateTime": "2019-06-24T20:53:08Z",
            "tenantId": "7928d5b5-7442-4a97-ne2d-66f9j9972ecn",
            "cycleId": "44576n58-v14b-70fj-8404-3d22tt46ed93",
            "changeId": "eaad2f8b-e6e3-409b-83bd-e4e2e57177d5",
            "action": "Create",
            "durationInMilliseconds": 2785,
            "sourceSystem": {
                "id": "0404601d-a9c0-4ec7-bbcd-02660120d8c9",
                "displayName": "Azure Active Directory",
                "details": {}
            },
            "targetSystem": {
                "id": "cd22f60b-5f2d-1adg-adb4-76ef31db996b",
                "displayName": "AWS Contoso",
                "details": {
                    "ApplicationId": "f2764360-e0ec-5676-711e-cd6fc0d4dd61",
                    "ServicePrincipalId": "chc46a42-966b-47d7-9774-576b1c8bd0b8",
                    "ServicePrincipalDisplayName": "AWS Contoso"
                }
            },
            "initiatedBy": {
                "id": "",
                "displayName": "Azure AD Provisioning Service",
                "initiatorType": "system"
            }
            ]
       }
    ]
}

Microsoft Graph API'lerini kullanarak sağlamayı yapılandırma

1. Adım: Galeri uygulamasını oluşturma

Galeri uygulaması şablon tanımlayıcısını alma

İste

Response

Galeri uygulamasını oluşturma

İste

Response

2. Adım: Şablona göre sağlama işini oluşturma

Sağlama bağlayıcısı için şablonu alma

İste

Response

Sağlama işini oluşturma

İste

Response

3. Adım: Erişimi yetkilendirme

Uygulama bağlantısını test etme

İste

Response

Kimlik bilgilerinizi kaydetme

İste

Response

4. Adım: Sağlama işini başlatma

İste

Response

5. Adım: Sağlamayı izleme

Sağlama işi durumunu izleme

İste

Response

Sağlama günlüklerini kullanarak sağlama olaylarını izleme

İste

Response

Ayrıca bkz.

Ek kaynaklar

Microsoft Graph API'lerini kullanarak sağlamayı yapılandırma

1. Adım: Galeri uygulamasını oluşturma

Microsoft Graph Gezgini'nde (önerilen), Postman'da veya kullandığınız başka bir API istemcisinde oturum açın

Galeri uygulaması şablon tanımlayıcısını alma

İste

Response

Galeri uygulamasını oluşturma

İste

Response

2. Adım: Şablona göre sağlama işini oluşturma

Sağlama bağlayıcısı için şablonu alma

İste

Response

Sağlama işini oluşturma

İste

Response

3. Adım: Erişimi yetkilendirme

Uygulama bağlantısını test etme

İste

Response

Kimlik bilgilerinizi kaydetme

İste

Response

4. Adım: Sağlama işini başlatma

İste

Response

5. Adım: Sağlamayı izleme

Sağlama işi durumunu izleme

İste

Response

Sağlama günlüklerini kullanarak sağlama olaylarını izleme

İste

Response

Ayrıca bkz.

Ek kaynaklar