Version: 4.32

Integração com o Certificate Enroll

Visão geral

Neste tutorial, você vai aprender como integrar com o Certificate Enroll, um serviço da Redtrust que permite que aplicações gerem chaves com segurança e solicitem a emissão de certificados digitais a partir de um ambiente controlado.

Este tutorial é destinado a desenvolvedores de parceiros da Redtrust com capacidade para emitir certificados e que desejam se integrar ao serviço de enrollment da Redtrust. Para acompanhá-lo, é necessário ter conhecimentos básicos sobre APIs HTTP, autenticação com token bearer e certificados digitais.

Contexto

Essa integração permite que um parceiro da Redtrust com capacidade de emitir certificados gere as chaves com segurança no servidor da Redtrust e que os certificados digitais sejam gerados ao final.

O Certificate Enroll gerencia todo o fluxo de emissão de certificados, incluindo:

Autenticação do usuário
Emissão de token
Geração de chave
Solicitação e renovação de certificado

O fluxo de integração é composto por duas fases principais:

Autenticação e obtenção do token O usuário se autentica com a Redtrust, que emite um JWT (JSON Web Token) para autorizar o acesso.
Geração de chave e emissão do certificado Você utiliza os endpoints da API para concluir o processo de emissão.

Antes de começar

Para integrar com o novo serviço, você precisará das seguintes informações fornecidas pelo cliente Redtrust:

Endereço IP ou nome do host do servidor Redtrust.
A porta utilizada para acessar o Sign Service (por padrão, 8083).
Nome do usuário de aplicação utilizado pelo serviço.
(Opcional) Nome do domínio.

Você também vai precisar das seguintes informações fornecidas pelo operador da aplicação cliente:

URL de redirecionamento para onde as credenciais temporárias serão enviadas. Este endereço precisa estar registrado na Redtrust para autorizar o redirecionamento e é essencial para obter o token final (JWT).

Etapa 1: Autenticação e obtenção do token

Requisição de autenticação

Acesse a URL do serviço.

https://[HOSTNAME_OU_IP]:[PORTA]/authclient/auth/loginrequest?Consumer=RA_API&Domain=[DOMÍNIO]&RedirectUrl=[URL_DE_REDIRECIONAMENTO]&timestamp=[TIMESTAMP]&partner=[NOME_PARCEIRO]&hmac=[ASSINATURA_HMAC]

Por exemplo:

https://localhost:8083/authclient/auth/loginrequest?Consumer=RA_API&Domain=local.users&RedirectUrl=https%3A%2F%2Fgoogle.es%3Ftkn%3D&timestamp=1744719496&partner=CA_DEMO&hmac=c360b2d221a55da777a5ba75264d8800ce6ebe89f41aa8b6da7e1a78bb601055

info

Para uma lista de parâmetros compatíveis, veja Parâmetros suportados.

Cabeçalhos obrigatórios

Para garantir a legitimidade de cada requisição, você deve incluir os seguintes cabeçalhos HTTP:

Cabeçalho	Descrição
`x-partner-name`	Nome da aplicação cliente, escrito em letras maiúsculas. Usado para identificar e autorizar o parceiro que está fazendo a chamada.
`x-request-timestamp`	Um timestamp UNIX indicando quando a requisição foi feita. Isso ajuda a evitar ataques de repetição. Consulte Unix TimeStamp - Epoch Converter.
`x-hmac-signature`	Assinatura criptográfica usada para validar a requisição. Ela é gerada assinando a mensagem `PARTNER_NAME:UNIX_TIMESTAMP` usando o algoritmo HMAC-SHA256 com um segredo compartilhado.

A x-hmac-signature permite que o servidor verifique a autenticidade e integridade da requisição usando o mesmo segredo compartilhado. Qualquer requisição com assinatura ausente, malformada ou inválida será rejeitada.

Redirecionamento com token temporário

Se a autenticação for concluída com sucesso, o servidor redirecionará automaticamente o usuário para a URL fornecida, adicionando o parâmetro tkn:

https://sua-aplicacao.com?tkn=TOKEN_TEMPORARIO

Sua aplicação deve interceptar esse parâmetro tkn na URL redirecionada. Essa credencial temporária deve então ser trocada por um token de acesso permanente e um token de atualização (refresh token), chamando um endpoint específico (consulte a etapa 2).

Etapa 2: Troca de token

Para concluir a autenticação, você deve trocar o token temporário (tkn) recebido no redirecionamento por um token de acesso e um token de atualização. Essa troca é feita por meio dos endpoints abaixo:

Endpoint: `/authapi/v1/login_by_temp_token`

Method: GET
Authentication: Authorization: Bearer <accessToken>
Body:

{
  "temporalToken": "string"
}

Resposta

{
  "message": "string",
  "messageType": "SUCCESS",
  "errorCode": "ERROR_CODE",
  "data": {
    "refreshToken": "string",
    "accessToken": "string",
    "expiration": "<dateTime>"
  }
}

