Designar funções de administrador personalizadas para recursos do Google Sala de Aula

Os administradores podem criar funções de administrador personalizadas no Admin Console para permitir que determinados indivíduos ou grupos com uma licença do Education Plus:

• Acesse as Análises do Google Sala de Aula para entender dados como a conclusão de atividades, as tendências de notas e a adoção do Google Sala de Aula.

• Acessar temporariamente as turmas no Google Sala de Aula para ajudar os educadores, postar avisos e muito mais, sem precisar ser um professor auxiliar permanente.

Este guia explica como configurar esses recursos no seu domínio usando as APIs do Google.

Aviso: apenas superadministradores podem concluir as operações descritas neste guia.

Automatizar o processo de atribuição de função personalizada

Para automatizar o processo de atribuição de função personalizada:

1. Crie grupos de segurança para organizar os usuários que podem acessar esses recursos.
2. Adicione participantes aos grupos.
3. Crie uma função de administrador personalizada selecionando o privilégio correto.
4. Recuperar IDs de unidades organizacionais.
5. Aplique a função de administrador personalizada aos grupos recém-criados.

Pré-requisitos

1. Leia os guias de início rápido para entender como configurar e executar um aplicativo usando APIs do Google em linguagens como JavaScript, Python e Java.
2. Leia a Visão geral da API Groups.
3. Antes de usar qualquer uma das APIs do Cloud Identity descritas neste guia, configure o Cloud Identity. Essas APIs são usadas para criar grupos e atribuir privilégios de administrador.
4. Configure a API Groups.

Criar grupos de segurança

Importante: se você quiser conceder acesso a esses recursos a um usuário específico, pule para a etapa Criar uma função de administrador personalizada.

Crie um grupo de segurança com o método groups.create. Um grupo pode ser definido como um grupo de segurança quando o marcador de segurança é incluído no campo labels da solicitação. Para mais informações e limitações sobre a criação de grupos de segurança, consulte o guia Criação de grupos de segurança.

POST https://cloudidentity.googleapis.com/v1/groups

Opcionalmente, é possível incluir o parâmetro de consulta InitialGroupConfig para inicializar o proprietário do grupo:

POST https://cloudidentity.googleapis.com/v1/groups&initialGroupConfig={initialGroupConfig}

A conta que faz essa solicitação requer um dos seguintes escopos:

• https://www.googleapis.com/auth/cloud-identity.groups
• https://www.googleapis.com/auth/cloud-identity
• https://www.googleapis.com/auth/cloud-platform

Corpo da solicitação

O corpo da solicitação contém detalhes do grupo a ser criado. O customerId precisa começar com "C" (por exemplo, C046psxkn). Encontre o ID do cliente.

{
   parent: "customers/<customer-id>",
   description: "This is the leadership group of school A.",
   displayName: "Leadership School A",
   groupKey: {
      id: "[e-mail]"
   },
   labels: {
      "cloudidentity.googleapis.com/groups.security": "",
      "cloudidentity.googleapis.com/groups.discussion_forum": ""
   }
}

Resposta

A resposta contém uma nova instância do recurso Operation.

{
   done: true,
   response: {
      @type: "type.googleapis.com/google.apps.cloudidentity.groups.v1.Group",
      name: "groups/<group-id>", // unique group ID
      groupKey: {
         id: "[e-mail]" // group email address
      },
      parent: "customers/<customer-id>",
      displayName: "Leadership School A",
      description: "This is the leadership group of school A.",
      createTime: "<created time>",
      updateTime: "<updated time>",
      labels: {
         "cloudidentity.googleapis.com/groups.security": "",
         "cloudidentity.googleapis.com/groups.discussion_forum": ""
      }
   }
}

Adicionar membros do grupo

Depois de criar o grupo, a próxima etapa é adicionar participantes. Um membro do grupo pode ser um usuário ou outro grupo de segurança. Se você adicionar um grupo como participante de outro, pode haver um atraso de até 10 minutos para que a associação seja propagada. Além disso, a API retorna um erro para ciclos em associações de grupo. Por exemplo, se group1 for membro de group2, group2 não poderá ser membro de group1.

