Configuración del aprovisionamiento mediante las Microsoft Graph API

Artículo
04/08/2024

El Centro de administración de Microsoft Entra ofrece una manera cómoda de configurar el aprovisionamiento de aplicaciones individuales de una en una. Pero si va a crear varias instancias de una aplicación, o incluso cientos, o migrar la configuración de la aplicación de un entorno a otro, puede ser más fácil automatizar la creación y la configuración de las aplicaciones con Microsoft Graph API. En este artículo se explica cómo automatizar la configuración de aprovisionamiento a través de las API. Este método se usa normalmente para aplicaciones como Amazon Web Services.

En este artículo se muestra el proceso con las API del punto de conexión beta de Microsoft Graph y Microsoft Graph Explorer; Las API similares también están disponibles en el punto de conexión de Microsoft Graph v1.0. Para obtener un ejemplo de configuración del aprovisionamiento con Graph v1.0 y PowerShell, consulte los pasos 6-13 de Configuración de la sincronización entre inquilinos mediante PowerShell o Microsoft Graph API.

Información general de los pasos para usar las Microsoft Graph API para automatizar la configuración del aprovisionamiento

Paso	Detalles
Paso 1. Crear la aplicación de galería	Iniciar sesión en el cliente API Recuperar la plantilla de la aplicación de galería Crear la aplicación de galería
Paso 2. Crear el trabajo de aprovisionamiento basado en la plantilla	Recuperar la plantilla para el conector de aprovisionamiento Crear el trabajo de aprovisionamiento
Paso 3. Autorizar el acceso	Probar la conexión con la aplicación Guardar las credenciales
Paso 4. Iniciar el trabajo de aprovisionamiento	Inicio del trabajo
Paso 5. Supervisar el aprovisionamiento	Comprobar el estado del trabajo de aprovisionamiento Recuperar los registros de aprovisionamiento

Si está aprovisionando en una aplicación local, también deberá instalar y configurar el agente de aprovisionamiento y asignarlo a la aplicación.

Paso 1: Crear la aplicación de galería

Inicie el Explorador de Microsoft Graph.
Seleccione el botón "Iniciar sesión con Microsoft" e inicie sesión con las credenciales de administrador de la aplicación o de administrador global de Microsoft Entra.
Una vez haya iniciado sesión correctamente, verá los detalles de la cuenta de usuario en el panel izquierdo.

Recuperar el identificador de plantilla de la aplicación de galería

Las aplicaciones en la galería de aplicaciones de Microsoft Entra tienen cada una; plantilla de aplicación que describe los metadatos para esa aplicación. Con esta plantilla, puede crear una instancia de la aplicación y la entidad de servicio en el inquilino para la administración. Recupere el identificador de la plantilla de aplicación para AWS Single-Account Access y, a partir de la respuesta, registre el valor de la propiedad id para usarlo más adelante en este tutorial.

Solicitud

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."    

}

Crear la aplicación de galería

Use el id. de plantilla recuperado para la aplicación en el último paso para crear una instancia de la aplicación y la entidad de servicio en el inquilino.

Solicitud

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"
        ],
    }
}

Paso 2: Crear el trabajo de aprovisionamiento basado en la plantilla

Recuperar la plantilla para el conector de aprovisionamiento

Las aplicaciones de la galería que están habilitadas para el aprovisionamiento tienen plantillas para simplificar la configuración. Use la solicitud siguiente para recuperar la plantilla para la configuración del aprovisionamiento. Tenga en cuenta que tendrá que proporcionar el identificador. El id. es el del recurso servicePrincipal, creado en el paso anterior.

Solicitar

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

Response

HTTP/1.1 200 OK

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

Crear el trabajo de aprovisionamiento

Para habilitar el aprovisionamiento, primero deberá crear un trabajo. Use la solicitud siguiente para crear un trabajo de aprovisionamiento. Use el elemento templateId del paso anterior al especificar la plantilla que se va a usar para el trabajo.

Solicitud

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
    }
}

Paso 3: Autorizar el acceso

Probar la conexión con la aplicación

