Partilhar via

Configurar afirmações opcionais

  • Artigo

Os tokens que o Microsoft Entra retorna são mantidos menores para garantir o desempenho ideal pelos 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 por meio da interface do usuário ou manifesto de aplicativos do centro de administração do Microsoft Entra.

Pré-requisitos

Configurar declarações opcionais em seu aplicativo

  1. Entre no centro de administração do Microsoft Entra como pelo menos um administrador de aplicativos na nuvem.
  2. Navegue até Registros do aplicativo Identity>Applications>.
  3. Escolha o aplicativo para o qual você deseja configurar declarações opcionais com base no seu cenário e no resultado desejado.
  1. Em Gerenciar, selecione Configuração de token.
  2. Selecione Adicionar declaração opcional.
  3. Selecione o tipo de token que deseja configurar, como o Access.
  4. Selecione as declarações opcionais a serem adicionadas.
  5. Selecione Adicionar.

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

Nome Tipo Description
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.

Se suportado por uma declaração específica, você também pode modificar o comportamento da declaração opcional usando o additionalProperties campo.

Nome Tipo Description
name Edm.String O nome da reivindicação opcional.
source Edm.String A origem (objeto de diretório) da declaração. Há declarações predefinidas e declarações definidas pelo usuário de propriedades de extensão. Se o valor de origem for null, a declaração será uma declaração opcional predefinida. Se o valor de origem for user, o valor na propriedade name será a propriedade extension do objeto user.
essential Edm.Boolean Se o valor for true, a declaração especificada pelo cliente é necessária para garantir uma experiência de autorização suave para a tarefa específica solicitada pelo usuário final. O valor predefinido é false.
additionalProperties Coleção (Edm.String) Outros imóveis da reivindicação. Se existir uma propriedade nessa coleção, ela modificará o comportamento da declaração opcional especificada 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, consulte Adicionar dados personalizados a recursos usando extensões.

Importante

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

Declarações opcionais suportam atributos de extensão e extensões de diretório. Esse recurso é útil para anexar mais informações do usuário que seu 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 do MSA fizer login no 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 usando o manifesto do aplicativo, use o nome completo da extensão (no formato: extension_<appid>_<attributename>). A <appid> é a versão removida do appId (ou ID do cliente) do aplicativo que solicita a reivindicação.

Dentro do JWT, essas declarações são emitidas com o seguinte formato de nome: extn.<attributename>. Dentro dos 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 grupos

Gorjeta

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

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 de grupo padrão para atributos sincronizados do Windows Ative Directory local. Você pode configurar declarações opcionais de grupos para seu aplicativo por meio do portal do Azure ou manifesto do aplicativo. As declarações opcionais de grupo só são emitidas no JWT para entidades de usuário. As entidades de serviço não estão incluídas nas declarações opcionais de grupo emitidas no JWT.

Importante

O número de grupos emitidos num token está limitado a 150 para asserçõ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, consulte Configurar declarações de grupo 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. Selecione os tipos de grupo 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 grupos atribuídos ao aplicativo. A opção Grupos atribuídos ao aplicativo é recomendada para grandes organizações devido ao limite de número de grupos no token. Para alterar os grupos atribuídos ao aplicativo, selecione o aplicativo na lista Aplicativos corporativos. Selecione Usuários e grupos e, em seguida, Adicionar usuário/grupo. Selecione o(s) grupo(s) que deseja adicionar ao aplicativo em Usuários e grupos.
    • A opção Todos os Grupos inclui SecurityGroup, DirectoryRole e DistributionList, mas não Grupos atribuídos ao aplicativo.
  5. Opcional: selecione as propriedades específicas do tipo de token para modificar o valor da declaração de grupos para conter atributos de grupo locais ou para alterar o tipo de declaração para uma função.
  6. Selecione Guardar.

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" (esta opção inclui SecurityGroup, DirectoryRole e DistributionList)
    • "Grupo de Segurança"
    • "DirectoryRole"
    • "ApplicationGroup" (esta opção inclui apenas grupos atribuídos à aplicação)

    Por exemplo:

    "groupMembershipClaims": "SecurityGroup"

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

  4. Defina as declarações opcionais de configuração do nome do grupo.

    Se desejar que os grupos no token contenham os atributos de grupo local na seção de declarações opcionais, especifique a qual declaração opcional de tipo de token deve ser aplicada. 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 OIDC
    • accessToken para o token de acesso OAuth
    • Saml2Token para tokens SAML.

    O Saml2Token tipo se aplica aos tokens de formato SAML1.1 e SAML2.0.

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

    {
    "name": "groups",
    "source": null,
    "essential": false,
    "additionalProperties": []
}
    Esquema de declarações opcional Value
    name Deve ser groups
    source Não utilizado. Omitir ou especificar null.
    essential Não utilizado. Omitir ou especificar false.
    additionalProperties Lista de outros imóveis. 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 dos sam_account_name, dns_domain_and_sam_account_namesão netbios_domain_and_sam_account_name necessários. Se houver mais de um, o primeiro é usado e quaisquer outros ignorados. Você também pode adicionar cloud_displayname para emitir o nome de exibição do grupo de nuvem. Esta opção funciona apenas quando groupMembershipClaims está definida 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 declaração de função, adicione emit_as_roles a additionalProperties. Os valores do grupo são emitidos na declaração de função.

    Se emit_as_roles for usado, todas as funções de aplicativo configuradas que o usuário (ou um aplicativo de recurso) está atribuído não estão 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 dnsDomainName\sAMAccountName formato.

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

Emita nomes de grupo para serem retornados no netbiosDomain\sAMAccountName formato conforme as funções declaradas nos tokens de ID SAML e 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 para grupos sincronizados locais e cloud_display nome para grupos de sam_account_name nuvem em tokens de ID SAML e 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 opcionais

Há várias opções disponíveis para atualizar as propriedades na configuração de identidade de um 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 seu 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 e o manifesto do Azure são usados para adicionar declarações opcionais aos tokens de acesso, ID e SAML destinados ao seu aplicativo. Diferentes declarações opcionais são adicionadas a cada tipo de token que o aplicativo pode receber:

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

Configure declarações 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 de ID , selecione upn na lista de declarações e, em seguida, selecione Adicionar.
  4. Selecione Adicionar declaração opcional, selecione o tipo de token de acesso , selecione auth_time na lista de declarações e, em seguida, selecione Adicionar.
  5. Na tela Visão geral da Configuração de Token, selecione o ícone de lápis ao lado de upn, selecione a alternância 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 apenas se você tiver criado um objeto de usuário do Microsoft Entra chamado skypeID) e selecione Adicionar.

Configure as 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 este editor. O manifesto segue o esquema para a entidade Application e formata automaticamente o manifesto depois de salvo. Novos elementos são adicionados à optionalClaims propriedade.

    "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 salvá-lo.

Conteúdos relacionados