Integração com a RA API

Visão geral

Neste guia, você aprende a se integrar com a RA API para gerenciar o ciclo de vida completo dos certificados: autenticar usuários, gerar CSR no servidor Redtrust, e emitir e renovar certificados digitais.

Este guia é destinado a desenvolvedores de parceiros da Redtrust com capacidade para emitir certificados. Para acompanhá-lo, você precisa ter conhecimentos básicos sobre API HTTP, autenticação com token bearer e certificados digitais.

Antes de começar

Para integrar o serviço, você precisa das seguintes informações fornecidas pelo cliente Redtrust:

• Endereço IP ou nome do host do servidor Redtrust.
• A porta utilizada para acessar o serviço (o valor padrão é 8082).
• Nome do usuário de aplicação para o serviço.
• (Opcional) Nome do domínio.

Se você usar o fluxo de redirecionamento HMAC, também precisará de:

• Uma URL de redirecionamento para onde a Redtrust envia o token temporário após a autenticação. Um administrador deve registrar esse endereço na Redtrust antes de você começar.

Etapa 1: Obtenha um token de acesso

A RA API suporta dois métodos de autenticação. Escolha o que se adapta à sua integração.

Login direto

Use esta opção para integrações servidor a servidor e testes com Postman.

Envie uma solicitação POST para /raapi/v1/auth/login com as credenciais do usuário:

POST /raapi/v1/auth/login

{
  "username": "string",
  "password": "string",
  "domain": "string"
}

A resposta inclui o accessToken e o refreshToken:

{
  "message": "string",
  "messageType": "SUCCESS",
  "errorCode": "OK",
  "data": {
    "accessToken": "string",
    "refreshToken": "string",
    "expiration": "string"
  }
}

Use o accessToken em todas as solicitações seguintes. Prossiga para a Etapa 2.

Redirecionamento HMAC

Use esta opção quando os usuários se autenticarem por meio da interface web da Redtrust.

O fluxo de redirecionamento usa o mesmo mecanismo HMAC da Sign API, com uma diferença: o parâmetro Consumer deve ser RA_API.

Redirecione o navegador do usuário para:

https://SEU_IP_REDTRUST:PORTA/authclient/auth/loginrequest?Consumer=RA_API&Domain=SEU_DOMÍNIO&RedirectUrl=URL_REDIRECIONAMENTO&timestamp=TIMESTAMP&partner=NOME_PARCEIRO&hmac=ASSINATURA_HMAC

Onde:

• SEU_IP_REDTRUST é o endereço IP ou o nome do host do seu servidor Redtrust.
• PORTA é a porta de acesso ao serviço (padrão 8082).
• SEU_DOMÍNIO é o domínio dos usuários (opcional).
• URL_REDIRECIONAMENTO é a URL para a qual o usuário é redirecionado após a autenticação. Aplique UrlEncode.
• TIMESTAMP é o timestamp no formato UNIX.
• NOME_PARCEIRO é o nome da aplicação cliente em maiúsculas.
• ASSINATURA_HMAC é a assinatura HMAC-SHA256 gerada com a chave compartilhada.

Se a autenticação for concluída com sucesso, a Redtrust redireciona o navegador do usuário para a sua URL de redirecionamento:

https://SUA_URL_REDIRECIONAMENTO/TOKEN_TEMPORÁRIO

Troque o token temporário

Intercepte o parâmetro tkn da URL redirecionada. Sua aplicação deve fazer uma chamada ao servidor para trocá-lo por um token de acesso permanente:

POST /authapi/v1/login_by_temp_token

{
  "temporalToken": "TOKEN_TEMPORÁRIO"
}

Onde TOKEN_TEMPORÁRIO é o valor do parâmetro tkn da URL redirecionada.

A resposta inclui o accessToken e o refreshToken:

{
  "message": "string",
  "messageType": "SUCCESS",
  "errorCode": "OK",
  "data": {
    "accessToken": "string",
    "refreshToken": "string",
    "expiration": "string"
  }
}

Use o accessToken para autenticar todas as chamadas à RA API. Prossiga para a Etapa 2.

Etapa 2: Emissão do certificado

Para emitir um certificado, chame dois endpoints em sequência.

1. Crie o CSR

POST https://SEU_IP_REDTRUST:PORTA/raapi/v1/csr/create

Onde SEU_IP_REDTRUST e PORTA são o endereço e a porta do seu servidor Redtrust.

Consulte a descrição completa do endpoint, com os campos do body e exemplos, na referência da RA API.

O servidor retorna um CSR e um requestCode. Salve o requestCode — você vai precisar dele na próxima etapa.

2. Finalize a emissão

PUT https://SEU_IP_REDTRUST:PORTA/raapi/v1/csr/finalize

Consulte a descrição completa do endpoint na referência da RA API.

Etapa 3: Renovação do certificado

O fluxo de renovação usa os mesmos endpoints que a emissão. A única diferença é que você deve incluir o campo thumbprintToRenew no body da chamada a POST /raapi/v1/csr/create:

{
  "...": "...",
  "thumbprintToRenew": "THUMBPRINT_DO_CERTIFICADO_A_RENOVAR"
}

Onde THUMBPRINT_DO_CERTIFICADO_A_RENOVAR é o thumbprint do certificado existente que você deseja renovar.

Após criar o CSR, chame o mesmo endpoint de finalização (PUT /raapi/v1/csr/finalize) com o requestCode obtido. O novo certificado substitui o anterior, preservando sua configuração e associações.

Consulte a descrição completa de ambos os endpoints na referência da RA API.