Token

Imagine que você criou a loja virtual de uma loja de roupas. Você quer puxar os produtos cadastrados no estúdio de conteúdo e exibi-los no site da loja que o visitante vê. Só que esse site não é uma pessoa, é um programa. Ele não consegue fazer login com usuário e senha como uma pessoa faz. Nesses casos, o token é a chave secreta emitida para que um site ou programa possa acessar o conteúdo no lugar de uma pessoa.

Pense no token como uma única chave que abre uma fechadura. Quem tem essa chave consegue manipular o conteúdo dentro de um escopo definido, sem precisar fazer login. Por isso o token deve ser tratado exatamente como uma senha. Não se deve mostrá-lo a qualquer pessoa, e, se ele vazar, quem o tiver em mãos pode usar essas permissões da mesma forma.

No WEEGLOO existem três tipos de chave com usos diferentes. A chave poderosa que substitui a conta inteira (Personal Access Token), a chave que lê e escreve conteúdo dentro de um único Space (Space Access Token) e a chave somente de leitura para ler e enviar conteúdo a um site público (Delivery Access Token). Nesta página, você vê o que é cada uma das três chaves e quando usá-las, e depois emite cada uma diretamente no estúdio de conteúdo.

As três chaves têm usos diferentes

Primeiro, veja a diferença entre as três de uma só vez.

O essencial é o seguinte. O Personal Access Token é mais parecido com uma chave-mestra que substitui por completo uma pessoa da conta; o Space Access Token é a chave que lê e escreve conteúdo apenas dentro de um único Space; e o Delivery Access Token é a chave somente de leitura, que apenas lê o conteúdo publicado. Basta escolher a chave adequada conforme o que você quer fazer: se a tarefa abrange a conta inteira, se envolve escrever dentro de um único Space, ou se é apenas ler em um site público.

A chave que substitui a conta inteira: Personal Access Token

O Personal Access Token é uma chave que usa, tal como estão, as permissões da própria conta que a emitiu. Com essa chave, é possível fazer, sem login, tudo o que essa conta pode fazer no estúdio de conteúdo. Isso inclui tarefas de gerenciamento como cadastrar, editar ou publicar produtos.

Por isso essa chave é poderosa. Se você a entregar a um programa que sobe e edita conteúdo automaticamente no lugar de uma pessoa, esse programa consegue trabalhar como o dono da conta. Para tarefas de gerenciamento que precisam transitar entre vários Space ou lidar até com as configurações do Space, essa é a chave necessária. Ao contrário, para um trabalho em que basta ler e escrever conteúdo dentro de um único Space, é mais seguro restringir as permissões com o Space Access Token descrito adiante, em vez desta chave que substitui a conta inteira.

Por ser poderosa, exige cuidado ao ser manipulada. Esta chave não deve ser colocada em um cliente público entregue ao visitante. Se for colocada em um lugar público, qualquer pessoa pode extrair a chave, e quem a obtiver pode usar as permissões da conta que a emitiu da mesma forma. Quando você só vai puxar e exibir produtos em um site público, em vez desta chave poderosa, use o Delivery Access Token abaixo.

Para emitir o Personal Access Token, basta definir o nome. Você não escolhe um escopo de permissão à parte, porque ele herda exatamente as permissões que a conta que o emitiu possui.

A chave que lê e escreve em um Space: Space Access Token

O Space Access Token é uma chave usada apenas dentro de um único Space específico. Ao contrário do Delivery Access Token, que só lê, com esta chave é possível não apenas ler, mas também escrever o conteúdo dentro daquele Space. Um programa pode cadastrar produtos novos ou alterá-los no lugar de uma pessoa, sem que ela precise fazer login.

Por exemplo, imagine que você queira permitir que o visitante deixe uma mensagem de contato no site da loja de roupas sem fazer login. O cliente usado pelo visitante precisa gravar essa mensagem como um novo texto no Space da loja de roupas, mas com o Delivery Access Token, que é somente de leitura, não é possível escrever. Por outro lado, colocar no cliente o Personal Access Token, que substitui a conta inteira, faz com que, se essa chave vazar, não só a loja de roupas, mas tudo o que a conta alcança fique em risco. O que se usa nesse caso é o Space Access Token, que escreve apenas dentro de um único Space. Permitir que o visitante escreva conteúdo a partir do seu cliente é o uso mais típico desta chave, e ela também é usada quando um servidor cadastra e edita conteúdo automaticamente.

