Compartilhar via

Tutorial: Desenvolver e planejar o provisionamento para um ponto de extremidade de SCIM no Microsoft Entra ID

Como desenvolvedor de aplicativos, você pode usar a API de gerenciamento de usuários do SCIM (Sistema de Gerenciamento de Usuários entre Domínios) para habilitar o provisionamento automático de usuários e grupos entre seu aplicativo e o Microsoft Entra ID. Este artigo descreve como criar um ponto de extremidade do SCIM e integrá-lo ao serviço de provisionamento do Microsoft Entra. A especificação do SCIM fornece um esquema de usuário comum para provisionamento. Quando usado com padrões de federação como SAML ou OpenID Connect, o SCIM fornece aos administradores uma solução de ponta a ponta baseada em padrões para o gerenciamento de acesso.

Provisionamento da ID do Microsoft Entra para um aplicativo com SCIM

O SCIM 2.0 é uma definição padronizada de dois pontos de extremidade: um ponto de extremidade /Users e um ponto de extremidade /Groups. Ele usa pontos de extremidades da API REST comuns para criar, atualizar e excluir objetos. O SCIM consiste em um esquema predefinido para atributos comuns, como nome do grupo, nome de usuário, nome, sobrenome e email.

Os aplicativos que oferecem uma API REST 2.0 do SCIM podem reduzir ou eliminar o problema de trabalhar com uma API de gerenciamento de usuários proprietária. Por exemplo, qualquer cliente em conformidade com o SCIM sabe como fazer um HTTP POST de um objeto JSON para o ponto de extremidade /Users para criar uma entrada de usuário. Em vez de precisar de uma API um pouco diferente para as mesmas ações básicas, os aplicativos que estão em conformidade com o padrão SCIM podem aproveitar instantaneamente os clientes, as ferramentas e o código preexistentes.

O esquema de objeto de usuário padrão e as APIs rest para gerenciamento definidos no SCIM 2.0 (RFC 7642, 7643, 7644) permitem que provedores de identidade e aplicativos se integrem com mais facilidade uns aos outros. Os desenvolvedores de aplicativos que criam um ponto de extremidade SCIM podem se integrar a qualquer cliente compatível com SCIM sem precisar fazer personalizações.

Para automatizar o provisionamento em um aplicativo, ele requer a criação e a integração de um ponto de extremidade do SCIM que é acessado pelo serviço de provisionamento do Microsoft Entra. Use as etapas a seguir para iniciar o provisionamento de usuários e grupos em seu aplicativo.

  1. Projetar seu esquema de usuário e grupo – identifique os objetos e atributos do aplicativo para determinar como eles são mapeados para o esquema de usuário e grupo compatível com a implementação do Microsoft Entra SCIM.

  2. Entender a implementação do Microsoft Entra SCIM – Entenda como o serviço de provisionamento do Microsoft Entra é implementado para modelar o tratamento e as respostas da solicitação de protocolo SCIM.

  3. Criar um ponto de extremidade SCIM – um ponto de extremidade deve ser compatível com SCIM 2.0 para integrar-se ao serviço de provisionamento do Microsoft Entra. Como opção, use as bibliotecas de CLI (Common Language Infrastructure) da Microsoft e os exemplos de código para criar seu ponto de extremidade. Esses exemplos são apenas para referência e teste; não é recomendável usá-los como dependências em seu aplicativo de produção.

  4. Integre seu ponto de extremidade SCIM ao serviço de provisionamento do Microsoft Entra. O Microsoft Entra ID dá suporte a vários aplicativos de terceiros que implementam o SCIM 2.0. Se você usar um desses aplicativos, poderá automatizar rapidamente o provisionamento e o desprovisionamento de usuários e grupos.

  5. [Opcional] Publicar seu aplicativo na galeria de aplicativos do Microsoft Entra – facilite para os clientes descobrirem seu aplicativo e configurarem facilmente o provisionamento.

Diagrama que mostra as etapas necessárias para integrar um endpoint SCIM com o Microsoft Entra ID.

Projete seu esquema de usuário e grupo

Cada aplicativo requer atributos diferentes para criar um usuário ou grupo. Inicie sua integração identificando os objetos necessários (usuários, grupos) e atributos (nome, gerente, cargo e assim por diante) de que seu aplicativo precisa.

O padrão SCIM define um esquema para gerenciar usuários e grupos.

O esquema de usuário principal requer apenas três atributos (todos os outros atributos são opcionais):

  • id, identificador definido pelo provedor de serviços
  • userName, um identificador exclusivo do usuário (geralmente, é mapeado para o nome UPN do Microsoft Entra)
  • meta, metadados somente leitura mantidos pelo provedor de serviços

Além do esquema de usuário principal , o padrão SCIM define uma extensão de usuário empresarial com um modelo para estender o esquema de usuário para atender às necessidades do aplicativo.

Por exemplo, se o aplicativo exigir o email de um usuário e o gerente do usuário, use o esquema principal para coletar o email do usuário e o esquema do usuário corporativo para coletar o gerente do usuário.

Para criar o esquema, siga estas etapas:

  1. Liste os atributos necessários pelo aplicativo e, em seguida, categorize como atributos necessários para autenticação (por exemplo, loginName e email). Atributos são necessários para gerenciar o ciclo de vida do usuário (por exemplo, status/ativo) e todos os outros atributos necessários para que o aplicativo funcione (por exemplo, gerente, marca).

  2. Verifique se os atributos já estão definidos no esquema de usuário principal ou no esquema de usuário corporativo . Caso contrário, você deve definir uma extensão para o esquema de usuário que abranja os atributos ausentes. Confira o exemplo para ver uma extensão para o usuário a fim de permitir o provisionamento de uma tag do usuário.

  3. Mapeie os atributos SCIM para os atributos de usuário no Microsoft Entra ID. Se um dos atributos que você definiu no ponto de extremidade do SCIM não tiver um equivalente claro no esquema de usuário do Microsoft Entra, oriente o administrador de locatários a estender o esquema ou use um atributo de extensão, conforme mostrado no exemplo para a propriedade tags.

A tabela a seguir lista um exemplo de atributos necessários:

Exemplo/atributo de aplicativo necessário Atributo SCIM mapeado Atributo do Microsoft Entra mapeado
nome de login userName Nome Principal do Usuário
primeiro nome nome.nomeDado nome dado
sobrenome nome.sobrenome sobrenome
workMail emails[tipo eq "trabalho"].valor Email
gerente gerente gerente
marca urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:tag atributoDeExtensão1
estado ativo isSoftDeleted (valor calculado não armazenado no usuário)

A seguinte carga JSON mostra um esquema do SCIM de exemplo:

{
     "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:CustomExtensionName:2.0:User"],
     "userName":"bjensen@testuser.com",
     "id": "48af03ac28ad4fb88478",
     "externalId":"bjensen",
     "name":{
       "familyName":"Jensen",
       "givenName":"Barbara"
     },
     "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
     "manager": "123456"
   },
     "urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User": {
     "tag": "701984",
   },
   "meta": {
     "resourceType": "User",
     "created": "2010-01-23T04:56:22Z",
     "lastModified": "2011-05-13T04:42:34Z",
     "version": "W\/\"3694e05e9dff591\"",
     "location":
 "https://example.com/v2/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
   }
}

Observação

Além dos atributos necessários para o aplicativo, a declaração JSON também inclui os atributos obrigatórios id, externalId e meta.

Ele ajuda a categorizar entre /User e /Group mapear quaisquer atributos de usuário padrão na ID do Microsoft Entra para o SCIM RFC, veja como os atributos personalizados são mapeados entre a ID do Microsoft Entra e seu ponto de extremidade SCIM.

A tabela a seguir lista um exemplo de atributos de usuário:

Usuário do Microsoft Entra urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
IsSoftDeleted ativo
departamento urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department
nome de exibição nome de exibição
identificação do funcionário urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber
Facsimile-TelephoneNumber númerosDeTelefone[type eq "fax"].value
nome dado nome.nomeDado
título do cargo título
correio emails[tipo eq "trabalho"].valor
apelido de email ID externo
gerente urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager
Serviço Móvel númerosDeTelefone[tipo eq "móvel"].valor
código postal endereços[tipo eq "trabalho"].códigoPostal
Endereços de Proxy emails[type eq "other"]. Valor
físico-Delivery-OfficeName addresses[type eq "other"]. Formatado
endereço enderecos[tipo eq "trabalho"].enderecoRua
sobrenome nome.sobrenome
número de telefone phoneNumbers[tipo eq "trabalho"].value
nome_do-usuário userName

A tabela a seguir lista um exemplo de atributos de grupo:

Grupo do Microsoft Entra urn:ietf:params:scim:schemas:core:2.0:Group
nome de exibição nome de exibição
membros membros
ID do objeto ID externo

Observação

Você não precisa dar suporte a usuários e grupos, nem a todos os atributos mostrados aqui; esta é apenas uma referência de como os atributos no Microsoft Entra ID geralmente são mapeados para propriedades no protocolo SCIM.

Há vários pontos de extremidade definidos no SCIM RFC. Você pode começar com o ponto de extremidade /User e, em seguida, expandir com base nele. A tabela a seguir lista alguns dos pontos de extremidade do SCIM:

Ponto de extremidade Descrição
/Utilizador Executa operações CRUD em um objeto de usuário.
/Grupo Executa operações CRUD em um objeto de grupo.
/Esquemas O conjunto de atributos com suporte de cada cliente e provedor de serviços pode variar. Um provedor de serviços poderá incluir name, title e emails, enquanto outro provedor de serviços usará name, title e phoneNumbers. O ponto de extremidade de esquemas permite a descoberta dos atributos com suporte.
/Granel As operações em lote permitem que você execute operações em uma grande coleção de objetos de recurso em uma única operação (por exemplo, atualizar associações para um grupo grande). Embora não dêmos suporte ao SCIM /Bulk hoje, isso é algo que pretendemos dar suporte no futuro para ajudar a melhorar o desempenho.
/ServiceProviderConfig Fornece detalhes sobre os recursos do padrão do SCIM que têm suporte, por exemplo, os recursos com suporte e o método de autenticação.
/Tipos de Recursos Especifica os metadados sobre cada recurso.

Observação

Use o ponto de extremidade /Schemas para dar suporte a atributos personalizados ou se o esquema for alterado com frequência, pois ele permite que um cliente recupere o esquema mais atualizado automaticamente. Use o ponto de extremidade /Bulk para dar suporte a grupos. Embora não damos suporte ao endpoint /Bulk hoje, isso é algo que pretendemos dar suporte no futuro para ajudar a melhorar o desempenho.

Entender a implementação do SCIM pelo Microsoft Entra

O serviço de provisionamento do Microsoft Entra foram projetados para dar suporte a uma API de gerenciamento de usuários do SCIM 2.0.

Importante

O comportamento da implementação do SCIM do Microsoft Entra foi atualizado pela última vez em 18 de dezembro de 2018. Para obter informações sobre o que mudou, consulte a conformidade do protocolo SCIM 2.0 do serviço de provisionamento de usuários do Microsoft Entra.

Dentro da especificação do protocolo SCIM 2.0, seu aplicativo deve dar suporte a esses requisitos:

Requisito Notas de referência (protocolo SCIM)
Criar usuários e, opcionalmente, também criar grupos Seção 3.3
Modificar usuários ou grupos com solicitações de PATCH Seção 3.5.2. O suporte garantirá que grupos e usuários sejam provisionados de modo a obter um desempenho adequado.
Recuperar um recurso conhecido para um usuário ou grupo criado anteriormente Seção 3.4.1
Consultar usuários ou grupos Seção 3.4.2. Por padrão, os usuários são recuperados com a id e consultados com o username e a externalId, e os grupos são consultados com displayName.
O filtro excludedAttributes=members ao consultar o recurso de grupo Seção 3.4.2.2
Suporte a listagem de usuários e paginação Seção 3.4.2.4.
Exclusão reversível de um usuário active=false e restauração do usuário active=true O objeto de usuário deverá ser retornado em uma solicitação, não importa se o usuário está ativo ou não. A única vez em que o usuário não deverá ser retornado será quando ele for excluído de maneira irreversível do aplicativo.
Suporte ao /Schemas endpoint Seção 7 O endpoint de descoberta de esquema é usado para descobrir mais atributos.
Aceitar um único token de portador para autenticação e autorização do Microsoft Entra ID para seu aplicativo.

Use estas diretrizes gerais ao implementar um ponto de extremidade de SCIM para garantir a compatibilidade com o Microsoft Entra ID:

Geral:

  • id é uma propriedade obrigatória para todos os recursos. Cada resposta que retorna um recurso deve garantir que cada recurso tenha essa propriedade, exceto para ListResponse com zero elementos.
  • Os valores enviados devem ser armazenados no mesmo formato em que foram enviados. Valores inválidos devem ser rejeitados com uma mensagem de erro descritiva e acionável. As transformações de dados não devem acontecer entre os dados do Microsoft Entra ID e os dados armazenados no aplicativo do SCIM. (por exemplo. Um número de telefone enviado como 55555555555 não deve ser salvo/retornado como + 5 (555) 555-5555)
  • Não é necessário incluir todo o recurso na resposta PATCH .
  • Não exija uma correspondência sensível a maiúsculas e minúsculas em elementos estruturais no SCIM, em particular nos valores de operação PATCHop, conforme definido na seção 3.5.2. O ID do Microsoft Entra emite os valores de op sob as formas de Adicionar, Substituir e Remover.
  • O Microsoft Entra ID faz com que as solicitações busquem um usuário aleatório e um grupo para garantir que o ponto de extremidade e as credenciais estão válidos. Ele também é feito como parte do fluxo de Teste de Conexão.
  • Suporte HTTPS em seu ponto de extremidade do SCIM.
  • Há suporte para atributos personalizados complexos e multivalorados, mas o Microsoft Entra ID não possui muitas estruturas de dados complexas para extrair dados nesses casos. Os atributos de nome/valor podem ser mapeados facilmente, mas não há suporte para o fluxo de dados para atributos complexos com três ou mais subatributos.
  • Os valores de subatributo “type” de atributos complexos com multivalores precisam ser exclusivos. Por exemplo, não pode haver dois endereços de email diferentes com o subtipo “work”.
  • O cabeçalho de todas as respostas deve ser do seguinte tipo de conteúdo: application/scim+json

Recuperando recursos:

  • A resposta a uma solicitação de consulta/filtro sempre deve ser ListResponse.
  • O Microsoft Entra utiliza apenas os seguintes operadores: eq, and
  • O atributo no qual os recursos podem ser consultados deve ser definido como um atributo correspondente no aplicativo, consulte Personalizando mapeamentos de atributo de provisionamento de usuário.

