Tutorial: Desenvolver e planear o provisionamento para um endpoint SCIM no Microsoft Entra ID

Como desenvolvedor de aplicativos, você pode usar a API de gerenciamento de usuários do System for Cross-Domain Identity Management (SCIM) 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 SCIM e integrar com o serviço de provisionamento do Microsoft Entra. A especificação 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 oferece aos administradores uma solução completa e baseada em padrões para gerenciamento de acesso.

SCIM 2.0 é uma definição padronizada de dois endpoints: um /Users endpoint e um /Groups endpoint. Ele usa pontos de extremidade comuns da API REST 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 e-mail.

Os aplicativos que oferecem uma API REST SCIM 2.0 podem reduzir ou eliminar a dor de trabalhar com uma API proprietária de gerenciamento de usuários. Por exemplo, qualquer cliente SCIM compatível sabe como fazer um HTTP POST de um objeto JSON para o /Users endpoint para criar um novo registo de utilizador. Em vez de precisar de uma API ligeiramente diferente para as mesmas ações básicas, os aplicativos que estão em conformidade com o padrão SCIM podem aproveitar instantaneamente clientes, ferramentas e código pré-existentes.

O esquema de objeto de usuário padrão e as APIs de repouso para gerenciamento definidas no SCIM 2.0 (RFC 7642, 7643, 7644) permitem que provedores de identidade e aplicativos se integrem mais facilmente uns aos outros. Os programadores de aplicações que criam um ponto de extremidade SCIM podem integrar-se a qualquer cliente compatível com SCIM sem necessidade de trabalho personalizado.

Para automatizar o provisionamento de uma aplicação, é necessário desenvolver e integrar um ponto de extremidade SCIM, ao qual o serviço de provisionamento do Microsoft Entra terá acesso. Use as etapas a seguir para começar a provisionar 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 suportado pela implementação do Microsoft Entra SCIM.

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

3. Criar um ponto de extremidade SCIM - Um ponto de extremidade deve ser compatível com SCIM 2.0 para integração com o serviço de aprovisionamento Microsoft Entra. Como opção, use bibliotecas e exemplos de código da Microsoft Common Language Infrastructure (CLI) para criar seu ponto de extremidade. Estas amostras destinam-se apenas a referência e a ensaio; recomendamos não usá-las como dependências no seu aplicativo de produção.

4. Integre o seu endpoint SCIM com o serviço de provisionamento Microsoft Entra. O Microsoft Entra ID suporta várias aplicações 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] Publique seu aplicativo na galeria de aplicativos do Microsoft Entra - Torne mais fácil para os clientes descobrirem seu aplicativo e configurarem facilmente o provisionamento.

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 prestador de serviços
• userName, um identificador exclusivo para o utilizador (geralmente corresponde ao nome principal do utilizador do Microsoft Entra)
• meta, metadados somente de leitura mantidas pelo provedor de serviços

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

Por exemplo, se seu aplicativo requer o email de um usuário e o gerenciador 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 seu esquema, siga estas etapas:

1. Liste os atributos que seu aplicativo requer e, em seguida, categorize como atributos necessários para autenticação (por exemplo, loginName e email). Os 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, tag).

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 cobre os atributos ausentes. Consulte o exemplo de uma extensão para o usuário para permitir o provisionamento de um usuário tag.

3. Mapeie atributos SCIM para os atributos de usuário no Microsoft Entra ID. Se um dos atributos que o utilizador definiu no seu endpoint SCIM não tiver um equivalente claro no esquema de utilizador do Microsoft Entra, oriente o administrador do cliente a estender o seu esquema ou a usar um atributo adicional, conforme mostrado no exemplo da propriedade tags.

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

Atributo/exemplo de aplicativo necessário	Atributo SCIM mapeado	Atributo mapeado do Microsoft Entra
Nome de Login	nome de utilizador	Nome Principal do Utilizador
nomePróprio	name.givenName	givenName
apelido	nome.sobrenome	Apelido
correio de trabalho	emails[type eq "work"].value	Correio
gestor	gestor	gestor
etiqueta	urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:tag	extensãoAtributo1
estado	ativo	isSoftDeleted (valor calculado não armazenado no usuário)

A carga JSON a seguir mostra um exemplo de esquema SCIM:

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

