Version: 4.31

Integração com o Sign Service

Visão geral

Neste tutorial, você vai aprender como integrar com o Sign Service da Redtrust, uma solução de assinatura digital do lado do servidor que centraliza a gestão de certificados e utiliza autenticação baseada em token para aplicar controle de acesso.

Este tutorial é destinado a desenvolvedores e administradores de TI. 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 sua aplicação utilize os certificados digitais centralizados da Redtrust para assinar documentos com segurança por meio do Sign Service.

O Sign Service da Redtrust gerencia todo o fluxo de assinatura, incluindo autenticação do usuário, emissão de tokens, gestão de certificados e execução da assinatura, tudo por meio de uma API centralizada e segura.

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 aos serviços de assinatura.
Assinatura de documentos usando certificados Redtrust: Após a autenticação, sua aplicação pode executar operações de assinatura utilizando os certificados digitais gerenciados pela Redtrust.

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).

Step 1: General configuration

Acesse a URL do serviço e faça login.
```
https://[HOSTNAME_OU_IP]:[PORTA]/authclient/auth/loginrequest?Consumer=SIGN_SERVICE&Domain=[DOMÍNIO]&RedirectUrl=[URL_DE_REDIRECIONAMENTO]&timestamp=[TIMESTAMP]&partner=[NOMBRE_PARCEIRO]&hmac=[ASSINATURA_HMAC]
```
Por exemplo: https://localhost:8083/authclient/auth/loginrequest?Consumer=SIGN_SERVICE&Domain=local.users&RedirectUrl=https%3A%2F%2Fgoogle.es%3Ftkn%3D&timestamp=1744719496&partner=CA_DEMO&hmac=c360b2d221a55da777a5ba75264d8800ce6ebe89f41aa8b6da7e1a78bb601055

nota

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

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.

Recursos para implementação

Classe .NET HMACSHA256
Gerador de Hash HMAC-SHA256 da Akto

Retorno da credencial temporária

Se a autenticação for concluída com sucesso, o servidor redirecionará automaticamente o usuário para a URL especificada na requisição original.

Esse redirecionamento incluirá uma credencial temporária na query string. Por exemplo:

https://apptest.com?tkn=WP0WSA2D4415ABZ270HW3F62F1152C48ORT0F929I6VISR780Y583FD10138FG4S

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 o passo 2 Processo de login).

O token de acesso é necessário para a assinatura digital (e outras operações autorizadas). O token de atualização permite renovar a sessão sem precisar fazer login novamente.

O processo de login é iniciado chamando a seguinte URL:

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

Dependendo dos parâmetros e da configuração do usuário, há três resultados possíveis:

Nenhum domínio especificado

Se nenhum domínio for informado (ou se o domínio informado não for do tipo OAuth ou SAML), será carregado o formulário de autenticação da Redtrust. O usuário deverá concluir o processo de login conforme configurado no ambiente Redtrust (por exemplo, nome de usuário e senha ou autenticação multifator).
Domínio externo especificado (OAuth ou SAML)

Se a requisição incluir um domínio registrado como Provedor de Identidade externo (IdP) usando OAuth ou SAML, a Redtrust redirecionará imediatamente o usuário para a página de login do IdP.

Esse fluxo ignora a interface de login da Redtrust. Também permite Single Sign-On (SSO) de forma transparente, caso exista federação entre a aplicação cliente e a Redtrust — ou seja, usuários já autenticados na aplicação cliente não precisarão se autenticar novamente.
Nenhum domínio especificado, mas o usuário pertence a um IdP externo

Essa é uma variação do cenário 1. O usuário insere seu nome de usuário Redtrust no formulário padrão. Com base nesse nome, se o usuário estiver associado a um IdP externo, a Redtrust fará o redirecionamento para a página de login apropriada do IdP.

Em todos os casos, o processo termina com o redirecionamento para a RedirectUrl especificada na requisição original. Esse redirecionamento incluirá uma credencial temporária (via o parâmetro tkn) que deve ser trocada por um token de acesso final.

Para completar a troca do token, você deve chamar os seguintes endpoints:

Endpoint: `/authapi/v1/login_by_temp_token`

Method: GET
Authentication: Token bearer no cabeçalho Authorization
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: Token bearer no cabeçalho Authorization
Body:

{
  "refreshToken": "string"
}

Content-Type: application/json

Resposta

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

Endpoint: `/authapi/v1/logout`