/Usuários:

  • Não há suporte para o atributo de direitos.
  • Todos os atributos que são considerados para exclusividade do usuário devem ser utilizáveis como parte de uma consulta filtrada. (por exemplo, se a exclusividade do usuário for avaliada para userName e emails[type eq "work"], um GET para /Users com um filtro deverá permitir consultas userName eq "user@contoso.com" e emails[type eq "work"].value eq "user@contoso.com".

/Grupos:

  • Os grupos são opcionais, mas só têm suporte se a implementação do SCIM der suporte a solicitações PATCH .
  • Os grupos devem ter exclusividade no valor 'displayName' para corresponder ao Microsoft Entra ID e ao aplicativo SCIM. A exclusividade não é um requisito do protocolo SCIM, mas é um requisito para integrar um ponto de extremidade do SCIM ao Microsoft Entra ID.

/Esquemas (descoberta de esquema):

  • Solicitação/resposta de exemplo
  • A descoberta de esquema está sendo usada em certos aplicativos de galeria. A descoberta de esquema é o único método para adicionar mais atributos ao esquema de um aplicativo SCIM de galeria existente. A descoberta de esquema não tem suporte atualmente no aplicativo SCIM personalizado sem galeria.
  • Se um valor não estiver presente, não envie valores nulos.
  • Os valores da propriedade deverão ter uma concatenação com maiúsculas e minúsculas (por exemplo, readWrite).
  • Será necessário retornar uma resposta da lista.
  • O serviço de provisionamento do Microsoft Entra faz a solicitação /esquemas quando você salva a configuração de provisionamento. A solicitação também é feita quando você abre a página de provisionamento da edição. Outros atributos descobertos são exibidos para os clientes nos mapeamentos de atributo na lista de atributos de destino. A descoberta de esquema só leva à adição de mais atributos de destino. Os atributos não são removidos.

Provisionamento e desprovisionamento de usuários

O diagrama a seguir mostra as mensagens que o Microsoft Entra ID envia para um ponto de extremidade SCIM para gerenciar o ciclo de vida de um usuário no repositório de identidades do aplicativo.

Diagrama que mostra a sequência de desprovisionamento do usuário.

Provisionamento e desprovisionamento de grupos

O provisionamento e desprovisionamento de grupos são opcionais. Quando implementado e habilitado, a ilustração a seguir mostra as mensagens que o Microsoft Entra ID envia a um ponto de extremidade do SCIM para gerenciar o ciclo de vida de um grupo no repositório de identidades do seu aplicativo. Essas mensagens são diferentes das mensagens sobre os usuários em dois aspectos:

  • As solicitações para recuperar grupos especificam que o atributo de membros deve ser excluído de qualquer recurso fornecido em resposta à solicitação.
  • As solicitações para determinar se um atributo de referência tem um determinado valor são sobre o atributo de membros.

O diagrama a seguir mostra a sequência de desprovisionamento de grupo:

Diagrama que mostra a sequência de desprovisionamento de grupo.

Solicitações e respostas do protocolo SCIM

Este artigo fornece solicitações SCIM de exemplo emitidas pelo serviço de provisionamento do Microsoft Entra e respostas esperadas de exemplo. Para obter melhores resultados, você deve codificar seu aplicativo para lidar com essas solicitações nesse formato e emitir as respostas esperadas.

Importante

Para entender como e quando o serviço de provisionamento de usuários do Microsoft Entra emite as operações descritas no exemplo, consulte a seção Ciclos de provisionamento: inicial e incremental em Como o provisionamento funciona.

Operações do usuário

Operações de grupo

Descoberta de esquema

Operações do Usuário

  • Use os atributos userName ou emails[type eq "work"] para consultar usuários.

Criar Usuário

Solicitação

POST /Usuários

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
    "externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
    "userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "active": true,
    "emails": [{
        "primary": true,
        "type": "work",
        "value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com"
    }],
    "meta": {
        "resourceType": "User"
    },
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName"
    },
    "roles": []
}
Resposta

HTTP/1.1 201 Criado

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "48af03ac28ad4fb88478",
    "externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
        "type": "work",
        "primary": true
    }]
}

Obter Usuário

Solicitação

GET /Usuários/5d48a0a8e9f04aa38008

Resposta (Usuário encontrado)

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "5d48a0a8e9f04aa38008",
    "externalId": "58342554-38d6-4ec8-948c-50044d0a33fd",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
        "type": "work",
        "primary": true
    }]
}
Solicitação

GET /Usuários/5171a35d82074e068ce2

Resposta (Usuário não encontrado. O detalhe não é obrigatório, apenas o status.)

HTTP/1.1 404 Não Encontrado

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "status": "404",
    "detail": "Resource 23B51B0E5D7AE9110A49411D@7cca31655d49f3640a494224 not found"
}

Obter Usuário por consulta

Solicitação

GET /Users?filter=userName eq "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee"

Resposta

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 1,
    "Resources": [{
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
        "id": "2441309d85324e7793ae",
        "externalId": "7fce0092-d52e-4f76-b727-3955bd72c939",
        "meta": {
            "resourceType": "User",
            "created": "2018-03-27T19:59:26.000Z",
            "lastModified": "2018-03-27T19:59:26.000Z"
            
        },
        "userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "name": {
            "familyName": "familyName",
            "givenName": "givenName"
        },
        "active": true,
        "emails": [{
            "value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
            "type": "work",
            "primary": true
        }]
    }],
    "startIndex": 1,
    "itemsPerPage": 20
}

Obter Usuário por consulta - Zero resultados

Solicitação

GET /Users?filter=userName eq "usuário inexistente"

Resposta

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 0,
    "Resources": [],
    "startIndex": 1,
    "itemsPerPage": 20
}

Atualizar Usuário [Propriedades com vários valores]

Solicitação

PATCH /Users/6764549bef60420686bc HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
            {
            "op": "Replace",
            "path": "emails[type eq \"work\"].value",
            "value": "updatedEmail@microsoft.com"
            },
            {
            "op": "Replace",
            "path": "name.familyName",
            "value": "updatedFamilyName"
            }
    ]
}
Resposta

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "6764549bef60420686bc",
    "externalId": "6c75de36-30fa-4d2d-a196-6bdcdb6b6539",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "name": {
        "formatted": "givenName updatedFamilyName",
        "familyName": "updatedFamilyName",
        "givenName": "givenName"
    },
    "active": true,
    "emails": [{
        "value": "updatedEmail@microsoft.com",
        "type": "work",
        "primary": true
    }]
}

Atualizar Usuário [Propriedades de valor único]

Solicitação

PATCH /Usuários/5171a35d82074e068ce2 HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Replace",
        "path": "userName",
        "value": "5b50642d-79fc-4410-9e90-4c077cdd1a59@testuser.com"
    }]
}
Resposta

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "5171a35d82074e068ce2",
    "externalId": "aa1eca08-7179-4eeb-a0be-a519f7e5cd1a",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
        
    },
    "userName": "5b50642d-79fc-4410-9e90-4c077cdd1a59@testuser.com",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
        "type": "work",
        "primary": true
    }]
}

Desabilitar Usuário

Solicitação

PATCH /Usuários/5171a35d82074e068ce2 HTTP/1.1

{
    "Operations": [
        {
            "op": "Replace",
            "path": "active",
            "value": false
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ]
}
Resposta
{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "CEC50F275D83C4530A495FCF@834d0e1e5d8235f90a495fda",
    "userName": "deanruiz@testuser.com",
    "name": {
        "familyName": "Harris",
        "givenName": "Larry"
    },
    "active": false,
    "emails": [
        {
            "value": "gloversuzanne@testuser.com",
            "type": "work",
            "primary": true
        }
    ],
    "addresses": [
        {
            "country": "ML",
            "type": "work",
            "primary": true
        }
    ],
    "meta": {
        "resourceType": "Users",
        "location": "/scim/5171a35d82074e068ce2/Users/CEC50F265D83B4530B495FCF@5171a35d82074e068ce2"
    }
}

Excluir usuário

Solicitação

DELETE /Usuários/5171a35d82074e068ce2 HTTP/1.1

Resposta

HTTP/1.1 204 Sem Conteúdo

Operações de Grupo

  • Os grupos são criados com uma lista de membros vazios.
  • Use o atributo displayName para consultar grupos.
  • A atualização para a solicitação patch de grupo deve produzir um HTTP 204 Sem conteúdo na resposta. Retornar um corpo com uma lista de todos os membros não é aconselhável.
  • Não é necessário dar suporte ao retorno de todos os membros do grupo.

Criar Grupo

Solicitação

POST /Grupos HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group", "http://schemas.microsoft.com/2006/11/ResourceManagement/ADSCIM/2.0/Group"],
    "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159",
    "displayName": "displayName",
    "meta": {
        "resourceType": "Group"
    }
}
Resposta

