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

O Microsoft Entra ID oferece informações da associação de grupo de um usuário em tokens para uso em aplicativos. Esse recurso dá suporte a três padrões principais:

• Grupos identificados pelo atributo de OID (identificador de objeto) do Microsoft Entra
• Grupos identificados pelo atributo sAMAccountName ou GroupSID para usuários e grupos sincronizados do Active 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 declarações SAML e 200 para JWT, incluindo grupos aninhados. Em organizações maiores, o número de grupos do qual um usuário faz parte pode exceder o limite que o Microsoft Entra ID aplica antes de emitir declarações de grupos em um token. Exceder esse limite fará com que o Microsoft Entra ID omita completamente o envio de declarações de grupo no token. Para obter soluções alternativas para esses limites, leia mais em Advertências importantes sobre essa funcionalidade.

Advertências importantes para essa funcionalidade

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

• Se os usuários tiverem um grande número de associações de grupo, será possível evitar o limite de número de grupos restringindo os grupos emitidos em declarações aos grupos relevantes do 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, configure um filtro de grupo para reduzir o número de grupos emitidos na declaração. A filtragem de grupo se aplica a tokens emitidos para aplicativos em que as declarações de grupo e a filtragem foram configuradas na folha Aplicativos empresariais no portal. Lembre-se que organizações maiores, o número de grupos do qual um usuário faz parte pode exceder o limite que o Microsoft Entra ID aplica antes de emitir declarações de grupos em um token. Exceder esse limite fará com que o Microsoft Entra ID omita completamente o envio de declarações de grupo no token.

• As declarações de grupo terão um limite de cinco grupos se o token for emitido por meio do fluxo implícito. Tokens solicitados por meio do fluxo implícito terão uma declaração "hasgroups":true somente se o usuário estiver em mais de cinco grupos.

• É recomendável 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.
  • O suporte para grupos aninhados não é necessário.

  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 estão sendo migrados dos AD FS e de outros provedores de identidade

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

Um aplicativo que tenha sido migrado dos AD FS precisa de declarações no mesmo formato. Declarações de grupo e função emitidas a partir do Microsoft Entra ID podem conter o atributo sAMAccountName qualificado pelo domínio ou o atributo GroupSID sincronizado do Active Directory, em vez do atributo objectID do Microsoft Entra ID do grupo.

Os formatos com suporte para as declarações de grupo são:

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

Observação

sAMAccountName e atributos GroupSID locais estão disponíveis somente em objetos de grupo sincronizados do Active 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 serem sincronizados com atributos de grupo locais os obtêm somente para grupos sincronizados.

Opções para os aplicativos consumirem informações de grupo

Os aplicativos podem chamar o ponto de extremidade de grupos do Microsoft Graph para obter informações de grupo para o usuário autenticado. Esta chamada garante que todos os grupos onde um usuário é um membro estão disponíveis, mesmo quando um grande número de grupos está envolvido. Dessa forma, a enumeração de grupo é independente das limitações de 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:

• Ao usar a associação de grupo para autorização no aplicativo, é preferível usar o atributo ObjectID do grupo. O atributo ObjectID do grupo é imutável e exclusivo no Microsoft Entra ID. Ele está disponível para todos os grupos.

• Se você estiver usando o atributo sAMAccountName do grupo local para autorização, use nomes qualificados por domínio. Ele reduz a chance de conflitos de nomes. O sAMAccountName pode ser exclusivo em um domínio do Active Directory, mas se mais de um domínio do Active Directory for sincronizado com um locatário do Microsoft Entra ID, haverá a possibilidade de que mais de um grupo tenha o mesmo nome.

• Considere o uso de funções de aplicativo para fornecer uma camada de indireção entre a associação de grupo e o aplicativo. O aplicativo então toma decisões de autorização internas com base nas declarações de função no token.

• Se o aplicativo estiver configurado para obter atributos de grupo que são sincronizados a partir do Active 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ê está usando a opção para restringir as declarações de grupo aos grupos que são atribuídos ao aplicativo.

  Se um usuário for membro de GroupB e GroupB for membro de GroupA, as declarações de grupo para o usuário conterão GroupA e GroupB. Quando os usuários de uma organização têm um grande número de associações a grupos, 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 será emitido em um token a 150 para instruções SAML e 200 para JWT. Se um usuário for membro de um número maior de grupos, os grupos serão omitidos. Um link para o ponto de Microsoft Graph para obter informações de grupo é incluído.

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

As declarações de associação de grupo poderão ser emitidas em tokens para qualquer grupo se você usar o formato ObjectId. Para usar declarações de grupo em formatos diferentes dos do grupo ObjectId, os grupos devem ser sincronizados pelo Active Directory através do Microsoft Entra Connect.

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