O Space Access Token só vale dentro de um único Space. Ainda que possa ler e escrever o conteúdo do Space da loja de roupas, ele não consegue espiar outros Space, alterar as configurações do Space, nem mexer na organização e na conta. Por isso, mesmo para a mesma tarefa de escrita, ele é mais seguro do que o Personal Access Token.

Onde colocar esta chave é algo que você define conforme o uso. Ela pode ficar em um servidor ou no cliente que o visitante usa. A segurança se garante não por esconder a chave em algum lugar, mas por restringir o papel atrelado conforme aquele uso. Por isso, a seguir, o importante é como atrelar o papel.

Atrele um papel para definir o que ele pode ler e escrever

Ao emitir um Space Access Token também, você define até onde esta chave pode ir por meio de um SpaceRole (papel) e o atrela junto. Ao contrário do papel do Delivery Access Token, que define "até onde é possível ler", o papel do Space Access Token define "até onde é possível ler e escrever".

O papel a atrelar deve ser restringido conforme o lugar onde a chave fica. Se for uma chave que cadastra e edita produtos automaticamente em um servidor, atrele um papel que permita apenas Read, Create e Edit sobre os produtos (Content) e não inclua Delete nem Publish. Já se for uma chave colocada no cliente do visitante para receber apenas mensagens de contato, atrele um papel mais restrito que permita apenas criar (Create) "mensagens de contato". Assim, mesmo que esse valor vaze, não é possível fazer nada além do que cada um permitiu.

Não atrele o papel Administrator, que pode manipular tudo. Quanto mais uma chave também escreve, e especialmente quanto mais ela fica em um lugar que o visitante pode ver, mais seguro é atrelar um papel restrito o bastante para que você consiga suportar mesmo que ela vaze.

Como criar um papel que permite escrita é tratado em Papéis e permissões. O papel Cadastro de produtos criado nessa página é um exemplo de papel de escrita, que permite até cadastrar e editar produtos.

A chave que só lê em um Space: Delivery Access Token

O Delivery Access Token é uma chave somente de leitura que só funciona dentro de um único Space específico. Com essa chave, só é possível ler o conteúdo que está em estado Published (publicado) dentro desse Space. O conteúdo em estado Draft que ainda não foi publicado não é lido por essa chave, e também não é possível editar nem excluir nada com ela.

Essa é justamente a chave usada quando o site da loja que o visitante vê puxa e exibe os produtos. O site só precisa exibir os produtos, não precisa cadastrá-los nem apagá-los, então uma chave restrita que só consegue ler já é suficiente. Mesmo que essa chave vaze, apenas o conteúdo publicado é lido, e não é possível danificar o conteúdo.

O que significa publicar (Published) um conteúdo e por que é preciso publicar para que ele fique disponível externamente (entregue) é tratado em Estados e publicação.

Atrele um papel restrito para limitar o que pode ser lido

Ao emitir um Delivery Access Token, você define até onde essa chave pode ler por meio de um SpaceRole (papel) e o atrela junto. Um papel é um conjunto de permissões que define "o que pode ser feito e até qual ação". Quando você atrela um papel à chave, ela só consegue ler até onde o papel atrelado permite.

No caso do site da loja, basta ler os "produtos", então você cria e atrela um papel restrito que permite apenas Read sobre os produtos (Content). Assim, mesmo que essa chave vaze, apenas as informações dos produtos são lidas, sem que outro conteúdo ou informações de membros vazem.

Não atrele o papel Administrator, que pode manipular tudo. O Administrator é o papel de permissão máxima, capaz de manipular tudo dentro desse Space. Atrelar uma permissão tão ampla a uma chave de site público que só precisa ler aumenta o risco quando a chave vaza. O mais seguro é criar à parte um papel restrito que leia apenas o necessário e atrelá-lo.

Como criar um papel e restringir suas permissões é tratado em Papéis e permissões. Veja essa página e prepare com antecedência o papel que permite apenas Read de produtos, para atrelar à chave do site público.

Defina com Referrers permitidos os sites que podem usar a chave

Se o papel atrelado define o que se pode ler com esta chave, os Referrers permitidos definem de onde ela pode ser usada. Essa configuração fica na parte de baixo da tela de emissão e pode ser alterada mesmo depois da emissão.