Nota

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

Ajuda a categorizar entre /User e /Group para mapear quaisquer atributos de utilizador padrão no Microsoft Entra ID para o SCIM RFC; veja como os atributos personalizados são mapeados entre o Microsoft Entra ID e o seu endpoint SCIM.

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

Utilizador 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
exibirNome	nome de exibição
ID de funcionário	urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber
Número de telefone de fax	phoneNumbers[tipo eq "fax"].value
givenName	name.givenName
título do trabalho	título
correio	emails[type eq "work"].value
apelido de email	Id externo
gestor	urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager
telemóvel	phoneNumbers[tipo igual a "telemóvel"].valor
código postal	endereços[tipo eq "trabalho"].postalCode
Endereços proxy	e-mails[digite eq "outros"]. Valor
físico-Entrega-NomeDoEscritório	endereços[digite eq "outro"]. Formatado
endereço de rua	endereços[digite eq "trabalho"].streetEndereço
surname	nome.sobrenome
Número de telefone	númerosDeTelefone[tipo eq "trabalho"].valor
Nome Principal do Utilizador	nome de utilizador

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

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

Nota

Você não é obrigado a dar suporte a utilizadores, nem a grupos, nem a todos os atributos aqui apresentados, é apenas uma referência sobre como os atributos no Microsoft Entra ID são frequentemente mapeados para propriedades no protocolo SCIM.

Existem vários pontos finais definidos no SCIM RFC. Você pode começar com o /User ponto de extremidade e, em seguida, expandir a partir daí. A tabela a seguir lista alguns dos pontos de extremidade SCIM:

Ponto final	Descrição
/Utilizador	Execute operações CRUD em um objeto de usuário.
/Grupo	Execute operações CRUD em um objeto de grupo.
/Esquemas	O conjunto de atributos suportados por cada cliente e provedor de serviços pode variar. Um provedor de serviços pode incluir name, titlee emails, enquanto outro provedor de serviços usa name, titlee phoneNumbers. O endpoint de esquemas permite descobrir os atributos suportados.
/A granel	As operações em massa permitem executar 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).
/ServiceProviderConfig	Fornece detalhes sobre os recursos do padrão SCIM suportados, por exemplo, os recursos suportados e o método de autenticação.
/ResourceTypes	Especifica metadados sobre cada recurso.

Nota

Use o /Schemas ponto de extremidade para oferecer suporte a atributos personalizados ou se o esquema for alterado com frequência, pois permite que um cliente recupere o esquema mais atualizado automaticamente. Utilize o endpoint /Bulk para apoiar grupos.

Compreender a implementação do Microsoft Entra SCIM

O serviço de provisionamento do Microsoft Entra foi projetado para oferecer suporte a uma API de gerenciamento de usuários SCIM 2.0.

Importante

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

Dentro da especificação do protocolo SCIM 2.0, seu aplicativo deve suportar estes requisitos:

Requisito	Notas de referência (protocolo SCIM)
Criar usuários e, opcionalmente, também grupos	Ponto 3.3
Modificar usuários ou grupos com solicitações PATCH	Ponto 3.5.2. O suporte garante que grupos e usuários sejam provisionados de maneira eficiente.
Recuperar um recurso conhecido para um usuário ou grupo criado anteriormente	Ponto 3.4.1
Consultar usuários ou grupos	Secção 3.4.2. Por padrão, os usuários são recuperados com seus id e consultados com seus username e externalId, e os grupos são consultados com displayName.
Quando se consulta o recurso de grupo, o filtro excludedAttributes=members é aplicado.	Seção 3.4.2.2
Suporte para listar utilizadores e paginar	Ponto 3.4.2.4.
Exclusão suave de um usuário active=false e restauração do usuário active=true	O objeto de usuário deve ser retornado em uma solicitação se o usuário está ativo ou não. A única vez que o utilizador não deve ser retornado é quando é apagado definitivamente do aplicativo.
Apoiar o endpoint /Schemas	Seção 7 O endpoint de descoberta de esquema é usado para descobrir mais atributos.
Aceite um token de portador único para autenticação e autorização do Microsoft Entra ID para o seu aplicativo.

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

Geral:

