itaú for developers - autenticação mTLS

home

autenticação mTLS - produção

Neste guia você encontra as informações necessárias para realizar a Autenticação em Produção e ter acesso às APIs do Itaú.

objetivo

O conteúdo desta documentação é indicado para times de tecnologia, que visam se autenticar no ambiente produtivo para utilizar nossas soluções. Aqui você encontra um compilado introdutório sobre os procedimentos para realizar a autenticação em produção, além de um glossário com termos relevantes para seu conhecimento.

arquitetura de autenticação

O modelo de nossas APIs é RESTful, seguem as regras definidas pela arquitetura REST - (Representational State Transfer) (referência: W3C), e utilizam o JSON como formato de troca de dados (referência: JSON.org).

Nossas APIs são compatíveis com o protocolo OAuth 2.0, contemplando especialmente o fluxo client_credentials e mTLS para autorizar acesso a dados e transações, baseado em tokens de acesso no qual utilizamos fluxos específicos para a situação server-to-server.

Porém, é importante destacar que as APIs de Sandbox não seguem a especificação do OAuth 2.0 e não tem mTLS, por outro lado, já as APIs de Produção seguem a especificação do OAuth 2.0 e tem mTLS. Se faz necessário saber também que, os access_tokens gerados para o fluxo do Sandbox só podem chamar a URL de Sandbox.

Recomendamos fortemente que, a etapa de testes em Sandbox seja realizada antes das chamadas para as APIs produtivas, já que, é neste momento que você pode testar vários cenários para entender o processo de implantação do certificado e facilitar sua aplicação no ambiente produtivo.

Importante: O certificado é válido por 365 dias e o access_token por 5 minutos, portanto, atente-se em enviar o certificado dentro do prazo vigente, tanto para gerar o token quanto para chamar a API.

credenciais produtivas

Para conseguir acessar nossas APIs no ambiente produtivo você precisa gerar o Certificado Dinâmico, para isso, é necessário ter em mãos suas credenciais produtivas, ou seja, a chave pública, chave privada e o token temporário, específicas para o ambiente de produção.

Confira abaixo mais detalhes para solicitar suas respectivas credenciais:

Credenciais para Cobranças e uso externo

As Credenciais para Cobranças e uso externo devem ser solicitadas através dos canais de suporte combinados com o seu ponto focal no Itaú ou API Owner. Você receberá as credenciais por meio de um e-mail com as informações criptografadas, pois elas são confidenciais, e é de sua responsabilidade armazená-las em local seguro, caso contrário elas serão revogadas pelo Itaú.

Credenciais para PIX pagamentos, PIX recebimentos e Bolecode

Já as Credenciais para PIX pagamentos, PIX recebimentos e Bolecode, não são criptografadas, portanto, basta sinalizar ao time OfficerCash, responsável por acionar o time de Backoffice, para gerar uma solicitação e lhe enviar suas credenciais (client_id e token temporário) via e-mail.

Token temporário

Deve ser solicitado através dos canais de suporte combinados com o seu ponto focal no Itaú ou API Owner. O token temporário será enviado para você por e-mail em até 1 dia útil depois da solicitação e terá validade de 7 dias corridos.

URL Produção

base token URL produção: sts.itau.com.br

Lembre-se: Consulte na documentação de cada API qual é o endereço de produção exato para utilizar a URL correta, pois há variação entre elas.

fluxos de autenticação do Itaú

O Itaú oferece dois fluxos de autenticação para acesso ao ambiente produtivo e você pode escolher conforme sua necessidade.

Confira abaixo os fluxos disponíveis:

1 - Client credentials e mTLS - É o fluxo em que após receber seu client_id Itaú produtivo e token de ativação temporário você estará apto a gerar um certificado de autenticação válido e assinado tanto por você quanto pelo Itaú e, fazendo o envio dessas informações em cada requisição de API, você poderá consumir nossas APIs em Produção.

Confira como realizar o procedimento do fluxo mTLS

Solicite o client_id + token temporário com o seu ponto focal ou API Owner do Itaú;
Após receber as credenciais, crie e assine o certificado de autenticação e envie para o Itaú;
Em seguida você precisará gerar seu access_token e automatizar o processo de criação de um novo access_token a cada 5 minutos, a qual a validade do token é de 300 segundos;
Finalize seu desenvolvimento enviando o certificado assinado + access_token em cada requisição de API para que as chamadas possam ser concluídas.

