Pular para o conteúdo principal
Version: 4.42

Integração com o Sign Service

Visão geral​

Neste tutorial, você aprenderá a integrar o Sign Service, uma solução de assinatura digital do lado do servidor que centraliza o gerenciamento de certificados e aplica controle de acesso por meio de autenticação baseada em tokens.

Este tutorial é destinado a desenvolvedores e administradores de TI. Para segui-lo, é útil ter conhecimentos básicos de API HTTP, autenticação com tokens bearer e certificados digitais.

Contexto​

Esta integração permite que sua aplicação use os certificados digitais centralizados do Redtrust para assinar documentos com segurança por meio do Sign Service.

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

O fluxo de integração consiste em duas fases principais:

  1. Autenticação e obtenção de token: O usuário se autentica no Redtrust, que emite um JWT (JSON Web Token) para autorizar o acesso ao serviço de assinatura.

  2. Assinatura de documentos usando certificados do Redtrust: Uma vez autenticada, sua aplicação pode realizar operações de assinatura usando os certificados digitais gerenciados pelo Redtrust.

Antes de começar​

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

  • Endereço IP ou nome do host do servidor Redtrust.

  • A porta usada para acessar o Sign Service (o valor padrão é 8083).

  • Nome do usuário de aplicação para o serviço.

  • (Opcional) Nome de domínio.

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

  • URL de redirecionamento para onde as credenciais temporárias serão enviadas. Esse endereço deve estar registrado no Redtrust para autorizar o destino do redirecionamento e é necessário para obter o token final (JWT).

Etapa 1: Configuração geral​

  1. Acesse a URL do serviço e faça login:

    https://SEU_IP_REDTRUST:PORTA/authclient/auth/loginrequest?Consumer=SIGN_SERVICE&Domain=SEU_DOMÍNIO&RedirectUrl=URL_REDIRECIONAMENTO&timestamp=TIMESTAMP&partner=NOME_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 ver a lista de parâmetros suportados, consulte Parâmetros suportados.

Cabeçalhos obrigatórios​

Para garantir a legitimidade de cada requisição, inclua os seguintes cabeçalhos HTTP:

CabeçalhoDescrição
x-partner-nameNome da aplicação cliente em maiúsculas. Usado para identificar e autorizar o parceiro que realiza a chamada.
x-request-timestampTimestamp UNIX que indica quando a requisição é feita. Ajuda a prevenir ataques de repetição. Consulte Unix TimeStamp - Epoch Converter.
x-hmac-signatureAssinatura criptográfica que valida a requisição. É gerada assinando a mensagem NOME_PARCEIRO:TIMESTAMP_UNIX usando HMAC-SHA256 com uma chave compartilhada.

O cabeçalho x-hmac-signature permite que o servidor verifique a autenticidade e integridade da requisição usando a chave secreta compartilhada. Toda requisição sem assinatura, malformada ou inválida será rejeitada.

Recursos para implementação​

Classe .NET HMACSHA256

Gerador de assinatura HMAC-SHA256 - Akto

Retorno da credencial temporária​

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

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

https://apptest.com?tkn=WP0WSA2D4415ABZ270HW3F62F1152C48ORT0F929I6VISR780Y583FD10138FG4S

Sua aplicação deve capturar o parâmetro tkn da URL de redirecionamento. Essa credencial temporária deve ser trocada por um token de acesso permanente e um token de atualização, chamando um endpoint específico (consulte a etapa 2, Processo de login).

O token de acesso é necessário para assinar documentos e realizar outras operações autorizadas. O token de atualização permite renovar a sessão sem precisar se autenticar novamente.

Etapa 2: Processo de login​

O processo começa chamando a seguinte URL:

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

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

  1. Sem domínio especificado

    Se nenhum domínio for fornecido (ou se não for do tipo OAuth ou SAML), o formulário de autenticação do Redtrust será exibido. O usuário deve fazer login com as credenciais configuradas (nome de usuário e senha, autenticação multifator, etc.).

  2. Domínio externo especificado (OAuth ou SAML)

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

    Esse fluxo ignora a interface de login do Redtrust. Se existir federação entre a aplicação cliente e o Redtrust, o Single Sign-On (SSO) também é suportado, evitando que o usuário precise se autenticar novamente.

  3. Sem domínio especificado, mas o usuário pertence a um IdP externo

    Variante do cenário 1. O usuário insere seu nome de usuário do Redtrust e, se pertencer a um IdP externo, é redirecionado automaticamente para o provedor correspondente.

Em todos os casos, o processo termina redirecionando o usuário para a URL de redirecionamento especificada, que inclui a credencial temporária (tkn) a ser trocada por um token de acesso definitivo.

Para concluir a troca do token, chame os seguintes endpoints:

Endpoint: /authapi/v1/login_by_temp_token​

Método: GET Autenticação: 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​

Método: PUT Autenticação: Authorization: Bearer <accessToken> 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​

Método: DELETE Autenticação: Authorization: Bearer <accessToken> Body: Nenhum
Content-Type: application/json

Resposta​

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

Recursos adicionais​

Os seguintes recursos estão disponíveis para ajudá-lo a testar a integração e gerar os cabeçalhos necessários:

  • Coleção Postman Fazer download Inclui requisições pré-configuradas para testar a autenticação com o Redtrust.

  • Script auxiliar para Postman Fazer download Gera automaticamente o cabeçalho x-hmac-signature no Postman com o formato e o segredo corretos.

tip

Certifique-se de importar a coleção no Postman e configurar as variáveis necessárias (timestamp, nome do parceiro, chave compartilhada) antes de enviar requisições.

Etapa 3: Processo de assinatura​

As requisições de assinatura são feitas para a seguinte URL base:

https://SEU_IP_REDTRUST:PORTA/signapi

Por exemplo https://localhost:8083/signapi/v1/sign/document ou https://localhost:8083/signapi/v1/certificate/list.

Para concluir o processo de assinatura, use os endpoints descritos na referência da Sign API.

Recursos adicionais​

Parâmetros suportados​

ParâmetroDescrição
Consumer (obrigatório)Deve ser sempre definido como SIGN_SERVICE para este serviço.
RedirectUrl (obrigatório)URL para a qual o usuário será redirecionado ao final do processo. Uma credencial temporária é adicionada. Certifique-se de aplicar UrlEncode.
Domain (opcional)Domínio dos usuários que usarão a API. Permite adaptar o fluxo com base no tipo de usuário.
timestamp (obrigatório)Timestamp no formato UNIX (segundos desde o epoch).
partner (obrigatório)Nome em maiúsculas da aplicação cliente que faz 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.

Esta página foi útil?