• id é uma propriedade necessária para todos os recursos. Cada resposta que retorna um recurso deve garantir que cada recurso tenha essa propriedade, exceto 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 SCIM. (por exemplo. Um número de telefone enviado como 55555555555 não deve ser salvo/devolvido como +5 (555) 555-5555)
• Não é necessário incluir todo o recurso na resposta PATCH .
• Não exija uma correspondência que diferencie maiúsculas de minúsculas em elementos estruturais no SCIM, em particular valores de operação PATCH, conforme definido na secção 3.5.2. O Microsoft Entra ID emite os valores de op como Adicionar, Substituir e Remover.
• O Microsoft Entra ID faz solicitações para buscar um usuário e um grupo aleatórios para garantir que o ponto de extremidade e as credenciais sejam válidos. Também é feito como parte do fluxo de Teste de Conexão.
• Suporta HTTPS no seu endpoint SCIM.
• Atributos personalizados complexos e de vários valores são suportados, mas o Microsoft Entra ID não tem muitas estruturas de dados complexas para extrair dados nesses casos. Os atributos de nome/valor podem ser mapeados facilmente, mas o fluxo de dados para atributos complexos com três ou mais subatributos não é suportado.
• Os valores de subatributo "tipo" de atributos complexos de valores múltiplos devem ser exclusivos. Por exemplo, não pode haver dois endereços de e-mail diferentes com o subtipo "trabalho".
• O cabeçalho de todas as respostas deve ser de content-Type: application/scim+json

Recuperando recursos:

• A resposta a uma solicitação de consulta/filtro deve ser sempre um ListResponse.
• Microsoft Entra-only usa 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 atributos de provisionamento de usuário.

/Utilizadores:

• O atributo entitlements não é suportado.
• Todos os atributos considerados para exclusividade do usuário devem ser utilizáveis como parte de uma consulta filtrada. (por exemplo, se a singularidade do utilizador for avaliada tanto para userName quanto para emails[type eq "work"], um GET para /Users com um filtro deve permitir tanto consultas de userName eq "user@contoso.com" e emails[type eq "work"].value eq "user@contoso.com".

/Grupos:

• Os grupos são opcionais, mas só são suportados se a implementação SCIM suportar pedidos PATCH .
• Os grupos devem ter um valor único em 'displayName' para serem compatíveis com o Microsoft Entra ID e a aplicação SCIM. A singularidade não é um requisito do protocolo SCIM, mas é um requisito para integrar um endpoint SCIM com o Microsoft Entra ID.

/Schemas (descoberta de esquema):

• Exemplo de pedido/resposta
• A descoberta de esquema está sendo usada em determinados aplicativos de galeria. A descoberta de esquema é o único método para adicionar mais atributos ao esquema de um aplicativo SCIM de galeria existente. Atualmente, a descoberta de esquema não é suportada em aplicativos SCIM personalizados que não sejam de galeria.
• Se um valor não estiver presente, não envie valores nulos.
• Os valores de propriedade devem ser escritos em camel case (por exemplo, readWrite), onde a primeira letra de cada palavra é maiúscula, exceto a primeira.
• Deve devolver uma lista de respostas.
• O serviço de provisionamento do Microsoft Entra faz a solicitação /schemas quando você salva a configuração de provisionamento. A solicitação também é feita quando você abre a página de provisionamento de edição. Outros atributos descobertos são apresentados aos clientes nos mapeamentos de atributos na lista de atributos de destino. A descoberta de esquema leva apenas à 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 seu aplicativo.

Provisionamento e desprovisionamento de grupo

O provisionamento e o desprovisionamento de grupo são opcionais. Quando implementada e habilitada, a ilustração a seguir mostra as mensagens que o Microsoft Entra ID envia a um ponto de extremidade SCIM para gerenciar o ciclo de vida de um grupo no repositório de identidades do seu aplicativo. Essas mensagens diferem das mensagens sobre usuários de duas maneiras:

• As solicitações para recuperar grupos especificam que o atributo members 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 solicitações sobre o atributo members.

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

Solicitações e respostas do protocolo SCIM

Este artigo fornece exemplos de solicitações SCIM emitidas pelo serviço de provisionamento do Microsoft Entra e exemplos de respostas esperadas. 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ário do Microsoft Entra emite as operações descritas no exemplo, consulte a seção Ciclos de provisionamento: inicial e incremental em Como funciona o provisionamento.

Operações do usuário

• Criar usuário (Solicitar / resposta)
• Obter usuário (Requisição / Resposta)
• Obter utilizador por consulta (Solicitação / Resposta)
• Obter Utilizador por consulta - Zero resultados (Solicitação / Resposta)
• Atualizar Utilizador [Propriedades de vários valores] (Pedido / Resposta)
• Atualizar usuário [Propriedades de valor único] (Solicitar / resposta)
• Desativar usuário (Solicitar / resposta)
• Excluir usuário (Solicitar / resposta)

Operações de Grupo

• Criar Grupo (Solicitar / Resposta)
• Obter Grupo (Pedido / Resposta)
• Obter grupo por displayName (Solicitação / Resposta)
• Grupo de atualização [Atributos de não-membro] (Solicitação / Resposta)
• Atualizar Grupo [Adicionar Membros] (Solicitar / resposta)
• Atualizar Grupo [Remover Membros] (Solicitação / Resposta)
• Excluir grupo (Solicitar / resposta)

Descoberta de esquema

• Descobrir esquema (Solicitação / Resposta)

Operações do usuário

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

Criar Utilizador

Pedido

POST /Utilizadores

{
    "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 Utilizador

Pedido

GET /Utilizadores/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
    }]
}

