Amplie o provisionamento controlado por API para sincronizar atributos personalizados

  • Artigo

Por padrão, os aplicativos de provisionamento orientados por API suportam atributos de processamento que fazem parte do esquema padrão de Usuário Principal SCIM e Usuário Corporativo. Seu sistema de registro pode ter atributos personalizados que podem ser incluídos como parte do provisionamento controlado por API. Este tutorial avançado descreve como estender seu aplicativo de provisionamento controlado por API para processar atributos personalizados adicionais.

Observação

Antes de tentar esse cenário avançado, recomendamos verificar se a configuração do seu aplicativo de provisionamento pronto para uso funciona conforme o esperado, usando um dos seguintes clientes de API: Explorador do Graph ou cURL.

Cenário de exemplo

Você configurou o aplicativo de provisionamento controlado por API. Seu aplicativo de provisionamento está consumindo com êxito os atributos que fazem parte do esquema padrão de Usuário Principal SCIM e de Usuário Corporativo, além do provisionamento de usuários na ID do Microsoft Entra. Agora você deseja enviar dois atributos personalizados HireDate e JobCode do seu sistema de RH para o ponto de extremidade da API de provisionamento de entrada. Você gostaria de mapear esses dois atributos personalizados para os atributos do Microsoft Entra employeeHireDate e jobTitle.

Etapa 1: estender o esquema do aplicativo de provisionamento

Nesta etapa, adicionaremos os dois atributos "HireDate" e "JobCode" que não fazem parte do esquema SCIM padrão para o aplicativo de provisionamento e os utilizaremos no fluxo de dados de provisionamento.

  1. Entre no Centro de administração do Microsoft Entra pelo menos como um Administrador de Aplicativo.
  2. Navegue até Identidade>Aplicativos>Aplicativos empresariais.
  3. Abra o aplicativo de provisionamento controlado por API.
  4. Abra a folha Provisionamento.
  5. Clique no botão Editar Provisionamento.
  6. Expanda a seção Mapeamentos e clique no link de mapeamento de atributos.
    Captura de tela do mapeamento de atributos de edição.
  7. Role a página Mapeamentos de Atributos para baixo. Selecione Mostrar opções avançadas e clique no link Editar lista de atributos para a API. Captura de tela da lista de atributos da API de edição.
  8. Role a tela para baixo até o final da página Editar Lista de Atributos.
  9. Adicione os dois atributos a seguir na lista como extensões do esquema SCIM. Utilize seu próprio namespace de esquema SCIM.
    urn:ietf:params:scim:schemas:extension:contoso:1.0:User:HireDate
    urn:ietf:params:scim:schemas:extension:contoso:1.0:User:JobCode
    Captura de tela da adição de atributos personalizados.
  10. Salvar suas alterações

Observação

Se quiser adicionar apenas mais alguns atributos ao aplicativo de provisionamento, utilize o Centro de administração do Microsoft Entra para estender o esquema. Se você quiser adicionar mais atributos personalizados (digamos, mais de 20 atributos), recomendamos utilizar o modo UpdateSchema do script CSV2SCIM do PowerShell que automatiza o processo manual acima.

Etapa 2: mapear os atributos personalizados

Vamos agora adicionar essas extensões ao mapeamento de atributos do aplicativo de provisionamento.

  1. Clique no link Adicionar Novo Mapeamento na página Mapeamento de Atributos. Captura de tela de adicionar novo mapeamento.

  2. Mapear o atributo urn:ietf:params:scim:schemas:extension:contoso:1.0:User:HireDate para employeeHireDate. Clique em OK.
    Captura de tela do mapeamento da data de contratação.

  3. Em seguida, selecione o mapeamento existente para title e clique nele para editar o mapeamento.

  4. Edite o mapeamento do atributo em uma expressão que incluirá urn:ietf:params:scim:schemas:extension:contoso:1.0:User:JobCode como parte do jobTitle atributo do Microsoft Entra.

      Join("", [title], "(", [urn:ietf:params:scim:schemas:extension:contoso:1.0:User:JobCode], ")")

    Captura de tela do mapeamento de cargos.

    Com esse mapeamento de expressão, se title for "Tour Lead" e JobCode for "TL-1001", o atributo do Microsoft Entra jobTitle será definido como "Tour Lead (TL-1001)".

  5. Salvar os mapeamentos de atributos.

