Tutorial: Desenvolver e planear o provisionamento de um ponto final scim no Azure Ative Directory

Como desenvolvedor de aplicações, pode utilizar a API de gestão de identidade de controlo de identidade de domínio cruzado (SCIM) para permitir o fornecimento automático de utilizadores e grupos entre a sua aplicação e o Diretório Ativo Azure (Azure AD). Este artigo descreve como construir um ponto final SCIM e integrar-se com o serviço de fornecimento Azure AD. A especificação SCIM fornece um esquema comum de utilização para o provisionamento. Quando usado com padrões de federação como SAML ou OpenID Connect, o SCIM dá aos administradores uma solução baseada em padrões para a gestão de acessos.

Provisionamento de Azure AD para uma app com SCIM

SCIM 2.0 é uma definição padronizada de dois pontos finais: um /Users ponto final e um /Groups ponto final. Utiliza pontos finais comuns da API REST para criar, atualizar e eliminar objetos. O SCIM consiste num esquema pré-definido para atributos comuns como nome de grupo, nome de utilizador, nome de primeiro nome, apelido e e-mail.

As aplicações que oferecem uma API SCIM 2.0 REST podem reduzir ou eliminar a dor de trabalhar com uma API de gestão de utilizadores proprietário. Por exemplo, qualquer cliente SCIM em conformidade sabe como fazer um HTTP POST de um objeto JSON para o /Users ponto final para criar uma nova entrada no utilizador. Em vez de precisar de uma API ligeiramente diferente para as mesmas ações básicas, as aplicações que estão em conformidade com a norma SCIM podem instantaneamente tirar partido de clientes, ferramentas e código pré-existentes.

O esquema padrão de objetos de utilizador e apIs de repouso para gestão definido em SCIM 2.0 (RFC 7642, 7643, 7644) permitem que os fornecedores de identidade e aplicações se integrem mais facilmente entre si. Os desenvolvedores de aplicações que construam um ponto final SCIM podem integrar-se com qualquer cliente compatível com SCIM sem ter que fazer trabalho personalizado.

Para automatizar o fornecimento a uma aplicação, é necessário construir e integrar um ponto final SCIM que seja o acesso pelo Serviço de Prestação de Azure AD. Utilize os seguintes passos para começar a agru estar a agrum utilizadores e grupos na sua aplicação.

  1. Desenhe o seu esquema de utilizador e grupo - Identifique os objetos e atributos da aplicação para determinar como mapeiam para o utilizador e esquema de grupo suportado pela implementação do SCIM Azure AD.

  2. Compreenda a Azure AD implementação do SCIM - Compreenda como é implementado o Serviço de Fornecimento de Azure AD para modelar o seu protocolo SCIM de tratamento e respostas.

  3. Construir um ponto final SCIM - Um ponto final deve ser compatível com SCIM 2.0 para integrar-se com o serviço de prestação de Azure AD. Como opção, utilize bibliotecas e amostras de código da Microsoft Common Language Infrastructure (CLI) para construir o seu ponto final. Estas amostras destinam-se apenas a referência e a testes; recomendamos contra a sua utilização como dependências na sua app de produção.

  4. Integre o seu ponto final SCIM com o Serviço de Fornecimento de Azure AD. Se a sua organização utilizar uma aplicação de terceiros para implementar um perfil de SCIM 2.0 que Azure AD suporta, pode automatizar rapidamente tanto o fornecimento como o desprovisionamento de utilizadores e grupos.

  5. [Opcional] Publique a sua aplicação na galeria de aplicações Azure AD - Facilite aos clientes a descoberta da sua aplicação e a configuração fácil do provisionamento.

Diagrama que mostra os passos necessários para a integração de um ponto final SCIM com Azure AD.

Desenhe o seu utilizador e esquema de grupo

Cada aplicação requer diferentes atributos para criar um utilizador ou grupo. Inicie a sua integração identificando os objetos necessários (utilizadores, grupos) e atributos (nome, gestor, título de emprego, etc.) que a sua aplicação necessita.

A norma SCIM define um esquema para gerir utilizadores e grupos.

O esquema do utilizador central só requer três atributos (todos os outros atributos são opcionais):

  • id, fornecedor de serviços identificador definido
  • userName, um identificador único para o utilizador (geralmente mapeia para o Azure AD nome principal do utilizador)
  • meta, metadados apenas de leitura mantidos pelo prestador de serviços

Além do esquema principal do utilizador, a norma SCIM define uma extensão do utilizador da empresa com um modelo para alargar o esquema do utilizador para satisfazer as necessidades da sua aplicação.

Por exemplo, se a sua aplicação necessitar tanto do e-mail de um utilizador como do gestor do utilizador, utilize o esquema principal para recolher o e-mail do utilizador e o esquema do utilizador da empresa para recolher o gestor do utilizador.

Para desenhar o seu esquema, siga estes passos:

  1. Enuma os atributos que a sua aplicação requer e, em seguida, categorize como atributos necessários para a autenticação (por exemplo, loginName e e-mail). São necessários atributos para gerir o ciclo de vida do utilizador (por exemplo, estado/ativo) e todos os outros atributos necessários para que a aplicação funcione (por exemplo, gestor, tag).

  2. Verifique se os atributos já estão definidos no esquema principal do utilizador ou no esquema do utilizador da empresa . Caso contrário, deve definir uma extensão do esquema do utilizador que cubra os atributos em falta. Veja o exemplo abaixo para uma extensão ao utilizador para permitir o provisionamento de um utilizador tag.

  3. O Map SCIM atribui aos atributos do utilizador em Azure AD. Se um dos atributos definidos no seu ponto final SCIM não tiver uma contrapartida clara no esquema de utilizador Azure AD, guie o administrador do inquilino para estender o seu esquema, ou use um atributo de extensão como mostrado abaixo para a tags propriedade.

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

