Configurar declarações de grupo para aplicativos usando a ID do Microsoft Entra

O Microsoft Entra ID pode fornecer informações de associação de grupo de um usuário em tokens para uso em aplicativos. Este recurso suporta três padrões principais:

• Grupos identificados pelo atributo Microsoft Entra object identifier (OID)
• Grupos identificados pelo atributo ou GroupSID para grupos e usuários sincronizados com o sAMAccountName Ative Directory
• Grupos identificados pelo atributo Nome de Exibição para grupos somente na nuvem

Importante

O número de grupos emitidos em um token é limitado a 150 para asserções SAML e 200 para JWT, incluindo grupos aninhados. Em organizações maiores, o número de grupos em que um usuário é membro pode exceder o limite que o Microsoft Entra ID adicionará a um token. Exceder um limite pode levar a resultados imprevisíveis. Para obter soluções alternativas para esses limites, leia mais em Advertências importantes para essa funcionalidade.

Advertências importantes para esta funcionalidade

• O suporte para uso e atributos de sAMAccountName identificador de segurança (SID) sincronizados no local foi projetado para permitir a movimentação de aplicativos existentes dos Serviços de Federação do Ative Directory (AD FS) e outros provedores de identidade. Os grupos gerenciados no Microsoft Entra ID não contêm os atributos necessários para emitir essas declarações.

• Para evitar o limite de número de grupos se os usuários tiverem um grande número de associações de grupo, você pode restringir os grupos emitidos em declarações aos grupos relevantes para o aplicativo. Leia mais sobre como emitir grupos atribuídos ao aplicativo para tokens JWT e tokens SAML. Se não for possível atribuir grupos aos seus aplicativos, você também poderá configurar um filtro de grupo para reduzir o número de grupos emitidos na declaração. A filtragem de grupo aplica-se a tokens emitidos para aplicativos em que as declarações de grupo e a filtragem foram configuradas na folha Aplicativos corporativos no portal.

• As declarações de grupo têm um limite de cinco grupos se o token for emitido através do fluxo implícito. Os tokens solicitados através do fluxo implícito terão uma "hasgroups":true reivindicação apenas se o usuário estiver em mais de cinco grupos.

• Recomendamos basear a autorização no aplicativo em funções de aplicativo em vez de grupos quando:

  • Você está desenvolvendo um novo aplicativo ou um aplicativo existente pode ser configurado para ele.
  • Não é necessário suporte para grupos aninhados.

  O uso de funções de aplicativo limita a quantidade de informações que precisam entrar no token, é mais seguro e separa a atribuição de usuário da configuração do aplicativo.

Declarações de grupo para aplicativos que migram do AD FS e outros provedores de identidade

Muitos aplicativos configurados para autenticação com o AD FS dependem de informações de associação a grupos na forma de atributos de grupo do Ative Directory do Windows Server. Esses atributos são o grupo sAMAccountName, que pode ser qualificado pelo nome de domínio ou o identificador de segurança do grupo do Windows (GroupSID). Quando o aplicativo é federado com o AD FS, O AD FS usa a TokenGroups função para recuperar as associações de grupo para o usuário.

Um aplicativo que foi movido do AD FS precisa de declarações no mesmo formato. As declarações de grupo e função emitidas pela ID do Microsoft Entra podem conter o atributo qualificado sAMAccountName pelo domínio ou o GroupSID atributo sincronizado do Ative Directory, em vez do atributo Microsoft Entra ID objectID do grupo.

Os formatos suportados para declarações de grupo são:

• Microsoft Entra group ObjectId: Disponível para todos os grupos.
• sAMAccountName: Disponível para grupos sincronizados a partir do Ative Directory.
• NetbiosDomain\sAMAccountName: Disponível para grupos sincronizados a partir do Ative Directory.
• DNSDomainName\sAMAccountName: Disponível para grupos sincronizados a partir do Ative Directory.
• Identificador de segurança de grupo local: disponível para grupos sincronizados a partir do Ative Directory.

Nota

sAMAccountName e os atributos locais GroupSID estão disponíveis apenas em objetos de grupo sincronizados a partir do Ative Directory. Eles não estão disponíveis em grupos criados no Microsoft Entra ID ou no Office 365. Os aplicativos configurados no Microsoft Entra ID para obter atributos de grupo locais sincronizados obtêm-nos apenas para grupos sincronizados.

Opções para que os aplicativos consumam informações de grupo

Os aplicativos podem chamar o ponto de extremidade do grupo Microsoft Graph para obter informações de grupo para o usuário autenticado. Essa chamada garante que todos os grupos em que um usuário é membro estejam disponíveis, mesmo quando um grande número de grupos está envolvido. A enumeração de grupo é, então, independente das limitações no tamanho do token.

