Configurar declarações de grupo para aplicativos com Azure Active Directory (visualização pública)Configure group claims for applications with Azure Active Directory (Public Preview)

Azure Active Directory pode fornecer informações de associação de grupo de usuários em tokens para uso em aplicativos.Azure Active Directory can provide a users group membership information in tokens for use within applications. Há suporte para dois padrões principais:Two main patterns are supported:

  • Grupos identificados por seu atributo de OID (identificador de objeto Azure Active Directory) (disponível para o público)Groups identified by their Azure Active Directory object identifier (OID) attribute (Generally Available)
  • Grupos identificados por atributos sAMAccountName ou GroupId para grupos e usuários sincronizados com Active Directory (AD) (visualização pública)Groups identified by sAMAccountName or GroupSID attributes for Active Directory (AD) synchronized groups and users (Public Preview)

Importante

Há várias advertências a serem observadas para essa funcionalidade de visualização:There are a number of caveats to note for this preview functionality:

  • O suporte para o uso de atributos sAMAccountName e SID (identificador de segurança) sincronizados do local foi projetado para habilitar a movimentação de aplicativos existentes do AD FS e de outros provedores de identidade.Support for use of sAMAccountName and security identifier (SID) attributes synced from on-premises is designed to enable moving existing applications from AD FS and other identity providers. Os grupos gerenciados no Azure AD não contêm os atributos necessários para emitir essas declarações.Groups managed in Azure AD do not contain the attributes necessary to emit these claims.
  • Em organizações maiores, o número de grupos de que um usuário é membro pode exceder o limite que Azure Active Directory será adicionado a um token.In larger organizations the number of groups a user is a member of may exceed the limit that Azure Active Directory will add to a token. 150 grupos para um token SAML e 200 para um JWT.150 groups for a SAML token, and 200 for a JWT. Isso pode levar a resultados imprevisíveis.This can lead to unpredictable results. Se esse for um problema potencial, recomendamos testar e, se necessário, aguardando até adicionarmos aprimoramentos para permitir que você restrinja as declarações aos grupos relevantes para o aplicativo.If this is a potential issue we recommend testing and if necessary waiting until we add enhancements to allow you to restrict the claims to the relevant groups for the application.
  • Para o novo desenvolvimento de aplicativos, ou em casos em que o aplicativo pode ser configurado para ele e onde o suporte a grupos aninhados não é necessário, é recomendável que a autorização no aplicativo seja baseada em funções de aplicativo em vez de grupos.For new application development, or in cases where the application can be configured for it, and where nested group support isn't required, we recommend that in-app authorization is based on application roles rather than groups. Isso 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.This limits the amount of infomation that needs to go into the token, is more secure, and separates user assignment from app configuration.

Declarações de grupo para aplicativos migrando do AD FS e de outros provedores de identidadeGroup claims for applications migrating from AD FS and other identity providers

Muitos aplicativos configurados para autenticar com AD FS dependem de informações de associação de grupo na forma de atributos de grupo do Windows AD.Many applications that are configured to authenticate with AD FS rely on group membership information in the form of Windows AD group attributes. Esses atributos são o sAMAccountName do grupo, que pode ser qualificado por nome de domínio ou o identificador de segurança do grupo do Windows (GroupId).These attributes are the group sAMAccountName, which may be qualified by-domain name, or the Windows Group Security Identifier (GroupSID). Quando o aplicativo é federado com AD FS, AD FS usa a função TokenGroups para recuperar as associações de grupo para o usuário.When the application is federated with AD FS, AD FS uses the TokenGroups function to retrieve the group memberships for the user.

Para corresponder ao token que um aplicativo receberia de AD FS, as declarações de grupo e função podem ser emitidas contendo o sAMAccountName qualificado pelo domínio em vez da objectID de Azure Active Directory do grupo.To match the token an app would receive from AD FS, group and role claims may be emitted containing the domain qualified sAMAccountName rather than the group's Azure Active Directory objectID.