Para adicionar um membro a um grupo, use a seguinte solicitação POST.

API Directory members.insert:

POST https://admin.googleapis.com/admin/directory/v1/groups/{groupKey}/members

O parâmetro de caminho groupKey é o endereço de e-mail do grupo do novo membro ou o ID exclusivo do grupo.

A conta que faz a solicitação POST precisa de um dos seguintes escopos:

• https://apps-apis.google.com/a/feeds/groups/
• https://www.googleapis.com/auth/admin.directory.group
• https://www.googleapis.com/auth/admin.directory.group.member

Corpo da solicitação

O corpo da solicitação contém detalhes do member a ser criado.

{
   email: "[e-mail]",
   role: "MEMBER", // can be `MEMBER`, `OWNER`, `MANAGER`
}

Resposta

A resposta contém a nova instância do membro.

{
   kind: "admin#directory#member",
   etag: "<etag-value>", // role's unique ETag
   id: "4567", // group member's unique ID
   email: "[e-mail]",
   role: "MEMBER",
   type: "GROUP",
   status: "ACTIVE"
}

Essa solicitação precisa ser feita para cada usuário que você quer adicionar como membro. É possível agrupar essas solicitações para reduzir o número de conexões HTTP que o cliente precisa fazer.

Criar uma função de administrador personalizada privilegiada

A API Directory permite usar o controle de acesso baseado em função (RBAC) para gerenciar o acesso a recursos no seu domínio do Google Workspace. É possível criar funções personalizadas com privilégios para limitar o acesso do administrador de maneira mais específica do que as funções predefinidas fornecidas com o Google Workspace. É possível atribuir funções a usuários ou grupos de segurança. Para mais informações detalhadas sobre as limitações da criação de papéis, consulte as limitações de atribuição e papéis personalizados.

Para criar uma função, use a seguinte solicitação POST.

API Directory roles.insert:

POST https://admin.googleapis.com/admin/directory/v1/customer/{customer}/roles

O customerId é o mesmo usado na etapa 1 deste guia.

A conta que faz a solicitação POST precisa ter o seguinte escopo:

• https://www.googleapis.com/auth/admin.directory.rolemanagement

Corpo da solicitação

O corpo da solicitação contém detalhes do role a ser criado. Adicione um privilegeName e um serviceId para cada privilégio que precisa ser concedido com essa função.

Análises do Google Sala de Aula

O privilégio EDU_ANALYTICS_DATA_ACCESS é necessário para criar uma função personalizada que possa acessar dados de análise, com o serviceId definido como 019c6y1840fzfkt.

{
   roleName: "Education Admin", // customize as needed
   roleDescription: "Access to view analytics data", // customize as needed
   rolePrivileges: [
      {
         privilegeName: "EDU_ANALYTICS_DATA_ACCESS",
         serviceId: "019c6y1840fzfkt"
      }
   ]
}

Acesso temporário a turmas

O privilégio ADMIN_OVERSIGHT_MANAGE_CLASSES é necessário para criar um papel personalizado que possa acessar temporariamente as classes, com o serviceId definido como 019c6y1840fzfkt.

{
   roleName: "Education Admin", // customize as needed
   roleDescription: "Access to manage classes privilege", // customize as needed
   rolePrivileges: [
      {
         privilegeName: "ADMIN_OVERSIGHT_MANAGE_CLASSES",
         serviceId: "019c6y1840fzfkt"
      }
   ]
}

Chame o método privileges.list para extrair uma lista de privilegeIds e serviceIds.

Resposta

A resposta contém a nova instância do papel.

Análises do Google Sala de Aula

{
   kind: "admin#directory#role",
   etag: "<etag-value>",  // role's unique ETag
   roleId: "<role-id>",   // role's unique ID
   roleName: "Education Admin",
   roleDescription: "Access to view analytics data",
   rolePrivileges: [
      {
         privilegeName: "EDU_ANALYTICS_DATA_ACCESS",
         serviceId: "019c6y1840fzfkt"
      }
   ],
   isSystemRole: false,
   isSuperAdminRole: false
}