No entanto, se um aplicativo existente espera consumir informações de grupo por meio de declarações, você pode configurar o Microsoft Entra ID com vários formatos de declaração. Considere as seguintes opções:

• Quando você estiver usando a associação de grupo para autorização no aplicativo, é preferível usar o atributo group ObjectID . O atributo group ObjectID é imutável e exclusivo no Microsoft Entra ID. Está disponível para todos os grupos.

• Se você estiver usando o atributo de grupo sAMAccountName local para autorização, use nomes qualificados de domínio. Reduz a chance de nomes se chocarem. sAMAccountName pode ser exclusivo dentro de um domínio do Ative Directory, mas se mais de um domínio do Ative Directory estiver sincronizado com um locatário do Microsoft Entra, há a possibilidade de mais de um grupo ter o mesmo nome.

• Considere o uso de funções de aplicativo para fornecer uma camada de indirecionamento entre a associação ao grupo e o aplicativo. Em seguida, o aplicativo toma decisões de autorização internas com base em declarações de função no token.

• Se o aplicativo estiver configurado para obter atributos de grupo sincronizados do Ative Directory e um grupo não contiver esses atributos, ele não será incluído nas declarações.

• As declarações de grupo em tokens incluem grupos aninhados, exceto quando você estiver usando a opção para restringir as declarações de grupo a grupos atribuídos ao aplicativo.

  Se um usuário for membro do Grupo B e o Grupo B for membro do Grupo A, as declarações de grupo para o usuário conterão o Grupo A e o Grupo B. Quando os usuários de uma organização têm um grande número de associações de grupo, o número de grupos listados no token pode aumentar o tamanho do token. O Microsoft Entra ID limita o número de grupos que emitirá em um token a 150 para asserções SAML e 200 para JWT. Se um usuário for membro de um número maior de grupos, os grupos serão omitidos. Em vez disso, é incluído um link para o ponto de extremidade do Microsoft Graph para obter informações do grupo.

Pré-requisitos para usar atributos de grupo sincronizados do Ative Directory

As declarações de associação a grupos podem ser emitidas em tokens para qualquer grupo se você usar o ObjectId formato. Para usar declarações de grupo em formatos diferentes de grupo ObjectId, os grupos devem ser sincronizados do Ative Directory por meio do Microsoft Entra Connect.

Para configurar o Microsoft Entra ID para emitir nomes de grupo para grupos do Ative Directory:

1. Sincronizar nomes de grupos do Ative Directory

   Antes que o Microsoft Entra ID possa emitir os nomes de grupo ou SID de grupo local em declarações de grupo ou função, você precisa sincronizar os atributos necessários do Ative Directory. Você deve estar executando o Microsoft Entra Connect versão 1.2.70 ou posterior. As versões anteriores do Microsoft Entra Connect que a 1.2.70 sincronizarão os objetos de grupo do Ative Directory, mas não incluirão os atributos de nome de grupo necessários.

2. Configurar o registro do aplicativo no Microsoft Entra ID para incluir declarações de grupo em tokens

   Você pode configurar declarações de grupo na seção Aplicativos Empresariais do portal ou usando o manifesto do aplicativo na seção Registros de Aplicativos. Para configurar declarações de grupo no manifesto do aplicativo, consulte Configurar o registro do aplicativo Microsoft Entra para atributos de grupo mais adiante neste artigo.

Adicionar declarações de grupo a tokens para aplicativos SAML usando a configuração SSO

Para configurar declarações de grupo para um aplicativo SAML de galeria ou não-galeria por meio do logon único (SSO):

1. Abra Aplicativos Corporativos, selecione o aplicativo na lista, selecione Configuração de Logon Único e selecione Atributos do Usuário & Declarações.

2. Selecione Adicionar uma declaração de grupo.

   

