Autenticação OAuth2.0

Use autenticação OAuth 2.0 para fazer chamadas seguras para a API Externa do Xtremepush. Você pode criar, gerenciar e excluir tokens de forma independente para diferentes conexões.

O /api/oauth/token endpoint suporta os seguintes tipos de subsídios:

• Autenticação de Portador JWT (urn:ietf:params:oauth:grant-type:jwt-bearer): Troque um token JWT assinado por um token de acesso.

• Autenticação de Segredo do Cliente (client_credentials): Autentique usando um ID do cliente e um segredo do cliente.

Apenas POST requisições são aceitas no /api/oauth/token endpoint.

Autenticação do Portador JWT

Para autenticar usando o jwt-bearer tipo de concessão:

1. Você gera um par de chaves pública/privada.

2. Crie seu ID de cliente e envie sua chave pública para o Xtremepush.

3. Assine um token JWT com sua chave privada e troque-o por um token de acesso.

4. Use o token de acesso nas suas requisições de API.

Gerar um par de chaves público/privado

Para usar a autenticação de portador JWT, você deve gerar um par de chaves pública/privada e enviar a chave pública para o Xtremepush. São suportados dois formatos de chave pública:

• Certificado X.509: Contém a chave pública e uma data de validade. O vencimento é lido do certificado e exibido na interface. O Xtremepush valida o certificado para expiração (exp) e válido a partir de (iat) no upload e em cada solicitação. Se seu certificado expirou, as requisições da API falharão.

• Chave Pública (formato SPKI): Contém apenas a chave pública sem validade. Você deve definir o vencimento do token manualmente na página de Integrações da API .

O par de chaves que você gerar deve usar um dos seguintes algoritmos. O Xtremepush impõe comprimentos mínimos de chave para conformidade com FIPS 140:

A seguir, mostra-se exemplos de como criar um par de chaves pública/privada usando RSA 2048:

Chave pública SPKI

#generate a private RSA key with the correct length 2048 (RS256)
openssl genrsa -out privatekey.pem 2048
#output public RSA key
openssl rsa -pubout -in privatekey.pem -out publickey.pem

# generate a private EC key (ES256)
openssl ecparam -name prime256v1 -genkey -noout -out privatekey.pem
# output public EC key
openssl ec -in privatekey.pem -pubout -out publickey.pem

Certificado X.509

# generate a private key with the correct length
openssl genrsa -out privatekey.pem 2048

# generate corresponding public key
# Enter the maximum number of days the cerficate if valid for in MAX CERT AGE
openssl req -new -x509 -key privatekey.pem -out pubcert.pem -days <MAX_CERT_AGE>

# generate a private EC key (ES256)
openssl ecparam -name prime256v1 -genkey -noout -out privatekey.pem

# generate corresponding public key
# Enter the maximum number of days the cerficate if valid for in MAX CERT AGE
openssl req -new -x509 -key privatekey.pem -out pubcert.pem -days <MAX_CERT_AGE>

# This command will ask for additional information. In the last step type `yes` and press Enter
keytool -genkey -alias <UNIQUE_KEY_IDENTIFIER> -keyalg RSA -keysize 2048 -validity <MAX_CERT_AGE> -keystore xtremepush.jks
# Import keys from the KeyStore
keytool -importkeystore -srckeystore xtremepush.jks -destkeystore xtremepush.p12 -deststoretype PKCS12
# Export the public and private keys
openssl pkcs12 -in xtremepush.p12 -nokeys -out pubcert.pem
openssl pkcs12 -in xtremepush.p12 -nodes -nocerts -out privatekey.pem

keytool -genkeypair \
  -alias <UNIQUE_KEY_IDENTIFIER> \
  -keyalg EC \
  -groupname secp256r1 \
  -sigalg SHA256withECDSA \
  -validity <MAX_CERT_AGE> \
  -keystore xtremepush.jks
keytool -importkeystore \
  -srckeystore xtremepush.jks \
  -destkeystore xtremepush.p12 \
  -deststoretype PKCS12
openssl pkcs12 -in xtremepush.p12 -nokeys -out pubcert.pem
openssl pkcs12 -in xtremepush.p12 -nodes -nocerts -out privatekey.pem

No MacOS/Linux, você pode usar o seguinte comando para copiar o conteúdo do certificado para os próximos passos:

pbcopy < filename.pem

Adicionar um ID de cliente

1. Vá para Configurações > Integrações > Integração de API.

2. Clique em Adicionar ID do Cliente.

3. Insira um nome no campo Nome para identificar o ID do seu cliente.

4. No menu suspenso de Tipo , selecione Chave Pública.

5. (Opcional) Se você estiver enviando uma chave pública no formato SPKI, defina uma data de expiração no campo Expira At .

6. Clique em Salvar.

7. Na fileira do seu novo ID de cliente, clique em Adicionar Chave.

