Configurar el aprovisionamiento con las API de Microsoft GraphConfigure provisioning using Microsoft Graph APIs

El portal de Azure es una forma cómoda de configurar el aprovisionamiento para aplicaciones individuales de una en una.The Azure portal is a convenient way to configure provisioning for individual apps one at a time. Pero si está creando varias instancias de una aplicación (o incluso cientos de ellas), puede ser más fácil automatizar la creación y la configuración de aplicaciones con las API de Microsoft Graph.But if you're creating several—or even hundreds—of instances of an application, it can be easier to automate app creation and configuration with the Microsoft Graph APIs. En este artículo se describe cómo automatizar la configuración de aprovisionamiento mediante las API.This article outlines how to automate provisioning configuration through APIs. Este método se suele usar para aplicaciones como servicios Web de Amazon.This method is commonly used for applications like Amazon Web Services.

Información general sobre los pasos para usar las API de Microsoft Graph para automatizar la configuración de aprovisionamientoOverview of steps for using Microsoft Graph APIs to automate provisioning configuration

PasoStep DetallesDetails
Paso 1. Crear la aplicación de la galeríaStep 1. Create the gallery application Inicio de sesión en el cliente APISign-in to the API client
Recuperar la plantilla de aplicación de la galeríaRetrieve the gallery application template
Crear la aplicación de la galeríaCreate the gallery application
Paso 2. Crear trabajo de aprovisionamiento basado en plantillaStep 2. Create provisioning job based on template Recuperar la plantilla para el conector de aprovisionamientoRetrieve the template for the provisioning connector
Crear el trabajo de aprovisionamientoCreate the provisioning job
Paso 3. Autorizar el accesoStep 3. Authorize access Probar la conexión a la aplicaciónTest the connection to the application
Guardar las credencialesSave the credentials
Paso 4. Iniciar aprovisionamiento de trabajoStep 4. Start provisioning job Iniciar el trabajoStart the job
Paso 5. Aprovisionamiento del monitorStep 5. Monitor provisioning Comprobar el estado del trabajo de aprovisionamientoCheck the status of the provisioning job
Recuperar los registros de aprovisionamientoRetrieve the provisioning logs
  1. Inicie el Explorador de Microsoft GraphStart Microsoft Graph Explorer.

  2. Selecciona el botón "iniciar sesión con Microsoft" e inicia sesión con las credenciales de administrador global de Azure AD o administrador de aplicaciones.Select the "Sign-In with Microsoft" button and sign in using Azure AD global administrator or App Admin credentials.

    Inicio de sesión en gráfico

  3. Una vez que haya iniciado sesión correctamente, verá los detalles de la cuenta de usuario en el panel izquierdo.Upon successful sign-in, you'll see the user account details in the left-hand pane.

Todas las aplicaciones de la galería de la aplicación de Azure AD tienen una plantilla de aplicación que describe los metadatos de la aplicación.Applications in the Azure AD application gallery each have an application template that describes the metadata for that application. Con esta plantilla, puede crear una instancia de la aplicación y de la entidad de servicio en su inquilino para administrarlas.Using this template, you can create an instance of the application and service principal in your tenant for management.

SolicitudRequest

GET https://graph.microsoft.com/beta/applicationTemplates

RespuestaResponse

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