Os formatos com suporte para declarações de grupo são:The supported formats for group claims are:

  • ObjectID do grupo de Azure Active Directory (Disponível para todos os grupos)Azure Active Directory Group ObjectId (Available for all groups)
  • sAMAccountName (Disponível para grupos sincronizados do Active Directory)sAMAccountName (Available for groups synchronized from Active Directory)
  • NetbiosDomain\sAMAccountName (Disponível para grupos sincronizados do Active Directory)NetbiosDomain\sAMAccountName (Available for groups synchronized from Active Directory)
  • DNSDomainName\sAMAccountName (Disponível para grupos sincronizados do Active Directory)DNSDomainName\sAMAccountName (Available for groups synchronized from Active Directory)
  • Identificador de segurança do grupo local (Disponível para grupos sincronizados do Active Directory)On Premises Group Security Identifier (Available for groups synchronized from Active Directory)

Observação

os atributos sAMAccountName e SID do grupo local só estão disponíveis em objetos de grupo sincronizados a partir de Active Directory.sAMAccountName and On Premises Group SID attributes are only available on Group objects synced from Active Directory. Eles não estão disponíveis em grupos criados no Azure Active Directory ou no office365.They aren't available on groups created in Azure Active Directory or Office365. Os aplicativos configurados no Azure Active Directory para serem sincronizados com atributos de grupo locais os obtêm somente para grupos sincronizados.Applications configured in Azure Active Directory to get synced on-premises group attributes get them for synced groups only.

Opções para que os aplicativos consumam informações de grupoOptions for applications to consume group information

Uma maneira de os aplicativos obterem informações de grupo é chamar o ponto de extremidade de grupos de gráficos para recuperar a associação de grupo para o usuário autenticado.One way for applications to obtain group information is to call the Graph groups endpoint in order to retrieve the group membership for the authenticated user. Essa chamada garante que todos os grupos dos quais um usuário é membro estejam disponíveis mesmo quando há um grande número de grupos envolvidos e o aplicativo precisa enumerar todos os grupos dos quais o usuário é membro.This call ensures that all the groups a user is a member of are available even when there are a large number of groups involved and the application needs to enumerate all groups the user is a member of. A enumeração de grupo, em seguida, é independente das limitações de tamanho do token.Group enumeration is then independent of token size limitations.

No entanto, se um aplicativo existente já espera consumir informações de grupo por meio de declarações no token que recebe, Azure Active Directory pode ser configurado com várias opções de declarações diferentes para atender às necessidades do aplicativo.However, if an existing application already expects to consume group information via claims in the token it receives, Azure Active Directory can be configured with a number of different claims options to fit the needs of the application. Considere as seguintes opções:Consider the following options:

  • Ao usar a associação de grupo para fins de autorização no aplicativo, é preferível usar o ObjectID do grupo, que é imutável e exclusivo em Azure Active Directory e está disponível para todos os grupos.When using group membership for in-application authorization purposes it’s preferable to use the Group ObjectID, which is immutable and unique in Azure Active Directory and available for all groups.
  • Se estiver usando o sAMAccountName do grupo local para autorização, use nomes qualificados do domínio; Há menos chances de situações decorrentes dos nomes conflitantes.If using the on-premises group sAMAccountName for authorization, use domain qualified names; there’s less chance of situations arising were names clash. o sAMAccountName por si só pode ser exclusivo dentro de um domínio Active Directory, mas se mais de um domínio Active Directory for sincronizado com um locatário Azure Active Directory, haverá a possibilidade de que mais de um grupo tenha o mesmo nome.sAMAccountName on its own may be unique within an Active Directory domain, but if more than one Active Directory domain is synchronized with an Azure Active Directory tenant there is a possibility for more than one group to have the same name.
  • Considere o uso de funções de aplicativo para fornecer uma camada de indireção entre a associação de grupo e o aplicativo.Consider using Application Roles to provide a layer of indirection between the group membership and the application. Em seguida, o aplicativo faz decisões de autorização interna com base em no token.The application then makes internal authorization decisions based on role clams in the token.
  • Se o aplicativo estiver configurado para obter atributos de grupo que são sincronizados de Active Directory e um grupo não contiver esses atributos, ele não será incluído nas declarações.If the application is configured to get group attributes that are synced from Active Directory and a Group doesn't contain those attributes it won't be included in the claims.
  • As declarações de grupo em tokens incluem grupos aninhados.Group claims in tokens include nested groups. Se um usuário for membro de GroupB e GroupB for um membro de GroupA, as declarações de grupo para o usuário conterão GroupA e GroupB.If a user is a member of GroupB and GroupB is a member of GroupA, then the group claims for the user will contain both GroupA and GroupB. Para organizações com uso intensivo de grupos aninhados e usuários com um grande número de associações de grupo, o número de grupos listados no token pode aumentar o tamanho do token.For organizations with heavy usage of nested groups and users with large numbers of group memberships the number of groups listed in the token can grow the token size. Azure Active Directory limita o número de grupos que emitirá em um token para 150 para asserções SAML e 200 para JWT para evitar que tokens fiquem muito grandes.Azure Active Directory limits the number of groups it will emit in a token to 150 for SAML assertions, and 200 for JWT to prevent tokens getting too large. Se um usuário for membro de um número maior de grupos do que o limite, os grupos serão emitidos junto com um link para o ponto de extremidade do grafo para obter informações sobre o grupo.If a user is a member of a larger number of groups than the limit, the groups are emitted along with a link to the Graph endpoint to obtain group information.