3. Use as opções para selecionar quais grupos devem ser incluídos no token.

   

   Seleção	Description
   Todos os grupos	Emite grupos de segurança e listas de distribuição e funções.
   Grupos de segurança	Emite grupos de segurança dos quais o usuário é membro na declaração de grupos. Se o usuário receber funções de diretório, elas serão emitidas como ID de objeto.
   Funções de diretório	Se forem atribuídas funções de diretório ao usuário, elas serão emitidas como uma wids declaração. (A reivindicação do grupo não será emitida.)
   Grupos atribuídos ao aplicativo	Emite apenas os grupos que são explicitamente atribuídos ao aplicativo e dos quais o usuário é membro. Recomendado para grandes organizações devido ao limite de número de grupos no token.

   • Por exemplo, para emitir todos os grupos de segurança dos quais o usuário é membro, selecione Grupos de segurança.

     

     Para emitir grupos usando atributos do Ative Directory sincronizados do Ative Directory em vez de atributos do Microsoft Entra ID objectID , selecione o formato necessário na lista suspensa Atributo de origem. Somente grupos sincronizados do Ative Directory serão incluídos nas declarações.

     

   • Para emitir apenas grupos atribuídos ao aplicativo, selecione Grupos atribuídos ao aplicativo.

     

     Os grupos atribuídos ao aplicativo serão incluídos no token. Outros grupos dos quais o usuário é membro serão omitidos. Com essa opção, os grupos aninhados não são incluídos e o usuário deve ser um membro direto do grupo atribuído ao aplicativo.

     Para alterar os grupos atribuídos ao aplicativo, selecione o aplicativo na lista Aplicativos Empresariais. Em seguida, selecione Usuários e grupos no menu esquerdo do aplicativo.

     Para obter mais informações sobre como gerenciar a atribuição de grupo a aplicativos, consulte Atribuir um usuário ou grupo a um aplicativo corporativo.

Emitir nome de exibição de grupo somente na nuvem no token

Você pode configurar a declaração de grupo para incluir o nome de exibição do grupo para os grupos somente na nuvem.

1. Abra Aplicativos Corporativos, selecione o aplicativo na lista, selecione Configuração de Logon Único e selecione Atributos do Usuário & Declarações.

2. Se você já tiver declarações de grupo configuradas, selecione-as na seção Declarações adicionais. Caso contrário, você pode adicionar a declaração de grupo conforme descrito nas etapas anteriores.

3. Para o tipo de grupo emitido no token, selecione Grupos atribuídos ao aplicativo:

   

4. Para emitir o nome de exibição do grupo apenas para grupos de nuvem, na lista suspensa Atributo de origem, selecione os nomes de exibição do grupo somente na nuvem:

   

5. Para uma configuração híbrida, para emitir atributo de grupo local para grupos sincronizados e nome de exibição para grupos de nuvem, você pode selecionar o atributo de fontes locais desejado e marcar a caixa de seleção Emitir nome de grupo para grupos somente na nuvem:

   

Nota

Você só pode adicionar nomes de grupos de nuvem de grupos atribuídos a um aplicativo. A restrição é groups assigned to the application porque um nome de grupo não é exclusivo e os nomes de exibição só podem ser emitidos para grupos explicitamente atribuídos ao aplicativo para reduzir os riscos de segurança. Caso contrário, qualquer usuário poderia criar um grupo com nome duplicado e obter acesso no lado do aplicativo.

Definir as opções avançadas

Personalizar o nome da declaração de grupo

Você pode modificar a maneira como as declarações de grupo são emitidas usando as configurações em Opções avançadas.

Se você selecionar Personalizar o nome da declaração de grupo, poderá especificar um tipo de declaração diferente para as declarações de grupo. Digite o tipo de declaração na caixa Nome e o namespace opcional para a declaração na caixa Namespace .

Alguns aplicativos exigem que as informações de associação ao grupo apareçam na declaração de função. Opcionalmente, você pode emitir os grupos do usuário como funções marcando a caixa de seleção Emitir grupos como declarações de função.

Nota

Se você usar a opção para emitir dados de grupo como funções, somente os grupos aparecerão na declaração de função. Todas as funções de aplicativo às quais o usuário está atribuído não aparecerão na declaração de função.

Filtragem de grupo

A filtragem de grupo permite um controle preciso da lista de grupos incluída como parte da declaração de grupo. Quando um filtro é configurado, apenas os grupos que correspondem ao filtro serão incluídos na declaração do grupo enviada para esse aplicativo. O filtro será aplicado contra todos os grupos, independentemente da hierarquia do grupo.

Nota

A filtragem de grupo aplica-se a tokens emitidos para aplicativos em que as declarações de grupo e a filtragem foram configuradas na folha Aplicativos corporativos no portal.
A filtragem de grupo não se aplica às funções do Microsoft Entra.

Você pode configurar filtros para serem aplicados ao nome de exibição ou SAMAccountName atributo do grupo. As seguintes operações de filtragem são suportadas:

• Prefixo: corresponde ao início do atributo selecionado.
• Sufixo: corresponde ao final do atributo selecionado.
• Contém: Corresponde a qualquer local no atributo selecionado.

Transformação do grupo

Alguns aplicativos podem exigir os grupos em um formato diferente de como eles são representados no Microsoft Entra ID. Para dar suporte a esse requisito, você pode aplicar uma transformação a cada grupo que será emitido na declaração de grupo. Você consegue isso permitindo a configuração de uma expressão regular (regex) e um valor de substituição em declarações de grupo personalizadas.

\