{
  "value": [
  {
    "id": "8b1025e4-1dd2-430b-a150-2ef79cd700f5",
        "displayName": "Amazon Web Services (AWS)",
        "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": null    
  
}

Use el identificador de plantilla recuperado para su aplicación en el último paso para crear una instancia de la entidad de servicio y de la aplicación en el espacio empresarial.Use the template ID retrieved for your application in the last step to create an instance of the application and service principal in your tenant.

SolicitudRequest

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

{
  "displayName": "AWS Contoso"
}

RespuestaResponse

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 plantillaStep 2: Create the provisioning job based on the template

Recuperar la plantilla para el conector de aprovisionamientoRetrieve the template for the provisioning connector

Las aplicaciones de la galería que están habilitadas para el aprovisionamiento tienen plantillas para simplificar la configuración.Applications in the gallery that are enabled for provisioning have templates to streamline configuration. Use la solicitud siguiente para recuperar la plantilla para la configuración de aprovisionamiento.Use the request below to retrieve the template for the provisioning configuration. Tenga en cuenta que tendrá que proporcionar el identificador.Note that you will need to provide the ID. El identificador hace referencia al recurso anterior, que en este caso es el recurso servicePrincipal.The ID refers to the preceding resource, which in this case is the servicePrincipal resource.

SolicitudRequest

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

RespuestaResponse

HTTP/1.1 200 OK

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

Crear el trabajo de aprovisionamientoCreate the provisioning job

Para habilitar el aprovisionamiento, primero debe crear un trabajo.To enable provisioning, you'll first need to create a job. Use la siguiente solicitud para crear un trabajo de aprovisionamiento.Use the following request to create a provisioning job. Use templateId del paso anterior al especificar la plantilla que se va a usar para el trabajo.Use the templateId from the previous step when specifying the template to be used for the job.

SolicitudRequest

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

{ 
    "templateId": "aws"
}

RespuestaResponse

HTTP/1.1 200 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 accesoStep 3: Authorize access

Probar la conexión a la aplicaciónTest the connection to the application

Compruebe la conexión con la aplicación de terceros.Test the connection with the third-party application. El ejemplo siguiente es para una aplicación que requiere un secreto de cliente y un token secreto.The following example is for an application that requires a client secret and secret token. Cada aplicación tiene sus propios requisitos.Each application has its own requirements. Las aplicaciones suelen usar una dirección de base en vez de un secreto de cliente.Applications often use a base address in place of a client secret. Para determinar qué credenciales requiere su aplicación, vaya a la página Configuración de aprovisionamiento de la aplicación y en modo para programadores haga clic en probar conexión.To determine what credentials your app requires, go to the provisioning configuration page for your application and in developer mode click test connection. El tráfico de red mostrará los parámetros usados para las credenciales.The network traffic will show the parameters used for credentials. Para obtener una lista completa de las credenciales, consulte synchronizationJob: validateCredentials.For a full list of credentials, see synchronizationJob: validateCredentials.

SolicitudRequest

POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{id}/validateCredentials
{ 
    credentials: [ 
        { key: "ClientSecret", value: "xxxxxxxxxxxxxxxxxxxxx" },
        { key: "SecretToken", value: "xxxxxxxxxxxxxxxxxxxxx" }
    ]
}

RespuestaResponse

HTTP/1.1 204 No Content

Guardar las credencialesSave your credentials

La configuración del aprovisionamiento requiere establecer una confianza entre Azure AD y la aplicación.Configuring provisioning requires establishing a trust between Azure AD and the application. Autorice el acceso a la aplicación de terceros.Authorize access to the third-party application. El ejemplo siguiente es para una aplicación que requiere un secreto de cliente y un token secreto.The following example is for an application that requires a client secret and a secret token. Cada aplicación tiene sus propios requisitos.Each application has its own requirements. Revise la documentación de la API para ver las opciones disponibles.Review the API documentation to see the available options.

SolicitudRequest

PUT https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/secrets 
 
{ 
    value: [ 
        { key: "ClientSecret", value: "xxxxxxxxxxxxxxxxxxxxx" },
        { key: "SecretToken", value: "xxxxxxxxxxxxxxxxxxxxx" }
    ]
}

RespuestaResponse

HTTP/1.1 204 No Content

Paso 4: iniciar el trabajo de aprovisionamientoStep 4: Start the provisioning job

Ahora que el trabajo de aprovisionamiento está configurado, use el siguiente comando para iniciar el trabajo.Now that the provisioning job is configured, use the following command to start the job.

SolicitudRequest

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

RespuestaResponse

HTTP/1.1 204 No Content

Paso 5: supervisar el aprovisionamientoStep 5: Monitor provisioning

Supervisión del estado del trabajo de aprovisionamientoMonitor the provisioning job status

Ahora que el trabajo de aprovisionamiento se está ejecutando, use el siguiente comando para realizar el seguimiento del progreso del ciclo de aprovisionamiento actual, así como las estadísticas hasta la fecha, como el número de usuarios y grupos que se han creado en el sistema de destino.Now that the provisioning job is running, use the following command to track the progress of the current provisioning cycle as well as statistics to date such as the number of users and groups that have been created in the target system.

SolicitudRequest

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

RespuestaResponse

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

{
    "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 los eventos de aprovisionamiento con los registros de aprovisionamientoMonitor provisioning events using the provisioning logs

Además de supervisar el estado del trabajo de aprovisionamiento, puede usar los registros de aprovisionamiento para consultar todos los eventos que se producen.In addition to monitoring the status of the provisioning job, you can use the provisioning logs to query for all the events that are occurring. Por ejemplo, una consulta para un usuario en particular y determine si se aprovisionó correctamente.For example, query for a particular user and determine if they were successfully provisioned.

SolicitudRequest

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

RespuestaResponse

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",
            "jobId": "BoxOutDelta.7928d5b574424a97ne2d66f9j9972ecn",
            "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": "Box",
                "details": {
                    "ApplicationId": "f2764360-e0ec-5676-711e-cd6fc0d4dd61",
                    "ServicePrincipalId": "chc46a42-966b-47d7-9774-576b1c8bd0b8",
                    "ServicePrincipalDisplayName": "Box"
                }
            },
            "initiatedBy": {
                "id": "",
                "displayName": "Azure AD Provisioning Service",
                "initiatorType": "system"
            },
            "sourceIdentity": {
                "id": "5e6c9rae-ab4d-5239-8ad0-174391d110eb",
                "displayName": "Self-service Pilot",
                "identityType": "Group",
                "details": {}
            },
            "targetIdentity": {
                "id": "",
                "displayName": "",
                "identityType": "Group",
                "details": {}
            },
            "statusInfo": {
                "@odata.type": "#microsoft.graph.statusDetails",
                "status": "failure",
                "errorCode": "BoxEntryConflict",
                "reason": "Message: Box returned an error response with the HTTP status code 409.  This response indicates that a user or a group already exisits with the same name. This can be avoided by identifying and removing the conflicting user from Box via the Box administrative user interface, or removing the current user from the scope of provisioning either by removing their assignment to the Box application in Azure Active Directory or adding a scoping filter to exclude the user.",
                "additionalDetails": null,
                "errorCategory": "NonServiceFailure",
                "recommendedAction": null
            },
            "provisioningSteps": [
                {
                    "name": "EntryImportAdd",
                    "provisioningStepType": "import",
                    "status": "success",
                    "description": "Received Group 'Self-service Pilot' change of type (Add) from Azure Active Directory",
                    "details": {}
                },
                {
                    "name": "EntrySynchronizationAdd",
                    "provisioningStepType": "matching",
                    "status": "success",
                    "description": "Group 'Self-service Pilot' will be created in Box (Group is active and assigned in Azure Active Directory, but no matching Group was found in Box)",
                    "details": {}
                },
                {
                    "name": "EntryExportAdd",
                    "provisioningStepType": "export",
                    "status": "failure",
                    "description": "Failed to create Group 'Self-service Pilot' in Box",
                    "details": {
                        "ReportableIdentifier": "Self-service Pilot"
                    }
                }
            ],
            "modifiedProperties": [
                {
                    "displayName": "objectId",
                    "oldValue": null,
                    "newValue": "5e0c9eae-ad3d-4139-5ad0-174391d110eb"
                },
                {
                    "displayName": "displayName",
                    "oldValue": null,
                    "newValue": "Self-service Pilot"
                },
                {
                    "displayName": "mailEnabled",
                    "oldValue": null,
                    "newValue": "False"
                },
                {
                    "displayName": "mailNickname",
                    "oldValue": null,
                    "newValue": "5ce25n9a-4c5f-45c9-8362-ef3da29c66c5"
                },
                {
                    "displayName": "securityEnabled",
                    "oldValue": null,
                    "newValue": "True"
                },
                {
                    "displayName": "Name",
                    "oldValue": null,
                    "newValue": "Self-service Pilot"
                }
            ]
       }
    ]
}

Vea tambiénSee also