HTTP/1.1 201 Criado

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "id": "927fa2c08dcb4a7fae9e",
    "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159",
    "meta": {
        "resourceType": "Group",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
        
    },
    "displayName": "displayName",
    "members": []
}

Obter Grupo

Solicitação

GET /Groups/40734ae655284ad3abcc?excludedAttributes=members HTTP/1.1

Resposta

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "id": "40734ae655284ad3abcc",
    "externalId": "60f1bb27-2e1e-402d-bcc4-ec999564a194",
    "meta": {
        "resourceType": "Group",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "displayName": "displayName",
}

Obter Grupo por displayName

Solicitação

GET /Groups?excludedAttributes=members&filter=displayName eq "displayName" HTTP/1.1

Resposta

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 1,
    "Resources": [{
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
        "id": "8c601452cc934a9ebef9",
        "externalId": "0db508eb-91e2-46e4-809c-30dcbda0c685",
        "meta": {
            "resourceType": "Group",
            "created": "2018-03-27T22:02:32.000Z",
            "lastModified": "2018-03-27T22:02:32.000Z",
            
        },
        "displayName": "displayName",
    }],
    "startIndex": 1,
    "itemsPerPage": 20
}

Atualizar Grupo [Atributos de não membro]

Solicitação

PATCH /Grupos/fa2ce26709934589afc5 HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Replace",
        "path": "displayName",
        "value": "1879db59-3bdf-4490-ad68-ab880a269474updatedDisplayName"
    }]
}
Resposta

HTTP/1.1 204 Sem Conteúdo

Atualizar Grupo [Adicionar Membros]

Solicitação

PATCH /Grupos/a99962b9f99d4c4fac67 HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Add",
        "path": "members",
        "value": [{
            "$ref": null,
            "value": "f648f8d5ea4e4cd38e9c"
        }]
    }]
}
Resposta

HTTP/1.1 204 Sem Conteúdo

Atualizar Grupo [Remover Membros]

Solicitação

PATCH /Grupos/a99962b9f99d4c4fac67 HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Remove",
        "path": "members",
        "value": [{
            "$ref": null,
            "value": "f648f8d5ea4e4cd38e9c"
        }]
    }]
}
Resposta

HTTP/1.1 204 Sem Conteúdo

Excluir grupo

Solicitação

DELETE /Groups/cdb1ce18f65944079d37 HTTP/1.1

Resposta

HTTP/1.1 204 Sem Conteúdo

Descoberta de Esquema

Descobrir esquema

Solicitação

GET /Esquemas

Resposta

HTTP/1.1 200 OK

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "itemsPerPage": 50,
    "startIndex": 1,
    "totalResults": 3,
    "Resources": [
  {
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
    "id" : "urn:ietf:params:scim:schemas:core:2.0:User",
    "name" : "User",
    "description" : "User Account",
    "attributes" : [
      {
        "name" : "userName",
        "type" : "string",
        "multiValued" : false,
        "description" : "Unique identifier for the User, typically
used by the user to directly authenticate to the service provider.
Each User MUST include a non-empty userName value.  This identifier
MUST be unique across the service provider's entire set of Users.
REQUIRED.",
        "required" : true,
        "caseExact" : false,
        "mutability" : "readWrite",
        "returned" : "default",
        "uniqueness" : "server"
      },                
    ],
    "meta" : {
      "resourceType" : "Schema",
      "location" :
        "/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:User"
    }
  },
  {
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
    "id" : "urn:ietf:params:scim:schemas:core:2.0:Group",
    "name" : "Group",
    "description" : "Group",
    "attributes" : [
      {
        "name" : "displayName",
        "type" : "string",
        "multiValued" : false,
        "description" : "A human-readable name for the Group.
REQUIRED.",
        "required" : false,
        "caseExact" : false,
        "mutability" : "readWrite",
        "returned" : "default",
        "uniqueness" : "none"
      },
    ],
    "meta" : {
      "resourceType" : "Schema",
      "location" :
        "/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:Group"
    }
  },
  {
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
    "id" : "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    "name" : "EnterpriseUser",
    "description" : "Enterprise User",
    "attributes" : [
      {
        "name" : "employeeNumber",
        "type" : "string",
        "multiValued" : false,
        "description" : "Numeric or alphanumeric identifier assigned
to a person, typically based on order of hire or association with an
organization.",
        "required" : false,
        "caseExact" : false,
        "mutability" : "readWrite",
        "returned" : "default",
        "uniqueness" : "none"
      },
    ],
    "meta" : {
      "resourceType" : "Schema",
      "location" :
"/v2/Schemas/urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    }
  }
]
}

Requisitos de segurança

Versões do protocolo TLS

A única versão de protocolo aceitável é o TLS 1.2. Nenhuma outra versão do SSL/TLS é permitida.

  • As chaves RSA devem ter pelo menos 2.048 bits.
  • Chaves ECC devem ter pelo menos 256 bits, geradas usando uma curva elíptica aprovada

Comprimentos de chave

Todos os serviços devem usar certificados X.509 gerados usando chaves de criptografia de tamanho suficiente, o que significa:

Suites de criptografia

Todos os serviços precisam ser configurados para usar os conjuntos de criptografia a seguir, na ordem exata especificada no exemplo. Se você tiver apenas um certificado RSA, os conjuntos de criptografia ECDSA não terão nenhum efeito.

Barra mínima dos conjuntos de criptografia TLS 1.2:

  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384

Intervalos de IP

O serviço de provisionamento do Microsoft Entra atualmente opera sob os Intervalos de IP da Microsoft Entra ID conforme listado aqui. Você pode adicionar os intervalos de IP listados na tag AzureActiveDirectory para permitir o tráfego do serviço de provisionamento do Microsoft Entra no aplicativo. Será necessário examinar com atenção a lista de intervalos de IP com os endereços computados. Um endereço como '40.126.25.32' poderá ser representado na lista de intervalos de IP como ' 40.126.0.0/18 '. Você também pode recuperar programaticamente a lista de intervalos de IP usando a API a seguir.

O Microsoft Entra ID também dá suporte a uma solução baseada em agente para fornecer conectividade a aplicativos em redes privadas (locais, hospedados no Azure, hospedados no AWS etc.). Os clientes podem implantar um agente leve, que fornece conectividade ao Microsoft Entra ID sem abrir nenhuma porta de entrada, em um servidor em sua rede privada. Saiba mais aqui.

Crie um ponto de extremidade do SCIM

Agora que você criou seu esquema e entendeu a implementação do SCIM do Microsoft Entra, pode começar a desenvolver seu ponto de extremidade do SCIM. Em vez de começar do zero e criar a implementação completamente por conta própria, você pode contar com várias bibliotecas de SCIM de software livre publicadas pela Comunidade do SCIM.

Para obter diretrizes sobre como criar um ponto de extremidade SCIM, incluindo exemplos, consulte Desenvolver um ponto de extremidade SCIM de exemplo.

O exemplo de código de referência do .NET Core de software livre publicado pela equipe de provisionamento do Microsoft Entra é um desses recursos que pode iniciar seu desenvolvimento. Crie um ponto de extremidade SCIM e teste-o executando as solicitações/respostas de exemplo fornecidas.

Observação

O código de referência destina-se a ajudá-lo a começar a criar seu ponto de extremidade SCIM e é fornecido como "AS IS". As contribuições da comunidade são bem-vindas para ajudar a criar e manter o código.

A solução é composta por dois projetos, Microsoft.SCIM e Microsoft.SCIM.WebHostSample.

O projeto Microsoft.SCIM é a biblioteca que define os componentes do serviço Web que está em conformidade com a especificação scim. Ele declara a interface Microsoft.SCIM.IProvider, as solicitações são traduzidas em chamadas para os métodos do provedor, que seriam programados para operar em um repositório de identidades.