8. Cole o conteúdo do seu certificado X.509 ou chave pública SPKI na área de texto e clique em Adicionar.

9. (Opcional) Clique em Definir Escopos na linha para restringir as permissões para esse ID de cliente. Todos os escopos são selecionados por padrão. Veja Acesso e Permissões à API para mais detalhes sobre a definição de escopos.

Obtenha um token JWT

Assine um token JWT com sua chave privada usando a estrutura de payload abaixo, depois troque-o por um token de acesso.

{
    "iss": "<UNIQUE_KEY_IDENTIFIER>",
    "sub": "<UNIQUE_KEY_IDENTIFIER>",
    "aud": "<ENDPOINT_URL>",
    "exp": 1541054464,
    "iat": 1521054464,
    "nbf": 1521054464,
    "jti": "example1234",
    "lifetime": 86400
}

Troque o token JWT por um token de acesso

Envie a seguinte solicitação para trocar seu token JWT por um token de acesso:

POST /api/oauth/token HTTP/1.1
Host: <your-instance>
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<jwt_token>

POST /api/oauth/token
Content-Type: application/json
{
  "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
  "assertion": "<jwt_token>"
}

Método de autenticação legado obsoleto

O método anterior de passar o JWT diretamente como Authorization: Bearer <jwt_token> está obsoleto e será removido em uma versão futura. Migre para o grant_type método acima.

O endpoint retorna a seguinte resposta:

{
    "access_token": "<ACCESS_TOKEN>",
    "token_type": "Bearer",
    "expires_in": 86400
}

Vida útil do token de acesso

Você pode definir a vida útil do token de acesso para 86400 segundos incluindo uma lifetime reivindicação no seu token JWT. A vida útil não pode se estender além do vencimento do ID do Cliente configurado na interface.

O padrão pode ser reduzido no futuro, portanto, sempre siga o tempo de vida indicado na resposta do /oauth/token endpoint. Tokens de acesso não podem ser revogados após a emissão. Use prazos de validade curtos e alterne as chaves regularmente.

Se receber uma 401 resposta, solicite um novo token mesmo que o token atual ainda não tenha expirado.

Use o token nas suas Solicitações de API

Adicione o Authorization cabeçalho a todas as requisições de API Externa:

Authorization: Bearer <access_token>

Autenticação de Segredo do Cliente

Use esse método com o client_credentials tipo de subsídio. O Xtremepush gera um segredo de cliente para você quando você cria um ID de cliente. Não é necessário nenhum par de chaves.

Para autenticar usando o client_credentials tipo de concessão:

1. Crie um ID de cliente no Xtremepush para gerar um segredo de cliente.

2. Troque seu ID de cliente e seu segredo por um token de acesso.

3. Use o token de acesso nas suas requisições de API.

Adicionar um ID de cliente

1. Vá em Configurações > Integrações > Integração de API.

2. Clique em Adicionar ID do Cliente.

3. Insira um nome no campo Nome como referência interna.

4. No menu suspenso do Tipo , selecione Secreto.

5. (Opcional) Defina uma data de expiração no campo Expira Em .

6. Clique em Salvar.

7. Aparece um diálogo Gerado por Segredo do Cliente exibindo o segredo do seu cliente. Copie e armazene de forma segura, pois não será mostrado novamente.

8. (Opcional) Clique em Definir Escopos na linha para restringir as permissões para esse ID de cliente. Todos os escopos são selecionados por padrão. Veja Acesso e Permissões à API para mais detalhes sobre a definição de escopos.

Obtenha um token

Envie o seguinte pedido para trocar suas credenciais de cliente por um token de acesso:

POST /api/oauth/token HTTP/1.1
Host: <your-instance>
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&lifetime=86400

POST /api/oauth/token
Content-Type: application/json
{
  "grant_type": "client_credentials",
  "client_id": "<CLIENT_ID>",
  "client_secret": "<CLIENT_SECRET>",
  "lifetime": 86400
}

O endpoint retorna a seguinte resposta:

{
    "access_token": "<ACCESS_TOKEN>",
    "token_type": "Bearer",
    "expires_in": 86400
}

Vida útil do Token de Acesso

Você pode definir a vida útil do token de acesso para 86400 segundos incluindo uma lifetime reivindicação no seu token JWT. A vida útil não pode se estender além do vencimento do ID do Cliente configurado na interface.

O padrão pode ser reduzido no futuro, portanto, sempre siga o tempo de vida indicado na resposta do /oauth/token endpoint. Tokens de acesso não podem ser revogados após a emissão. Use prazos de validade curtos e alterne as chaves regularmente.

Se receber uma 401 resposta, solicite um novo token mesmo que o token atual ainda não tenha expirado.

Use o token nas suas requisições de API

Adicione o Authorization cabeçalho a todas as requisições de API Externa:

Authorization: Bearer <access_token>