Como autenticar uma aplicação A2A

Este documento fornece um guia passo a passo sobre como autenticar uma aplicação criada no módulo A2A em um cliente REST ou HTTP de sua escolha.

As APIs do módulo A2A do Segura® suportam os métodos de autenticação OAuth v1.0, OAuth v2.0 e AWS.

Embora o OAuth 2.0 seja o método de autenticação recomendado, o módulo também suporta integrações seguras com outros protocolos, como OAuth 1.0 e AWS.

Autenticação OAuth v1.0

O OAuth v1.0 é um método de autenticação que utiliza um conjunto de consumer_key, consumer_secret, token_key, e token_secret para identificar e autorizar o acesso da aplicação.

Pré-requisitos

• Uma aplicação previamente adicionada que utiliza OAuth v1.0 como método de autenticação e uma autorização previamente adicionada para esta aplicação. Saiba mais em Como gerenciar aplicações no A2A e Como gerenciar autorizações no A2A.

Obter os parâmetros de requisição para OAuth v1.0

Para fazer requisições usando OAuth v1.0, é necessário informar os valores dos seguintes parâmetros:

• consumer_key
• consumer_secret
• token_key
• token_secret

Para encontrar esses valores, siga os passos abaixo:

1. No Segura®, na barra de navegação, passe o mouse sobre o Menu de produtos, e selecione A2A.
2. No menu lateral, selecione Aplicações.
3. Na lista de aplicações, encontre a aplicação desejada ou use o filtro Método de autenticação > OAuth 1.0.
4. No botão Ações, clique em Autorizações.
5. Na tela Autorização da aplicação, encontre a autorização desejada ou use os filtros de pesquisa.
6. No botão Ações, clique em Visualizar.
7. Clique em Exibir nos campos Consumer Key, Consumer Secret, Token e Token Secret para visualizar as informações.
8. Copie as informações e guarde-as em um local seguro.

Fazer uma requisição usando o OAuth v1.0

Há várias maneiras de fazer uma requisição de autenticação utilizando o OAuth v1.0. No exemplo a seguir, a linguagem Python é usada para demonstração.

Utilize o script a seguir:

import requests
import urllib3
from requests_oauthlib import OAuth1


def make_oauth1_request():
    url = "https://<SENHASEGURA_HOSTNAME>/<ENDPOINT>"
    consumer_key = "CONSUMER_KEY"
    consumer_secret = "CONSUMER_SECRET"
    token_key = "TOKEN_KEY"
    token_secret = "TOKEN_SECRET"


    oauth = OAuth1(consumer_key, consumer_secret, token_key, token_secret)


    try:
        response = requests.get(url, auth=oauth, verify=False)
        if response.status_code == 200:
            print("Request was successful!")
            print("Response:")
            print(response.text)
        else:
            print("Request failed with status code:", response.status_code)
    except requests.exceptions.RequestException as e:
        print("An error occurred:", e)


if __name__ == "__main__":
    urllib3.disable_warnings()
    make_oauth1_request()

/api/pam/credential

/api/pam/device

Parâmetros
A tabela a seguir apresenta uma lista com os parâmetros de autenticação obrigatórios e opcionais.

Autenticação OAuth v2.0

O OAuth v2.0 é um método de autenticação que utiliza um Client ID e um Client Secret para solicitar um access_token com tempo limitado e acessar os recursos da Segura®.

Pré-requisitos

• Uma aplicação adicionada que utiliza OAuth v2.0 como método de autenticação e uma autorização previamente adicionada para esta aplicação. Saiba mais em Como gerenciar aplicações no A2A e Como gerenciar autorizações no A2A.

Obter o client_id e client_secret para OAuth v2.0

Para fazer requisições usando OAuth v2.0, é necessário informar os valores dos seguintes parâmetros:

• client_id
• client_secret
• access_token

Para encontrar esses valores, siga os passos abaixo:

1. No Segura®, na barra de navegação, passe o mouse sobre o Menu de produtos, e selecione A2A.
2. No menu lateral, selecione Aplicações.
3. Na lista de aplicações, encontre a aplicação desejada ou use o filtro Método de autenticação > OAuth 2.0.
4. No botão Ações, clique em Autorizações.
5. Na tela Autorização da aplicação, encontre a autorização desejada ou use os filtros de pesquisa.
6. No botão Ações, clique em Visualizar.
7. Clique em Exibir nos campos Client ID, Client Secret para visualizar as informações.
8. Copie as informações e guarde-as em um local seguro.

Obter um access_token

Em posse das chaves de acesso client_id e client_secret, você pode solicitar o access_token e autenticar sua aplicação. Siga os passos abaixo:

1. No cliente HTTP ou REST de sua escolha, como o Postman, crie uma coleção.

2. Na guia Authorization> Type, selecione OAuth 2.0.

3. Em Configure New Token > Configuration Options > Grant Type, selecione Client Credentials.

4. Em Access Token URL, faça uma requisição para o endpoint do appliance. Por exemplo,

https://applianceURI/api/oauth2/token

5. Em Client ID, insira o valor obtido no passo 7 da seção Obter o client_id e client_secret para OAuth v2.0.

6. Em Client Secret, insira o valor obtido no passo 7 da seção Obter o client_id e client_secret para OAuth v2.0.

7. Clique em Get New Access Token, na parte inferior da página.

8. Clique em Proceed para abrir a página MANAGE ACCESS TOKENS e visualizar o Access Token.

9. Use este Access Token para fazer as requisições nas APIs do módulo A2A da Segura®.

Solicitar um novo token de acesso

Se necessário, solicite o novo token de acesso para o A2A utilizando o seguinte URI:

POST /api/oauth2/token

e os parâmetros obrigatórios a seguir:

Parâmetros

Envie os parâmetros codificados como formulário no corpo da requisição, com o cabeçalho Content-Type: application/x-www-form-urlencoded. O endpoint não aceita corpo JSON. Um corpo JSON retorna 401 com o erro unsupported_grant_type.

Exemplo de requisição

POST /api/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=765299ec425cf0255badc739c2dce1b10634973e1&client_secret=f13aeddeb57f262835871dab5d839b70

Resposta esperada

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIzY2E4YTk4ZDkwNzU0MzgxMjMzNGY3ZjVkYmFmY2E2NTA1ZTMzMTlmYiJ9.efqHZdlij6sQcj_l9RbNNKxDbf81CbIoTFwdIk",
    "refresh_token": "def50200b4f8e1c3a9d27e6f05b8c4a1d93e7f2b6c08a5d1e4f7b9c2a6d3e8f1b5c7a0d4e9f2"
}

Guarde o access_token em um local seguro e para utilize-o nas próximas chamadas de cada método.

Autenticação AWS

O AWS é um método de autenticação que permite que as aplicações acessem dados armazenados usando as AWS Access Keys e as Secret Access Keys da AWS, juntamente com uma chave exclusiva gerada pelo Segura® DSM. Esse método é usado principalmente para integração com aplicativos de DevOps. Para mais informações sobre autenticação AWS, acesse a documentação do Autenticador da AWS.

Requisições e respostas

As requisições são feitas usando métodos HTTP como GET, POST, PUT e DELETE.

Os parâmetros incluem id, identifier, hostname, username, entre outros, e a depender da chamada, podem ser enviados no path da URL ou no body da requisição.

As respostas são retornadas em formato JSON, facilitando a análise e o gerenciamento de dados fornecidos pela API.

Exemplo:
Ao fazer uma requisição para o endpoint GET /api/pam/device/14, a API retorna os dados do dispositivo cujo id é igual a 14.

{
    "code": 200,
    "response": {
        "status": 200,
        "message": "Device 14",
        "error": false,
        "error_code": 0,
        "detail": "",
        "mensagem": "Device 14",
        "erro": false,
        "cod_erro": 0
    },
    "tenant": "teste",
    "device": {
        "id": "14",
        "hostname": "API device",
        "ip": "10.66.33.17",
        "model": "Gmail",
        "type": "Desktop",
        "vendor": "Linux",
        "site": "AWS",
        "device_domain": "my_device_domain",
        "connectivities": "HTTP:80,SSH:22,MySQL:65535",
        "session_remote_config": "HTTP::",
        "device_tags": "test"
    }
}

Cada documento apresenta uma descrição dos campos do corpo da resposta.
Acesse o documento GET | List a device by [id] para visualizar a descrição dos campos listados na resposta acima.

Erros

A API retorna códigos de status HTTP padrão e inclui mensagens de erro no corpo da resposta para facilitar a compreensão e a resolução de problemas.

Exemplo:
A mensagem a seguir retorna um erro para o caso de dispositivo não encontrado.

{
    "code": 400,
    "response": {
        "status": 400,
        "message": "1011: Device not found",
        "error": true,
        "error_code": 1,
        "detail": "",
        "mensagem": "1011: Device not found",
        "erro": true,
        "cod_erro": 1
    },
    "exception": {
        "code": 1011,
        "message": "1011: Device not found",
        "detail": null
    }
}

Acesse a documentação de cada método para descrições detalhadas dos erros, suas possíveis causas e soluções.