Etapa 3: carregar solicitação em massa com atributos personalizados

  1. Abra seu cliente de API (Explorador do Graph / cURL).
  2. Copie e cole a solicitação em massa com atributos personalizados.
  3. Envie a solicitação em massa para a URL do ponto de extremidade da API de provisionamento.
    Captura de tela da solicitação de upload em massa.
  4. Depois de algum tempo, é possível verificar os logs de provisionamento para verificar a alteração do atributo.
    Captura de tela dos logs de provisionamento.
  5. Você também pode verificar a alteração no perfil de usuário do Microsoft Entra. O valor de Employee hire date reflete o fuso horário do seu locatário.
    Captura de tela do perfil do usuário.

Apêndice

Solicitação em massa com atributos personalizados

A solicitação em massa inclui os atributos personalizados configurados nas etapas acima.

Corpo da solicitação

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
    "Operations": [
    {
        "method": "POST",
        "bulkId": "701984",
        "path": "/Users",
        "data": {
            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
            "urn:ietf:params:scim:schemas:extension:contoso:1.0:User"],
            "externalId": "701984",
            "userName": "bjensen@example.com",
            "name": {
                "formatted": "Ms. Barbara J Jensen, III",
                "familyName": "Jensen",
                "givenName": "Barbara",
                "middleName": "Jane",
                "honorificPrefix": "Ms.",
                "honorificSuffix": "III"
            },
            "displayName": "Babs Jensen",
            "nickName": "Babs",
            "emails": [
            {
              "value": "bjensen@example.com",
              "type": "work",
              "primary": true
            }
            ],
            "addresses": [
            {
              "type": "work",
              "streetAddress": "234300 Universal City Plaza",
              "locality": "Hollywood",
              "region": "CA",
              "postalCode": "91608",
              "country": "USA",
              "formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",
              "primary": true
            }
            ],
            "phoneNumbers": [
            {
              "value": "555-555-5555",
              "type": "work"
            }
            ],
            "userType": "Employee",
            "title": "Tour Guide",
            "preferredLanguage": "en-US",
            "locale": "en-US",
            "timezone": "America/Los_Angeles",
            "active":true,
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                "employeeNumber": "701984",
                "costCenter": "4130",
                "organization": "Universal Studios",
                "division": "Theme Park",
                "department": "Tour Operations",
                "manager": {
                  "value": "89607",
                  "displayName": "John Smith"
                 }
            },
            "urn:ietf:params:scim:schemas:extension:contoso:1.0:User": {
                "HireDate": "2021-05-01T00:00:00-05:00",
                "JobCode": "TG-1001"
            }            
        }
    },
    {
        "method": "POST",
        "bulkId": "701985",
        "path": "/Users",
        "data": {
            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
            "urn:ietf:params:scim:schemas:extension:contoso:1.0:User"],
            "externalId": "701985",
            "userName": "Kjensen@example.com",
            "name": {
                "formatted": "Ms. Kathy J Jensen, III",
                "familyName": "Jensen",
                "givenName": "Kathy",
                "middleName": "Jane",
                "honorificPrefix": "Ms.",
                "honorificSuffix": "III"
            },
            "displayName": "Kathy Jensen",
            "nickName": "Kathy",
            "emails": [
            {
              "value": "kjensen@example.com",
              "type": "work",
              "primary": true
            }
            ],
            "addresses": [
            {
              "type": "work",
              "streetAddress": "100 Oracle City Plaza",
              "locality": "Hollywood",
              "region": "CA",
              "postalCode": "91618",
              "country": "USA",
              "formatted": "100 Oracle City Plaza\nHollywood, CA 91618 USA",
              "primary": true
            }
            ],
            "phoneNumbers": [
            {
              "value": "555-555-5545",
              "type": "work"
            }
            ],
            "userType": "Employee",
            "title": "Tour Lead",
            "preferredLanguage": "en-US",
            "locale": "en-US",
            "timezone": "America/Los_Angeles",
            "active":true,
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
              "employeeNumber": "701984",
              "costCenter": "4130",
              "organization": "Universal Studios",
              "division": "Theme Park",
              "department": "Tour Operations",
              "manager": {
                "value": "701984",
                "displayName": "Barbara Jensen"
             }
            },
            "urn:ietf:params:scim:schemas:extension:contoso:1.0:User": {
                "HireDate": "2022-07-15T00:00:00-05:00",
                "JobCode": "TL-1003"
            }            
        }
    }
],
    "failOnErrors": null
}

Próximas etapas