O valor inicial é Sem restrição. Nesse estado, o conteúdo é entregue não importa de qual site venha a chamada. Ao escolher Permitir apenas os referrers indicados, aparece um campo para escrever o endereço, e a partir daí só passam as requisições vindas dos endereços anotados ali. Se o endereço do site da loja for https://shop.example.com, anote esse endereço. Assim, mesmo que o valor desta chave caia nas mãos de outra pessoa, esse valor não funciona fora do site da loja.

Você pode anotar vários endereços. Ao pressionar o botão Adicionar, surge mais um campo, e ao pressionar o ícone de apagar à direita do campo, aquela linha desaparece.

Para permitir de uma vez os endereços que ficam abaixo de shop.example.com, escreva *. no começo, assim: https://*.shop.example.com. Escrito dessa forma, ficam incluídos todos os endereços que tenham algo na frente, como event.shop.example.com. Mas, mesmo escrito assim, o próprio https://shop.example.com não fica incluído. Se você precisa permitir os dois, coloque https://shop.example.com também em uma linha separada.

Esta lista funciona para o caso em que o visitante abre o site no navegador e o conteúdo é buscado a partir dali. Se quem usa esta chave for um programa que roda em um servidor, e não um site, não há como saber de qual site a requisição veio, então deixe Sem restrição nesse tipo de chave.

Cuidando do valor secreto emitido

Para as três chaves, ao concluir a emissão você é levado à tela de detalhes daquela chave. O valor secreto do token está no campo Token de Informações básicas, e, ao pressionar o botão Copiar à esquerda do campo, o valor inteiro é copiado. Como o valor é mais comprido que o campo, a parte final aparece cortada na tela, mas o que se copia é o valor inteiro. Esse valor é a própria chave, e é ele que você usa ao colocar a chave em um servidor ou site. Mesmo que você não o tenha copiado logo após a emissão, é possível voltar depois a esta tela de detalhes e copiá-lo. O ID que fica no item Token do painel à direita é o identificador que aponta para esta chave, e não é o valor secreto.

Mas cada chave fica em um lugar diferente.

• Trate o Personal Access Token como uma senha. Por ser uma chave poderosa, mantenha-a apenas dentro do servidor e não a coloque em um cliente público que o visitante vê nem em código que outras pessoas possam ver.
• Para o Space Access Token, ajuste onde colocá-lo pelo papel atrelado. Para uma chave que fica em um servidor, atrele um papel de escrita na medida do necessário; para uma chave que fica em um cliente entregue ao visitante, atrele um papel restrito o bastante para que você consiga suportar mesmo que ela vaze (por exemplo, criar apenas um tipo de texto). Não atrele Administrator nem papéis de escrita amplos a uma chave colocada em um lugar público.
• O Delivery Access Token, ao contrário, tem como finalidade original ser colocado no site público que o visitante vê. Na prática, qualquer pessoa que abrir o site pode ver esse valor, mas, como você atrelou um papel restrito, mesmo que alguém pegue esse valor não consegue fazer nada além do escopo de leitura que o papel permite. Por isso, colocá-lo no site em si não é um problema. Se, além disso, você anotar em Referrers permitidos o endereço do site da loja, mesmo que o valor caia nas mãos de outra pessoa esse valor não pode ser usado fora daquele site. Apenas não o espalhe à toa para fora do site onde você pretende usá-lo.

Se você perder uma chave ou achar que ela foi usada de forma diferente da pretendida, basta apagar essa chave, emitir uma nova e fazer a substituição.

Emitir um Personal Access Token

Vamos emitir o Personal Access Token que será entregue ao programa que sobe automaticamente os produtos novos toda noite.

1. Nas configurações da conta, abra a tela de Personal Access Token.
2. Pressione o botão Criar no canto superior direito.
3. No campo de nome, digite Upload noturno de produtos novos. Esse nome serve para você reconhecer depois para que fim a chave foi criada.
4. Pressione o botão Guardar para emitir.

Quando a emissão termina, você é levado à tela de detalhes daquela chave. Copie o valor secreto do token nessa tela, como explicado em Cuidando do valor secreto emitido, e guarde-o em um lugar seguro no servidor onde este programa roda.

Emitir um Space Access Token

Desta vez, vamos emitir o Space Access Token que um servidor vai usar para cadastrar produtos automaticamente no Space da loja de roupas. Essa chave é usada no Space da loja de roupas e vem atrelada a um papel que pode cadastrar e editar produtos.