1. Sincronizar nomes de grupo do Active Directory

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

2. Configurar o registro de 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 Aplicativo. Para configurar as declarações de grupo no manifesto do aplicativo, confira Configurar o registro de aplicativos do Microsoft Entra para atributos de grupo posteriormente nesse artigo.

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

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

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

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	Descrição
   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 o usuário tiver funções de diretório atribuídas, ele será emitido como uma declaração wids. (A declaração do grupo não será emitida.)
   Grupos atribuídos ao aplicativo	Emite apenas os grupos atribuídos explicitamente 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 os atributos do Active Directory sincronizados do Active Directory em vez de atributos objectID do Microsoft Entra ID, selecione o formato necessário na lista suspensa de Atributo de origem. Somente os grupos sincronizados do Active 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 à esquerda 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 empresarial.

Emitir o nome de exibição do grupo somente na nuvem no token (versão prévia)

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 Empresariais, selecione o aplicativo na lista, selecione Configuração de Logon Único e, em seguida, selecione Atributos e Declarações do Usuário.

2. Se você já tiver declarações de grupo configuradas, selecione-a 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 nuvem:

   

5. Para uma configuração híbrida, para emitir o atributo de grupo local para grupos sincronizados e o 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 do grupo para grupos apenas na nuvem:

   

Observação

Você só pode adicionar os nomes de grupos de nuvem dos grupos atribuídos a um aplicativo. A restrição a groups assigned to the application se deve ao fato de um nome de grupo não ser exclusivo, uma vez que 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 o nome duplicado e obter acesso no lado do aplicativo.

Definir opções avançadas

Personalizar o nome da declaração de grupo

É possível 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 declarações de grupo. Insira 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 de grupo apareçam na declaração de função. Opcionalmente, você pode emitir os grupos do usuário como funções, marcando a caixa Emitir grupos como declarações de função.

Observação

Se usar a opção de emitir dados de grupo como funções, somente os grupos aparecerão na declaração de função. Qualquer função de aplicativo atribuída ao usuário não será exibida na declaração de função.

Filtragem de grupo

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

Observação

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

Você pode configurar filtros a serem aplicados ao nome de exibição ou atributo SAMAccountName do grupo. Há suporte para as operações de filtragem a seguir:

• 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 de 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 este 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 de uma expressão regular (regex) e de um valor de substituição em declarações de grupo personalizadas.

\

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

Para saber mais sobre grupos de captura e substituição de regex, confira O modelo de objeto de expressão regular: o grupo capturado.

Observação

Conforme descrito na documentação do Microsoft Entra, você não pode 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 da declaração de grupo personalizado, a declaração será ignorada em runtime.

Você também pode usar o recurso de transformação de regex como um filtro, pois quaisquer grupos que não correspondam ao padrão de 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 original será incluída no token.

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

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

Configurar o registro de aplicativo do Microsoft Entra para atributos de grupo

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

1. No portal, selecioneIdentidade>Aplicativos>Registros de aplicativo>Selecionar Aplicativos>Manifesto.

2. Habilita declarações de associação de grupo alterando groupMembershipClaims.

   Os valores válidos são:

   Seleção	Descrição
   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 dos quais o usuário é membro na declaração de grupo.
   DirectoryRole	Se o usuário tiver funções de diretório atribuídas, ele será emitido como uma declaração wids. (Uma declaração de grupo não será emitida.)
   ApplicationGroup	Emite apenas os grupos atribuídos explicitamente ao aplicativo e dos quais o usuário é membro.
   None	Nenhum grupo é retornado. (Ele não diferencia maiúsculas de minúsculas, portanto, none também funciona. Ele pode ser definido diretamente no manifesto do aplicativo.)

   Por exemplo:

   "groupMembershipClaims": "SecurityGroup"
   

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

3. De acordo com as definições opcionais para a configuração de nome de grupo.

   Se quiser que os grupos no token contenham os atributos do grupo do Active Directory local, especifique a qual tipo de token a declaração opcional deve ser aplicada na seção optionalClaims. É possível listar vários tipos de token:

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

   Observação

   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 no manifesto. O esquema optionalClaims é o seguinte:

   {
   "name": "groups",
   "source": null,
   "essential": false,
   "additionalProperties": []
   }
   

   Esquema de declarações opcionais	Valor
   name	Deve ser "groups".
   source	Não usado. Omitir ou especificar null.
   essential	Não usado. 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".

   Em additionalProperties, apenas um de "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.

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

   Para emitir o nome de exibição do grupo para grupos somente na nuvem, você pode adicionar "cloud_displayname" a additional properties. Essa opção só é válida quando “groupMembershipClaims” estiver definido como ApplicationGroup

   Observação

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

Exemplos

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 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"]
    }]
}

Próximas etapas

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