Endpoint: `/authapi/v1/refresh-token`

Method: PUT
Authentication: Authorization: Bearer <accessToken> Content-Type: application/json Body:

{
  "refreshToken": "string"
}

Resposta

{
  "message": "string",
  "messageType": "SUCCESS",
  "errorCode": "ERROR_CODE",
  "data": {
    "refreshToken": "string",
    "accessToken": "string",
    "expiration": "<dateTime>"
  }
}

Endpoint: /authapi/v1/logout

Method: DELETE
Authentication: Authorization: Bearer <accessToken>
Body: None
Content-Type: application/json

Resposta

{
  "message": "string",
  "messageType": "SUCCESS",
  "errorCode": "ERROR_CODE",
  "data": {}
}

Etapa 3: Geração e emissão do certificado

As requisições relacionadas a certificados devem ser enviadas para a seguinte URL base:

https://[HOSTNAME_OU_IP]:[PORTA]/raapi

Por exemplo: https://localhost:8082/raapi/v1/csr/create ou https://localhost:8082/raapi/v1/csr/finalize

Para emitir um certificado, você deve chamar dois endpoints em sequência:

Endpoint: `/raapi/v1/csr/create`

Method: GET
Authentication: Authorization: Bearer <accessToken>
Content-Type: application/json
Body:

{
  "dn": [
      {
          "attribute": "<string>",
          "value": "<string>"
      },
      {
          "attribute": "<string>",
          "value": "<string>"
      }
  ],
  "hashType": "SHA384",
  "keyLength": "<integer>",
  "keyType": "DSA",
  "provider": "<string>",
  "requestCode": "<string>",
  "info": {
      "proident_9b": "<string>"
  },
}

Essa requisição retorna um CSR e um requestCode, que serão usados para concluir o processo.

Resposta

{
  "message": "<string>",
  "messageType": "IGNORE",
  "errorCode": "OK",
  "data": "<string>"
}

Exemplo

Requisição

{
  "dn": [
    {
      "attribute": "cn",
      "value": "john doe"
    },
    {
      "attribute": "o",
      "value": "Redtrust"
    },
    {
      "attribute": "c",
      "value": "Brasil"
    },
    {
      "attribute": "st",
      "value": "PJE"
    },
    {
      "attribute": "l",
      "value": "Sao Paolo"
    },
    {
      "attribute": "ou",
      "value": "Developement"
    }
  ],
  "hashType": "SHA384",
  "keyLength": "2048",
  "keyType": "RSA",
  "provider": "CA_BRASIL"
}

Resposta

{
"message": "Operation finalized successfully",
    "messageType": "SUCCESS",
    "errorCode": "OK",
    "data": {
        "requestCode": "P775W98SSW4Z1774PMZU",
        "csr": "MIIDYzCCAksCAQAwADCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKpo256NtdwCAcY9tsEzQu/PYMq5lmzkyC8hHqRWKl4IQY9YdSx7Qg7r8P9GHB+CydL2IarzPSE9KXrlWUb4YyKAcEKjlsIcXyTEbTJg0WScETw25Q7lZg2K7erJYfQlLJfZ8EWkZl6ufZoxC/gL8/RMkWAhZouOHXhBy3Ut//RNHPFA1dcGjcMEIAf/rOSp2vnfD7M96ph9NZzJsovUzISogdBayY0QYHHITxtLJbGTa+QoXzPQz9toCEOktCaoJKJALHiw5/IQuEvaYXPh5sh1OGC4el5J+qprGtB4JDq6ztVFo+yK+dRvrLaCh61kblxzw/njPTUm/jXblC13wBUCAwEAAaCCARwwHAYKKwYBBAGCNw0CAzEOFgwxMC4wLjE3NzYzLjIwNwYJKwYBBAGCNxUUMSowKAIBBQwGYmV0YTAxDBFXT1JLR1JPVVBcYmV0YTAxJAwIdzN3cC5leGUwPgYJKoZIhvcNAQkOMTEwLzAdBgNVHQ4EFgQUS8EPLaw20Fc186vA+W2Hs3JgcnkwDgYDVR0PAQH/BAQDAgUgMIGCBgorBgEEAYI3DQICMXQwcgIBAR5qAE0AaQBjAHIAbwBzAG8AZgB0ACAARQBuAGgAYQBuAGMAZQBkACAAUgBTAEEAIABhAG4AZAAgAEEARQBTACAAQwByAHkAcAB0AG8AZwByAGEAcABoAGkAYwAgAFAAcgBvAHYAaQBkAGUAcgMBADANBgkqhkiG9w0BAQUFAAOCAQEAgkJ3Z3a7PCIKL46og9Wljh37xY9za5gNZ8Y+/W4ZFAkVJp0kiI1CdTrgq3XLT0lX/RZ7MOEH7U0nZKQay+wUrEnXLjETGUdr/vmifzhTNzl3Q7wrI53Qg2XAEuAho2vwIE7Hc8PKa2S9da2Z1DprbnnY09P+YlfVes5o9MEm5AKlu1kBnPAsrLSa0cSAywUsZpyTJU+5/zma//ODgTzbl99P06VHIMeJW/Pog4yX+UA420RU8z76pmwgJOs2JqfiRmx7qo5herr0V7A0qdT/pfMInpRmuJlrwAlfIowyx9uK1Tzzs5ZNKhZXaXZ626yq9p1tJcajiUiCUjbatI844w=="
    },
    "isValid": true
}

