Workplace

Permissões

Visão geral

Com a função de administrador do sistema do Workplace, é possível controlar os recursos oferecidos a cada integração ao criar apps com permissões específicas. O nome de cada app pode ser determinado de acordo com o serviço para o qual ele é usado. Os apps são equipados com permissões e tokens de acesso únicos que servem para controlar quais informações os apps podem ler ou gravar.

Este guia descreve em mais detalhes o modelo de permissão e app.

Controles de permissão ao editar um app de integração personalizada

Permissões disponíveis

Cada app do Workplace pode receber o próprio conjunto de permissões para controlar o nível de funcionalidade disponibilizado na Graph API e na API de Gerenciamento de Contas.

Quando o app é criado, as permissões concedidas a ele são aplicadas a todas as contas da comunidade. Para aproveitar a funcionalidade do app, os proprietários das contas não precisam conceder permissões adicionais. Isso é diferente do modelo de permissões do Facebook, em que cada usuário concede permissões ao entrar no app.

Confira abaixo a lista completa das permissões do app disponíveis para integração, bem como uma visão geral de como cada uma pode ser usada.

PermissãoDescrição

Ler conteúdo do grupo

Leia publicações e comentários em grupos selecionados.

read_group

Use essa permissão para criar uma integração que busque todo o conteúdo de grupos selecionados.

Caso a integração funcione como um bot no grupo, use a permissão Mencionar o bot.

Gerenciar conteúdo do grupo

Gerencie publicações e comentários em grupos selecionados.

write_group

Use essa permissão para criar uma integração que publique conteúdo em grupos (como relatórios semanais de serviços internos) ou um bot que notifique sobre o status do serviço.

Ler linha do tempo do usuário

Veja as publicações feitas pelos membros do grupo na linha do tempo deles.

read_user_feed

Use essa permissão ao criar uma integração que faça o seguinte:

  • Busque todo o conteúdo da linha do tempo de um membro do grupo
  • Assine para receber alterações no campo de status do perfil do usuário

Gerencie a linha do tempo do usuário

Publique e comente na linha do tempo de qualquer membro do grupo

write_user_feed

Use essa permissão para ativar uma integração que crie ou edite uma publicação na linha do tempo de um membro do grupo.

Mencionar o bot

Quando você for mencionado em uma publicação, é possível ver a publicação e responder aos comentários.

bot_mention

Use essa permissão para criar bots nos Grupos do Workplace.

Gerenciar grupos

Crie, edite ou remova grupos selecionados e os respectivos membros.

manage_group

Use essa permissão para criar uma integração que gera grupos automaticamente e preenche os membros do grupo com base na estrutura do organograma ou nos grupos do projeto.

Caso uma integração com essa permissão esteja no escopo de grupos específicos, ela não poderá criar novos grupos.

Gerenciar contas

Provisione, atualize ou desative contas por meio da API de Gerenciamento de Contas.

manage_accounts

Use essa permissão para integrações com serviço de provisionamento de conta, como os provedores de identidade, a ferramenta de sincronização do Active Directory ou um cliente personalizado da API de Gerenciamento de Contas.

Ao ativar essa permissão, também será possível ativar a permissão "Convidar as pessoas automaticamente para o Workplace assim que elas forem adicionadas usando esta integração".

Gerenciar selos

Conceda selos às pessoas em uma comunidade do Workplace.

manage_badges

Use essa permissão para permitir que uma integração faça o seguinte:

  • Conceda selos aos membros
  • Acesse a lista de selos que um membro recebeu
  • Acesse a lista de selos disponíveis

Leia emails do usuário

Veja o endereço de email dos membros do grupo.

read_user_email

Permite buscar a conta de email associada à conta de um usuário do Workplace.

Ler perfil profissional

Acesso somente leitura às informações dos diretórios das pessoas.

read_user_work_profile

Permite que um app busque os campos department, division, organization, primary_address, primary_phone, title e gender das pessoas.

Ler organograma

Acesso somente leitura aos gerentes e subordinados das pessoas.