Atributo de aplicação exigido Atributo SCIM mapeado Atributo de Azure AD mapeado
nome de login userName userPrincipalName
nomePróprio name.givenName nomeDado
apelido name.familyName surName
workMail e-mails[tipo eq "work"].value Correio
gestor gestor gestor
etiqueta urn:ietf:params:scim:schemas:extensão:CustomExtensionName:2.0:User:tag extensãoAttribute1
status active isSoftDeleted (valor calculado não armazenado no utilizador)

A carga útil JSON que se segue mostra um esquema SCIM 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/2819c223-7f76-453a-919d-413861904646"
   }
}   

Nota

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

Ajuda a categorizar entre /User e a mapear quaisquer atributos padrão do utilizador em Azure AD ao SCIM RFC, ver como os atributos personalizados são mapeados entre Azure AD e o seu ponto final SCIM/Group.

A tabela a seguir enumera um exemplo de atributos do utilizador:

Utilizador do Azure Active Directory urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
IsSoftDeleted active
departamento urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department
displayName displayName
employeeId urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber
Facsimile-TelephoneNumber números de telefone[tipo eq "fax"].valor
nomeDado name.givenName
jobTitle título
correio emails[type eq "work"].value
mailSemame externalId
gestor urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager
dispositivo móvel phoneNumbers[type eq "mobile"].value
postalCode endereços[tipo eq "work"].postalCode
endereços de procuração e-mails[tipo eq "outros"]. Valor
nome físico-entrega endereços[tipo eq "outros"]. Formatado
streetAddress endereços[tipo eq "work"].streetAddress
surname name.familyName
número de telefone phoneNumbers[type eq "work"].value
nome principal do utilizador userName

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

Azure AD grupo urn:ietf:params:scim:schemas:core:2.0:Grupo
displayName displayName
membros membros
objectId externalId

Nota

Não é obrigado a suportar tanto os utilizadores como os grupos, ou todos os atributos mostrados aqui, é apenas uma referência sobre como os atributos em Azure AD são frequentemente mapeados para propriedades no protocolo SCIM.

Existem vários pontos finais definidos no SCIM RFC. Pode começar com o /User ponto final e depois expandir a partir daí. A tabela que se segue lista alguns dos pontos finais do SCIM:

Ponto final Descrição
/Utilizador Execute operações CRUD num objeto do utilizador.
/Grupo Execute operações CRUD num objeto de grupo.
/Schemas O conjunto de atributos suportados por cada cliente e prestador de serviços pode variar. Um prestador de serviços pode incluir name, titlee emails, enquanto outro prestador de serviços usa name, titlee phoneNumbers. O ponto final dos esquemas permite a descoberta dos atributos suportados.
/Granel As operações a granel permitem realizar operações numa grande coleção de objetos de recursos numa única operação (por exemplo, atualizar as adesões para um grande grupo).
/ServiceProviderConfig Fornece detalhes sobre as características da norma SCIM que são suportadas, por exemplo, os recursos que são suportados e o método de autenticação.
/RecursosTypes Especifica metadados sobre cada recurso.

Nota

Utilize o /Schemas ponto final para suportar atributos personalizados ou se o seu esquema mudar frequentemente, pois permite que um cliente recupere automaticamente o esquema mais atualizado. Utilize o /Bulk ponto final para apoiar grupos.

Compreender a implementação Azure AD SCIM

Para suportar uma API de gestão de utilizadores SCIM 2.0, esta secção descreve como o Serviço de Fornecimento de Azure AD é implementado e mostra como modelar o seu protocolo SCIM solicita tratamento e respostas.

Importante

O comportamento da implementação do SCIM Azure AD foi atualizado pela última vez em 18 de dezembro de 2018. Para obter informações sobre o que mudou, consulte o protocolo SCIM 2.0 da Azure AD serviço de Fornecimento de Utilizadores.

Dentro da especificação do protocolo SCIM 2.0, a sua aplicação deve apoiar estes requisitos:

Requisito Notas de referência (protocolo SCIM)
Criar utilizadores, e opcionalmente também grupos Secção 3.3
Modificar utilizadores ou grupos com pedidos PATCH Secção 3.5.2. O apoio garante que os grupos e utilizadores são a provisionados de forma performante.
Recupere um recurso conhecido para um utilizador ou grupo criado anteriormente Secção 3.4.1
Utilizadores ou grupos de consultas Secção 3.4.2. Por padrão, os utilizadores são recuperados pelos seus id e, e externalIdos grupos são questionados por displayNameusername .
O filtro excluídoAttributes=membros ao consultar o recurso de grupo Secção 3.4.2.2
Apoiar utilizadores com listagem e paginating Secção 3.4.2.4.
Eliminar suavemente um utilizador active=false e restaurar o utilizador active=true O objeto do utilizador deve ser devolvido num pedido se o utilizador está ou não ativo. A única altura em que o utilizador não deve ser devolvido é quando é duramente eliminado da aplicação.
Apoiar o ponto final /Schemas Secção 7 O ponto final da descoberta do esquema será usado para descobrir mais atributos.
Aceite um único sinal de portador para autenticação e autorização de Azure AD à sua aplicação.

Utilize as diretrizes gerais ao implementar um ponto final SCIM para garantir a compatibilidade com Azure AD:

Geral:

  • id é uma propriedade necessária para todos os recursos. Cada resposta que devolve um recurso deve garantir que cada recurso tem esta propriedade, exceto ListResponse com zero elementos.
  • Os valores enviados devem ser armazenados no mesmo formato que os enviados. Os valores inválidos devem ser rejeitados com uma mensagem de erro descritiva e exequível. As transformações de dados não devem ocorrer entre os dados enviados por Azure AD e os dados armazenados na aplicação SCIM. (por exemplo. Um número de telefone enviado como 55555555555 não deve ser guardado/devolvido 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 elementos estruturais no SCIM, em particular os valores de funcionamento patchop, tal como definidos na secção 3.5.2. Azure AD emite os valores de op como Adicionar, Substituir e Remover.
  • Microsoft Azure AD faz pedidos para ir buscar um utilizador e um grupo aleatórios para garantir que o ponto final e as credenciais são válidos. Também é feito como parte do fluxo de ligação de teste no portal do Azure.
  • Suporte HTTPS no seu ponto final SCIM.
  • Os atributos complexos e multivalorizados personalizados são suportados, mas Azure AD não tem muitas estruturas de dados complexas para extrair dados nestes casos. Os atributos complexos simples de tipo emparelhado/valor podem ser mapeados facilmente, mas os dados fluídos para atributos complexos com três ou mais subtributos não são bem suportados neste momento.
  • Os valores de subtribução "tipo" de atributos complexos multivalorizados devem ser únicos. Por exemplo, não pode haver dois endereços de e-mail diferentes com o subtipo "work".
  • O cabeçalho para todas as respostas deve ser de tipo de conteúdo: aplicação/scim+json

Recuperação de Recursos:

  • A resposta a um pedido de consulta/filtro deve ser sempre um ListResponse.
  • Microsoft Azure AD utiliza apenas os seguintes operadores: eqand
  • O atributo em que os recursos podem ser consultados deve ser definido como um atributo correspondente na aplicação no portal do Azure, ver Personaling User Provisioning Attribute Mappings.

/Utilizadores:

  • O atributo de direitos não é suportado.
  • Quaisquer atributos considerados para a singularidade do utilizador devem ser utilizáveis como parte de uma consulta filtrada. (por exemplo, se a singularidade do utilizador for avaliada tanto para o nome do utilizador como para e-mails[tipo eq "work"], um GET para /Utilizadores com filtro deve permitir tanto para o utilizadorName eq euser@contoso.come-mails[tipo eq "work"].valor eq "user@contoso.com" consultas.

/Grupos:

  • Os grupos são opcionais, mas só são apoiados se a implementação do SCIM apoiar os pedidos do PATCH .
  • Os grupos devem ter singularidade no valor 'displayName' para combinar com Azure AD e a aplicação SCIM. A singularidade não é um requisito do protocolo SCIM, mas é um requisito para integrar um ponto final scim com Azure AD.

/Schemas (descoberta de Schema):

  • Pedido/resposta de amostra
  • A descoberta de Schema não é suportada atualmente na aplicação personalizada não-galeria SCIM, mas está a ser usada em certas aplicações de galeria. Em frente, a descoberta de esquemas será usada como o único método para adicionar mais atributos ao esquema de uma aplicação SCIM de galeria existente.
  • Se um valor não estiver presente, não envie valores nulos.
  • Os valores da propriedade devem ser arquivados de camelo (por exemplo, lerDes).
  • Deve devolver uma resposta da lista.
  • O pedido /esquemas será feito pelo Serviço de Fornecimento de Azure AD sempre que alguém guardar a configuração de provisionamento no portal do Azure ou sempre que um utilizador pousar na página de fornecimento de edição no portal do Azure. Outros atributos descobertos serão encontrados para os clientes nos mapeamentos de atributos na lista de atributos-alvo. A descoberta de Schema só leva a que mais atributos-alvo sejam adicionados. Não resultará na remoção de atributos.

Fornecimento e desprovisionamento dos utilizadores

O diagrama seguinte mostra as mensagens que Azure AD envia para um ponto final do SCIM para gerir o ciclo de vida de um utilizador na loja de identidade da sua aplicação.

Diagrama que mostra a sequência de desprovisionamento do utilizador.

Provisão e desprovisionamento em grupo

O provisionamento e a desprovisionamento em grupo são opcionais. Quando implementada e ativada, a seguinte ilustração mostra as mensagens que Azure AD envia para um ponto final DO SCIM para gerir o ciclo de vida de um grupo na loja de identidade da sua aplicação. Estas mensagens diferem das mensagens sobre os utilizadores de duas formas:

  • Os pedidos de recuperação de grupos especificam que os membros atribuídos devem ser excluídos de qualquer recurso fornecido em resposta ao pedido.
  • Os pedidos para determinar se um atributo de referência tem um determinado valor são pedidos sobre os membros atribuídos.

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

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

Pedidos e respostas do protocolo SCIM

Este artigo dá o exemplo dos pedidos do SCIM emitidos pelo Azure Ative Directory (Azure AD) Serviço de Provisionamento e respostas esperadas. Para obter os melhores resultados, deverá codificar a sua app para lidar com estes pedidos neste formato e emitir as respostas esperadas.

Importante

Para entender como e quando o serviço de prestação de serviços de prestação de Azure AD utilizador emite as operações descritas abaixo, consulte a secção Ciclos de Provisionamento: Inicial e incremental em Como funciona o provisionamento.

Operações de Utilizador

Operações de Grupo

Descoberta de Schema

Operações de Utilizador

  • Os utilizadores podem ser consultados por userName ou emails[type eq "work"] atributos.

Criar Utilizador

Pedir

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_ab6490ee-1e48-479e-a20b-2d77186b5dd1",
    "active": true,
    "emails": [{
        "primary": true,
        "type": "work",
        "value": "Test_User_fd0ea19b-0777-472c-9f96-4f70d2226f2e@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_ab6490ee-1e48-479e-a20b-2d77186b5dd1",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_fd0ea19b-0777-472c-9f96-4f70d2226f2e@testuser.com",
        "type": "work",
        "primary": true
    }]
}

Obter Utilizador

Pedir

GET /Utilizadores/5d48a0a8e9f04aaa38008

Resposta (Utilizador 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_feed3ace-693c-4e5a-82e2-694be1b39934",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_22370c1a-9012-42b2-bf64-86099c2a1c22@testuser.com",
        "type": "work",
        "primary": true
    }]
}
Pedir

GET /Utilizadores/5171a35d82074e068ce2

Resposta (Utilizador não encontrado. O detalhe não é necessário, apenas o estado.)
{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "status": "404",
    "detail": "Resource 23B51B0E5D7AE9110A49411D@7cca31655d49f3640a494224 not found"
}

Obter Utilizador por consulta

Pedir