Endpoint: `/raapi/v1/csr/finalize`

Method: PUT
Authentication: Authorization: Bearer <accessToken>
Body:

{
  "dataInB64": "<string>",
  "provider": "<string>",
  "requestCode": "<string>"
}

Response: HTTP Code Response
Content-Type: application/json

Esta llamada finaliza el proceso de emisión del certificado.

Etapa 4: Renovação de certificado

Para renovar um certificado, você também deve chamar dois endpoints. Observe que a versão do endpoint de criação muda para v2, enquanto o endpoint de finalização permanece o mesmo (v1).

Endpoint: `/raapi/v2/csr/create`

Você deve incluir o campo thumbprintToRenew no corpo da requisição:

{
  ...
  "thumbprintToRenew": "<thumbprint>"
}

Exemplo

Requisição

{
    "dn": [
        {
            "attribute": "<string>",
            "value": "<string>"
        },
        {
            "attribute": "<string>",
            "value": "<string>"
        }
    ],
    "hashType": "SHA384",
    "keyLength": "<integer>",
    "keyType": "DSA",
    "provider": "<string>",
    "requestCode": "<string>",
    "info": {
        "proident_9b": "<string>"
    },
    "thumbprintToRenew": "<string>"
}

Resposta

{
  "message": "<string>",
  "messageType": "IGNORE",
  "errorCode": "OK",
  "data": "<string>"
}

Endpoint: `/raapi/v1/csr/finalize`

Este passo é o mesmo da emissão inicial. Você deve chamar este endpoint usando o mesmo requestCode retornado durante a criação. Não é necessário modificar os dados da requisição. O novo certificado substituirá o anterior, preservando sua configuração e associações.

Parâmetros suportados

Parâmetro	Descrição
`Consumer` (obrigatório)	Deve sempre ser definido como `RA_API` para este serviço.
`RedirectUrl` (obrigatório)	A URL para a qual o usuário será redirecionado ao final do processo. Uma credencial temporária será adicionada a essa URL. Certifique-se de aplicar `UrlEncode` ao valor final.
`Domain` (opcional)	Refere-se ao domínio dos usuários que utilizarão a API. Ajuda a adaptar o fluxo com base no tipo de usuário (veja observações adicionais abaixo).
`timestamp` (obrigatório)	Timestamp da requisição no formato UNIX (segundos desde a época Unix).
`partner` (obrigatório)	Nome da aplicação cliente, em letras maiúsculas, que está fazendo a requisição.
`hmac` (obrigatório)	Assinatura HMAC para segurança. Consulte a seção sobre o cabeçalho `x-hmac-signature` para mais informações.

Visão geral​

Contexto​

Antes de começar​

Etapa 1: Autenticação e obtenção do token​

Requisição de autenticação​

Cabeçalhos obrigatórios​

Redirecionamento com token temporário​

Etapa 2: Troca de token​

Endpoint: /authapi/v1/login_by_temp_token​

Resposta​

Endpoint: /authapi/v1/refresh-token​

Resposta​

Endpoint: /authapi/v1/logout​

Resposta​

Etapa 3: Geração e emissão do certificado​

Endpoint: /raapi/v1/csr/create​

Resposta​

Exemplo​

Endpoint: /raapi/v1/csr/finalize​

Etapa 4: Renovação de certificado​

Endpoint: /raapi/v2/csr/create​

Exemplo​

Endpoint: /raapi/v1/csr/finalize​

Parâmetros suportados​

Visão geral

Contexto

Antes de começar

Etapa 1: Autenticação e obtenção do token

Requisição de autenticação

Cabeçalhos obrigatórios

Redirecionamento com token temporário

Etapa 2: Troca de token

Endpoint: `/authapi/v1/login_by_temp_token`

Resposta

Endpoint: `/authapi/v1/refresh-token`

Resposta

Endpoint: /authapi/v1/logout

Resposta

Etapa 3: Geração e emissão do certificado

Endpoint: `/raapi/v1/csr/create`

Resposta

Exemplo

Endpoint: `/raapi/v1/csr/finalize`

Etapa 4: Renovação de certificado

Endpoint: `/raapi/v2/csr/create`

Exemplo

Endpoint: `/raapi/v1/csr/finalize`

Parâmetros suportados