Pré-requisitos para usar atributos de grupo sincronizados do Active Directory: Os grupos devem ser sincronizados Active Directory usando Azure AD Connect.Prerequisites for using Group attributes synchronized from Active Directory: The groups must be synchronized from Active Directory using Azure AD Connect.

Há duas etapas para configurar Azure Active Directory para emitir nomes de grupo para grupos de Active Directory.There are two steps to configuring Azure Active Directory to emit group names for Active Directory Groups.

  1. Sincronizar nomes de grupo de Active Directory Antes que Azure Active Directory possa emitir os nomes de grupo ou o SID do grupo local em declarações de grupo ou função, os atributos necessários precisam ser sincronizados do Active Directory.Synchronize group names from Active Directory Before Azure Active Directory can emit the group names or on premises group SID in group or role claims, the required attributes need to be synchronized from Active Directory. Você deve estar executando Azure AD Connect versão 1.2.70 ou posterior.You must be running Azure AD Connect version 1.2.70 or later. Antes da versão 1.2.70 Azure AD Connect sincronizará os objetos de grupo de Active Directory, mas não incluirá os atributos de nome de grupo necessários por padrão.Prior to version 1.2.70 Azure AD Connect will synchronize the group objects from Active Directory, but doesn’t include the required group name attributes by default. Você deve atualizar para a versão atual.You should upgrade to the current version.

  2. Configurar o registro do aplicativo no Azure Active Directory para incluir declarações de grupo em tokens As declarações de grupo podem ser configuradas na seção aplicativos empresariais do portal para uma galeria ou aplicativo de SSO do SAML não Galeria, ou usando o manifesto do aplicativo na seção registros do aplicativo.Configure the application registration in Azure Active Directory to include group claims in tokens Group claims can be configured either in the Enterprise Applications section of the portal for a Gallery or Non-Gallery SAML SSO application, or using the Application Manifest in the Application Registrations section. Para configurar as declarações de grupo no manifesto do aplicativo, consulte "Configurando o Azure Active Directory registro de aplicativo para atributos de grupo" abaixo.To configure group claims in the application manifest see “Configuring the Azure Active Directory Application Registration for group attributes” below.

Configurar declarações de grupo para aplicativos SAML usando a configuração de SSOConfigure group claims for SAML applications using SSO configuration

Para configurar declarações de grupo para um aplicativo SAML de galeria ou não Galeria, abra aplicativos empresariais, clique no aplicativo na lista e selecione configuração de logon único.To configure Group Claims for a Gallery or Non-Gallery SAML application, open Enterprise Applications, click on the application in the list and select Single Sign On configuration.

Selecione o ícone de edição ao lado de "grupos retornados no token"Select the edit icon next to "Groups returned in token"

interface do usuário de declarações

Use os botões de opção para selecionar quais grupos devem ser incluídos no tokenUse the radio buttons to select which groups should be included in the token

interface do usuário de declarações

