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.

Cuidando do valor secreto emitido

Para as três chaves, ao concluir a emissão, o valor secreto do token aparece na tela. Esse valor é a própria chave. É ele que você usa ao colocá-la em um servidor ou site. Copie e guarde o valor ali mesmo, logo após a emissão. Você também pode conferi-lo novamente na tela de detalhes do token.

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. 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, o valor secreto do token aparece na tela. Copie-o ali mesmo e guarde-o em um lugar seguro. O formato da tela é igual ao resultado da emissão do Delivery Access Token abaixo.

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.
3. No campo de nome, digite Servidor de cadastro automático de produtos novos.
4. Em Space Role, escolha Cadastro de produtos. Não escolha Administrator.
5. Pressione o botão Criar para emitir.

Quando a emissão termina, o valor secreto do token aparece na tela. Copie-o ali mesmo 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. O formato da tela é igual ao resultado da emissão do Delivery Access Token abaixo.

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.
3. No campo de nome, digite Entrega para o site da loja.
4. No campo de descrição, você pode anotar onde essa chave é usada. (É opcional.)
5. Em Space Role, escolha Somente leitura de produtos. Não escolha Administrator.
6. Pressione o botão Criar para emitir.

Quando a emissão termina, o valor secreto do token aparece na tela. Copie-o ali mesmo e guarde-o em um lugar seguro.

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.
• 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.