read_user_org_chart

Permite que um app busque os gerentes e subordinados de uma pessoa.

Enviar mensagem para um membro

Troque mensagens de bate-papo com os membros da comunidade.

message

Use essa permissão para criar bots no Work Chat.

Ler todas as mensagens

Leia as mensagens de bate-papo dos membros da comunidade.

read_all_messages

Use essa permissão para ativar uma integração de conformidade responsável por monitorar o uso do Workplace Chat.

Excluir mensagens de bate-papo

delete_messages

Use essa permissão para permitir que um app exclua as mensagens de bate-papo das conversas de uma pessoa. Por exemplo, para implementar uma política de retenção.

Ler registros de segurança

Acesse informações detalhadas sobre eventos de segurança, como tentativas de login e solicitações de redefinição de senha.

receive_security_logs

Use essa permissão para ativar uma integração de conformidade responsável por monitorar o uso do Workplace Chat.

Desconexão

Desconecte membros de todas as sessões ativas.

logout

Use essa permissão para desconectar um usuário do Workplace.

Criar prévias de link

Veja prévias detalhadas dos links compartilhados no Workplace.

link_unfurling

Os apps com essa permissão podem gerar prévias autenticadas de links compartilhados no Workplace.

Gerenciar perfis profissionais

Leia e atualize perfis profissionais no Workplace.

manage_profiles

Os apps com essa permissão combinam as permissões de leitura read_user_work_profile e read_user_org_chart. Eles também podem atualizar informações das contas (por exemplo, nome, departamento, divisão, cargo, organização, telefones)

Provisionar contas de usuários

Provisione contas no Workplace.

provision_accounts

Os apps com essa permissão podem provisionar, desativar e excluir contas (não reivindicadas) do Workplace. Ela também permite atualizar os campos online, email, name, hire_date e invited members.

Ler membros do grupo

Liste os membros de um grupo e os grupos dos quais um usuário participa.

list_group_members

Os apps com essa permissão podem consultar a lista de membros de um grupo específico. Além disso, é possível listar os grupos dos quais um usuário participa.

Gerenciar conteúdo da Biblioteca de Conhecimento

Crie, edite e exclua informações importantes da empresa na Biblioteca de Conhecimento.

manage_knowledge_library

Os apps com essa permissão podem criar e modificar o conteúdo da Biblioteca de Conhecimento. Use essa permissão para permitir que uma integração faça o seguinte:

  • Crie/atualize/exclua uma categoria
  • Crie subcategorias dentro de uma categoria
  • Atualize fotos/vídeos/arquivos em uma categoria
  • Crie/atualize/exclua links rápidos

Ler conteúdo da Biblioteca de Conhecimento

Leia informações importantes sobre a empresa na Biblioteca de Conhecimento.

read_knowledge_library

Os apps com essa permissão podem acessar o conteúdo da Biblioteca de Conhecimento. Use essa permissão para permitir que uma integração faça o seguinte:

  • Obtenha a lista de categorias
  • Obtenha o conteúdo de uma categoria específica
  • Obtenha a lista de links rápidos

Exportar dados de funcionário

Exporte a lista atualizada de funcionários e respectivos dados de atividade no formato CSV.

export_employee_data

Os apps com essa permissão podem agendar trabalhos de exportação de dados que gerem um arquivo CSV com a lista de todos os usuários do Workplace. O CSV também inclui dados sobre o usuário, bem como informações sobre o respectivo uso recente dos recursos do Workplace.

Bot do bate-papo em grupo

Permite que bots interajam no bate-papo em grupo.

bot_group_chat

Nos apps com essa permissão, os bots podem interagir com membros em um bate-papo em grupo. Use essa permissão para ativar uma integração que crie ou gerencie um bate-papo em grupo com mais de uma pessoa.

Essa permissão é dependente da permissão message.

Gerenciar pesquisas

Crie, atualize, exclua e leia as configurações de pesquisa.

manage_surveys

Os apps com essa permissão podem criar, atualizar, excluir e ler as configurações de pesquisa.

