Configuração

Integração

Esta página descreve o processo completo para integração com nossa plataforma.

O setup estabelece uma relação segura entre sua aplicação e a Autra por meio de criptografia assimétrica e credenciais OAuth.

Este processo deve ser realizado uma única vez por ambiente.

---

🔐

Importante

Sandbox e Production possuem chaves e credenciais totalmente independentes.

---

Quando o setup é necessário

O setup deve ser executado quando:

• Um novo tenant é criado
• Um novo ambiente é configurado
• É necessária a rotação de chaves de segurança

Após o setup, sua aplicação estará apta a autenticar e consumir a API da Autra.

---

Visão geral do fluxo de setup

O processo de setup segue obrigatoriamente a seguinte ordem:

1. Receber o tenantID conforme pontos descritos no link Segurança
2. Geração de um par de chaves RSA
3. Upload da public key para a Autra
4. Assinatura e validação de um challenge
5. Geração das credenciais OAuth

Cada etapa depende da conclusão da etapa anterior.

---

1. Geração do par de chaves

Sua aplicação deve gerar um par de chaves criptográficas assimétricas.

Requisitos técnicos:

• Algoritmo RSA
• Tamanho mínimo de 2048 bits
• A private key nunca deve ser compartilhada
• A public key será registrada na Autra

Exemplo de geração de chaves (OpenSSL)

Essas chaves serão usadas exclusivamente para provar a identidade da sua aplicação durante o setup.

📘

Exemplo - Geração da chave RSA

O exemplo abaixo pode sofrer variações de acordo com o seu sistema operacional.

Bash

set -e

echo "🔐 Gerando chave privada RSA 2048..."
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private_key.pem

echo "🔓 Extraindo chave pública..."
openssl pkey -in private_key.pem -pubout -out public_key.pem

echo "✅ Chaves geradas com sucesso!"
echo " - private_key.pem (mantenha em segurança)"
echo " - public_key.pem

Após gerar a public key, registre-a na Autra utilizando o endpoint Upload public key.

Esse passo associa a chave pública ao tenant e ao ambiente atual.

---

2. Verificação da assinatura (Setup inicial)

Após o upload da public key, a Autra retorna um challenge criptográfico que deve ser assinado com a private key correspondente.

Este é um procedimento de setup, realizado uma única vez por chave, e não faz parte do fluxo de execução da aplicação.

---

⚠️

Importante

A assinatura do challenge é um passo manual ou automatizado de onboarding.
Ela comprova a posse da private key associada à public key enviada, seu procedimento deve ser realizado no máximo até 30 minutos após seu enviado realizado no passo anterior.

Após a validação bem-sucedida, não é necessário repetir este processo, a menos que:

• uma nova chave seja cadastrada
• o challenge expire antes da validação
• a chave seja revogada

---

Procedimento de assinatura do challenge

1. Receba o challengeNonce retornado pela Autra após o upload da public key
2. Assine o challenge utilizando a private key
3. Envie a assinatura para o endpoint de verificação

---

📘

Exemplo — Geração da assinatura

O script abaixo ilustra como gerar a assinatura do challenge utilizando OpenSSL.

Esse script deve ser executado no ambiente seguro onde a private key está armazenada.

Bash

#!/bin/bash
set -e

PRIVATE_KEY="./private.pem"

if [ ! -f "$PRIVATE_KEY" ]; then
  echo "❌ private.pem não encontrado no diretório atual."
  exit 1
fi

CHALLENGE="$1"

if [ -z "$CHALLENGE" ]; then
  echo "❌ Uso: ./validate_challenge.sh <challengeNonce>"
  exit 1
fi

SIGNATURE=$(echo -n "$CHALLENGE" \
  | base64 --decode \
  | openssl dgst -sha256 -sign "$PRIVATE_KEY" \
  | openssl base64 -A)

echo -n "$SIGNATURE" > signature.txt

echo "🟢 Assinatura gerada com sucesso!"
echo "📄 Arquivo salvo: $(pwd)/signature.txt"
echo "📌 Conteúdo da assinatura:"
cat signature.txt

---

Após assinar o challenge nonce, o resultado deve ser enviado para validação no endpoint Verify key signature Verify key signature.

❌

Erro — Challenge expirado

Caso o challenge expire antes da validação, a assinatura será recusada. Caso ocorra este cenário, é necessário reiniciar o setup da chave, reenviando a public key para gerar um novo challenge.

---

✅

Sucesso

Após a validação da assinatura:

• A public key é marcada como validada
• A chave passa a ser confiável para o tenant
• O fluxo de onboarding pode avançar para a emissão das credenciais

---

Considerações de segurança

• A private key nunca deve ser enviada para a Autra
• A assinatura deve ocorrer exclusivamente em ambiente controlado
• O challenge é temporário e de uso único
• Esse processo não é executado em runtime, apenas no setup inicial da integração

---

3. Geração das credenciais

Após a validação da assinatura, a Autra gera as credenciais OAuth da sua aplicação através do endpoint Generate credentials.

Por motivos de segurança, as credenciais não são retornadas em texto plano.
Elas são entregues em um formato criptografado, utilizando a public key previamente registrada pelo tenant.

Cada parte do payload é:

• criptografada individualmente;
• codificada em Base64;
• descriptografável apenas com a private key correspondente, gerada no primeiro passo do setup.