Dica: Para saber mais sobre como receber suas credenciais do Certificado de Autenticação, também conhecido como Certificado Dinâmico, consulte nossa documentação.

Exemplos de obtenção do access_token

cURL
Java
Python
PHP
C#

curl --location --request POST 'https://sts.itau.com.br/api/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id={CLIENT_ID}' \
--data-urlencode 'client_secret={CLIENTE_SECRET}' \
--cert ./meu_app_certificado.crt \
--key ./ARQUIVO_CHAVE_PRIVADA.key

public class ProdAuthentication {
  public static void main(String[] args) {
    HttpURLConnection connection = null;
    try {
      URL url = new URL("https://sts.itau.com.br/api/oauth/token");
      connection = (HttpURLConnection) url.openConnection();
      connection.addRequestProperty(
          "Content-Type", "application/x-www-form-urlencoded");
      connection.setRequestMethod("POST");
      connection.setDoOutput(true);

      // Add certificate
      File p12 = new File("{CAMINHO_CERTIFICADO}\\certificado.pfx");
      String p12password = "{SENHA_CERTIFICADO}";
      InputStream keyInput = new FileInputStream(p12);
      KeyStore keyStore = KeyStore.getInstance("PKCS12");
      keyStore.load(keyInput, p12password.toCharArray());
      keyInput.close();
      KeyManagerFactory keyManagerFactory =
          KeyManagerFactory.getInstance("SunX509");
      keyManagerFactory.init(keyStore, p12password.toCharArray());
      SSLContext context = SSLContext.getInstance("TLS");
      context.init(
          keyManagerFactory.getKeyManagers(), null, new SecureRandom());
      SSLSocketFactory socketFactory = context.getSocketFactory();
      if (connection instanceof HttpsURLConnection)
        ((HttpsURLConnection) connection).setSSLSocketFactory(socketFactory);
      //

      String body = "grant_type=client_credentials"
          + "&client_id={CLIENT_ID}"
          + "&client_secret={CLIENTE_SECRET}";
      OutputStream outputStream = connection.getOutputStream();
      outputStream.write(body.toString().getBytes());
      outputStream.close();
      BufferedReader bufferedReader = new BufferedReader(
          new InputStreamReader(connection.getInputStream()));
      StringBuilder response = new StringBuilder();
      String line = null;
      while ((line = bufferedReader.readLine()) != null) {
        response.append(line);
      }
      bufferedReader.close();
      System.out.println(response.toString());
    } catch (Exception e) {
      e.printStackTrace();
    } finally {
      if (connection != null)
        connection.disconnect();
    }
  }
}

import json
import requests

url = "https://sts.itau.com.br/api/oauth/token"
cert = ("./Certificado.crt", "./ARQUIVO_CHAVE_PRIVADA.key")
payload = 'grant_type=client_credentials&{CLEINT_ID}&client_secret={CLIENT_SECRET}'
headers = {
	'x-itau-flowID': "1",
	'x-itau-correlationID': "2",
	'Content-Type': 'application/x-www-form-urlencoded'
}

response = requests.post(url=url, data=payload, headers=headers, cert=cert)

if 200 != response.status_code:
	print(response.headers)

print(response.json())

<?php
$curl = curl_init();

$client_id = "{CLIENTE_ID}";
$client_secret = "{CLIENTE_SECRET}";

curl_setopt_array($curl, array(
    CURLOPT_URL => "https://api.itau.com.br/sandbox/api/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_SSLCERT => "CERTIFICAO.p12",
    CURLOPT_SSLCERTPASSWD => "PASSWORD",
    CURLOPT_SSLKEYTYPE => "P12",
    CURLOPT_POSTFIELDS => "grant_type=client_credentials&client_id=$client_id&client_secret=$client_secret",
    CURLOPT_HTTPHEADER => array(
		"Content-Type: application/x-www-form-urlencoded"
	),
));

$response = curl_exec($curl);

curl_close($curl);

echo $response;

