Partilhar via

Atributos de extensão de diretório em declarações

  • Artigo

Os atributos de extensão de diretório fornecem uma maneira de armazenar mais dados em objetos de diretório, como usuários. Apenas os atributos da extensão em objetos do utilizador podem ser utilizados para emitir afirmações para aplicações. Este artigo descreve como usar atributos de extensão de diretório para enviar dados do usuário para aplicativos em declarações de token.

Nota

O Microsoft Graph fornece três outros mecanismos de extensão para personalizar objetos Graph. Estes são os atributos de extensão 1-15, extensões abertas e extensões de esquema. Veja a documentação do Microsoft Graph para obter mais detalhes. Os dados armazenados em objetos do Microsoft Graph usando extensões abertas e de esquema não estão disponíveis como fontes para declarações em tokens.

Os atributos de extensão de diretório são sempre associados a um aplicativo no locatário. O nome do atributo directory inclui o appId do aplicativo em seu nome.

O identificador de um atributo de extensão de diretório é do formato extension_xxxxxxxxx_AttributeName. Onde xxxxxxxxx é o appId do aplicativo para o qual a extensão foi definida, com apenas os caracteres 0-9 e A-Z.

Registrar e usar extensões de diretório

Registre atributos de extensão de diretório de uma das seguintes maneiras:

  • Configure o Microsoft Entra Connect para criá-los e sincronizar dados com eles a partir do local. Consulte Extensões de diretório de sincronização do Microsoft Entra Connect.
  • Use o Microsoft Graph para registrar, definir os valores e ler as extensões de diretório. Os cmdlets do PowerShell também estão disponíveis.

Emita declarações com dados do Microsoft Entra Connect

Os atributos de extensão de diretório criados e sincronizados usando o Microsoft Entra Connect são sempre associados à ID do aplicativo usada pelo Microsoft Entra Connect. Esses atributos podem ser usados como uma fonte para declarações, configurando-os como declarações na configuração de Aplicativos Corporativos no Portal. Depois que um atributo de extensão de diretório é criado usando o AD Connect, ele é exibido na configuração de declarações SAML SSO.

Emitir declarações usando o Graph ou o PowerShell

Se um atributo de extensão de diretório estiver registrado para usar o Microsoft Graph ou o PowerShell, o aplicativo poderá ser configurado para receber dados nesse atributo quando o usuário entrar. O aplicativo pode ser configurado para receber dados em extensões de diretório que são registradas no aplicativo usando declarações opcionais que podem ser definidas no manifesto do aplicativo.

Os aplicativos multilocatários podem então registrar atributos de extensão de diretório para seu próprio uso. Quando o aplicativo é provisionado em um locatário, as extensões de diretório associadas ficam disponíveis e são consumidas para os usuários nesse locatário. Depois que a extensão de diretório estiver disponível, ela poderá ser usada para armazenar e recuperar dados usando o Microsoft Graph. A extensão de diretório também pode mapear para declarações em tokens que a plataforma de identidade da Microsoft emite para aplicativos.

Se um aplicativo precisar enviar declarações com dados de um atributo de extensão registrado em um aplicativo diferente, uma política de mapeamento de declarações deverá ser usada para mapear o atributo de extensão para a declaração.

Um padrão comum para gerenciar atributos de extensão de diretório é registrar um aplicativo especificamente para todas as extensões de diretório que você precisa. Quando você usa esse tipo de aplicativo, todas as extensões têm o mesmo appID em seu nome.

Por exemplo, o código a seguir mostra uma política de mapeamento de declarações para emitir uma única declaração de um atributo de extensão de diretório em um token OAuth/OIDC:

{
    "ClaimsMappingPolicy": {
        "Version": 1,
        "IncludeBasicClaimSet": "false",
        "ClaimsSchema": [{
                "Source": "User",
                "ExtensionID": "extension_xxxxxxx_test",
                "JWTClaimType": "http://schemas.contoso.com/identity/claims/exampleclaim"
            },
        ]
    }
}

Onde xxxxxxx é o appID (ou ID do cliente) do aplicativo no qual a extensão foi registrada.

Aviso

Ao definir uma política de mapeamento de declarações para um atributo de extensão de diretório, use a ExtensionID propriedade em vez da propriedade dentro do ID corpo da ClaimsSchema matriz, como mostrado no exemplo anterior.

Gorjeta

A consistência de maiúsculas e minúsculas é importante quando você define atributos de extensão de diretório em objetos. Os nomes de atributos de extensão não diferenciam maiúsculas de minúsculas ao serem configurados, mas diferenciam maiúsculas de minúsculas ao serem lidos do diretório pelo serviço de token. Se um atributo de extensão for definido em um objeto de usuário com o nome "LegacyId" e em outro objeto de usuário com o nome "legacyid", quando o atributo for mapeado para uma declaração usando o nome "LegacyId", os dados serão recuperados com êxito e a declaração incluída no token para o primeiro usuário, mas não para o segundo.

Próximos passos