Pedido

GET /Utilizadores/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

Pedido

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

Pedido

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]

Solicitar

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]

Pedido

PATCH /Users/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
    }]
}

Desativar usuário

Solicitação

PATCH /Users/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"
    }
}

Eliminar Utilizador

Pedido

EXCLUIR /users/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 vazia.
• Utilize o atributo displayName para consultar grupos.
• A atualização para a solicitação PATCH do grupo deve gerar um HTTP 204 No Content na resposta. Devolver um corpo com uma lista de todos os membros não é aconselhável.
• Não é necessário apoiar o retorno de todos os membros do grupo.

Criar Grupo

Pedido

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

Pedido

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 pelo nome de exibição

Pedido

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]

Pedido

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]

Pedido

PATCH /Groups/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]

Pedido

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

Pedido

EXCLUIR /groups/cdb1ce18f65944079d37 HTTP/1.1

Resposta

HTTP/1.1 204 Sem conteúdo

Descoberta de esquema

Descobrir esquema

Pedido

GET /Schemas

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 SSL/TLS é permitida.

• As chaves RSA devem ter pelo menos 2.048 bits.
• As 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 criptográficas de comprimento suficiente, ou seja:

Suítes de Cifração

Todos os serviços devem ser configurados para usar os seguintes pacotes de codificação, na ordem exata especificada no exemplo. Se você tiver apenas um certificado RSA, os pacotes de codificação ECDSA instalados não terão qualquer efeito.

Barra mínima do TLS 1.2 Cipher Suites:

• 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 opera atualmente sob os intervalos de IP para ID do Microsoft Entra, conforme listado aqui. Você pode adicionar os intervalos de IP listados sob a AzureActiveDirectory tag para permitir o tráfego do serviço de provisionamento do Microsoft Entra em seu aplicativo. Você precisa revisar cuidadosamente a lista de intervalos de IP para endereços calculados. Um endereço como '40.126.25.32' pode 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 seguinte API.

O Microsoft Entra ID também oferece suporte a uma solução baseada em agente para fornecer conectividade a aplicativos em redes privadas (locais, hospedadas no Azure, hospedadas na AWS e assim por diante). Os clientes podem implantar um agente leve, que fornece conectividade ao Microsoft Entra ID sem abrir portas de entrada, em um servidor em sua rede privada. Saiba mais aqui.

Criar um ponto de extremidade SCIM

Agora que você projetou seu esquema e entendeu a implementação do Microsoft Entra SCIM, você pode começar a desenvolver seu endpoint SCIM. Em vez de começar do zero e construir a implementação completamente por conta própria, você pode confiar em muitas bibliotecas SCIM de código aberto publicadas pela comunidade SCIM.

Para obter orientação sobre como criar um ponto de extremidade SCIM, incluindo exemplos, consulte Desenvolver um exemplo de ponto de extremidade SCIM.

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

Nota