GET /Utilizadores?filter=userName eq "Test_User_dfeef4c5-5681-4387-b016-bdf221e82081"

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_dfeef4c5-5681-4387-b016-bdf221e82081",
        "name": {
            "familyName": "familyName",
            "givenName": "givenName"
        },
        "active": true,
        "emails": [{
            "value": "Test_User_91b67701-697b-46de-b864-bd0bbe4f99c1@testuser.com",
            "type": "work",
            "primary": true
        }]
    }],
    "startIndex": 1,
    "itemsPerPage": 20
}

Obtenha o Utilizador por consulta - Resultados zero

Pedir

GET /Utilizadores?filter=userName eq "utilizador 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 o Utilizador [propriedades multi-valorizadas]

Pedir

PATCH /Utilizadores/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_fbb9dda4-fcde-4f98-a68b-6c5599e17c27",
    "name": {
        "formatted": "givenName updatedFamilyName",
        "familyName": "updatedFamilyName",
        "givenName": "givenName"
    },
    "active": true,
    "emails": [{
        "value": "updatedEmail@microsoft.com",
        "type": "work",
        "primary": true
    }]
}

Atualizar o Utilizador [propriedades de valor único]

Pedir

PATCH /Utilizadores/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_49dc1090-aada-4657-8434-4995c25a00f7@testuser.com",
        "type": "work",
        "primary": true
    }]
}

Desativar Utilizador

Pedir

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

Pedir

DELETE /Utilizadores/5171a35d82074e068ce2 HTTP/1.1

Resposta

HTTP/1.1 204 Sem Conteúdo

Operações de Grupo

  • Os grupos devem ser sempre criados com uma lista de membros vazios.
  • Os grupos podem ser questionados pelo displayName atributo.
  • A atualização ao pedido patch do grupo deve produzir 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 a devolução de todos os membros do grupo.

Criar Grupo

Pedir

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

Pedir

GET /Groups/40734ae655284ad3abcc?excluídosAttributes=membros 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",
}

Obtenha grupo por displayName

Pedir

GET /Groups?excluiuAttributes=membros&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
}

Grupo de Atualização [Atributos não membros]

Pedir

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

Grupo de Atualização [Adicionar Membros]

Pedir

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

Grupo de atualização [Remover Membros]

Pedir

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

Eliminar Grupo

Pedir

DELETE /Groups/cdb1ce18f65944079d37 HTTP/1.1

Resposta

HTTP/1.1 204 Sem Conteúdo

Descoberta de Schema

Descubra o esquema

Pedir

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

As únicas versões aceitáveis do protocolo TLS são tLS 1.2 e TLS 1.3. Não são permitidas outras versões de TLS. Não é permitida nenhuma versão do SSL.

  • As chaves RSA devem ser de pelo menos 2.048 bits.
  • As chaves ECC devem ser de pelo menos 256 bits, geradas com uma curva elíptica aprovada

Comprimentos-chave

Todos os serviços devem utilizar certificados X.509 gerados com teclas criptográficas de comprimento suficiente, o que significa:

Suítes Cipher

Todos os serviços devem ser configurados para utilizar as seguintes suítes cifra, na ordem exata especificada abaixo. Se tiver apenas um certificado RSA, as suítes de cifra ECDSA não têm qualquer efeito.

Barra mínima 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

Gamas IP

O serviço de prestação de Azure AD opera atualmente ao abrigo dos Intervalos IP para AzureActiveDirectory, conforme listado aqui. Pode adicionar as gamas IP listadas na tag AzureActiveDirectory para permitir o tráfego do serviço de fornecimento de Azure AD na sua aplicação. Terá de rever cuidadosamente a lista de gamas IP para endereços computados. Um endereço como '40.126.25.32' poderia estar representado na lista de intervalos de IP como '40.126.0.0/18'. Também pode recuperar programáticamente a lista de gama IP utilizando a seguinte API.

Azure AD também apoia uma solução baseada em agentes para fornecer conectividade a aplicações em redes privadas (no local, hospedadas em Azure, hospedadas em AWS, etc.). Os clientes podem implementar um agente leve, que fornece conectividade para Azure AD sem abrir portas de entrada, num servidor da sua rede privada. Sabia mais aqui.

Construir um ponto final SCIM

Agora que concebeu o seu esquema e compreendeu a implementação do SCIM Azure AD, pode começar a desenvolver o seu ponto final SCIM. Em vez de começar do zero e construir a implementação completamente por conta própria, pode contar com muitas open source bibliotecas SCIM publicadas pela comunidade SCIM.

Para obter orientações sobre como construir um ponto final SCIM, incluindo exemplos, consulte Desenvolver uma amostra do ponto final SCIM.

O open source exemplo de código de referência .NET Core publicado pela equipa de provisionamento Azure AD é um desses recursos que podem saltar para iniciar o seu desenvolvimento. Uma vez construído o seu ponto final SCIM, vai querer testá-lo. Pode utilizar a recolha de testes do Carteiro fornecidos como parte do código de referência ou passar pelos pedidos/respostas da amostra fornecidos acima.

Nota

O código de referência destina-se a ajudá-lo a começar a construir o seu ponto final SCIM e é fornecido "AS IS". As 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 a interface Microsoft.SCIM.IProvider, os pedidos são traduzidos em chamadas para os métodos do fornecedor, que seriam programados para operar numa loja de identidade.

Repartição: Um pedido traduzido em chamadas para os métodos do fornecedor

O projeto Microsoft.SCIM.WebHostSample é um ASP.NET Core Aplicação Web, baseado no modelo Empty. Permite que o código de amostra seja implantado como autónomo, alojado em contentores ou dentro dos Serviços de Informação da Internet. Também implementa a interface Microsoft.SCIM.IProvider mantendo as aulas na memória como uma loja de identidade de amostra.

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();
    }
    ...

Construção de um ponto final personalizado do SCIM

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

  • CNNIC
  • Comodo
  • CyberTrust
  • DigiCert
  • GeoTrust
  • GlobalSign
  • Vai papai
  • VeriSign
  • Rio WoSign
  • Raiz DST CA X3

O .NET Core SDK inclui um certificado de desenvolvimento HTTPS que pode ser utilizado durante o desenvolvimento, o certificado é instalado como parte da experiência de primeira execução. Dependendo da forma como executar a aplicação web ASP.NET Core, ouvirá uma porta diferente:

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

