Provedor de Segurança - Chave de API¶
O provedor de segurança API Key permite que os administradores protejam APIs REST do Vinyl usando "chaves de API ". Uma chave API é um código gerado pelo Vinyl. O consumidor passa a chave API para o Vinyl ao fazer solicitações de API REST. Como cada chave de API está associada a um usuário individual, isso fornece autenticação e autorização.
Chaves de API Versus Nome de Usuário e Senhas¶
Uma chave de API é semelhante a um nome de usuário e senha, pois é um segredo compartilhado entre o cliente e o servidor. As chaves de API compartilham vários pontos fracos com esquemas de autenticação de nome de usuário e senha, como autenticação básica HTTP:
- As chaves de API podem vazar.
- A distribuição de chaves de API pode ser difícil de gerenciar.
No entanto, as chaves de API têm vantagens sobre nomes de usuário e senhas:
- As chaves de API têm maior entropia do que as combinações de nome de usuário/senha.
- As chaves de API podem sobreviver a uma redefinição de senha.
- As chaves API podem ser facilmente revogadas.
- As chaves de API podem ser rotacionadas.
- As chaves de API são mais rápidas. As senhas devem ter hash, o que é deliberadamente lento.
Usos de Chave de API¶
Apesar dos pontos fracos das chaves de API, elas ainda podem ser apropriadas para determinados cenários, incluindo:
- Contas de nível de serviço
- Comunicação entre aplicativos
- Comunicação servidor a servidor
- Acesso somente leitura
- Informações não confidenciais
Material de Chave de API¶
As chaves de API do Vinyl consistem em um número criptograficamente aleatório de 128 bits. As chaves são codificadas em base64url.
Veja a seguir um exemplo de chave de API:
DLOo9sPS5slJEMHpXBFt3g
Configuração¶
Parâmetros¶
O provedor de segurança da chave de API define os seguintes parâmetros:
| Parâmetro | Valor padrão | Descrição |
|---|---|---|
| AllowApiKeyInQueryString | Falso | Indica se o provedor de segurança deve aceitar chaves de API passadas na cadeia de consultar. Por padrão, o provedor de segurança permitirá apenas que chaves de API sejam passadas nos cabeçalhos de solicitação HTTP. Veja abaixo para mais informações. |
| PermitirConexõesUnsafeHttp | Falso | Indica se o provedor de segurança deve aceitar chaves de API enviadas por meio de uma solicitação HTTP insegura. Por padrão, o provedor de segurança só permitirá que chaves de API sejam transmitidas por meio de uma conexão HTTPS segura. Veja abaixo para mais informações. |
Cabeçalho HTTP Vs. String de Consultar¶
Normalmente, o cliente passará a chave de API por meio de um cabeçalho personalizado. O cabeçalho deve ser denominado X- API-Key. Isto limita o risco de exposição. Por exemplo, em contraste com os parâmetros de string de consultar, os cabeçalhos HTTP raramente são registrados no disco.
O exemplo a seguir demonstra como passar a chave de API como um cabeçalho HTTP:
GET /Vinyl/rest/v1/sales/customers HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g
Alguns clientes podem não ter acesso aos cabeçalhos de solicitação HTTP. Se for esse o caso e nenhuma outra solução alternativa estiver disponível, os administradores de segurança poderão ativar a opção AllowApiKeyInQueryString. Isso forçará o Vinyl a aceitar a chave API como parâmetro de string de consultar. O parâmetro da string de consultar deve ser denominado apiKey.
O exemplo a seguir demonstra como passar a chave de API como um parâmetro de string de consultar:
GET /Vinyl/rest/v1/sales/customers?apiKey=DLOo9sPS5slJEMHpXBFt3g HTTP/1.1
HOST: example.com:443
Accept: application/json
Observe que há um conflito potencial aqui. Ao consultar a API REST, os parâmetros de string de consultar normalmente são mapeados para nomes de campos de recursos. Se as chaves de API puderem ser passadas como um parâmetro de string de consultar, os recursos não poderão ter um campo denominado "apiKey".
HTTPS X HTTP¶
Para evitar ataques man-in-the-middle, as chaves de API devem ser passadas através de uma conexão HTTPS segura. O Vinyl reforça isso ignorando as chaves de API passadas por HTTP.
No entanto, em alguns ambientes, a conexão HTTPS pode ser encerrada antes do servidor web. Neste cenário, os administradores de segurança podem ativar a opção AllowUnsafeHttpConnections para forçar o Vinyl a aceitar chaves de API enviadas através de conexões HTTP inseguras.