Ler pesquisas

Leia as configurações de pesquisa e receba atualizações de webhook relacionadas.

read_surveys

Os apps com essa permissão podem ler as configurações de pesquisa e receber atualizações de webhook relacionadas.

Ler pesquisas

Leia as configurações de pesquisa e receba atualizações de webhook relacionadas.

read_surveys

Os apps com essa permissão podem ler as configurações de pesquisa e receber atualizações de webhook relacionadas.

Ler conjuntos de pessoas

Leia conjuntos de pessoas.

read_people_sets

Os apps com essa permissão podem ver as configurações de conjuntos de pessoas dinâmicos e assinar as atualizações relacionadas.

Gerenciar conjuntos de pessoas

Gerencie conjuntos de pessoas.

manage_people_sets

Os apps com essa permissão podem criar, atualizar e excluir conjuntos de pessoas na comunidade do Workplace.

Ler publicações importantes

Leia publicações importantes.

read_important_posts

Permite que a integração leia informações sobre a promoção de publicações importantes (ativas atualmente e expiradas).

Gerenciar publicações importantes

Gerencie publicações importantes.

manage_important_posts

Permite que a integração marque publicações do grupo como importantes. Isso faz com que elas apareçam no topo do feed e permite interromper a promoção de publicações importantes prematuramente.

Remover informações do perfil

Remova as informações pessoais de um usuário desativado.

remove_profile_information

Permite que a integração remova campos de perfil (como nome e imagem de perfil) de usuários desativados no Workplace.

Permissões no nível do grupo

Em algumas permissões, é possível limitar a ativação de uma integração em grupos específicos. Isso permite restringir o acesso da integração apenas ao conteúdo que você deseja expor.

Por exemplo, é possível permitir que uma integração de publicação de alertas publique apenas no grupo da equipe ou que a integração de um app de funcionário leia o conteúdo apenas de grupos abertos específicos.

Para especificar uma permissão no nível do grupo em uma integração personalizada, use o painel de acesso do grupo no diálogo Editar integração.

Como ativar permissões no nível do grupo nesta integração

As permissões no nível do grupo podem ser aplicadas às seguintes permissões:

  • Ler conteúdo do grupo: ler publicações, comentários e perfis dos membros em grupos selecionados.
  • Gerenciar conteúdo do grupo: gerenciar publicações e comentários em grupos selecionados.
  • Gerenciar grupos: editar ou remover grupos selecionados e respectivos membros.

É possível configurar uma integração para que as permissões no nível do grupo sejam aplicadas a todos os grupos ou a grupos específicos, conforme escolhido por um administrador do sistema, ou ainda Permitir que os administradores ativem para os seus respectivos grupos.

Fluxo de instalação do administrador

Quando a função Permitir que os administradores ativem para os seus respectivos grupos estiver ativa, um administrador do grupo verá uma nova aba Integrações na tela Gerenciar grupo, o que permite ativar a integração no grupo.

Exemplo de app que pode ser ativado pelo administrador do grupo

Uso e tokens do app

Quando você cria um novo app para o Workplace, um token de acesso é gerado para uso na Graph API, na API de Gerenciamento de Contas ou nos Webhooks.

O token de acesso será mostrado apenas uma vez. Por isso, é importante armazená-lo de forma segura para uso posterior no código.

Fluxo de redefinição de token para um app de integração personalizada

Os tokens de app do Workplace não expiram e não precisam ser atualizados, a menos que sejam redefinidos manualmente. Se você editar as permissões disponíveis para um app, o token existente ainda funcionará, e não será necessário gerar um novo.

Caso seja necessário invalidar um token, será possível redefini-lo por meio do botão Redefinir token de acesso no diálogo Editar aplicativo. Um novo token será gerado e mostrado, e o existente será invalidado imediatamente.

Segurança do token

Os tokens de acesso são poderosos porque concedem acesso aos dados da empresa no Workplace. Ao criar um app, considere o conjunto mínimo de permissões necessárias para realizar os recursos de integração. Além disso, não conceda permissões desnecessárias.