Para obter mais informações sobre HTTPS em ASP.NET Core utilize o seguinte link: Impor HTTPS em ASP.NET Core

Tratamento da autenticação do ponto final

Os pedidos do Serviço de Provisionamento Azure AD incluem um token portador de OAuth 2.0. O token do portador é um símbolo de segurança emitido por um servidor de autorização, como Azure AD e é confiável pela sua aplicação. Pode configurar o serviço de provisões Azure AD para utilizar uma das seguintes fichas:

  • Um símbolo de portador de longa data. Se o ponto final do SCIM necessitar de um token portador de OAuth de um emitente que não Azure AD, em seguida, copie o símbolo do portador de OAuth necessário no campo token secreto opcional. Num ambiente de desenvolvimento, pode utilizar o token de teste a /scim/token partir do ponto final. Os tokens de teste não devem ser usados em ambientes de produção.

  • Azure AD símbolo do portador. Se o campo Secret Token for deixado em branco, Azure AD inclui um token portador de OAuth emitido a partir de Azure AD a cada pedido. As aplicações que usam Azure AD como fornecedor de identidade podem validar este token emitido pelo Azure AD.

    • O pedido que recebe pedidos deve validar o emitente simbólico como sendo Azure AD para um inquilino Azure AD esperado.
    • No token, o emitente é identificado por uma reclamação iss . Por exemplo, "iss":"https://sts.windows.net/12345678-0000-0000-0000-000000000000/". Neste exemplo, o endereço base do valor da reclamação, https://sts.windows.net identifica Azure AD como o emitente, enquanto o segmento de endereço relativo, 12345678-0000-0000-0000-00000000000000000, é um identificador único do Azure AD inquilino para o qual o token foi emitido.
    • O público para um token é o ID de aplicação para a aplicação na galeria. Os pedidos registados num único inquilino recebem a mesma iss reclamação com pedidos de SCIM. O ID da aplicação para todas as aplicações personalizadas é 8adf8e6e-67b2-4cf2-a259-e3dc5476c621. O token gerado pelo serviço de prestação de Azure AD só deve ser utilizado para testes. Não deve ser usado em ambientes de produção.

No código de amostra, os pedidos são autenticados utilizando o pacote Microsoft.AspNetCore.Authentication.JwtBearer. O seguinte código aplica que os pedidos a qualquer um dos pontos finais do serviço são autenticados usando o token ao portador emitido por Azure AD 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/12345678-0000-0000-0000-000000000000/";
                options.Audience = "8adf8e6e-67b2-4cf2-a259-e3dc5476c621";
                ...
            });
    }
    ...
}

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

Um sinal de portador também é necessário para usar os testes do Carteiro fornecido e realizar depuragem local usando local local. O código de amostra utiliza ambientes ASP.NET Core para alterar as opções de autenticação durante a fase de desenvolvimento e permitir a utilização de um token auto-assinado.

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

O seguinte código aplica que os pedidos a qualquer um dos pontos finais do serviço são autenticados usando um token ao 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 um pedido GET ao controlador Token para obter um token ao portador válido, o método GenerateJSONWebToken é responsável por criar um símbolo correspondente aos parâmetros configurados para o 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 do fornecimento e desprovisionamento dos utilizadores

Exemplo 1. Consultar o serviço para um utilizador que corresponde

Azure AD consulta o serviço para um utilizador com um externalId valor de atributo correspondente ao valor de atributo mailSname de um utilizador em Azure AD. A consulta é expressa como um pedido de Hipertext Transfer Protocol (HTTP) como este exemplo, em que jyoung é uma amostra de um nome de correioNickname de um utilizador em Azure AD.

Nota

Este é apenas um exemplo. Nem todos os utilizadores terão um atributo de correioSse, e o valor que um utilizador tem pode não ser único no diretório. Além disso, o atributo utilizado para a correspondência (que neste caso éexternalId) é configurável nos mapeamentos de atributos Azure AD.

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

No código de amostra, o pedido é traduzido numa chamada para o método QueryAsync do prestador 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.  
// Microsoft.SCIM.IQueryParameters is defined in 
// Microsoft.SCIM.Protocol.  

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

Na consulta da amostra, para um utilizador com um dado valor para o externalId atributo, os valores dos argumentos transmitidos ao método QueryAsync são:

  • parâmetros. Filtros Alternativos.Contagem: 1
  • parâmetros. AlternateFiltros.ElementAt(0). AtributoPath: "externalId"
  • parâmetros. AlternateFiltros.ElementAt(0). ComparaçãoOperador: CompareOperador.Equals
  • parâmetros. AlternateFilter.ElementAt(0). ComparaçãoValue: "jyoung"

Exemplo 2. Provisionamento de um utilizador

Se a resposta a uma consulta ao ponto final do SCIM para um utilizador com um externalId valor de atributo que corresponda ao valor de atributo mailSname de um utilizador não devolver nenhum utilizador, então Azure AD solicita que a prestação de serviço de um utilizador correspondente ao Azure AD. Aqui está um exemplo de tal pedido:

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 amostra, o pedido é traduzido numa chamada para o método CreateAsync do prestador 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);

Num pedido a um utilizador de provisionamento, o valor do argumento de recurso é uma instância da classe Microsoft.SCIM.Core2EnterpriseUser, definida na biblioteca Microsoft.SCIM.Schemas. Se o pedido de provisionamento do utilizador for bem sucedido, espera-se que a implementação do método devolva uma instância da classe Microsoft.SCIM.Core2EnterpriseUser, com o valor da propriedade Identifier definida para o identificador único do utilizador recém-atado.

Exemplo 3. Consulta do estado atual de um utilizador

Para atualizar um utilizador conhecido por existir numa loja de identidade frontalizada por um SCIM, Azure AD receitas solicitando ao serviço o estado atual desse utilizador com um pedido como:

GET ~/scim/Users/54D382A4-2050-4C03-94D1-E769F1D15682 HTTP/1.1
Authorization: Bearer ...