Acesso temporário a turmas

{
   kind: "admin#directory#role",
   etag: "<etag-value>",  // role's unique ETag
   roleId: "<role-id>",   // role's unique ID
   roleName: "Education Admin",
   roleDescription: "Access to manage classes privilege",
   rolePrivileges: [
      {
         privilegeName: "ADMIN_OVERSIGHT_MANAGE_CLASSES",
         serviceId: "019c6y1840fzfkt"
      }
   ],
   isSystemRole: false,
   isSuperAdminRole: false
}

Extrair IDs de unidades organizacionais

É possível limitar o acesso da função de administrador personalizado a uma ou mais unidades organizacionais usando o ID da unidade organizacional. Use a API OrgUnit para recuperar o orgUnitId.

Análises do Google Sala de Aula

Recomendamos que você selecione uma unidade organizacional de estudante e de professor ao atribuir a função de administrador personalizada a um usuário ou grupo específico. Isso permite que os usuários designados com o privilégio de administrador personalizado acessem dados de estudantes e turmas das unidades organizacionais. Se a unidade organizacional do estudante for omitida, os usuários designados não vão ter acesso aos dados dele. Se a unidade organizacional do professor for omitida, os usuários designados não terão acesso aos dados no nível da turma.

Acesso temporário a turmas

É possível limitar os privilégios de acesso temporário a turmas permitindo que usuários com a função de administrador personalizada acessem turmas em unidades organizacionais específicas. Se você restringir o acesso a uma unidade organizacional, o grupo atribuído à função de administrador personalizada só poderá acessar as turmas em que o professor principal faz parte dessa unidade.

Atribuir a função de administrador personalizada

Para atribuir a função de administrador personalizada a um grupo, use a seguinte solicitação POST. Consulte as orientações sobre limitações de atribuição de função e papéis personalizados para saber mais sobre os limites de atribuição de função.

API Directory roleAssignments.insert:

POST https://admin.googleapis.com/admin/directory/v1/customer/{customer}/roleassignments

Observação: use o alias my_customer com esse endpoint para representar o customerId da sua conta. O customerId também é retornado como parte do recurso users. É necessário fornecer o parâmetro do cliente ou do domínio.

Atribuir a um grupo ou usuário individual

Se você estiver atribuindo o privilégio a um grupo, inclua groupId no campo assignedTo no corpo da solicitação. O groupId foi recebido na etapa Criar grupos de segurança. Se você estiver atribuindo o privilégio a um usuário individual, inclua o ID do usuário no campo assignedTo no corpo da solicitação. O ID do usuário pode ser recuperado chamando users.get e especificando o endereço de e-mail do usuário como o parâmetro userKey ou chamando users.list.

A conta que faz a solicitação POST precisa ter o seguinte escopo:

• https://www.googleapis.com/auth/admin.directory.rolemanagement

Corpo da solicitação

O corpo da solicitação contém detalhes do RoleAssignment a ser criado. Você precisa fazer uma solicitação por unidade organizacional que gostaria de associar a esse grupo.

{
   roleId: "<role-id>",        // role's unique ID obtained from Step 3
   assignedTo: "<id>",         // group ID or user ID
   scopeType: "ORG_UNIT",      // can be `ORG_UNIT` or `CUSTOMER`
   orgUnitId: "<org-unit-id>"  // organizational unit ID referenced in Step 4
}

Resposta

A resposta contém a nova instância do RoleAssignment.

{
   kind: "admin#directory#roleAssignment",
   etag: "<etag-value>",
   roleAssignmentId: "<role-assignment-id>",
   roleId: "<role-id>",
   assignedTo: "<group-id or user-id>",
   assigneeType: "GROUP",
   scopeType: "ORG_UNIT",
   orgUnitId: "<org-unit-id>"
}

Recursos

Confira mais informações em:

• Visão geral da API Directory
• Autenticação e autorização específicas da API Directory
• Documentação REST da API Directory
• Suporte para desenvolvedores da API Admin SDK