SeleçãoSelection DescriçãoDescription
Todos os gruposAll groups Emite grupos de segurança e listas de distribuição.Emits security groups and distribution lists. Ele também faz com que as funções de diretório que o usuário está atribuído sejam emitidas em uma declaração de ' wids ' e qualquer função de aplicativo à qual o usuário seja emitido na declaração de funções.It also causes Directory Roles the user is assigned to be emitted in a 'wids' claim, and any application roles the user is assigned to be emitted in the roles claim.
Grupos de segurançaSecurity groups Emite grupos de segurança dos quais o usuário é membro na declaração de gruposEmits security groups the user is a member of in the groups claim
Listas de distribuiçãoDistribution lists Emite listas de distribuição para as quais o usuário é membroEmits distribution lists the user is a member of
Funções de diretórioDirectory roles Se as funções de diretório atribuídas ao usuário forem emitidas como uma declaração ' wids ' (a declaração de grupos não será emitida)If the user is assigned directory roles they are emitted as a 'wids' claim (groups claim won't be emitted)

Por exemplo, para emitir todos os grupos de segurança dos quais o usuário é membro, selecione grupos de segurançaFor example, to emit all the Security Groups the user is a member of, select Security Groups

interface do usuário de declarações

Para emitir grupos usando Active Directory atributos sincronizados de Active Directory em vez de objectIDs do Azure AD, selecione o formato necessário na lista suspensa.To emit groups using Active Directory attributes synced from Active Directory instead of Azure AD objectIDs select the required format from the drop-down. Isso substitui a ID de objeto nas declarações por valores de cadeia de caracteres que contêm nomes de grupo.This replaces the object ID in the claims with string values containing group names. Somente os grupos sincronizados do Active Directory serão incluídos nas declarações.Only groups synchronized from Active Directory will be included in the claims.

interface do usuário de declarações

Opções avançadasAdvanced options

A maneira como as declarações de grupo são emitidas pode ser modificada pelas configurações em opções avançadasThe way group claims are emitted can be modified by the settings under Advanced options

Personalize o nome da declaração de Grupo: Se selecionado, um tipo de declaração diferente pode ser especificado para declarações de grupo.Customize the name of the group claim: If selected, a different claim type can be specified for group claims. Insira o tipo de declaração no campo nome e o namespace opcional para a declaração no campo namespace.Enter the claim type in the Name field and the optional namespace for the claim in the namespace field.

interface do usuário de declarações

Alguns aplicativos exigem que as informações de associação de grupo apareçam na declaração ' role '.Some applications require the group membership information to appear in the 'role' claim. Opcionalmente, você pode emitir os grupos do usuário como funções, marcando a caixa ' emitir grupos de declarações de função '.You can optionally emit the user's groups as roles by checking the 'Emit groups a role claims' box.

interface do usuário de declarações

Observação

Se a opção para emitir dados de grupo como funções for usada, somente os grupos aparecerão na declaração de função.If the option to emit group data as roles is used, only groups will appear in the role claim. Qualquer função de aplicativo à qual o usuário está atribuído não aparecerá na declaração de função.Any Application Roles the user is assigned will not appear in the role claim.

Configurar o registro de aplicativo do Azure AD para atributos de grupoConfigure the Azure AD Application Registration for group attributes

As declarações de grupo também podem ser configuradas na seção declarações opcionais do manifesto do aplicativo.Group claims can also be configured in the Optional Claims section of the Application Manifest.

  1. No portal-> Azure Active Directory-> registros do aplicativo-> selecione o manifesto do aplicativo >In the portal ->Azure Active Directory -> Application Registrations->Select Application->Manifest

  2. Habilitar declarações de associação de grupo alterando o groupMembershipClaimEnable group membership claims by changing the groupMembershipClaim

    Os valores válidos são:The valid values are:

    • Os"All"
    • SecurityGroup"SecurityGroup"
    • DistributionList"DistributionList"
    • DirectoryRole"DirectoryRole"

    Por exemplo:For example:

    "groupMembershipClaims": "SecurityGroup"
    

    Por padrão, ObjectIDs de grupo serão emitidas no valor de declaração de grupo.By default Group ObjectIDs will be emitted in the group claim value. Para modificar o valor da declaração para conter os atributos do grupo local ou para alterar o tipo de declaração para função, use a configuração OptionalClaims da seguinte maneira:To modify the claim value to contain on premises group attributes, or to change the claim type to role, use OptionalClaims configuration as follows:

  3. Definir declarações opcionais de configuração de nome de grupo.Set group name configuration optional claims.

    Se você quiser que os grupos no token contenham os atributos do grupo do AD local na seção declarações opcionais, especifique a qual tipo de token a declaração opcional deve ser aplicada, o nome da declaração opcional solicitada e todas as propriedades adicionais desejadas.If you want the groups in the token to contain the on premises AD group attributes in the optional claims section specify which token type optional claim should be applied to, the name of optional claim requested and any additional properties desired. Vários tipos de token podem ser listados:Multiple token types can be listed:

    • Token para o token de ID de OIDCidToken for the OIDC ID token
    • accessToken para o token de acesso do OAuth/OIDCaccessToken for the OAuth/OIDC access token
    • Saml2Token para tokens SAML.Saml2Token for SAML tokens.

    Observação

    O tipo Saml2Token aplica-se aos tokens de formato SAML 1.1 e SAML 2.0The Saml2Token type applies to both SAML1.1 and SAML2.0 format tokens

    Para cada tipo de token relevante, modifique a declaração de grupos para usar a seção OptionalClaims no manifesto.For each relevant token type, modify the groups claim to use the OptionalClaims section in the manifest. O esquema OptionalClaims é o seguinte:The OptionalClaims schema is as follows:

    {
    "name": "groups",
    "source": null,
    "essential": false,
    "additionalProperties": []
    }
    
    Esquema de declarações opcionalOptional Claims Schema ValorValue
    name:name: Deve ser "grupos"Must be "groups"
    originalsource: Não usado.Not used. Omitir ou especificar nuloOmit or specify null
    essential:essential: Não usado.Not used. Omitir ou especificar falseOmit or specify false
    additionalProperties:additionalProperties: Lista de propriedades adicionais.List of additional properties. 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"Valid options are "sam_account_name", “dns_domain_and_sam_account_name”, “netbios_domain_and_sam_account_name”, "emit_as_roles"

    Em AdditionalProperties, apenas um de "sam_account_name", "dns_domain_and_sam_account_name", "netbios_domain_and_sam_account_name" são necessários.In additionalProperties only one of "sam_account_name", “dns_domain_and_sam_account_name”, “netbios_domain_and_sam_account_name” are required. Se mais de um estiver presente, o primeiro será usado e todos os outros serão ignorados.If more than one is present, the first is used and any others ignored.

    Alguns aplicativos exigem informações de grupo sobre o usuário na declaração de função.Some applications require group information about the user in the role claim. Para alterar o tipo de declaração para de uma declaração de grupo para uma declaração de função, adicione "emit_as_roles" a propriedades adicionais.To change the claim type to from a group claim to a role claim, add “emit_as_roles” to additional properties. Os valores de grupo serão emitidos na declaração de função.The group values will be emitted in the role claim.

    Observação

    Se "emit_as_roles" for usado, qualquer função de aplicativo configurada que o usuário está atribuído não aparecerá na declaração de funçãoIf "emit_as_roles" is used any Application Roles configured that the user is assigned will not appear in the role claim

ExemplosExamples

Emitir grupos como nomes de grupo nos tokens de acesso OAuth no formato dnsDomainName\SAMAccountNameEmit groups as group names in OAuth access tokens in dnsDomainName\SAMAccountName format

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

Para emitir nomes de grupo a serem retornados no formato netbiosDomain\samAccountName como a declaração de funções nos tokens de ID SAML e OIDC:To emit group names to be returned in netbiosDomain\samAccountName format as the roles claim in SAML and OIDC ID Tokens:

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

    "idToken": [{
        "name": "groups",
        "additionalProperties": ["netbios_name_and_sam_account_name", "emit_as_roles"]
    }]
 }

Próximas etapasNext steps

O que é identidade híbrida?What is hybrid identity?