public class ProdAuthentication
 {
  public string GetToKen(string ClientID, string ClientSecret) {
    HttpWebResponse requestResponse = null;
    var request = (HttpWebRequest) WebRequest.Create(
        "https://sts.itau.com.br/api/oauth/token");
    request.ContentType = "application/x-www-form-urlencoded";
    request.Method = "POST";
    var dataBody = "grant_type=" + Uri.EscapeDataString("client_credentials");
    dataBody += "&client_id=" + Uri.EscapeDataString(ClientID);
    dataBody += "&client_secret=" + Uri.EscapeDataString(ClientSecret);
    var body = Encoding.ASCII.GetBytes(dataBody);
    request.ContentLength = body.Length;
    string response = "";
    Stream myWriter = null;
    try {
      X509Certificate2 certificate = new X509Certificate2();
      certificate.Import(@"{CAMINHO_CERTIFICADO}\certificado.pfx",
          @"{SENHA_CERTIFICADO}", X509KeyStorageFlags.DefaultKeySet);
      request.ClientCertificates.Add(certificate);
      myWriter = request.GetRequestStream();
      myWriter.Write(body, 0, body.Length);
      requestResponse = (HttpWebResponse) request.GetResponse();
      response =
          new StreamReader(requestResponse.GetResponseStream()).ReadToEnd();
      return response;
    } catch (Exception ex) {
      var headerResponse = requestResponse.GetResponseHeader("");
      throw new Exception(
          "Erro ao solicitar o token.\r\nDetalhe: " + ex.Message);
    } finally {
      if (myWriter != null)
        myWriter.Close();
    }
  }
}

2 - Client credentials com private key JWT e mTLS - Resumidamente, o JWT (Json Web Token) é um padrão para autenticação e troca de informações definido pela RFC7519, composto por vários caracteres entre letras e números codificados que, caso cliente e servidor estejam sob o protocolo HTTPS, permite que somente o servidor que conhece o 'segredo' possa ler o conteúdo do token, e assim confirmar a autenticidade do cliente. Ou seja, essa funcionalidade garante segurança por meio de diversas claims.

O JWT é composto por um Header, um Payload e uma assinatura, além de preservar a segurança necessária para sua decodificação, exceto o client_secret.

Quando um usuário se autentica no sistema (cliente_id e client_secret), o servidor gera um token com data de expiração para ele. Durante as requisições seguintes do cliente, o JWT (Json Web Token) é enviado no cabeçalho da requisição e, caso esteja válido, cuja validação permeia em 5 minutos, a API irá permitir acesso aos recursos solicitados, sem a necessidade de se autenticar novamente.

Dica: Fique tranquilo! Este tipo de autenticação possui uma validação dupla que leva maior segurança aos seus projetos.

Confira como realizar o procedimento JWT + mTLS

Crie e disponibilize a sua JWKS_URI para o Itaú, pois ela será usada para verificar a autenticidade a cada solicitação de acess_token;
Solicite o client_id + token temporário para o seu ponto focal ou API Owner do Itaú;
Após receber suas credenciais por e-mail, crie a sua private_key_jwt, ela deve conter informações de Header e Body conforme o formato abaixo.

Header

kid identificador da chave utilizada na assinatura do JWT.

alg valor fixo "RS256" (algoritmo utilizado)

Payload

sub identificador da aplicação consumidora (client id recebido).

aud valor fixo "id.itau.com.br/as/token.oauth2".

iss endereço do gerador do JWT, validado durante a requisição.

iat data e hora de geração do JWT (opcional).

exp data e hora de expiração do JWT.

jti identificador único do JWT (UUID).

Confira abaixo um trecho de referência da geração de JWT que atende este cenário, implementado na linguagem Java:

publicStringgenerateRSAKeyPair(StringkeyID) throwsJOSEException, ParseException {

KeyPairGeneratorgen;
KeyPairkeyPair;
Stringresult = "";

try {
gen = KeyPairGenerator.getInstance("RSA");
gen.initialize(2048);
keyPair = gen.generateKeyPair();

// Convert to JWK format
RSAKeyjwk = new RSAKey.Builder((RSAPublicKey)keyPair.getPublic())
.privateKey((RSAPrivateKey)keyPair.getPrivate())
.keyUse(KeyUse.SIGNATURE)
.keyID(keyID)
.build();
result = jwk.toJSONString();

}catch (NoSuchAlgorithmExceptione) {
e.printStackTrace();
}

return result;
}

