Compartilhar via

Configurar declarações opcionais

  • Artigo

Os tokens retornados pelo Microsoft Entra são mantidos menores para garantir o desempenho ideal dos clientes que os solicitam. Como resultado, várias declarações não estão mais presentes no token por padrão e devem ser solicitadas especificamente por aplicativo.

Você pode configurar declarações opcionais para seu aplicativo pela interface do usuário ou manifesto dos aplicativos do centro de administração do Microsoft Entra.

Pré-requisitos

Configurar as declarações opcionais do aplicativo

  1. Entre no Centro de administração do Microsoft Entra como pelo menos Administrador de Aplicativo de nuvem.
  2. Navegue até Identidade>Aplicativos>Registros de aplicativo.
  3. Escolha o aplicativo para o qual você deseja configurar declarações opcionais com base no cenário e no resultado desejado.
  1. Em Gerenciar, selecione Configuração de token.
  2. Escolha Adicionar declaração opcional.
  3. Selecione o tipo de token que você quer configurar, como Acesso.
  4. Escolha as declarações opcionais a serem adicionadas.
  5. Selecione Adicionar.

O objeto optionalClaims declara as declarações opcionais solicitadas por um aplicativo. Um aplicativo pode configurar declarações opcionais retornadas em tokens de ID, tokens de acesso e tokens SAML 2. O aplicativo pode configurar um conjunto de declarações opcionais a serem retornadas em cada tipo de token diferente.

Nome Tipo Descrição
idToken Coleção As declarações opcionais retornadas no token de ID JWT.
accessToken Coleção As declarações opcionais retornadas no token de acesso JWT.
saml2Token Coleção As declarações opcionais retornadas no token SAML.

Caso uma declaração específica dê suporte, você também poderá modificar o comportamento da declaração opcional usando o campo additionalProperties.

Nome Tipo Descrição
name Edm.String O nome da declaração opcional.
source Edm.String A origem (objeto de diretório) da declaração. Há declarações predefinidas e definidas pelo usuário de propriedades de extensão. Se o valor de origem for nulo, a declaração será uma declaração opcional predefinida. Se o valor de origem for um usuário, o valor na propriedade name será a propriedade de extensão do objeto de usuário.
essential Edm.Boolean Se o valor for true, a declaração especificada pelo cliente será necessária para garantir uma experiência de autorização sem problemas para a tarefa específica solicitada pelo usuário final. O valor padrão é false.
additionalProperties Coleção (Edm.String) Outras propriedades da declaração. Se uma propriedade existir na coleção, ela modificará o comportamento da declaração opcional especificado na propriedade name.

Configurar declarações opcionais de extensão de diretório

Além do conjunto de declarações opcionais padrão, você também pode configurar tokens para incluir extensões do Microsoft Graph. Para obter mais informações, confira Adicionar dados personalizados aos recursos usando extensões.

Importante

Os tokens de acesso são sempre gerados com o manifesto do recurso, não do cliente. Na solicitação ...scope=https://graph.microsoft.com/user.read..., o recurso é a API do Microsoft Graph. O token de acesso é criado com o manifesto da API do Microsoft Graph, não com o manifesto do cliente. A alteração do manifesto do seu aplicativo nunca fará com que os tokens da API do Microsoft Graph fiquem diferentes. Para validar que as alterações de accessToken estejam em vigor, solicite um token para seu aplicativo, não para outro.

As declarações opcionais dão suporte a atributos de extensão e extensões de diretório. Esse recurso é útil para anexar informações adicionais do usuário que o aplicativo pode usar. Por exemplo, outros identificadores ou opções de configuração importantes que o usuário definiu. Se o manifesto do aplicativo solicitar uma extensão personalizada, e um usuário da MSA fizer logon em seu aplicativo, essas extensões não serão retornadas.

Formatação de extensão de diretório

Ao configurar declarações opcionais de extensão de diretório com o manifesto do aplicativo, use o nome completo da extensão (no formato: extension_<appid>_<attributename>). O <appid> é a versão reduzida de appId (ou ID do cliente) do aplicativo que solicita a declaração.

No JWT, essas declarações são emitidas com o seguinte formato de nome: extn.<attributename>. Em tokens SAML, essas declarações são emitidas com o seguinte formato de URI: http://schemas.microsoft.com/identity/claims/extn.<attributename>

Configurar declarações opcionais de grupo

Dica

As etapas neste artigo podem variar ligeiramente com base no portal do qual você começa.