No código de amostra, o pedido é traduzido numa chamada para o método RetrieveAsync do prestador 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 um pedido de recuperação do estado atual de um utilizador, os valores das propriedades do objeto fornecidos como o valor do argumento dos parâmetros são os seguintes:

  • Identificador: "54D382A4-2050-4C03-94D1-E769F1D15682"
  • Schemaidentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Exemplo 4. Consulta do valor de um atributo de referência a atualizar

Se um atributo de referência for atualizado, então Azure AD consulta o serviço para determinar se o valor atual do atributo de referência na loja de identidade frontalmente pelo serviço já corresponde ao valor desse atributo em Azure AD. Para os utilizadores, o único atributo do qual o valor atual é consultado desta forma é o atributo do gestor. Aqui está um exemplo de um pedido para determinar se o atributo do gestor de um objeto de utilizador tem atualmente um determinado valor: No código de amostra, o pedido é traduzido numa chamada para o método QueryAsync do prestador do serviço. O valor das propriedades do objeto fornecido como o valor do argumento dos parâmetros são os seguintes:

  • parâmetros. Filtros Alternativos.Contagem: 2
  • parâmetros. AlternateFiltros.ElementAt(x). AtributoPath: "ID"
  • parâmetros. AlternateFiltros.ElementAt(x). ComparaçãoOperador: CompareOperador.Equals
  • parâmetros. AlternateFilter.ElementAt(x). ComparaçãoValue: "54D382A4-2050-4C03-94D1-E769F1D15682"
  • parâmetros. AlternateFiltros.ElementAt(y). AtributoPata: "manager"
  • parâmetros. AlternateFiltros.ElementAt(y). ComparaçãoOperador: CompareOperador.Equals
  • parâmetros. AlternateFilter.ElementAt(y). ComparaçãoValue: "2819c223-7f76-453a-919d-413861904646"
  • parâmetros. SolicitadoAttributePaths.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 do filtro.

Exemplo 5. Pedido de Azure AD a um ponto final do SCIM para atualizar um utilizador

Aqui está um exemplo de um pedido de Azure AD para um ponto final do SCIM para atualizar um utilizador:

PATCH ~/scim/Users/54D382A4-2050-4C03-94D1-E769F1D15682 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/2819c223-7f76-453a-919d-413861904646",
              "value":"2819c223-7f76-453a-919d-413861904646"}]}]}

No código de amostra, o pedido é traduzido numa chamada para o método UpdateAsync do prestador do serviço. Aqui está a assinatura deste 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 um pedido de atualização de um utilizador, o objeto fornecido como o valor do argumento do patch tem estes valores de propriedade:

Argumento Valor
ResourceIdentifier.Identifier "54D382A4-2050-4C03-94D1-E769F1D15682"
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/2819c223-7f76-453a-919d-413861904646
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Value 2819c223-7f76-453a-919d-4138619046

Exemplo 6. Desprovisionamento de um utilizador

Para desprovisionar um utilizador de uma loja de identidade frontalizada por um ponto final do SCIM, Azure AD envia um pedido como:

DELETE ~/scim/Users/54D382A4-2050-4C03-94D1-E769F1D15682 HTTP/1.1
Authorization: Bearer ...

No código de amostra, o pedido é traduzido numa chamada para o método DeleteAsync do prestador 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.IResourceIdentifier, 
// is defined in Microsoft.SCIM.Protocol. 

Task DeleteAsync(IRequest<IResourceIdentifier> request);

O objeto fornecido como o valor do argumento do gestor de recursos tem estes valores de propriedade no exemplo de um pedido de desprovisionamento de um utilizador:

  • ResourceIdentifier.Identifier: "54D382A4-2050-4C03-94D1-E769F1D15682"
  • ResourceIdentifier.Schemaidentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Integre o seu ponto final SCIM com o Serviço de Provisionamento Azure AD

Azure AD pode ser configurado para fornecer automaticamente utilizadores e grupos atribuídos a aplicações que implementem um perfil específico do protocolo SCIM 2.0. As especificidades do perfil estão documentadas na Compreensão da Azure AD implementação scim.

Consulte o seu fornecedor de aplicações ou a documentação do seu fornecedor de aplicações para obter declarações de compatibilidade com estes requisitos.

Importante

A implementação Azure AD SCIM é construída em cima do serviço de fornecimento de utilizadores Azure AD, que é projetado para manter os utilizadores constantemente sincronizados entre Azure AD e a aplicação-alvo, e implementa um conjunto muito específico de operações padrão. É importante entender estes comportamentos para entender o comportamento do Serviço de Fornecimento de Azure AD. Para obter mais informações, consulte a secção Ciclos de Provisionamento: Inicial e incremental em Como o provisionamento funciona.

Introdução

As aplicações que suportam o perfil SCIM descrito neste artigo podem ser ligadas a Azure AD utilizando a funcionalidade "non-gallery application" na galeria de aplicações Azure AD. Uma vez ligado, Azure AD executa um processo de sincronização a cada 40 minutos onde consulta o ponto final SCIM da aplicação para utilizadores e grupos designados, e cria ou modifica-os de acordo com os detalhes da atribuição.