Isso garante que:

• apenas o tenant detentor da private key consiga acessar as credenciais;
• a Autra nunca precise expor ou trafegar segredos em texto plano;
• o processo seja compatível com ambientes automatizados e seguros.

📘

Exemplo — Decriptografar o ClientID e ClientSecret

O script abaixo ilustra como gerar o clientID e o clientSecret

Esse script deve ser executado no ambiente seguro onde a private key está armazenada.

Bash

#!/bin/bash
set -e

# ---------------------------------------------------------
# Diretório real onde o script está localizado
# ---------------------------------------------------------
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
cd "$SCRIPT_DIR"

PRIVATE_KEY="$SCRIPT_DIR/private.pem"
CRED_FILE="$SCRIPT_DIR/credentials.txt"

if [ ! -f "$PRIVATE_KEY" ]; then
  echo "❌ private.pem não encontrado em $SCRIPT_DIR"
  exit 1
fi

if [ ! -f "$CRED_FILE" ]; then
  echo "❌ credentials.txt não encontrado em $SCRIPT_DIR"
  exit 1
fi

# ---------------------------------------------------------
# Lê o conteúdo completo do credentials.txt
# ---------------------------------------------------------
COMBINED="$(cat "$CRED_FILE" | tr -d '\n\r')"

# ---------------------------------------------------------
# Separa encID e encSecret
# ---------------------------------------------------------
ENC_ID="${COMBINED%%:*}"
ENC_SECRET="${COMBINED#*:}"

# Temporários REAIS (e automáticos) — ficarão só enquanto o script roda
ENC_ID_BIN="/tmp/enc_id.bin"
ENC_SECRET_BIN="/tmp/enc_secret.bin"

# ---------------------------------------------------------
# Base64 decode compatível macOS + Linux
# ---------------------------------------------------------
echo "$ENC_ID"     | base64 -D -i -o "$ENC_ID_BIN"     2>/dev/null || echo "$ENC_ID"     | base64 -d > "$ENC_ID_BIN"
echo "$ENC_SECRET" | base64 -D -i -o "$ENC_SECRET_BIN" 2>/dev/null || echo "$ENC_SECRET" | base64 -d > "$ENC_SECRET_BIN"

# ---------------------------------------------------------
# Decriptação RSA-OAEP(SHA-256)
# ---------------------------------------------------------
CLIENT_ID=$(openssl pkeyutl -decrypt -inkey "$PRIVATE_KEY" -in "$ENC_ID_BIN" \
  -pkeyopt rsa_padding_mode:oaep \
  -pkeyopt rsa_oaep_md:sha256)

CLIENT_SECRET=$(openssl pkeyutl -decrypt -inkey "$PRIVATE_KEY" -in "$ENC_SECRET_BIN" \
  -pkeyopt rsa_padding_mode:oaep \
  -pkeyopt rsa_oaep_md:sha256)

# Remove temporários
rm -f "$ENC_ID_BIN" "$ENC_SECRET_BIN"

# ---------------------------------------------------------
# Grava arquivo único
# ---------------------------------------------------------
OUTFILE="$SCRIPT_DIR/credentials_decoded.txt"

echo "clientId=$CLIENT_ID"       >  "$OUTFILE"
echo "clientSecret=$CLIENT_SECRET" >> "$OUTFILE"

# ---------------------------------------------------------
# Exibe resultado
# ---------------------------------------------------------
echo "---- Decrypted credentials ----"
cat "$OUTFILE"
echo "--------------------------------"
echo "📄 Arquivo salvo em: $OUTFILE"

---

⚠️

Atenção

O client_secret deve ser armazenado de forma segura e nunca exposto publicamente.

---

Resultado do setup

Ao concluir o setup, sua aplicação terá:

• Um par de chaves RSA válido
• Credenciais OAuth ativas
• Permissão para gerar tokens de acesso
• Acesso completo à Autra Platform no ambiente configurado

Próximo passo: Autenticação

Com o setup concluído, gere um token de acesso utilizando o fluxo OAuth.

Endpoint relacionado:

• Generate access token.

O token deve ser enviado no header de todas as requisições protegidas:

Authorization: Bearer access_token

Validade do token

O token de acesso possui prazo de validade de 60 minutos.

Após esse período:

• o token expira automaticamente;
• novas requisições utilizando o token expirado serão rejeitadas;
• um novo token deverá ser gerado por meio do endpoint de autenticação.

A geração de tokens pode ser realizada de forma automatizada, não sendo necessário repetir o processo de onboarding ou geração de credenciais.

Uso do token

O token deve ser enviado no header de todas as requisições protegidas, no formato:

Authorization: Bearer <access_token>

Cada requisição é validada quanto à:

• autenticidade do token;
• tempo de expiração;
• escopos e permissões associados.

---

---

Boas práticas de segurança

• Nunca compartilhe a private key
• Armazene segredos em variáveis de ambiente
• Utilize chaves diferentes por ambiente
• Rotacione chaves periodicamente
• Nunca versionar segredos em repositórios

---

Resumo do setup

Etapa	Descrição
1	Gerar par de chaves RSA e enviar a public key
2	Validar assinatura
3	Gerar credenciais
4	Autenticar via OAuth

---

🚀

Setup concluído

Sua aplicação está pronta para consumir nossas APIs.