Primeiro, é preciso que exista no Space o papel que será atrelado a essa chave. Prepare com antecedência, em Papéis e permissões, um papel que possa Read, Create e Edit os produtos (Content). A seguir, vamos supor que esse papel foi criado com o nome Cadastro de produtos.

A tela de emissão e gerenciamento fica dentro das configurações do Space, junto com a do Delivery Access Token.

1. Nas configurações do Space da loja de roupas, abra a tela de Space Access Token.
2. Pressione o botão Criar no canto superior direito da lista. A tela de criação de Space Access Token se abre.
3. No campo Nome, digite Servidor de cadastro automático de produtos novos.
4. Em SpaceRole, escolha Cadastro de produtos. Não escolha Administrator.
5. Em Referrers permitidos, deixe Sem restrição como está, porque esta chave é usada em um servidor, e não em um site.
6. Pressione o botão Criar no canto superior direito da tela para emitir.

Quando a emissão termina, você é levado à tela de detalhes daquela chave. Copie o valor secreto do token nessa tela, como explicado em Cuidando do valor secreto emitido, e guarde-o em um lugar seguro. Aqui atrelamos um papel que pode cadastrar e editar produtos, então esta chave é usada em um servidor que precisa desse papel. Se você tiver de colocá-la diretamente no cliente que o visitante usa, emita à parte e use uma chave atrelada a um papel mais restrito, restrito o bastante para que você consiga suportar mesmo que ela vaze. Em uma chave entregue ao visitante dessa forma, anote também o endereço daquele site em Referrers permitidos.

Emitir um Delivery Access Token

Desta vez, vamos emitir o Delivery Access Token que o site da loja vai usar ao puxar e exibir os produtos. Essa chave fica atrelada ao Space da loja de roupas, e você atrela junto um papel restrito que consegue ler os produtos.

Primeiro, é preciso que exista no Space o papel que será atrelado a essa chave. Prepare com antecedência, em Papéis e permissões, um papel que permita apenas Read sobre os produtos (Content). A seguir, vamos supor que esse papel foi criado com o nome Somente leitura de produtos.

1. Nas configurações do Space da loja de roupas, abra a tela de Delivery Access Token.

2. Pressione o botão Criar no canto superior direito da lista. A tela de criação de Delivery Access Token se abre.

3. No campo Nome, digite Entrega para o site da loja.

4. No campo Descrição, você pode anotar onde esta chave é usada. (É opcional.)

5. Em SpaceRole, escolha Somente leitura de produtos. Não escolha Administrator.

   

6. Na parte de baixo da tela, em Referrers permitidos, escolha Permitir apenas os referrers indicados. É a configuração que restringe esta chave ao site da loja.

7. No campo que apareceu, digite https://shop.example.com.

8. Pressione o botão Adicionar.

9. No campo recém-criado, digite https://*.shop.example.com.

   

10. Pressione o botão Criar no canto superior direito da tela para emitir.

Quando a emissão termina, você é levado à tela de detalhes daquela chave. Copie o valor secreto do token nessa tela, como explicado em Cuidando do valor secreto emitido, e coloque-o no site da loja para usá-lo.

Apague as chaves que você não usa mais

É mais seguro apagar as chaves que deixaram de ser usadas, em vez de deixá-las como estão. Encontre na lista de tokens a chave que você não usa mais e apague-a. Quando você apaga uma chave, não é mais possível acessar nada com ela. O mesmo vale quando você acha que uma chave vazou. Basta apagar a chave suspeita, emitir uma nova e fazer a substituição.

O que fazer a seguir

• Papéis e permissões: crie o papel somente de leitura para atrelar ao Delivery Access Token e o papel de leitura e escrita para atrelar ao Space Access Token.
• Estados e publicação: o que é lido com o Delivery Access Token é apenas o conteúdo em estado Published. Entenda o que é publicar.
• Space Access Token: trata de especificações técnicas, como o formato das requisições necessárias para emitir um Space Access Token a partir de um programa ou para ler e escrever conteúdo com esta chave.
• Delivery Access Token: trata de especificações técnicas, como as regras exatas de notação para anotar endereços em Referrers permitidos e o formato das requisições necessárias para lidar com esta chave a partir de um programa.
• Referência da API: trata de especificações técnicas, como o formato das requisições necessárias para emitir outros tokens ou lidar com o conteúdo diretamente a partir de um programa.