Para ligar uma aplicação que suporta o SCIM:

  1. Inscreva-se no portal Azure AD. Você pode obter acesso a um teste gratuito para Azure AD com licenças P2, inscrevendo-se no programa de desenvolvedores

  2. Selecione aplicações Enterprise a partir do painel esquerdo. É mostrada uma lista de todas as aplicações configuradas, incluindo aplicações que foram adicionadas da galeria.

  3. Selecione + Nova aplicação>+ Crie a sua própria aplicação.

  4. Introduza um nome para a sua aplicação, escolha a opção "integrar qualquer outra aplicação que não encontre na galeria" e selecione Adicionar para criar um objeto de aplicação. A nova aplicação é adicionada à lista de aplicações empresariais e abre-se ao seu ecrã de gestão de aplicações.

    A imagem que se segue mostra a galeria de aplicações Azure AD:

    A screenshot mostra a galeria de aplicações Azure AD.

    Nota

    Se estiver a utilizar a experiência antiga da galeria de aplicações, siga o guia de ecrã abaixo.

    A imagem que se segue mostra a experiência Azure AD antiga da galeria de aplicações:

    Screenshot mostra a Azure AD experiência antiga da galeria de aplicações

  5. No ecrã de gestão de aplicações, selecione Provisioning no painel esquerdo.

  6. No menu Modo de Provisionamento , selecione Automatic.

    A imagem que se segue mostra as definições de provisionamento configurantes no portal do Azure:

    Screenshot da página de provisionamento de aplicativos no portal do Azure.

  7. No campo URL do inquilino , insira o URL do ponto final SCIM da aplicação. Exemplo: https://api.contoso.com/scim/

  8. Se o ponto final do SCIM necessitar de um token portador de OAuth de um emitente que não Azure AD, em seguida, copie o símbolo do portador de OAuth necessário no campo token secreto opcional. Se este campo ficar em branco, Azure AD inclui um token portador de OAuth emitido a partir de Azure AD a cada pedido. As aplicações que usam Azure AD como fornecedor de identidade podem validar este token emitido pelo Azure AD.

    Nota

    Não é recomendado deixar este campo em branco e depender de um símbolo gerado por Azure AD. Esta opção está disponível principalmente para efeitos de teste.

  9. Selecione a Ligação de Teste para ter Azure AD tentativa de ligar ao ponto final DO SCIM. Se a tentativa falhar, é apresentada informação de erro.

    Nota

    A Ligação de Teste consulta o ponto final SCIM para um utilizador que não existe, utilizando um GUID aleatório como a propriedade correspondente selecionada na configuração Azure AD. A resposta correta esperada é HTTP 200 OK com uma mensagem scim ListResponse vazia.

  10. Se as tentativas de ligação à aplicação forem bem sucedidas, então selecione Guardar para guardar as credenciais de administração.

  11. Na secção mapeamentos , existem dois conjuntos selecionáveis de mapeamentos de atributos: um para objetos do utilizador e outro para objetos de grupo. Selecione cada um para rever os atributos que são sincronizados de Azure AD para a sua aplicação. Os atributos selecionados como propriedades de correspondência são utilizados para combinar com os utilizadores e grupos na sua aplicação para operações de atualização. Selecione Guardar para escoar quaisquer alterações.

    Nota

    Pode desativar opcionalmente a sincronização de objetos de grupo desativando o mapeamento de "grupos".

  12. Em Definições, o campo Scope define quais os utilizadores e grupos que estão sincronizados. Selecione Sync apenas utilizadores e grupos atribuídos (recomendados) apenas para sincronizar utilizadores e grupos atribuídos no separador Utilizadores e grupos .

  13. Uma vez concluída a sua configuração, desa estale o Estado de Provisionamento para On.

  14. Selecione Guardar para iniciar o serviço de fornecimento de Azure AD.

  15. Se sincronizar apenas utilizadores e grupos atribuídos (recomendados), selecione o separador Utilizadores e grupos . Em seguida, atribua os utilizadores ou grupos que pretende sincronizar.

Uma vez iniciado o ciclo inicial, pode selecionar registos de provisionamento no painel esquerdo para monitorizar o progresso, o que mostra todas as ações feitas pelo serviço de fornecimento na sua aplicação. Para obter mais informações sobre como ler os registos de fornecimento de Azure AD, consulte Reportar sobre o provisionamento automático da conta de utilizador.

Nota

O ciclo inicial demora mais tempo a ser praticado do que as sincronizações posteriores, que ocorrem aproximadamente a cada 40 minutos enquanto o serviço estiver em funcionamento.

Se estiver a construir uma aplicação que será usada por mais de um inquilino, pode disponibilizá-la na galeria de candidaturas Azure AD. É fácil para as organizações descobrir a aplicação e configurar o provisionamento. Publicar a sua aplicação na galeria Azure AD e disponibilizar o provisionamento a outros é fácil. Veja os degraus aqui. A Microsoft trabalhará consigo para integrar a sua aplicação na nossa galeria, testar o seu ponto final e lançar documentação de bordo para os clientes utilizarem.

Utilize a lista de verificação para embarcar rapidamente na sua aplicação e os clientes têm uma experiência de implementação suave. A informação será recolhida de si quando embarcar na galeria.

  • Suporte um utilizador SCIM 2.0 e ponto final de grupo (Apenas um é necessário, mas ambos são recomendados)
  • Apoiar pelo menos 25 pedidos por segundo por inquilino para garantir que os utilizadores e grupos sejam aprovisionados e desprovisionados sem demora (Obrigatório)
  • Estabelecer contactos de engenharia e apoio para orientar os clientes post gallery onboarding (Obrigatório)
  • 3 Credenciais de teste não expiradas para a sua aplicação (Requerida)
  • Apoiar a concessão do código de autorização OAuth ou um símbolo de longa duração, conforme descrito abaixo (Obrigatório)
  • Estabeleça um ponto de contacto de engenharia e apoio para apoiar os clientes post gallery onboarding (Obrigatório)
  • Deteção de esquemas de suporte (necessário)
  • Apoiar a atualização de várias associações de grupo com um único PATCH
  • Documente publicamente o seu ponto final SCIM

A especificação SCIM não define um esquema específico do SCIM para a autenticação e autorização e baseia-se na utilização dos padrões industriais existentes.

