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

  • Artigo

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

Observação

O Microsoft Graph fornece outros três mecanismos de extensão para personalizar objetos do Graph. Esses são os atributos de extensão 1 a 15, extensões abertas e extensões de esquema. Confira a documentação do Microsoft Graph para obter 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 da extensão de diretório estão sempre associados a um aplicativo no locatário. O nome do atributo do diretório inclui a appId do aplicativo em seu nome.

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

Registrar e usar as extensões de diretório

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

Emitir declarações com dados no Microsoft Entra Connect

Os atributos de extensão de diretório criados e sincronizados por meio do Microsoft Entra Connect estã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 Empresariais 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 do SSO da SAML.

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 se conectar. O aplicativo pode ser configurado para receber dados em extensões de diretório 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 do 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 pelos usuários nesse locatário. Depois que a extensão do diretório estiver disponível, ela poderá ser usada para armazenar e recuperar dados usando o Microsoft Graph. A extensão do diretório também pode mapear declarações em tokens que a plataforma de identidade da Microsoft emite para os 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 necessárias. 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 é a appID (ou ID do cliente) do aplicativo com o 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 propriedade ExtensionID em vez da propriedade ID no corpo da matriz ClaimsSchema, conforme mostrado no exemplo anterior.

Dica

A consistência de maiúsculas e minúsculas é importante quando você define os atributos da 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 quando 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 será incluída no token para o primeiro usuário, mas não para o segundo.

Próximas etapas