Esta seção aborda as opções de configuração em declarações opcionais para alterar os atributos de grupo usados em declarações de grupo do objectID do grupo padrão para os atributos sincronizados do Microsoft Active Directory local. Você pode configurar declarações opcionais de grupos para seu aplicativo por meio do portal do Azure ou do manifesto do aplicativo. As declarações opcionais de grupo são emitidas apenas no JWT para entidade de usuário. As entidades de serviço não são incluídas em declarações opcionais de grupo emitidas no JWT.

Importante

O número de grupos emitidos em um token é limitado a 150 para declarações SAML e 200 para JWT, incluindo grupos aninhados. Para obter mais informações sobre limites de grupo e advertências importantes para declarações de grupo de atributos locais, confira Configurar declarações de grupos para aplicativos.

Conclua as seguintes etapas para configurar declarações opcionais de grupos usando o portal do Azure:

  1. Selecione o aplicativo para o qual você deseja configurar declarações opcionais.
  2. Em Gerenciar, selecione Configuração de token.
  3. Selecione Adicionar declaração de grupos.
  4. Escolha os tipos de grupos a serem retornados (Grupos de segurança ou Funções de diretório, Todos os grupos e/ou Grupos atribuídos ao aplicativo):
    • A opção Grupos atribuídos ao aplicativo inclui apenas os grupos atribuídos ao aplicativo. A opção Grupos atribuídos ao aplicativo é recomendada para grandes organizações devido ao limite do número do grupo no token. Para alterar os grupos atribuídos ao aplicativo, selecione o aplicativo na lista Aplicativos empresariais. Selecione Usuários e grupos e, em seguida, Adicionar usuário/grupo. Selecione os grupos que você deseja adicionar ao aplicativo em Usuários e grupos.
    • A opção Todos os Grupos inclui o SecurityGroup, a DirectoryRole e a DistributionList, mas não os Grupos atribuídos ao aplicativo.
  5. Opcional: selecione as propriedades do tipo de token específico para modificar o valor da declaração de grupos a fim de conter os atributos do grupo local ou alterar o tipo de declaração para uma função.
  6. Selecione Salvar.

Conclua as seguintes etapas para configurar declarações opcionais de grupos por meio do manifesto do aplicativo:

  1. Selecione o aplicativo para o qual você deseja configurar declarações opcionais.

  2. Em Gerenciar, selecione Manifesto.

  3. Adicione a seguinte entrada usando o editor de manifesto:

    Os valores válidos são:

    • "Todos" (essa opção inclui o SecurityGroup, DirectoryRole e DistributionList)
    • “SecurityGroup”
    • “DirectoryRole”
    • "ApplicationGroup" (essa opção inclui apenas os grupos atribuídos ao aplicativo)

    Por exemplo:

    "groupMembershipClaims": "SecurityGroup"

    Por padrão, as IDs de objeto de grupo serão emitidas no valor da declaração de grupo. Para modificar o valor da declaração para que contenha os atributos do grupo local ou para alterar o tipo de declaração para função, use a configuração optionalClaims da seguinte maneira:

  4. Definir declarações opcionais de configuração de nome de grupo.

    Se quiser que os grupos no token contenham os atributos do grupo local, especifique a qual tipo de token a declaração opcional deve ser aplicada na seção de declarações opcionais. Você também especifica o nome da declaração opcional solicitada e quaisquer outras propriedades desejadas.

    Vários tipos de token podem ser listados:

    • idToken para o token de ID de OIDC
    • accessToken para o token de acesso OAuth
    • Saml2Token para os tokens SAML.

    O tipo Saml2Token se aplica a tokens nos formatos SAML1.1 e SAML2.0.

    Para cada tipo de token relevante, modifique a declaração de grupos para usar a seção optionalClaims do manifesto. O esquema optionalClaims é o seguinte:

    {
    "name": "groups",
    "source": null,
    "essential": false,
    "additionalProperties": []
}
    Esquema de declarações opcionais Valor
    name Precisa ser groups
    source Não usado. Omitir ou especificar como null.
    essential Não usado. Omitir ou especificar como false.
    additionalProperties Lista de outras propriedades. As opções válidas são sam_account_name, dns_domain_and_sam_account_name, netbios_domain_and_sam_account_name, emit_as_roles e cloud_displayname.

    Em additionalProperties, apenas um entre sam_account_name, dns_domain_and_sam_account_name, e netbios_domain_and_sam_account_name é obrigatório. Se mais de um estiver presente, o primeiro será usado e os outros serão ignorados. Você também pode adicionar cloud_displayname para emitir o nome de exibição do grupo de nuvem. Essa opção só funciona quando groupMembershipClaims é definido como ApplicationGroup.

    Alguns aplicativos exigem informações de grupo sobre o usuário na declaração de função. Para alterar o tipo de declaração de uma declaração de grupo para uma de função, adicione emit_as_roles às additionalProperties. Os valores de grupo são emitidos na declaração de função.

    Se emit_as_roles for usado, as funções de aplicativo configuradas que o usuário (ou um aplicativo de recurso) recebeu não serão exibidas na declaração de função.