Tenha cuidado ao armazenar tokens ou adicioná-los a repositórios de código para que eles não sejam compartilhados com as pessoas erradas.

Nunca aloque tokens de acesso de produção em repositórios de código públicos.

Você deve armazenar e usar suas credenciais de API apenas no seu ambiente de servidor, bem como garantir que esses valores não serão copiados nem transmitidos para outros locais, como clientes de navegador da web ou apps para celular.

Para incluir uma camada extra de segurança nas integrações, adicione uma lista de liberação de IPs para restringir o uso dos tokens especificamente aos servidores na respectiva lista de endereços IP.

Como adicionar uma lista de liberação de IPs para restringir o uso de tokens a servidores específicos e como exigir prova da chave secreta do app

Remoção automática de permissões não usadas

Uma permissão específica será removida se não for usada por uma integração personalizada para fazer ligações por 30 dias. Após a primeira ocorrência em uma integração personalizada, será disponibilizada uma opção para impedir o processo de remoção.

Caso uma assinatura válida de webhook seja configurada, os webhooks enviados por ela contam como um uso da permissão em questão.

Controles para remoção automática de permissão

Prova da chave secreta do app

Os token de acesso do Workplace não expiram. As integrações personalizadas podem exigir uma prova da chave secreta do app para incluir uma camada adicional de segurança. A ativação da opção "Exigir prova da chave secreta do app" garante que as ligações da API serão sempre feitas a partir de um código do lado do servidor. Ao fazer ligações da API, será exigida uma prova de chave secreta do app, além do token de acesso.

Para gerar uma prova da chave secreta do app com prazo de validade, será necessário concatenar o token com um registro de data e hora do Unix, separado pelo símbolo de barra vertical |. Depois disso, será preciso criar um hash SHA-256 da string concatenada usando a chave secreta do app. Veja um exemplo em PHP:

$appsecret_proof = hash_hmac('sha256', $access_token.'|'.time(), $app_secret);

Alguns sistemas operacionais e linguagens de programação retornarão um registro de data e hora do tipo float. Faça a conversão para um número inteiro antes de calcular a prova da chave secreta do app. Além disso, algumas linguagens de programação criam o hash como um objeto digest. Nesse caso, expresse o hash na forma de um objeto hexadecimal.

Para fazer ligações da API usando a chave secreta do app, passe o hash gerado via parâmetro appsecret_proof, com o conjunto appsecret_time definido como o registro de data e hora usado ao converter em hash a chave secreta do app, juntamente com o token de acesso.

GET https://graph.facebook.com/v2.9/community/groups?
&access_token={access-token}
&appsecret_proof={appsecret_proof}
&appsecret_time={appsecret_time}

As provas de chave secreta do app com registro de data e hora expiram em 5 minutos. Por isso, é recomendado gerar uma nova prova in-line ao fazer cada ligação da Graph API.

Como explorar a funcionalidade da API com o Postman

O Postman é uma ferramenta de trabalho muito usada por APIs da web. Apesar da conveniência em explorar a API do Workplace com o Postman, o parâmetro $appsecret_proof apresenta uma complicação, pois o valor precisa ser calculado e expira após 5 minutos. Seria mais simples se o Postman gerasse o valor no momento da solicitação. Na verdade, o Postman pode fazer isso por meio de seus recursos Parâmetros e Scripts de pré-solicitação. O script a seguir pode ser usado como ponto de partida:

// Add to Postman's Pre-request Script Tab
var access_token = "replace-me";
var app_secret = "replace-me";
var time = (new Date().getTime()/1000|0);
postman.setEnvironmentVariable("access_token", access_token)
postman.setEnvironmentVariable("appsecret_time", time);
postman.setEnvironmentVariable("appsecret_proof", CryptoJS.HmacSHA256(access_token + '|' + time, app_secret));
1) Crie um ambiente ativo (não existe um por padrão). Depois, 2) adicione esses três parâmetros, que são calculados pelo recurso "Script de pré-solicitação".