• Padrão Regex: use um regex para analisar cadeias de texto de acordo com o padrão definido nesta caixa. Se o padrão regex que você descreve for avaliado para true, o padrão de substituição de regex será executado.
• Padrão de substituição de regex: descreva na notação regex como você deseja substituir sua cadeia de caracteres se o padrão regex descrito for avaliado como true. Use grupos de captura para corresponder subexpressões neste regex de substituição.

Para obter mais informações sobre grupos de substituição e captura de regex, consulte O modelo de objeto de expressão regular: o grupo capturado.

Nota

Conforme descrito na documentação do Microsoft Entra, não é possível modificar uma declaração restrita usando uma política. A fonte de dados não pode ser alterada e nenhuma transformação é aplicada quando você está gerando essas declarações. A declaração de grupo ainda é uma declaração restrita, portanto, você precisa personalizar os grupos alterando o nome. Se você selecionar um nome restrito para o nome de sua declaração de grupo personalizada, a declaração será ignorada no tempo de execução.

Você também pode usar o recurso de transformação regex como um filtro, porque quaisquer grupos que não correspondam ao padrão regex não serão emitidos na declaração resultante.

Se a transformação aplicada à declaração de grupos original resultar em uma nova declaração personalizada, a declaração de grupos original será omitida do token. No entanto, se o regex configurado não corresponder a nenhum valor na lista original, a declaração personalizada não estará presente e a declaração de grupos originais será incluída no token.

Editar a configuração da declaração de grupo

Depois de adicionar uma configuração de declaração de grupo à configuração de Atributos de Usuário & Declarações , a opção para adicionar uma declaração de grupo não estará disponível. Para alterar a configuração da declaração de grupo, selecione a declaração de grupo na lista Declarações adicionais.

Configurar o registro do aplicativo Microsoft Entra para atributos de grupo

Você também pode configurar declarações de grupo na seção de declarações opcionais do manifesto do aplicativo.

1. No portal, selecione Registros de aplicativos de identidade>>Selecione Manifesto>do aplicativo.>

2. Habilite as declarações de associação ao grupo alterando o groupMembershipClaims.

   Os valores válidos são:

   Seleção	Description
   All	Emite grupos de segurança, listas de distribuição e funções.
   SecurityGroup	Emite grupos de segurança e funções do Microsoft Entra das quais o usuário é membro na declaração de grupo.
   DirectoryRole	Se forem atribuídas funções de diretório ao usuário, elas serão emitidas como uma wids declaração. (Uma declaração de grupo não será emitida.)
   ApplicationGroup	Emite apenas os grupos que são explicitamente atribuídos ao aplicativo e dos quais o usuário é membro.
   None	Nenhum grupo é retornado. (Não diferencia maiúsculas de minúsculas, por isso none também funciona. Ele pode ser definido diretamente no manifesto do aplicativo.)

   Por exemplo:

   "groupMembershipClaims": "SecurityGroup"
   

   Por padrão, os atributos de grupo ObjectID serão emitidos no valor da declaração de grupo. Para modificar o valor da declaração para conter atributos de grupo locais ou para alterar o tipo de declaração para uma função, use a optionalClaims configuração descrita na próxima etapa.

3. Defina declarações opcionais para a configuração do nome do grupo.

   Se desejar que os grupos no token contenham os atributos de grupo do Ative Directory local, especifique qual declaração opcional de tipo de token deve ser aplicada na optionalClaims seção . Você pode listar vários tipos de token:

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

   Nota

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

   Para cada tipo de token relevante, modifique a declaração de grupo 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 propriedades adicionais. As opções válidas são "sam_account_name", "dns_domain_and_sam_account_name", "netbios_domain_and_sam_account_name", "cloud_displayname"e "emit_as_roles".

   No additionalProperties, apenas um dos "sam_account_name", "dns_domain_and_sam_account_name"ou "netbios_domain_and_sam_account_name" é necessário. Se houver mais de um, o primeiro é usado e quaisquer outros são ignorados.

   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" propriedades adicionais. Os valores do grupo serão emitidos na declaração de função.

   Para emitir nome de exibição de grupo para grupos somente na nuvem, você pode adicionar "cloud_displayname" ao additional properties. Esta opção funcionará apenas quando “groupMembershipClaims” estiver definida como ApplicationGroup

   Nota

   Se você usar "emit_as_roles"o , todas as funções de aplicativo configuradas às quais o usuário está atribuído não aparecerão na declaração de função.

Exemplos

Emitir 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 como a declaração de função em 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"]
    }]
}

Próximos passos

• Adicionar autorização usando grupos & declarações de grupo a um aplicativo Web ASP.NET Core (exemplo de código)
• Atribuir um usuário ou grupo a um aplicativo corporativo
• Configurar afirmações de funções