Pruebe la conexión con la aplicación de otro fabricante. El ejemplo siguiente es para una aplicación que requiere un secreto de cliente y un token secreto. Cada aplicación tiene sus propios requisitos. Las aplicaciones suelen usar una dirección base en lugar de un secreto de cliente. Para determinar qué credenciales requiere la aplicación, vaya a la página de configuración de aprovisionamiento de la aplicación y, en el modo de desarrollador, haga clic en Probar conexión. El tráfico de red mostrará los parámetros que se usan para las credenciales. Para obtener una lista completa de las credenciales, vea synchronizationJob: validateCredentials. La mayoría de las aplicaciones, como Azure Databricks, se basan en BaseAddress y SecretToken. BaseAddress se conoce como una dirección URL de inquilino en el Centro de administración de Microsoft Entra.

Solicitud

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

Guardar las credenciales

La configuración del aprovisionamiento requiere establecer una confianza entre Microsoft Entra ID y la aplicación para autorizar a Microsoft Entra a tener la capacidad de llamar a la aplicación de terceros. El ejemplo siguiente es específico de una aplicación que requiere un secreto de cliente y un token secreto. Cada aplicación tiene sus propios requisitos. Revise la documentación de la API para ver las opciones disponibles.

Solicitud

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

Paso 4: Iniciar el trabajo de aprovisionamiento

Ahora que el trabajo de aprovisionamiento está configurado, use el siguiente comando para iniciar el trabajo.

Solicitud

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

Response

HTTP/1.1 204 No Content

Paso 5: Supervisar el aprovisionamiento

Supervisar el estado del trabajo de aprovisionamiento

Ahora que se está ejecutando el trabajo de aprovisionamiento, use el siguiente comando para realizar el seguimiento del progreso. Cada trabajo de sincronización en la respuesta incluye el estado del ciclo de aprovisionamiento actual, así como estadísticas hasta la fecha, como el número de usuarios y grupos que se han creado en el sistema de destino.

Solicitar

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"
      }
    ]
}
]
}

Supervisar eventos de aprovisionamiento mediante los registros de aprovisionamiento

Además de supervisar el estado del trabajo de aprovisionamiento, puede usar registros de aprovisionamiento para consultar todos los eventos que se están produciendo. Por ejemplo, consulte un usuario determinado y determine si se aprovisionó correctamente.

Solicitud

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"
            }
            ]
       }
    ]
}

Configuración del aprovisionamiento mediante las Microsoft Graph API

Paso 1: Crear la aplicación de galería

Recuperar el identificador de plantilla de la aplicación de galería

Solicitud

Response

Crear la aplicación de galería

Solicitud

Response

Paso 2: Crear el trabajo de aprovisionamiento basado en la plantilla

Recuperar la plantilla para el conector de aprovisionamiento

Solicitar

Response

Crear el trabajo de aprovisionamiento

Solicitud

Response

Paso 3: Autorizar el acceso

Probar la conexión con la aplicación

Solicitud

Response

Guardar las credenciales

Solicitud

Response

Paso 4: Iniciar el trabajo de aprovisionamiento

Solicitud

Response

Paso 5: Supervisar el aprovisionamiento

Supervisar el estado del trabajo de aprovisionamiento

Solicitar

Response

Supervisar eventos de aprovisionamiento mediante los registros de aprovisionamiento

Solicitud

Response

Vea también

Recursos adicionales

Configuración del aprovisionamiento mediante las Microsoft Graph API

Paso 1: Crear la aplicación de galería

Iniciar sesión en el Explorador de Microsoft Graph (recomendado), Postman o cualquier otro cliente de API que use

Recuperar el identificador de plantilla de la aplicación de galería

Solicitud

Response

Crear la aplicación de galería

Solicitud

Response

Paso 2: Crear el trabajo de aprovisionamiento basado en la plantilla

Recuperar la plantilla para el conector de aprovisionamiento

Solicitar

Response

Crear el trabajo de aprovisionamiento

Solicitud

Response

Paso 3: Autorizar el acceso

Probar la conexión con la aplicación

Solicitud

Response

Guardar las credenciales

Solicitud

Response

Paso 4: Iniciar el trabajo de aprovisionamiento

Solicitud

Response

Paso 5: Supervisar el aprovisionamiento

Supervisar el estado del trabajo de aprovisionamiento

Solicitar

Response

Supervisar eventos de aprovisionamiento mediante los registros de aprovisionamiento

Solicitud

Response

Vea también

Recursos adicionales