O código de referência destina-se a ajudá-lo a começar a construir seu ponto de extremidade SCIM e é fornecido "COMO ESTÁ". Contribuições da comunidade são bem-vindas para ajudar a construir 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. Declara-se a interface Microsoft.SCIM.IProvider, e as solicitações são traduzidas em chamadas para os métodos do provedor, que seriam configurados para operar em um armazenamento de identidade.

O projeto Microsoft.SCIM.WebHostSample é um aplicativo Web ASP.NET Core, baseado no modelo vazio . Ele permite que o código de exemplo seja implantado como autônomo, hospedado em contêineres ou nos Serviços de Informações da Internet. Ele também implementa a interface Microsoft.SCIM.IProvider mantendo classes na memória como um armazenamento 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 SCIM deve ter um endereço HTTP e um certificado de autenticação do servidor cuja autoridade de certificação raiz é um dos seguintes nomes:

• CNNIC
• Comodo
• Confiança Cibernética
• DigiCert
• GeoConfiança
• GlobalSign
• Vá papai
• VeriSign
• WoSign
• DST Raiz CA X3

O SDK do .NET Core inclui um certificado de desenvolvimento HTTPS que é usado durante o desenvolvimento. O certificado é instalado como parte da experiência inicial. Dependendo de como você executa o ASP.NET Core Web Application, ele escuta 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

Lidar com a autenticação de endpoint

As solicitações do serviço de provisionamento Microsoft Entra incluem um token de portador OAuth 2.0. Um servidor de autorização emite o token de portador. 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 longa duração. 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 Token Secreto. Em um ambiente de desenvolvimento, podes usar o token de teste do endpoint /scim/token. Os tokens de teste não devem ser usados em ambientes de produção.

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

  • A aplicação que recebe solicitações deve validar o emissor do token como sendo o Microsoft Entra ID para um tenant esperado do Microsoft Entra.
  • Uma iss declaração 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 o Microsoft Entra ID como o emissor, enquanto o segmento de endereço relativo, aaaabbbb-0000-cccc-1111-dddd2222eeee, é um identificador exclusivo do inquilino do Microsoft Entra para o qual o token foi emitido.
  • O público de um token é o ID da aplicação na galeria. Os aplicativos registrados em um único locatário recebem a mesma iss reivindicação com solicitações SCIM. O ID do aplicativo para todos os aplicativos personalizados é 8adf8e6e-67b2-4cf2-a259-e3dc5476c621. O token gerado pelo ID do Microsoft Entra só deve ser usado para testes. Ele não deve ser usado 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 finais do serviço sejam autenticadas utilizando o token portador emitido pelo Microsoft Entra ID para um inquilino 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 correspondente 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;
}

Tratamento de provisionamento e desprovisionamento de usuários

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

O Microsoft Entra ID consulta o serviço em busca de um utilizador cujo valor do atributo externalId corresponde ao valor do atributo mailNickname de um utilizador no Microsoft Entra ID. A consulta é expressa como uma solicitação HTTP (Hypertext Transfer Protocol), como este exemplo, em que jyoung é um exemplo de um mailNickname de um usuário no Microsoft Entra ID.

Nota

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 neste caso é externalId) é configurável nos mapeamentos de atributos 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. Aqui está 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 determinado valor para o externalId atributo, os valores dos argumentos passados para o método QueryAsync são:

• parâmetros.FiltrosAlternativos.Contar: 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

Se a resposta a uma consulta ao ponto de extremidade SCIM para um usuário com um externalId valor de atributo que corresponda ao valor do atributo mailNickname de um usuário não retornar nenhum usuário, o Microsoft Entra ID solicitará que o serviço forneça um usuário correspondente ao do Microsoft Entra ID. Aqui está 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. Aqui está a assinatura deste 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 de provisionamento de usuário, o valor do argumento resource é uma instância da Microsoft.SCIM.Core2EnterpriseUser classe. Esta classe é definida na Microsoft.SCIM.Schemas biblioteca. Se a solicitação para provisionar o usuário for bem-sucedida, espera-se que a implementação do método retorne uma instância da Microsoft.SCIM.Core2EnterpriseUser classe. O valor da Identifier propriedade é 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. Aqui está a assinatura deste 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 fornecido como o valor do argumento parameters são os seguintes:

• Identificador: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1e1"
• SchemaIdentifier: 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 identidades antes de atualizá-lo. No entanto, só o atributo do gestor é verificado primeiro para os utilizadores. Aqui está um exemplo de uma solicitação para determinar se o atributo manager 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 parameters é o seguinte:

• parâmetros. AlternateFilters.Contagem: 2
• parâmetros.AlternateFilters.ElementAt(x).AttributePath: "ID"
• parâmetros.AlternateFilters.ElementAt(x).ComparisonOperator: ComparisonOperator.Equals
• parâmetros. AlternateFilter.ElementAt(x). Valor de comparação: "a0a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
• parâmetros.AlternateFilters.ElementAt(y).AttributePath: "gerente"
• parâmetros.AlternateFilters.ElementAt(y).ComparisonOperator: ComparisonOperator.Equals
• parâmetros.AlternateFilter.ElementAt(y): Valor de comparação: "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
• parâmetros.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 um endpoint SCIM para atualizar um utilizador

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

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. Aqui está 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 o valor do argumento patch tem estes valores de propriedade:

Argumento	Valor
ResourceIdentifier.Identifier	"a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
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	Gestor
(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-44EE44EE44EE

Exemplo 6. Desprovisionar um usuário

Para desprovisionar um utilizador de um repositório de identidades gerido por um ponto final SCIM, o Microsoft Entra ID envia uma solicitação como:

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. Aqui está 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 o 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-e1e1e1e1e1e1"
• ResourceIdentifier.SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Integre seu ponto de extremidade SCIM com o serviço de provisionamento do Microsoft Entra

O Microsoft Entra ID pode ser configurado 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 em Compreender a implementação do Microsoft Entra SCIM.

Consulte o provedor de aplicativos ou a documentação do provedor de aplicativos para obter declarações de compatibilidade com esses requisitos.

Importante

A implementação do Microsoft Entra SCIM é construída sobre o serviço de provisionamento de usuários do Microsoft Entra, que foi projetado para manter os usuários constantemente sincronizados entre o ID do Microsoft Entra 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 suportam o perfil SCIM descrito neste artigo podem ser conectados ao Microsoft Entra ID usando o recurso "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 é executado a cada 40 minutos. O processo consulta o ponto de extremidade SCIM do aplicativo para usuários e grupos atribuídos e os cria ou modifica de acordo com os detalhes da atribuição.

Para conectar um aplicativo que suporte SCIM:

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

2. Navegue até Aplicativos de identidade>>Aplicativos corporativos.

3. É apresentada uma lista de todas as aplicações configuradas, incluindo as aplicações que foram adicionadas a partir da galeria.

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

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

   A captura de tela a seguir 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 do locatário, insira o URL do ponto de extremidade SCIM da aplicação. Exemplo: https://api.contoso.com/scim/

9. Se o ponto de extremidade SCIM exigir um token de portador OAuth proveniente de um emissor que não seja o Microsoft Entra ID, então copie o token de portador OAuth necessário para o campo opcional Token Secreto. Se este campo for deixado em branco, o Microsoft Entra ID incluirá um token de portador OAuth emitido a partir do Microsoft Entra ID com cada solicitação. Os aplicativos que usam o Microsoft Entra ID como um provedor de identidade podem validar esse token emitido pelo Microsoft Entra ID.

   Nota

   Não é recomendado deixar este campo em branco e confiar em um token gerado pelo Microsoft Entra ID. Esta 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 ponto de extremidade SCIM. Se a tentativa falhar, as informações de erro serão exibidas.

    Nota

    Test Connection consulta o endpoint SCIM por um utilizador que não existe, usando um GUID aleatório como o atributo de correspondência selecionado nas definições do Microsoft Entra. A resposta correta esperada é HTTP 200 OK com uma mensagem SCIM ListResponse vazia.

11. Se a tentativa de conexão com o aplicativo for bem-sucedida, selecione Criar para criar o trabalho de provisionamento.

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

13. Selecione Mapeamento de atributos no painel esquerdo. Há dois conjuntos selecionáveis de mapeamentos de atributos : um para objetos de usuário e outro para objetos de grupo. Selecione cada um deles para revisar os atributos sincronizados da ID do Microsoft Entra 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 desativar a sincronização de objetos de grupo desativando o mapeamento de "grupos".

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

15. Quando a configuração estiver concluída, selecione Visão geral no painel esquerdo.

16. Selecione Propriedades.

17. Selecione o lápis para editar as propriedades. Habilite e-mails de notificação e forneça um e-mail para receber e-mails de quarentena. Ative a opção para evitar eliminação acidental. Clique 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 realizadas 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.

Nota

O ciclo inicial leva mais tempo para ser executado do que as sincronizações posteriores, que ocorrem aproximadamente a cada 40 minutos, enquanto o serviço estiver em execução.

Publique seu aplicativo na galeria de aplicativos do Microsoft Entra

Se você estiver criando um aplicativo 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 configurarem o provisionamento. Publicar seu aplicativo na galeria do Microsoft Entra e disponibilizar o provisionamento para outras pessoas é fácil. Confira os passos aqui. A Microsoft trabalha com você para integrar seu aplicativo à galeria, testar seu endpoint e liberar a documentação de integração para os clientes.

Lista de verificação para integração na galeria

Use a lista de verificação para integrar seu aplicativo rapidamente e os clientes terão uma experiência de implantação suave. As informações são recolhidas de si durante o processo de integração na galeria.

• Suporte a um endpoint de utilizador e grupo SCIM 2.0 (Apenas um é necessário, mas ambos são recomendados)
• Ofereça suporte a pelo menos 25 solicitações por segundo por locatário para garantir que usuários e grupos sejam provisionados e desprovisionados sem demora (Obrigatório)
• Estabeleça contatos de engenharia e suporte para orientar os clientes após a integração da galeria (Obrigatório)
• 3 Credenciais de teste que não expiram para seu aplicativo (Obrigatório)
• Ofereça suporte à concessão de código de autorização OAuth ou a um token de longa duração, conforme descrito no exemplo (Obrigatório)
• Os aplicativos OIDC devem ter pelo menos 1 função (personalizada ou padrão) definida
• Estabelecer um ponto de contato de engenharia e suporte para dar suporte aos clientes após a integração da galeria (Obrigatório)
• Suporte à descoberta de esquema (obrigatório)
• Suporte à atualização de várias associações de grupo com um único PATCH
• Documente o seu endpoint SCIM publicamente

Autorização para provisionamento de conectores na galeria de aplicativos

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

Método de autorização	Prós	Contras	Suporte
Nome de utilizador e palavra-passe (não recomendados ou suportados pelo Microsoft Entra ID)	Fácil de implementar	Inseguro - A sua palavra-passe não tem importância	Não suportado para novas aplicações de galeria ou que não sejam de galeria.
Token ao portador de longa duração	Os tokens de longa duração não exigem a presença de um usuário. Eles são fáceis de usar pelos administradores ao configurar o provisionamento.	Tokens de longa duração podem ser difíceis de compartilhar com um administrador sem usar métodos inseguros, como e-mail.	Compatível com aplicações de galeria e outras.
Concessão do código de autorização OAuth	Os tokens de acesso têm uma vida útil mais curta do que as senhas e possuem um mecanismo de atualização automatizado que os tokens de autenticação 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.	Requer a presença de um usuário. Se o usuário sair da organização, o token será inválido e a autorização precisará ser concluída novamente.	Compatível com aplicações de galeria, mas não com aplicações que não sejam de galeria. No entanto, você pode fornecer um token de acesso na interface do usuário como o token secreto para fins de teste de curto prazo. O suporte para concessão de código OAuth em não-galeria está em nossa lista de pendências, além do suporte para URLs de autenticação / token configuráveis no aplicativo de galeria.
Concessão de credenciais de cliente OAuth	Os tokens de acesso têm uma vida útil mais curta do que as senhas e têm um mecanismo automatizado de atualização que os tokens duradouros não possuem. Tanto a concessão do código de autorização quanto a concessão de credenciais do cliente criam o mesmo tipo de token de acesso, portanto, a movimentação entre esses métodos é transparente para a API. O provisionamento pode ser automatizado e novos tokens podem ser solicitados silenciosamente sem interação do usuário.		Compatível com aplicações de galeria, mas não com aplicações que não sejam de galeria. No entanto, você pode fornecer um token de acesso na interface do usuário como o token secreto para fins de teste de curto prazo. O suporte para a concessão de credenciais de cliente OAuth em ambientes fora de galeria está na nossa lista de pendências.

Nota

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 suporta a concessão do 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 fornecida pelo cliente para obter autorização do proprietário do recurso por meio do redirecionamento do navegador. O usuário é redirecionado para este URL para autorizar o acesso.

• URL de troca de token, 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 de cliente.

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

Nota

No momento, a URL de autorização e a URL de troca de token não são configuráveis por locatário.

Nota

OAuth v1 não é suportado devido à exposição do segredo do cliente. OAuth v2 é suportado.

Ao usar o fluxo de concessão de código OAuth, é necessário que você ofereça suporte a um modelo em que cada cliente enviará sua própria ID de cliente e segredo do cliente ao configurar uma instância de provisionamento. Não é suportado um par único de ID de Cliente/Segredo de Cliente para toda a aplicação.

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é Identity>Aplicações>Aplicações 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é Aplicativos de identidade>>Aplicativos corporativos.

5. Selecione seu aplicativo e vá para Provisionamento.

6. Selecionar Autorizar.

   1. Os utilizadores são redirecionados para o URL de Autorização (página de início de sessão para a aplicação de terceiros).

   2. Admin fornece 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 responde com o token de acesso, token de atualização e data de expiração

7. Quando o ciclo de provisionamento começa, o serviço verifica se o token de acesso atual é válido e o troca por um novo token, se necessário. O token de acesso é fornecido em cada solicitação feita ao aplicativo e a validade da solicitação é verificada antes de cada solicitação.

Nota

Embora não seja possível configurar o OAuth nos aplicativos que não são da galeria, você pode gerar manualmente um token de acesso do seu servidor de autorização e inseri-lo como o token secreto para um aplicativo que não seja da galeria. Isso permite que você verifique a compatibilidade do seu servidor SCIM com o serviço de provisionamento do Microsoft Entra antes de integrar à galeria de aplicativos, que suporta a concessão de código OAuth.

Tokens de portador OAuth de longa duração: se seu aplicativo não suportar o fluxo de concessão de código de autorização OAuth, 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, caso contrário, o trabalho de provisionamento será colocado em quarentena quando o token expirar.

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

Lista de verificação para lançamento no mercado da galeria

Para ajudar a aumentar a conscientização e a demanda de nossa integração conjunta, recomendamos que você atualize sua documentação existente e amplie a integração em seus canais de marketing. Recomendamos que preencha a seguinte lista de verificação para apoiar o lançamento:

• Certifique-se de que suas equipes de vendas e suporte ao cliente estejam cientes, prontas e possam falar com os recursos de integração. Informe as suas equipas, forneça-lhes FAQs e inclua a integração nos seus materiais de vendas.
• Crie uma postagem de blog ou comunicado de imprensa que descreva a integração conjunta, os benefícios e como começar. Exemplo: Imprivata e Microsoft Entra Press Release
• Aproveite suas mídias sociais como X, Facebook ou LinkedIn para promover a integração com seus clientes. Certifique-se de incluir @Microsoft o Entra ID para que possamos retweetar sua postagem. Exemplo: Imprivata X Post
• Crie ou atualize suas páginas/site de marketing (como página de integração, página de parceiro, página de preços e assim por diante) para incluir a disponibilidade da integração conjunta. Exemplo: página de integração do Pingboard, página de integração do Smartsheet, página de preços do Monday.com
• Crie um artigo da Central de Ajuda ou documentação técnica sobre como os clientes podem começar. Exemplo: integração Envoy + Microsoft Entra.
• Alerte os clientes sobre a nova integração através da sua comunicação com o cliente (boletins informativos mensais, campanhas de e-mail, notas de lançamento de produtos).

Próximos passos

Desenvolver um exemplo de ponto de extremidade SCIMAutomatizar o provisionamento e o desprovisionamento de utilizadores para aplicações SaaSPersonalizar mapeamentos de atributos para o provisionamento de utilizadoresEscrever expressões para mapeamentos de atributosFiltros de escopo para provisionamento de utilizadoresNotificações de provisionamento de contasLista de tutoriais sobre como integrar aplicações SaaS