Os exemplos a seguir mostram a configuração de manifesto para declarações de grupo:

Emita grupos como nomes de grupo em tokens de acesso OAuth no formato dnsDomainName\sAMAccountName.

"optionalClaims": {
    "accessToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "dns_domain_and_sam_account_name"
            ]
        }
    ]
}

Emita nomes de grupo a serem retornados no formato netbiosDomain\sAMAccountName como a declaração de função em tokens SAML e tokens de ID do OIDC.

"optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "netbios_domain_and_sam_account_name",
                "emit_as_roles"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "netbios_domain_and_sam_account_name",
                "emit_as_roles"
            ]
        }
    ]
}

Emita nomes de grupo no formato de sam_account_name para grupos sincronizados locais e o nome cloud_display para grupos de nuvem em tokens SAML e tokens de ID OIDC para os grupos atribuídos ao aplicativo.

"groupMembershipClaims": "ApplicationGroup",
"optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ]
}

Exemplo de declarações opcional

Há várias opções disponíveis para atualizar as propriedades na configuração de identidade do aplicativo para habilitar e configurar declarações opcionais:

  • Você pode usar o portal do Azure
  • Você pode usar o manifesto.
  • Também é possível escrever um aplicativo que usa a API do Microsoft Graph para atualizar o aplicativo. O tipo OptionalClaims no guia de referência da API do Microsoft Graph pode ajudá-lo a configurar as declarações opcionais.

No exemplo a seguir, o portal do Azure e o manifesto são usados para adicionar declarações opcionais aos tokens de acesso, de ID e SAML destinados ao aplicativo. Diferentes declarações opcionais são adicionadas a cada tipo de token que o aplicativo pode receber:

  • Os tokens de ID agora contêm o UPN para usuários federados no formato (<upn>_<homedomain>#EXT#@<resourcedomain>) completo.
  • Os tokens de acesso que outros clientes solicitam para esse aplicativo agora incluirão a declaração auth_time.
  • Agora os tokens SAML contêm a extensão do esquema de diretório skypeId (neste exemplo, a ID de aplicativo para esse aplicativo é ab603c56068041afb2f6832e2a17e237). Os tokens SAML vão expor a ID do Skype como extension_ab603c56068041afb2f6832e2a17e237_skypeId.

Configurar alertas no portal do Azure:

  1. Selecione o aplicativo para o qual você deseja configurar declarações opcionais.
  2. Em Gerenciar, selecione Configuração de token.
  3. Selecione Adicionar declaração opcional, selecione o tipo de token ID, selecione UPN na lista de declarações e selecione Adicionar.
  4. Selecione Adicionar declaração opcional, selecione o tipo de token Acesso, selecione auth_time na lista de declarações e selecione Adicionar.
  5. Na tela Visão geral da configuração do token, selecione o ícone de lápis ao lado de UPN, selecione a opção Autenticado externamente e selecione Salvar.
  6. Selecione Adicionar declaração opcional, selecione o tipo de token SAML, selecione extn.skypeID na lista de declarações (aplicável somente se você tiver criado um objeto de usuário do Azure AD chamado SkypeID) e selecione Adicionar.

Configurar declarações no manifesto:

  1. Selecione o aplicativo para o qual você deseja configurar declarações opcionais.

  2. Em Gerenciar, selecione Manifesto para abrir o editor de manifesto embutido.

  3. Você pode editar diretamente o manifesto usando esse editor. O manifesto segue o esquema para Entidade de aplicativoe formata automaticamente o manifesto quando é salvo. Novos elementos são adicionados para a propriedade optionalClaims.

    "optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "essential": false,
            "additionalProperties": [
                "include_externally_authenticated_upn"
            ]
        }
    ],
    "accessToken": [
        {
            "name": "auth_time",
            "essential": false
        }
    ],
    "saml2Token": [
        {
            "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
            "source": "user",
            "essential": true
        }
    ]
}

  4. Quando terminar de atualizar o manifesto, selecione Salvar para salvar o manifesto.

Limitação

Um aplicativo pode emitir um número máximo de 10 atributos de extensão como declarações opcionais.

Conteúdo relacionado