Crie e assine o Certificado Dinâmico e envie para para o STS por meio do endpoint: https://sts.itau.com.br/seguranca/v1/certificado/solicitacao;
Em seguida, você precisa gerar seu access_token e automatizar o processo de renovação do access_token a cada 5 minutos a qual a validade é de 300 segundos;
O formato de validação realizado pelo STS através da requisição que envia o JWT é o par de chaves (Key pair). Portanto, no endpoint que disponibiliza a chave pública deve conter essa informação. Não deve ser exposto no endpoint o certificado utilizado na assinatura do JWT, mas sim a chave pública;
E por útlimo, finalize seu desenvolvimento enviando o certificado válido assinado + access_token em cada requisição de API, para que as chamadas possam ser concluídas.

Confira o exemplo de obtenção de access token a partir do private_key_jwt e certificado: sts.itau.com.br/as/token.oauth2

curl --location --request POST 'https://sts.itau.com.br/as/token.oauth2' \

--header 'Content-Type: application/x-www-form-urlencoded' \

--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:client_credentials' \

--data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \

--data-urlencode 'client_assertion={{PRIVATE KEY JWT gerado pelo seu serviço de JWT}}'

--cert ARQUIVO_CERTIFICADO.crt \

--key ARQUIVO_CHAVE_PRIVADA.key

Importante: Tempo recomendado de expiração do seu private_key_jwt: 300 segundos.

Tempo de expiração do access_token Itaú: 300 segundos.

IPs de origem do Itaú (para validação do JWKS): 200.196.144.0/20, 138.59.160.0/22, 18.230.2.236 e 54.207.195.108..

Confira abaixo o exemplo de jwks_uri: https://example.com/.well-known/jwks.json

{
"keys": [{
"kty": "RSA",
"e": "AQAB",
"use": "sig",
"kid": "4c0c4df3-301d-4f30-9355-0cf5a12fdd5e",
"n": "lTVPr7K-
k3VaVhxoLsGoIZDv_0DulDqweDa13ojDNWI14xK81pWKItbGHGwRr88T4a2FHx1j0IfT0mE7AwIriVlZrp--
KRoL3X1sxmg4Y3i4xM52ZfB6zpxrYPZeyTqMXgTmeRUji2dVIM5L9d5Z3cHItvtMqjLwC7g10wxaGb
Wimh1C_DnHO2x5Qnd8wJ9SxEqKMnPRa3w8WoVSksmO62DIlDuvcDgzYVmCzEIZmUjEiC4_4i_jI
EJcglYhWUQx3Hp4ciHR3QFZ3C4EfAw8bD8yfqKOU8_aRZ04LkWwJKGM-
NlDRXP2Tk9KizcBU3A8AMMT1UfZtBNLTPJf4DB8FQ"
} ]
}

Importante: O endpoint que disponibiliza a chave pública e é consultado pelo STS, deve possuir uma URL e certificado válidos, conforme exposto na porta 443.

fluxos de autenticação Webhook

O que é autenticação Webhook ou Hub de Notificação?

Com o Webhook, um participante externo pode ser notificado por meio de um evento de negócio, ou seja, internamente há um controle que ajuda a designar o destinatário correto da emissão de cada tipo de evento para seu respectivo endpoint, e consequentemente, diferenciar a respectiva entidade com base no seu target-id cadastrado.

Quando deve ser utilizado?

A utilização do Hub de Notificação é indicada para arquiteturas que tenham a necessidade de notificar Parceiro(s) interno(s) ou externo(s) do Itaú.

Como utilizar esta solução?

Para utilizar esta solução, é necessário realizar a implementação de APIs específicas para o recebimento de cada notificação do webhook, além de implementar também um endpoint do serviço de autenticação. Confira no próximo tópico os detalhes dos tipos de autenticação para o Webhook.

Posteriormente, deve ser feito o cadastro dos endpoints das APIs implementadas, endpoint do serviço de autenticação, bem como as credenciais, os parâmetros e headers no ambiente de homologação para utilizar o serviço escolhido. O mesmo procedimento deve ser realizado no ambiente de produção quando o participante externo estiver apto a entrar no ambiente produtivo.

Tipos de autenticação para o Webhook