Método de autorização Vantagens Desvantagens Suporte
Nome de utilizador e palavra-passe (não recomendado ou suportado por Azure AD) Fácil de implementar Inseguro - O seu pa$$word não importa Não suportado para novas galerias ou aplicativos não-galeria.
Ficha de portador de longa data Fichas de longa duração não requerem que um utilizador esteja presente. São fáceis de usar para os administradores quando se prepara o provisionamento. Fichas de longa duração podem ser difíceis de partilhar com um administrador sem usar métodos inseguros como e-mail. Suportado para apps de galeria e não galeria.
Concessão de código de autorização OAu Os tokens de acesso são muito mais curtos do que as palavras-passe, e têm um mecanismo automatizado de atualização que os tokens portadores de longa duração não têm. Um utilizador real deve estar presente durante a autorização inicial, adicionando um nível de responsabilidade. Requer que um utilizador esteja presente. Se o utilizador sair da organização, o token é inválido e a autorização terá de ser concluída novamente. Suportado para apps de galeria, mas não para aplicações não-galeria. No entanto, você pode fornecer um token de acesso na UI como o símbolo secreto para fins de teste de curto prazo. O suporte para a concessão de código OAuth em não-galeria está no nosso atraso, além do suporte para URLs configuráveis na aplicação da galeria.
Concessão de credenciais de cliente oauth Os tokens de acesso são muito mais curtos do que as palavras-passe, e têm um mecanismo automatizado de atualização que os tokens portadores de longa duração não têm. Tanto a concessão do código de autorização como as credenciais do cliente concedem criam o mesmo tipo de sinal de acesso, pelo que a deslocação entre estes métodos é transparente para a API. O provisionamento pode ser automatizado e novos tokens podem ser solicitados silenciosamente sem a interação do utilizador. Suportado para apps de galeria, mas não para aplicações não-galeria. No entanto, você pode fornecer um token de acesso na UI como o símbolo secreto para fins de teste de curto prazo. O apoio às credenciais de cliente da OAuth em não-galeria está nos nossos atrasos.

Nota

Não é aconselhável deixar o campo simbólico em branco no Azure AD a disposição da aplicação personalizada UI. O token gerado está principalmente disponível para fins de teste.

Fluxo de concessão de código OAuth

O serviço de prestação suporta a concessão do código de autorização e, após submeter o seu pedido de publicação da sua app na galeria, a nossa equipa trabalhará consigo para recolher as seguintes informações:

  • URL de autorização, um URL do cliente para obter autorização do proprietário do recurso através da reorientação do agente de utilizador. O utilizador é redirecionado para este URL para autorizar o acesso.

  • URL de troca de token, um URL do cliente para trocar um subsídio de autorização para um token de acesso, tipicamente com autenticação do cliente.

  • ID do cliente, o servidor de autorização emite ao cliente registado um identificador de cliente, que é uma cadeia única que representa as informações de registo fornecidas pelo cliente. O identificador de clientes não é um segredo. está exposto ao titular do recurso e não deve ser usado sozinho para a autenticação do cliente.

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

Nota

A URL de autorização e a URL de troca de Token não são atualmente configuráveis por inquilino.

Nota

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

Boas práticas (recomendadas, mas não necessárias):

  • Suporte urls de redirecionamento múltiplos. Os administradores podem configurar o fornecimento de "portal.azure.com" e "aad.portal.azure.com". O suporte a múltiplos URLs de redirecionamento garantirá que os utilizadores podem autorizar o acesso a partir de qualquer um dos portais.
  • Suporte vários segredos para uma renovação fácil, sem tempo de inatividade.

Como configurar o fluxo de subvenção de código OAuth

  1. Inscreva-se no portal do Azure, vá aoProvisionamento deAplicações de Aplicações>> da Empresae selecione Authorize.

    1. portal do Azure redireciona o utilizador para o URL de Autorização (sinal na página para a aplicação de terceiros).

    2. Administração fornece credenciais à aplicação de terceiros.

    3. App de terceiros redireciona o utilizador de volta para portal do Azure e fornece o código de subvenção

    4. Azure AD Serviço de Provisionamento liga para o TOKen URL e fornece o código de concessão. A aplicação de terceiros responde com o token de acesso, token de atualização e data de validade

  2. Quando o ciclo de provisionamento começa, o serviço verifica se o token de acesso atual é válido e troca-o por um novo token, se necessário. O token de acesso é fornecido em cada pedido feito à app e a validade do pedido é verificada antes de cada pedido.

Nota

Embora não seja possível configurar o OAuth nas aplicações que não são de galeria, pode gerar manualmente um token de acesso a partir do seu servidor de autorização e inseri-lo como o símbolo secreto de uma aplicação não-galeria. Isto permite-lhe verificar a compatibilidade do seu servidor SCIM com o Serviço de Provisionamento Azure AD antes de embarcar na galeria de aplicações, que suporta a concessão de código OAuth.

Fichas portadoras de OAuth de longa duração: Se a sua aplicação não apoiar o fluxo de concessão de código de autorização OAuth, em vez disso gere um sinal de portador de OAuth de longa duração que um administrador pode usar para configurar a integração do provisionamento. O símbolo deve ser perpétuo, ou então o trabalho de provisionamento será colocado em quarentena quando o símbolo expirar.

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

Para ajudar a impulsionar a consciencialização e a procura da nossa integração conjunta, recomendamos que atualize a documentação existente e amplifique a integração nos seus canais de marketing. Recomendamos que complete a seguinte lista de verificação para apoiar o lançamento:

  • Certifique-se de que as suas equipas de vendas e apoio ao cliente estão conscientes, prontas e podem falar com as capacidades de integração. Informe as suas equipas, forneça-lhes perguntas frequentes e inclua a integração nos seus materiais de venda.
  • Faça um post de blog ou um comunicado de imprensa que descreva a integração conjunta, os benefícios e como começar. Exemplo: Imprivata e Azure AD Comunicado de Imprensa
  • Aproveite as suas redes sociais como o Twitter, Facebook ou LinkedIn para promover a integração aos seus clientes. Certifique-se de incluir @AzureAD para que possamos retweetar o seu post. Exemplo: Imprivata Twitter Post
  • Crie ou atualize as suas páginas de marketing/website (por exemplo, página de integração, página de parceiros, página de preços, etc.) para incluir a disponibilidade da integração conjunta. Exemplo: Página de integração de pingboard, página de integração smartsheet, página de preços Monday.com
  • Crie um artigo do centro de ajuda ou documentação técnica sobre como os clientes podem começar. Exemplo: Enviado + integração Microsoft Azure AD.
  • Alerte os clientes da nova integração através da comunicação do seu cliente (newsletters mensais, campanhas de email, notas de lançamento do produto).

Passos seguintes