Method: DELETE
Authentication: Token bearer no cabeçalho Authorization
Body: None
Content-Type: application/json

Resposta

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

Recursos adicionais

Para ajudar você a testar a integração e gerar os cabeçalhos necessários, os seguintes recursos estão disponíveis:

Coleção Postman Download
Esse arquivo contém um conjunto de requisições preconfiguradas para testar o processo de autenticação com a Redtrust.
Script auxiliar para Postman Download
Esse script ajuda a gerar o cabeçalho x-hmac-signature no Postman com o formato e segredo corretos.

tip

Certifique-se de importar a coleção no Postman e configurar as variáveis (por exemplo, timestamp, nome do parceiro, segredo compartilhado) antes de enviar as requisições.

Passo 3: Processo de assinatura

As requisições de assinatura devem ser feitas para a seguinte URL base:

https://[HOSTNAME_OU_IP]:[PORT]/signapi

For example https://localhost:8083/signapi/v1/sign/document ou https://localhost:8083/signapi/v1/certificate/list

Para concluir as chamadas de assinatura, você deve utilizar os seguintes três endpoints:

Endpoint: `/signapi/v1/certificate/list`

Method: GET
Authentication: Token bearer no cabeçalho Authorization
Body: None
Content-Type: application/json

Resposta

{
  "message": "string",
  "messageType": "SUCCESS",
  "errorCode": "OK",
  "data": [
    {
      "id": 0,
      "alias": "string",
      "thumbprint": "string",
      "pinPolicy": "NoPIN",
      "requireUsageReason": true
    }
  ]
}

Endpoint: `/signapi/v1/sign/document`

Method: POST
Authentication: Token bearer no cabeçalho Authorization
Body: None
Content-Type: application/json
Response: Signed file.

nota

Essa requisição utiliza dados de formulário. Você deve incluir:

jsonUploadData: um campo contendo o JSON serializado (veja o exemplo abaixo).
file: o documento a ser assinado.

O campo visualSignature é opcional.

{
    "certificateId":11,
    "pin":null,
    "reason":null,
    "visualSignature": {
        "x": 316,
        "y":843,
        "width":385,
        "height":96, 
        "imageBase64":"[IMAGE_IN_B64]",
        "pages":[1]
    }
}

Endpoint: `/signapi/v1/sign/hash`

Method: POST
Authentication: Token bearer no cabeçalho Authorization
Content-Type: application/json
Body:

{
  "dataInBase64": "string",
  "hashAlgorithm": "MD5",
  "padding": "PKCS1",
  "certificate": "string",
  "pin": "a131wC",
  "usageReason": "string"
}

Resposta

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

Algoritmos e paddings compatíveis

Algoritmos suportados: [ MD5, SHA1, SHA224, SHA256, SHA384, SHA512 ]

Paddings suportados: [ PKCS1, PSS, OAEP ]

Recursos adicionais

Postman collection Download

Parâmetros suportados

Parâmetro	Descrição
`Consumer` (obrigatório)	Deve sempre ser definido como `SIGN_SERVICE` 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​

Step 1: General configuration​

Cabeçalhos obrigatórios​

Recursos para implementação​

Retorno da credencial temporária​

Passo 2: Processo de login​

Endpoint: /authapi/v1/login_by_temp_token​

Resposta​

Endpoint: /authapi/v1/refresh-token​

Resposta​

Endpoint: /authapi/v1/logout​

Resposta​

Recursos adicionais​

Passo 3: Processo de assinatura​

Endpoint: /signapi/v1/certificate/list​

Resposta​

Endpoint: /signapi/v1/sign/document​

Endpoint: /signapi/v1/sign/hash​

Resposta​

Algoritmos e paddings compatíveis​

Recursos adicionais​

Parâmetros suportados​

Visão geral

Contexto

Antes de começar

Step 1: General configuration

Cabeçalhos obrigatórios

Recursos para implementação

Retorno da credencial temporária

Passo 2: Processo de login

Endpoint: `/authapi/v1/login_by_temp_token`

Resposta

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

Resposta

Endpoint: `/authapi/v1/logout`

Resposta

Recursos adicionais

Passo 3: Processo de assinatura

Endpoint: `/signapi/v1/certificate/list`

Resposta

Endpoint: `/signapi/v1/sign/document`

Endpoint: `/signapi/v1/sign/hash`

Resposta

Algoritmos e paddings compatíveis

Recursos adicionais

Parâmetros suportados