Detalhamento: uma solicitação traduzida em chamadas para os métodos do provedor

O projeto Microsoft.SCIM.WebHostSample é um aplicativo Web ASP.NET Core, com base no modelo Vazio . Ele permite que o código de exemplo seja implantado como autônomo, hospedado em contêineres ou dentro de Serviços de Informações da Internet. Ele também implementa a interface Microsoft.SCIM.IProvider mantendo classes na memória como um repositório de identidade de exemplo.

public class Startup
{
    ...
    public IMonitor MonitoringBehavior { get; set; }
    public IProvider ProviderBehavior { get; set; }

    public Startup(IWebHostEnvironment env, IConfiguration configuration)
    {
        ...
        this.MonitoringBehavior = new ConsoleMonitor();
        this.ProviderBehavior = new InMemoryProvider();
    }
    ...

Criando um ponto de extremidade SCIM personalizado

O ponto de extremidade do SCIM deve ter um endereço HTTP e um certificado de autenticação de servidor do qual a autoridade de certificação raiz é destes nomes:

  • CNNIC
  • Comodo
  • Confiança cibernética
  • DigiCert
  • GeoTrust
  • GlobalSign
  • Vai papai
  • VeriSign
  • WoSign
  • DST Raiz CA X3

O SDK do .NET Core inclui um certificado de desenvolvimento HTTPS usado durante o desenvolvimento. O certificado é instalado como parte da experiência de primeira execução. Dependendo de como você executa o Aplicativo Web ASP.NET Core, ele escuta em uma porta diferente:

  • Microsoft.SCIM.WebHostSample: https://localhost:5001
  • IIS Expresso: https://localhost:44359

Para obter mais informações sobre HTTPS no ASP.NET Core, use o seguinte link: Impor HTTPS no ASP.NET Core

Manipulando a autenticação do ponto de extremidade

As solicitações do serviço de provisionamento do Microsoft Entra incluem um token de portador do OAuth 2.0. Um servidor de autorização emite o token de portador. O Microsoft Entra ID é um exemplo de um servidor de autorização confiável. Configure o serviço de provisionamento do Microsoft Entra para usar um dos seguintes tokens:

  • Um token de portador de vida útil longa. Se o ponto de extremidade SCIM exigir um token de portador OAuth de um emissor diferente do Microsoft Entra ID, copie o token de portador OAuth necessário para o campo opcional Secret Token. Em um ambiente de desenvolvimento, você pode usar o token de teste do ponto de extremidade /scim/token. Os tokens de teste não devem ser usados em ambientes de produção.

  • Token de portador do Microsoft Entra. Se o campo Token Secreto for deixado em branco, a Microsoft Entra ID incluirá um token de portador OAuth emitido pela Microsoft Entra ID com cada solicitação. Os aplicativos que usam o Microsoft Entra ID como provedor de identidade podem validar esse token emitido pelo Microsoft Entra ID.

    • O aplicativo que recebe solicitações deve validar o emissor do token como sendo Microsoft Entra ID para um locatário do Microsoft Entra esperado.
    • Uma declaração iss identifica o emissor do token. Por exemplo, "iss":"https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/". Neste exemplo, o endereço base do valor da declaração, https://sts.windows.net identifica a ID do Microsoft Entra como o emissor, enquanto o segmento de endereço relativo, aaaabbbb-0000-cccc-1111-dddd2222eeee, é um identificador exclusivo do locatário do Microsoft Entra para o qual o token foi emitido.
    • O público-alvo de um token é a ID do aplicativo na galeria. Os aplicativos registrados em um único locatário recebem a mesma declaração iss com solicitações SCIM. A ID do aplicativo para todos os aplicativos personalizados é 8adf8e6e-67b2-4cf2-a259-e3dc5476c621. O token gerado pelo Microsoft Entra ID só deve ser usado para teste. Ele não devem ser usados em ambientes de produção.

No código de exemplo, as solicitações são autenticadas usando o pacote Microsoft.AspNetCore.Authentication.JwtBearer. O código a seguir impõe que as solicitações para qualquer um dos pontos de extremidade do serviço sejam autenticadas usando o token de portador emitido pelo Microsoft Entra ID para um locatário especificado:

public void ConfigureServices(IServiceCollection services)
{
    if (_env.IsDevelopment())
    {
        ...
    }
    else
    {
        services.AddAuthentication(options =>
        {
            options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
            options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
        })
            .AddJwtBearer(options =>
            {
                options.Authority = " https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/";
                options.Audience = "8adf8e6e-67b2-4cf2-a259-e3dc5476c621";
                ...
            });
    }
    ...
}

public void Configure(IApplicationBuilder app)
{
    ...
    app.UseAuthentication();
    app.UseAuthorization();
    ...
}

O código de exemplo usa ambientes ASP.NET Core para alterar as opções de autenticação durante o estágio de desenvolvimento e habilitar o uso de um token autoassinado.

Para obter mais informações sobre vários ambientes no ASP.NET Core, consulte Usar vários ambientes no ASP.NET Core.

O código a seguir impõe que as solicitações para qualquer um dos pontos de extremidade do serviço sejam autenticadas usando um token de portador assinado com uma chave personalizada:

public void ConfigureServices(IServiceCollection services)
{
    if (_env.IsDevelopment())
    {
        services.AddAuthentication(options =>
        {
            options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
            options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
        })
        .AddJwtBearer(options =>
        {
            options.TokenValidationParameters =
                new TokenValidationParameters
                {
                    ValidateIssuer = false,
                    ValidateAudience = false,
                    ValidateLifetime = false,
                    ValidateIssuerSigningKey = false,
                    ValidIssuer = "Microsoft.Security.Bearer",
                    ValidAudience = "Microsoft.Security.Bearer",
                    IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("A1B2C3D4E5F6A1B2C3D4E5F6"))
                };
        });
    }
...

Envie uma solicitação GET para o controlador de token para obter um token de portador válido, o método GenerateJSONWebToken é responsável por criar um token que corresponda aos parâmetros configurados para desenvolvimento:

private string GenerateJSONWebToken()
{
    // Create token key
    SymmetricSecurityKey securityKey =
        new SymmetricSecurityKey(Encoding.UTF8.GetBytes("A1B2C3D4E5F6A1B2C3D4E5F6"));
    SigningCredentials credentials =
        new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256);

    // Set token expiration
    DateTime startTime = DateTime.UtcNow;
    DateTime expiryTime = startTime.AddMinutes(120);

    // Generate the token
    JwtSecurityToken token =
        new JwtSecurityToken(
            "Microsoft.Security.Bearer",
            "Microsoft.Security.Bearer",
            null,
            notBefore: startTime,
            expires: expiryTime,
            signingCredentials: credentials);

    string result = new JwtSecurityTokenHandler().WriteToken(token);
    return result;
}

Realização do provisionamento e o desprovisionamento de usuários

Exemplo 1. Consultar o serviço para um usuário correspondente

O Microsoft Entra ID consulta o serviço para encontrar um usuário com um valor de atributo externalId correspondente ao valor de atributo mailNickname de um usuário no Microsoft Entra ID. A consulta é expressa como solicitação HTTP como no exemplo, na qual jyoung é o exemplo de um mailNickname de um usuário no Microsoft Entra ID.

Observação

Este é apenas um exemplo. Nem todos os usuários terão um atributo mailNickname, e o valor que um usuário tem pode não ser exclusivo no diretório. Além disso, o atributo usado para correspondência (que nesse caso é externalId) é configurável nos mapeamentos de atributo do Microsoft Entra.

GET https://.../scim/Users?filter=externalId eq jyoung HTTP/1.1
 Authorization: Bearer ...

No código de exemplo, a solicitação é convertida em uma chamada para o método QueryAsync do provedor do serviço. Veja a assinatura desse método:

// System.Threading.Tasks.Tasks is defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in 
// Microsoft.SCIM.Service.  
// Microsoft.SCIM.Resource is defined in 
// Microsoft.SCIM.Schemas.  
// Microsoft.SCIM.IQueryParameters is defined in 
// Microsoft.SCIM.Protocol.  

Task<Resource[]> QueryAsync(IRequest<IQueryParameters> request);

Na consulta de exemplo, para um usuário com um valor fornecido para o atributo externalId, os valores dos argumentos passados para o método QueryAsync serão:

  • Parâmetros.AlternateFilters.Count: 1
  • Parâmetros. AlternateFilters.ElementAt(0). AttributePath: "externalId"
  • Parâmetros. AlternateFilters.ElementAt(0). ComparisonOperator: ComparisonOperator.Equals
  • Parâmetros. AlternateFilter.ElementAt(0). ComparisonValue: "jyoung"

Exemplo 2. Provisionar um usuário

Caso a resposta a uma consulta ao ponto de extremidade do SCIM para um usuário com um valor de atributo externalId que corresponde ao valor de atributo mailNickname de um usuário não retorne nenhum usuário, o Microsoft Entra ID solicitará que o serviço provisione um usuário correspondente ao usuário no Microsoft Entra ID. Veja um exemplo de tal solicitação:

POST https://.../scim/Users HTTP/1.1
Authorization: Bearer ...
Content-type: application/scim+json
{
   "schemas":
   [
     "urn:ietf:params:scim:schemas:core:2.0:User",
     "urn:ietf:params:scim:schemas:extension:enterprise:2.0User"],
   "externalId":"jyoung",
   "userName":"jyoung@testuser.com",
   "active":true,
   "addresses":null,
   "displayName":"Joy Young",
   "emails": [
     {
       "type":"work",
       "value":"jyoung@Contoso.com",
       "primary":true}],
   "meta": {
     "resourceType":"User"},
    "name":{
     "familyName":"Young",
     "givenName":"Joy"},
   "phoneNumbers":null,
   "preferredLanguage":null,
   "title":null,
   "department":null,
   "manager":null}

No código de exemplo, a solicitação é convertida em uma chamada para o método CreateAsync do provedor do serviço. Veja a assinatura desse método:

// System.Threading.Tasks.Tasks is defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in 
// Microsoft.SCIM.Service.  
// Microsoft.SCIM.Resource is defined in 
// Microsoft.SCIM.Schemas.  

Task<Resource> CreateAsync(IRequest<Resource> request);

Em uma solicitação para um provisionamento de usuário, o valor do argumento do recurso é uma instância da classe Microsoft.SCIM.Core2EnterpriseUser. Essa classe é definida na biblioteca Microsoft.SCIM.Schemas. Se a solicitação de provisionamento do usuário for bem-sucedida, a implementação do método deverá retornar uma instância da classe Microsoft.SCIM.Core2EnterpriseUser. O valor da propriedade Identifier é definido como o identificador exclusivo do usuário recém-provisionado.

Exemplo 3. Consultar o estado atual de um usuário

O Microsoft Entra ID solicita o estado atual do usuário especificado do serviço com uma solicitação como:

GET ~/scim/Users/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 HTTP/1.1
Authorization: Bearer ...

No código de exemplo, a solicitação é convertida em uma chamada para o método RetrieveAsync do provedor do serviço. Veja a assinatura desse método:

// System.Threading.Tasks.Tasks is defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in 
// Microsoft.SCIM.Service.  
// Microsoft.SCIM.Resource and 
// Microsoft.SCIM.IResourceRetrievalParameters 
// are defined in Microsoft.SCIM.Schemas 

Task<Resource> RetrieveAsync(IRequest<IResourceRetrievalParameters> request);

No exemplo de uma solicitação para recuperar o estado atual de um usuário, os valores das propriedades do objeto fornecidos como o valor do argumento de parâmetros são:

  • Identificador: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
  • Identificador de esquema: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Exemplo 4. Consultar o valor de um atributo de referência a ser atualizado

O Microsoft Entra ID verifica o valor do atributo atual no repositório de identidade antes de atualizá-lo. No entanto, somente o atributo de gerente é o verificado primeiramente para os usuários. Veja o exemplo de uma solicitação para determinar se o atributo de gerenciador de um objeto de usuário atualmente tem um determinado valor: no código de exemplo, a solicitação é convertida em uma chamada para o método QueryAsync do provedor do serviço. O valor das propriedades do objeto fornecido como o valor do argumento de parâmetros é:

  • Parâmetros.AlternateFilters.Count: 2
  • parameters.AlternateFilters.ElementAt(x).AttributePath: “ID”
  • Parâmetros. AlternateFilters.ElementAt(x). ComparisonOperator: ComparisonOperator.Equals
  • Parâmetros. AlternateFilter.ElementAt(x). ComparisonValue: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1e1"
  • Parâmetros.AlternateFilters.ElementAt(y).AttributePath: "manager"
  • Parâmetros.AlternateFilters.ElementAt(y).ComparisonOperator: ComparisonOperator.Equals
  • Parâmetros. AlternateFilter.ElementAt(y). ComparisonValue: "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
  • parameters.RequestedAttributePaths.ElementAt(0): “ID”
  • Parâmetros. SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

O valor do índice x pode ser 0 e o valor do índice y pode ser 1. Ou o valor de x pode ser 1 e o valor de y pode ser 0. Depende da ordem das expressões do parâmetro de consulta de filtro.

Exemplo 5. Solicitação do Microsoft Entra ID para atualizar um usuário em um ponto de extremidade SCIM

Aqui está um exemplo de uma solicitação do Microsoft Entra ID para um ponto de extremidade do SCIM para atualizar um usuário:

