Itaú for Developers

O que é o certificado dinâmico (CSR)?

O Certificate Sign Request (CSR) é um certificado não assinado e usado apenas no ambiente de produção, gerado pelo responsável técnico que contém os dados da empresa requisitante e sua chave pública.

Esse procedimento é realizado para que ao solicitar um certificado ao Itaú o solicitante identifique sua aplicação e receba um certificado de uso único e exclusivo.

O CSR (Certificate Sign Request) é o arquivo que contém a chave pública do certificado e as demais informações de identificação. Utilizado para requisitar ao STS Itaú a assinatura do certificado.

Seu formato segue o seguinte padrão:

-----BEGIN CERTIFICATE REQUEST-----
...
-----END CERTIFICATE REQUEST-----

A segurança do processo é baseada no conceito de chave assimétrica ou chave pública.

Importante:

Renovar/gerar o certificado dentro do prazo de validade de 365 dias: Basta utilizar o arquivo .CSR gerado anteriormente e o token temporário gerado pela sua aplicação, cuja validade é de 5 minutos.
Decorrido o prazo de 365 dias do certificado: Solicite um novo token temporário ao seu ponto focal do Itaú, a validade deste token é de 7 dias corridos para este cenário.

O que é a chave pública?

A chave pública é um valor gerado a partir de operações matemáticas com a chave privada. Como seu nome já sugere, seu conhecimento pode ser público e não é necessário ser armazenada de forma confidencial. Seu valor fica embutido dentro do próprio certificado.

O que é a chave privada?

A chave privada é um valor altamente sensível. Portanto, deve ser armazenada de forma segura, pois ela será requisitada para comprovar que o certificado está em uso pelo seu dono no processo de mutual TLS.

Seu formato segue o seguinte padrão:

-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----

O que é SSL?

O SSL (Secure Socket Layer) na requisição oferece total segurança entre aplicativos cliente/servidor, preservando a integridade e a veracidade do conteúdo trafegado na rede, por meio da autenticação das partes envolvidas com a troca destas informações. A versão recomendada pelo banco é a 1.1.1.c ou superior.

O que são credenciais?

As credenciais são o conjunto client_id + client_secret.

O que é o token temporário?

O token é um valor obtido através do STS Itaú que representa a autenticação da credencial. Ele é obrigatório para o consumo das APIs disponibilizadas pelo Itaú, assim como o certificado.

Como faço para obter um token temporário?

Para obter um token temporário do Itaú o procedimento varia conforme a etapa da jornada em que você está: onboarding ou consumo.

Etapa de onboarding- Esta etapa é quando você está iniciando seu contato com o Itaú , você receberá um token temporário por e-mail com validade de 7 dias corridos com o único objetivo de emitir suas credenciais e o certificado, após este período esse token será invalidado. É fundamental seguir o procedimento de recebimento das credenciais de acesso e emissão do certificado dentro desse prazo a contar da data de emissão do token.

Importante: Vale ressaltar que o Token enviado tem validade de 7 dias para o início do fluxo de geração de certificado. Caso não seja utilizado dentro desse período, você precisará solicitar novamente e aguardar o tempo de resposta, correspondente a 1 dia útil.

Etapa de Consumo- Esta etapa é quando você já tem em mãos suas credenciais e o certificado devidamente emitidos pelo STS Itaú. O processo de emissão do token é bem simples e pode ser realizado por meio de requisição ao STS Itaú.

Importante: O token emitido pelo STS Itaú tem duração de 5 minutos e deve ser utilizado durante esse período para consumo das APIs sendo necessário sua renovação sempre que estiver próximo a expirar.

Glossário

Termo	Definição
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 qual 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ária 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.