Chave Pública (CA): é a chave que o Itaú disponibiliza para ativar o fluxo de autenticação via mTLS, para isso, é necessário primeiramente realizar o download da CA do Itaú: ca-cert.zip. Após o download, essa CA deverá ser importada no API Gateway, servidor proxy ou na aplicação que irá receber a requisição de Webhook do Itaú.

mTLS - A autenticação mútua ou autenticação bidirecional refere-se à duas partes que se autenticam ao mesmo tempo em um protocolo de autenticação padrão, pois o usuário decide se quer usar as 2 autenticações ou não, só uma ou até mesmo nenhuma. A autenticação via mTLS é específica para quem usa as APIs regulatórias do pix direto, conforme especificação do Banco Central (BACEN).

OAuth2.0 - O tipo de autenticação utilizado é o protocolo de autorização OAuth2.0, que possibilita à aplicativos obterem acesso limitado às contas de usuários em um serviço HTTP, dispensando o envio de usuário e senha. A autenticação via OAuth2.0 para Webhook é específica para quem é parceiro do pix indireto.

Importante: Ressaltamos que possuímos apenas o suporte à OAuth2.0 por client_secret_basic.

glossário

access token - É um JWT que contém informações de uma autenticação, o qual será validado quando houver uma chamada de API, para identificar quem se autenticou e se tem permissão para o recurso da API solicitado.

arquivo. CRT (Certificate File) - No mesmo formato do . KEY e CSR, é o certificado que em nosso contexto, contém as informações e assinaturas de ambas as partes envolvidas: consumidor da API e Itaú.

arquivo.CSR (Certificate Signing Request) - No mesmo formato de um .KEY, contém informações que precisam constar em um certificado gerado por uma CA (Certificate Authority / Autoridade de certificação) e assinatura do solicitante, por meio da sua chave privada.

arquivo.KEY - Assim com no JWK, é uma chave criptográfica primária em um bloco de texto codificado, porém, em formato de arquivo e com codificação diferente de um JWT. Ex: arquivo.key.

bearer token - É um dos tipos de access token predominante e utilizado em nossas APIs.

client_credentials - Tipo de autorização (grant) que obtém um access token fora do contexto de um usuário (pessoa).

client_id - Identificador único e público de uma aplicação no fluxo OAuth 2.0.

client_secret - Segredo conhecido somente pela aplicação e o servidor de autorização o quel pertence a um client_id.

JKWS_URI - Endereço de internet no qual é possível localizar um JWKS para validar a autenticidade de um private_key_jwt.

JWK (JSON Web Key) - Estrutura JSON que representa uma chave criptográfica, comumente a primária ou private_key.

JWKS(JSON Web Key Set) - Conjunto de chaves (JWK) que contém as chaves públicas (public_key) usadas para verificar qualquer JWT emitido e assinado por uma chave privada (private_key).

JWT (JSON Web Token) - Método compacto e autocontido de transmissão de dados no formado JSON. Referência: https://jwt.io/introduction/ e https://jwt.io/ (exemplo de JWT).

mTLS Authentication - (Mutual Transport Layer Security) - Em nosso contexto, é um método de segurança baseado em certificados gerados por uma chave privada e uma pública (ou primári e secundária) e de ambas as partes (mútua). É conhecido também com two-way authentication.

private_key - Chave criptográfica (primária) que pode ser obtida e utilizada para codificar mensagens intencionadas a um destinatário particular. As mensagens criptografadas só podem ser decifradas por uma segunda chave conhecida como public key.

private_key_jwt - JWT assinado por uma chave privada (private_key).

public key - Chave criptográfica (pública/secundária) que pode ser obtida e utilizada para decodificar mensagens intencionadas a um destinatário particular.

STS - Security token service (STS) - Servidor de autorização responsável por gerenciar os tokens de acesso e autorizar requisições às APIs.

token temporário de ativação - No contexto do Itaú, é um primeiro access token, que é utilizado para a ativação fluxo de mTLS de nosso processo de autenticação.

URI - (Uniform Resource Identifier) - É um identificador uniforme de recurso, que para nosso contexto, especifica um endereço único de internet de um determinado recurso para uma determinada função.

Dica: Para dúvidas que não forem esclarecidas por essa documentação, entre em contato conosco diretamente pelos canais de suporte combinados com o seu representante comercial Itaú.