PATCH ~/scim/Users/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 HTTP/1.1
Authorization: Bearer ...
Content-type: application/scim+json
{
    "schemas": 
    [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations":
    [
      {
        "op":"Add",
        "path":"manager",
        "value":
          [
            {
              "$ref":"http://.../scim/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
              "value":"00aa00aa-bb11-cc22-dd33-44ee44ee44ee"}]}]}

No código de exemplo, a solicitação é convertida em uma chamada para o método UpdateAsync do provedor do serviço. Veja a assinatura desse método:

// System.Threading.Tasks.Tasks and 
// System.Collections.Generic.IReadOnlyCollection<T>  // are defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in
// Microsoft.SCIM.Service.
// Microsoft.SCIM.IPatch, 
// is defined in Microsoft.SCIM.Protocol. 

Task UpdateAsync(IRequest<IPatch> request);

No exemplo de uma solicitação, para atualizar um usuário, o objeto fornecido como valor do argumento de patch tem estes valores de propriedade:

Argumento Valor
ResourceIdentifier.Identifier "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1e1"
ResourceIdentifier.SchemaIdentifier urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
(PatchRequest as PatchRequest2).Operations.Count 1
(PatchRequest as PatchRequest2).Operations.ElementAt(0).OperationName OperationName.Add
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Path.AttributePath Gerente
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.Count 1
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Reference http://.../scim/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Value 00AA00AA-BB11-CC22-DD33-44EE44EE44EE44EEE

Exemplo 6. Desprovisionar um usuário

Para desprovisionar um usuário de um repositório de identidades administrado por um ponto de extremidade do SCIM, o Microsoft Entra ID envia uma solicitação como esta:

DELETE ~/scim/Users/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 HTTP/1.1
Authorization: Bearer ...

No código de exemplo, a solicitação é convertida em uma chamada para o método DeleteAsync do provedor do serviço. Veja a assinatura desse método:

// System.Threading.Tasks.Tasks is defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in 
// Microsoft.SCIM.Service.  
// Microsoft.SCIM.IResourceIdentifier, 
// is defined in Microsoft.SCIM.Protocol. 

Task DeleteAsync(IRequest<IResourceIdentifier> request);

O objeto fornecido como valor do argumento resourceIdentifier tem estes valores de propriedade no exemplo de uma solicitação para desprovisionar um usuário:

  • ResourceIdentifier.Identifier: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1e1"
  • ResourceIdentifier.SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Integre seu ponto de extremidade do SCIM ao Serviço de Provisionamento de Microsoft Entra

A ID do Microsoft Entra pode ser configurada para provisionar automaticamente usuários e grupos atribuídos a aplicativos que implementam um perfil específico do protocolo SCIM 2.0. As especificidades do perfil estão documentadas no Understand the Microsoft Entra SCIM implementation.

Verifique com o seu provedor de aplicativo ou na documentação do seu provedor de aplicativo as declarações de compatibilidade com esses requisitos.

Importante

A implementação do SCIM do Microsoft Entra é criada sobre o serviço de provisionamento de usuários do Microsoft Entra, projetado para manter constantemente os usuários sincronizados entre o Microsoft Entra ID e o aplicativo de destino, e implementa um conjunto muito específico de operações padrão. É importante entender esses comportamentos para entender o comportamento do serviço de provisionamento do Microsoft Entra. Para obter mais informações, consulte a seção Ciclos de provisionamento: inicial e incremental em Como o provisionamento funciona.

Introdução

Os aplicativos que dão suporte ao perfil do SCIM descrito neste artigo podem ser conectados ao Microsoft Entra ID usando o recurso de “aplicativo não galeria” na galeria de aplicativos do Microsoft Entra. Uma vez conectado, o Microsoft Entra ID executa um processo de sincronização. O processo acontece a cada 40 minutos. O processo consulta o ponto de extremidade SCIM do aplicativo para os usuários e grupos atribuídos e os cria ou modifica de acordo com os detalhes da atribuição.

Para conectar um aplicativo que dá suporte ao SCIM:

  1. Entre no Centro de administração do Microsoft Entra como pelo menos um Administrador de Aplicativos.

  2. Navegue até Entra ID>Aplicativos corporativos.

  3. É mostrada uma lista com todos os aplicativos configurados, incluindo aplicativos que foram adicionados da galeria.

  4. Selecione + Novo aplicativo>+ Criar seu próprio aplicativo.

  5. Insira um nome para seu aplicativo, escolha a opção "integrar qualquer outro aplicativo que você não encontrar na galeria" e selecione Adicionar para criar um objeto de aplicativo. O novo aplicativo é adicionado à lista de aplicativos empresariais e é aberto em sua tela de gerenciamento de aplicativo.

    A captura de tela a seguir mostra a galeria de aplicativos do Microsoft Entra:

    A captura de tela mostra a galeria de aplicativos do Microsoft Entra.

  6. Na tela de gerenciamento de aplicativos, selecione Provisionamento no painel esquerdo.

  7. Selecione + Nova configuração.

  8. No campo URL de Locatário, insira a URL do ponto de extremidade SCIM do aplicativo. Exemplo: https://api.contoso.com/scim/

  9. Se o ponto de extremidade SCIM exigir um token de portador OAuth de um emissor diferente do Microsoft Entra ID, copie o token de portador OAuth necessário para o campo opcional Secret Token. Esse campo fica em branco, o Microsoft Entra ID inclui um token de portador OAuth emitido do Microsoft Entra ID com cada solicitação. Os aplicativos que usam o Microsoft Entra ID como provedor de identidade podem validar esse token emitido pelo Microsoft Entra ID.

    Observação

    Não é recomendável deixar esse campo em branco e contar com um token gerado pela ID do Microsoft Entra. Essa opção está disponível principalmente para fins de teste.

  10. Selecione Testar Conexão para que o Microsoft Entra ID tente se conectar ao endpoint SCIM. Se a tentativas falhar, informações de erro serão exibidas.

    Observação

    Test Connection consulta o ponto de extremidade SCIM para um usuário que não existe, usando um GUID aleatório como propriedade de correspondência selecionada na configuração do Microsoft Entra. A resposta correta esperada é HTTP 200 OK com uma mensagem de SCIM ListResponse vazia.

  11. Se a tentativa de se conectar ao aplicativo for bem-sucedida, selecione Criar para criar o trabalho de provisionamento.

  12. Se estiver sincronizando somente usuários e grupos atribuídos (recomendado), selecione a guia Usuários e grupos . Em seguida, atribua os usuários ou grupos que você deseja sincronizar.

  13. Selecione mapeamento de atributo no painel esquerdo. Há dois conjuntos selecionáveis de mapeamentos de atributo : um para objetos de usuário e outro para objetos de grupo. Selecione cada um para revisar os atributos que são sincronizados do Microsoft Entra ID para seu aplicativo. Os atributos selecionados como propriedades correspondentes são usados para corresponder aos usuários e grupos em seu aplicativo para operações de atualização. Selecione Salvar para confirmar as alterações.

    Opcionalmente, você pode desabilitar a sincronização dos objetos de grupo desabilitando o mapeamento "grupos".

  14. Selecione Provisionar sob demanda no painel esquerdo. Pesquise um usuário dentro do escopo de provisionamento e provisione-o quando necessário. Repita com outros usuários com os quais você gostaria de testar o provisionamento.

  15. Depois que a configuração for concluída, selecione Visão geral no painel esquerdo.

  16. Selecione Propriedades.

  17. Selecione o lápis para editar as propriedades. Habilite emails de notificação e forneça um email para receber emails de quarentena. Habilitar a prevenção de exclusões acidentais. Clique em Aplicar para salvar as alterações.

  18. Selecione Iniciar provisionamento para iniciar o serviço de provisionamento do Microsoft Entra.

Depois que o ciclo inicial for iniciado, você poderá selecionar logs de provisionamento no painel esquerdo para monitorar o progresso, que mostra todas as ações feitas pelo serviço de provisionamento em seu aplicativo. Para obter mais informações sobre como ler os logs de provisionamento do Microsoft Entra, consulte Relatórios sobre provisionamento automático de conta de usuário.

Observação

O ciclo inicial demora mais do que as sincronizações posteriores, que ocorrem aproximadamente a cada 40 minutos desde que o serviço esteja em execução.

Se você estiver criando um aplicativo que será usado por mais de um locatário, disponibilize-o na galeria de aplicativos do Microsoft Entra. É fácil para as organizações descobrirem o aplicativo e configurem o provisionamento. Publicar seu aplicativo na galeria do Microsoft Entra e disponibilizar o provisionamento para outras pessoas é fácil. Confira as etapas aqui. A Microsoft trabalha com você para integrar seu aplicativo à galeria, testar seu ponto de extremidade e liberar a documentação de integração para os clientes.

Use a lista de verificação para integrar seu aplicativo rapidamente e para que os clientes tenham uma experiência de implantação tranquila. As informações serão coletadas quando você estiver realizando a integração à galeria.

  • Suporte a um usuário e um grupo SCIM 2.0 endpoint (apenas um é necessário, mas ambos são recomendados)
  • Dar suporte a pelo menos 25 solicitações por segundo e por locatário para garantir que usuários e grupos sejam provisionados e desprovisionados sem atraso (obrigatório)
  • Estabelecer contatos de engenharia e suporte para orientar os clientes após a integração à galeria (obrigatório)
  • 3 credenciais de teste sem expiração para seu aplicativo (obrigatório)
  • Dar suporte à concessão de código de autorização OAuth ou a um token de vida útil longa, conforme descrito no exemplo (obrigatório)
  • Os aplicativos OIDC devem ter pelo menos uma função (personalizada ou padrão) definida
  • Estabelecer um ponto de contato de engenharia e suporte para ajudar os clientes após a integração à galeria (obrigatório)
  • Descoberta de esquema de suporte (obrigatório)
  • Dar suporte à atualização de várias associações de grupo com um único PATCH
  • Documentar seu ponto de extremidade do SCIM publicamente

A especificação do SCIM não define um esquema específico de SCIM para autenticação e autorização e se baseia no uso de padrões existentes do setor.

Método de autorização Vantagens Desvantagens Suporte
Nome de usuário e senha (não recomendado ou com suporte do Microsoft Entra ID) Fácil de implementar Inseguro - Seu Pa$$word não importa Sem suporte para aplicativos que não são ou que são da nova galeria.
Token de portador de vida útil longa Os tokens de vida útil longa não exigem que um usuário esteja presente. Eles são fáceis para os administradores usarem ao configurar o provisionamento. Os tokens de vida útil longa podem ser difíceis de compartilhar com um administrador sem usar métodos inseguros, como email. Com suporte para aplicativos que não são e que são da galeria.
Concessão de código de autorização OAuth Os tokens de acesso têm uma vida útil mais curta que as senhas e têm um mecanismo de atualização automatizado que os tokens de portador de longa duração não têm. Um usuário real deve estar presente durante a autorização inicial, adicionando um nível de responsabilidade. Exige que um usuário esteja presente. Se o usuário sair da organização, o token será inválido e a autorização precisará ser realizada novamente. Com suporte para aplicativos da galeria, porém não para aplicativos inexistentes na galeria. No entanto, é possível fornecer um token de acesso na interface do usuário como um token secreto para fins de teste de curto prazo. O suporte para concessão de código OAuth em aplicativos que não são da galeria está em nossa lista de pendências, além do suporte a URLs de autenticação/token configuráveis no aplicativo da galeria.
Concessão de credenciais de cliente do OAuth Os tokens de acesso têm uma vida útil mais curta que as senhas e têm um mecanismo de atualização automatizado que os tokens de portador de longa duração não têm. A concessão de código de autorização e a concessão de credenciais de cliente criam o mesmo tipo de token de acesso; portanto, a transferência entre esses métodos é transparente para a API. O provisionamento pode ser automatizado e novos tokens podem ser silenciosamente solicitados sem interação do usuário. Com suporte para aplicativos da galeria, porém não para aplicativos inexistentes na galeria. No entanto, é possível fornecer um token de acesso na interface do usuário como um token secreto para fins de teste de curto prazo. Dar suporte para a concessão de credenciais do cliente OAuth fora da galeria não está em nossa lista de pendências.

Observação

Não é recomendável deixar o campo de token em branco na interface do usuário do aplicativo personalizado de configuração de provisionamento do Microsoft Entra. O token gerado está disponível principalmente para fins de teste.

Fluxo de concessão de código OAuth

O serviço de provisionamento dá suporte à concessão de código de autorização e, depois de enviar sua solicitação para publicar seu aplicativo na galeria, nossa equipe trabalhará com você para coletar as seguintes informações:

  • URL de autorização, uma URL do cliente para obter autorização do proprietário do recurso por meio do redirecionamento do agente de usuário. O usuário é redirecionado para essa URL para autorizar o acesso.

  • URL de troca de tokens, uma URL do cliente para trocar uma concessão de autorização por um token de acesso, normalmente com autenticação de cliente.

  • ID do cliente, o servidor de autorização emite ao cliente registrado um identificador de cliente, que é uma cadeia de caracteres exclusiva que representa as informações de registro fornecidas pelo cliente. O identificador do cliente não é um segredo; ele é exposto ao proprietário do recurso e não deve ser usado sozinho para autenticação do cliente.

  • Segredo do cliente, um segredo gerado pelo servidor de autorização que deve ser um valor exclusivo conhecido apenas para o servidor de autorização.

Observação

Atualmente a URL de Autorização e a URL de troca de tokens não são configuráveis por inquilino.

Observação

O OAuth v1 não tem suporte devido à exposição do segredo do cliente. Há suporte para OAuth v2.

Ao usar o fluxo de concessão de código OAuth, é necessário oferecer suporte a um modelo em que cada cliente enviará a própria ID do cliente e o segredo do cliente ao configurar uma instância de provisionamento. Não há suporte para um único par de ID do cliente/segredo do cliente em todo o aplicativo.

Como configurar o fluxo de concessão de código OAuth

  1. Entre no Centro de administração do Microsoft Entra como pelo menos um Administrador de Aplicativos.

  2. Navegue até o Entra ID>Aplicativos Empresariais>Aplicação>Provisionamento e selecione Autorizar.

  3. Entre no Centro de administração do Microsoft Entra como pelo menos um Administrador de Aplicativos.

  4. Navegue até Entra ID>Aplicativos corporativos.

  5. Selecione seu aplicativo e vá para Provisionamento.

  6. Selecione Autorizar.

    1. Os usuários são redirecionados para a URL de autorização (página de entrada do aplicativo de terceiros).

    2. O administrador fornecerá credenciais para o aplicativo de terceiros.

    3. O aplicativo de terceiros redireciona o usuário de volta e fornece o código de concessão

    4. O Serviço de Provisionamento chama a URL do token e fornece o código de concessão. O aplicativo de terceiros responderá com o token de acesso, o token de atualização e a data de expiração

  7. Quando o ciclo de provisionamento for iniciado, o serviço verificará se o token de acesso atual é válido e o trocará por um novo token, se necessário. Um token de acesso será fornecido em cada solicitação feita ao aplicativo e a validade da solicitação será verificada antes de cada solicitação.

Observação

Embora atualmente não seja possível configurar o OAuth nos aplicativos de fora da galeria, você poderá gerar um token de acesso de modo manual no servidor de autorização e inseri-lo como o token secreto de um aplicativo que não é da galeria. Isso permitirá verificar a compatibilidade do seu servidor SCIM com o serviço de provisionamento do Microsoft Entra antes de realizar a integração à galeria de aplicativos, que é compatível com a concessão do código OAuth.

Tokens de portador OAuth de longa duração: Se o aplicativo não der suporte ao fluxo de concessão de código de autorização OAuth, em vez disso, gere um token de portador OAuth de longa duração que um administrador pode usar para configurar a integração de provisionamento. O token deve ser perpétuo ou a tarefa de provisionamento será colocada em quarentena quando o token expirar.

Para obter mais métodos de autenticação e autorização, nos avise no UserVoice.

Para ajudar a impulsionar o reconhecimento e a demanda de nossa integração conjunta, recomendamos que você atualize sua documentação existente e amplifique a integração em seus canais de marketing. Recomendamos que você conclua a seguinte lista de verificação para dar suporte à inicialização:

  • Verifique se suas equipes de vendas e de suporte ao cliente estão cientes, prontas e podem se comunicar com os recursos de integração. Comunique suas equipes, forneça perguntas frequentes e inclua a integração em seus materiais de vendas.
  • Crie uma postagem no blog ou um comunicado à imprensa que descreve a integração conjunta, os benefícios e como começar. Exemplo: Imprivata e Microsoft Entra Press Release
  • Aproveite as redes sociais, como o X, o Facebook ou o LinkedIn, para promover a integração aos seus clientes. Certifique-se de incluir @Microsoft Entra ID de forma que possamos retweetar sua postagem. Exemplo: Imprivata X Post
  • Crie ou atualize suas páginas/seu site de marketing (por exemplo, página de integração, página de parceiro, página de preços etc.) para incluir a disponibilidade da integração conjunta. Exemplo: Página de integração do Pingboard, página de integração do SmartsheetMonday.com página de preços
  • Crie um artigo da central de ajuda ou documentação técnica sobre como os clientes podem começar. Exemplo: Envoy + integração do Microsoft Entra.
  • Alerte os clientes da nova integração por meio de comunicação dos seus clientes (boletins informativos mensais, campanhas de email, notas de versão de produto).

Próximas etapas

Desenvolver um exemplo de endpoint SCIMAutomatizar o provisionamento e desprovisionamento de usuários para aplicativos SaaSPersonalizar mapeamentos de atributos para o provisionamento de usuáriosEscrever expressões para mapeamentos de atributosFiltros de escopo para o provisionamento de usuáriosNotificações de provisionamento de contasLista de tutoriais sobre como integrar aplicativos SaaS