Introdução

O Open Insurance, ou Sistema de Seguros Aberto, é a possibilidade de consumidores de produtos e serviços de seguros, previdência complementar aberta e capitalização permitirem o compartilhamento de suas informações entre diferentes sociedades autorizadas/credenciadas pela Susep, de forma segura, ágil, precisa e conveniente.

Para entregar esses benefícios ao consumidor, o Open Insurance operacionaliza e padroniza o compartilhamento de dados e serviços por meio de abertura e integração de sistemas, com privacidade e segurança.

Cronograma de Implementação

Cronograma Unificado de Implementação Fases 2 e 3

Notificações

Boletim OPIN 2023

Este material tem como objetivo reunir os principais temas e informações referentes ao projeto. Caso tenha alguma dúvida ou sugestão, ou queira entrar em contato com a nossa equipe, o canal de comunicação oficial é o Service Desk.

Boletim OPIN #B23-016

• Próximas entregas das participantes
• Informativo sobre novas cadeias intermediárias V4/G4 para certificados ICP-Brasil
• Análise do Comportamento das Requisições dos Endpoints de Fase 1 - Plataforma de Coleta de Métricas
• Release de Correções das APIs de Fase 1 – Backlog de Correções

Boletim OPIN #B23-015

• Abertura da Certificação no Motor de Conformidade para APIs do Bloco 1
• Workshop de Instruções Técnicas da Plataforma de Coleta de Métricas
• Informativo referente ao produto de “Pessoas”
• Comunicação de release de correções das APIs de Fase 1

Boletim OPIN #B23-014

• Lançamento RFPs de Segurança da Informação e Prevençãoa Fraudes e DPO (as a service)
• Próximos Workshops de Instrução aos Participantes
• Próximos passos para as participantes
• Advertência para desenvolvimento de aplicações utilizando componente WebView

Boletim OPIN #B23-013

• Liberação Mock Insurance e Motor de Conformidade
• Cronograma de Implementação das Fases II e III

Boletim OPIN #B23-012

• Status do plano de correção
• Mailing de Comunicado e Boletins do Open Insurance

Boletim OPIN #B23-011

• Re-homolgação das APIs de Fase 1
• 2º Workshop de apresentação do Mock Insurance
• Atualização de Materiais de Suporte à Participante
• Plataforma de Coleta de Métricas – PCM

Boletim OPIN #B23-010

• Próximas entregas Open Insurance (03 e 05 de maio)
• 2º Workshop do Processo de Certificação de Conformidade
• 1º Workshop do Fluxo de Validação em Produção (FVP)
• Melhorias nas APIs

Boletim OPIN #B23-009

• Próximas entregas Open Insurance
• 1º Workshop para Instruções do Fluxo de Validação em Produção (FVP)
• Aprimoramentos no Mock Insurance
• Disponibilização das APIs do Bloco 06 da Fase 02

Boletim OPIN #B23-008

• Próximas entregas Open Insurance
• 2º Workshop de Instruções do Processo de Certificação de Conformidade
• Plataforma de Coleta de Métricas
• Liberação da Execução de Testes no Motor de Conformidade

Boletim OPIN #B23-007

• 1º Workshop de Treinamento da Plataforma Service Desk
• Plataforma de Coleta de Métricas

Boletim OPIN #B23-006

• 1º Workshop de Treinamento da Plataforma Service Desk
• Cronogramas de Datas Intermediarias Fase 2 e 3

Boletim OPIN #B23-005

• Atenção! Revogação e reemissão de certificados das Autoridades Certificadoras Serasa Experian, Soluti e CertiSign
• Plataforma de Coleta de Métricas
• Lembrete: Release de melhorias das APIs das Fases 1 e 2
• Próximas entregas Open Insurance
• Mock Insurance
• Cadastro das Participantes como N2 – Service Desk
• Cronograma Fase 2 – Alterações de datas intermediárias – Bloco 6

Boletim OPIN #B23-004

• Revogação e reemissão de certificados das Acs Sera Experian, soluit e CertiSign
• Plataforma de Coleta de Métricas
• Próximas entregas Open Insurance

Boletim OPIN #B23-003

• Revogação e reemissão de certificados de cadeia V10
• Plataforma de Coleta de Métricas
• Release de melhorias das APIs das Fases 1 e 2
• Mock Insurance
• Relatório Anual de compartilhamento de dados e serviços

Boletim OPIN #B23-002

• Próximas entregas Open Insurance (30-jan)
• Workshop de apresentação do Mock Insurance

Boletim OPIN #B23-001

• Próximas entregas Open Insurance (13/01/2023)
• Certificação FAPI de Receptora

Boletim OPIN 2022

Boletim OPIN #B22-007

• Próximas entregas Open Insurance
• Dúvidas sobre à Certificação de Receptora

Boletim OPIN #B22-006

• Próximas entregas Open Insurance
• Orientações do Pedido de Certificação funcional das APIs de Consentimento e Recursos com data limite de 13/01/2023
• Liberação do cadastro das APIs no Diretório Bloco 4
• Recesso de fim de ano: Grupos de Trabalho e Conselho Deliberativo
• Publicação dos Swaggers de Bloco 5 no Portal do Desenvolvedor
• Passo a Passo do Registro da Certificação FAPI no Diretório de Participantes
• Atualização na Cadeia de certificados V10
• Retirada das APIs de Grandes Riscos Natos

Boletim OPIN #B22-005

• Anonimização de dados para testes das APIs da Fase 2
• Próximas entregas Open Insurance
• Atualizações - Portal do Desenvolvedor
• Recesso de fim de ano: Grupos de Trabalho e Conselho Deliberativo
• Agradecimentos de boas festas
• Agradecemos desde já as providências a serem tomadas.

Boletim OPIN #B22-004

• Atualização de Grandes Riscos e Dados Embarcados de Auto
• Atualização de APIs no portal do desenvolvedor
• Requisitos de Segurança
• Prorrogação da Implantação de melhorias às APIs da Fase 1

Boletim OPIN #B22-003

• Orientação sobre os testes estruturais do motor de conformidade Fase 2
• Requisitos de Segurança
• Implantação de melhorias às APIs da Fase 1

Boletim OPIN #B22-002

• Nova versão das APIs: Dados Cadastrais e Patrimonial Residencial
• Testes estruturais e funcionais da Fase 2
• Lembrete: Implantação de melhorias às APIs da Fase 1 (28/10/2022)

Boletim OPIN #B22-001

• Diretório: Cadastro de APIs Fase 2 (prazo 01/09/2022) e Nova Interface do Usuário
• Implantação de melhorias às APIs da Fase 1 (prazo de homologação 28/10/2022)
• Certificados de Segurança Padronização e Orientações (prazo estendido)

Comunicados Open Insurance 2023

Confira as últimas atualizações do Open Insurance Brasil.

OPIN Comunica #D23-023 023 – Hotfix - Correção do campo documentationDeliveryDate em 8 APIs de Fase 2
OPIN Comunica #D23-022 022 – Atualização do Portal do desenvolvedor
OPIN Comunica #D23-018 018 – Análise do Comportamento das Requisições dos endpoints de fase 1 – PCM
OPIN Comunica #D23-017 020 – Guia de Experiência do Usuário Completo Fase 2 e 3
OPIN Comunica #D23-016 019 – Workshop sobre o Processo de Certificação de Conformidade da Fase 2
OPIN Comunica #D23-015 017 – Orientações sobre plano de correção e próximos passos
OPIN Comunica #D23-014 016 – Visões da área pública da Plataforma de Métricas
OPIN Comunica #D23-013 015 – Prorrogação – Publicação das APIs Bloco 06 Fase 02
OPIN Comunica #D23-012 014 – Motor de Conformidade - Suspensão dos Testes de Fase 2
OPIN Comunica #D23-011 013 – Guia de Experiência do Usuário Fase 3
OPIN Comunica #D23-010 012 – Disponibilização de APIs no Portal do Desenvolvedor
OPIN Comunica #D23-009 011 – Cadastro de representante N2 no Service Desk
OPIN Comunica #D23-008 009 – Release de Melhorias
OPIN Comunica #D23-007 008 – Disponibilização de APIs – Fase 3
OPIN Comunica #D23-006 007 – Certificação FAPI Receptora
OPIN Comunica #D23-005 006 – Workshop: Plataforma de Métricas
OPIN Comunica #D23-004 004 – Atualização no Diretório de Participantes - Cadastro de APIs
OPIN Comunica #D23-003 003 – Registro de Certificação funcional no diretório de participantes do OPIN
OPIN Comunica #D23-002 002 – Disponbilização do Mock Insurance em Produção
OPIN Comunica #D23-001 001 – Término das certificações: Consentimento e Recursos

Comunicados Open Insurance 2022

OPIN Comunica #D22-052 099 – Cadastro de APIs de Bloco 3 da Fase 2
OPIN Comunica #D22-051 097 – Orientações sobre certificações
OPIN Comunica #D22-050 095 – Atualização método de cadastro de APIs com parâmetros no diretório de participantes
OPIN Comunica #D22-049 094 – Atenção às próximas entregas
OPIN Comunica #D22-048 093 – Ativação da camada de segurança nos endpoints
OPIN Comunica #D22-047 091 – Orientações e prazos para implementação
OPIN Comunica #D22-046 090 – Workshop de Certificação Funcional e Estrutural
OPIN Comunica #D22-045 088 – Lembrete importante de próximas entregas
OPIN Comunica #D22-044 086 – APIs da Fase 2
OPIN Comunica #D22-043 084 – Requisitos de Segurança - orientações para implementação
OPIN Comunica #D22-042 083 – Extensão de prazo final para republicação das APIs – release 1 de melhorias
OPIN Comunica #D22-041 082 – Motor de Conformidade e Inserção de Logomarca no Diretório
OPIN Comunica #D22-040 077 – Disponibilização de novas APIs no Portal do Desenvolvedor - Patrimonial
OPIN Comunica #D22-039 076 – Requisitos de Segurança - orientações para implementação
OPIN Comunica #D22-038 075 – Atualização dos Certificados de Segurança
OPIN Comunica #D22-037 072 – Novo lembrete sobre cadastro das APIs
OPIN Comunica #D22-036 067 – Entregas - Fase II - Proposta de cronograma
OPIN Comunica #D22-035 066 – Certificação FAPI - alinhamento de próximos passos
OPIN Comunica #D22-034 065 – Manuais de orientação certificado BRSEAL e BRCAC
OPIN Comunica #D22-033 064 – Dilação de prazo para a implementação do seguro coletivo para o grupo de ramos Habitacional do Open Insurance Brasil- Posicionamento da Susep
OPIN Comunica #D22-032 058 – Disponibilização das APIs de Dados no Portal do Desenvolvedor – Fase 2
OPIN Comunica #D22-031 057 – 2° Workshop - Plantão de Dúvidas - Certificados ICP Brasil
OPIN Comunica #D22-030 056 – Provisionamento dos custos de certificado (ICP-Brasil) e de certificação (FAPI BR)
OPIN Comunica #D22-029 055 – Cadastro das Participantes como N2 - Service Desk - baixa aderência
OPIN Comunica #D22-028 054 – Service Desk - Novo Campo e Status no Fluxo de Atendimento
OPIN Comunica #D22-027 052 – Obrigatoriedade de inclusão dos dados de seguro coletivo Habitacional
OPIN Comunica #D22-026 050 – Disponibilização da Publicação das APIs da Etapa II e III no ambiente produção
OPIN Comunica #D22-025 049A – Período de Homologação das APIs das Etapas 1.2 e 1.3
OPIN Comunica #D22-024 049 – Esclarecimento de dúvidas sobre a relação da Circular SUSEP 638 e a Estrutura Inicial do Open Insurance
OPIN Comunica #D22-023 048 – Disponibilização da Publicação das APIs da Etapa III no Sandbox
OPIN Comunica #D22-022 047 – Acesso Global dos Usuários N2 no Service Desk
OPIN Comunica #D22-021 046 – Disponibilização do Motor de conformidade - Etapa III
OPIN Comunica #D22-020 045 – Disponibilização de APIs - Etapa III
OPIN Comunica #D22-019 044 – Manuais de utilização das APIs do diretório
OPIN Comunica #D22-018 043 – Disponibilização do Motor de conformidade - Etapa III
OPIN Comunica #D22-017 041 – Manuais de APIs do OPIN - Versão 1.1
OPIN Comunica #D22-016 040 – Disponibilização de APIs - Estapa III
OPIN Comunica #D22-015 039A – A Pesquisa - Formato dos campos LMIs e LMGs
OPIN Comunica #D22-014 038 – Homologação Automática Diretório de Participantes
OPIN Comunica #D22-013 037 – Correção de Erros no Dashboard de Participantes
OPIN Comunica #D22-012 034 – Disponibilização do Motor de Conformidade para a Etapa II
OPIN Comunica #D22-011 032 – Atualização das APIs da Etapa 2 da Fase 1
OPIN Comunica #D22-010 031 – Priorização das alterações do Motor de Conformidade para a Etapa II
OPIN Comunica #D22-009 030 – Liberação do Motor de Conformidade para homologação de APIs
OPIN Comunica #D22-008 028 – Liberação do Ambiente SandBox - Orientações Gerais
OPIN Comunica #D22-007 026 – Publicação das APIs da Etapa 2 da Fase 1
OPIN Comunica #D22-006 022 – Publicação das APIs da Etapa 2 da Fase 1
OPIN Comunica #D22-005 019 – Direcionamento Execução de Testes de Conformidade da API Discovery
OPIN Comunica #D22-004 018 – Direcionamento de Erros Conhecidos para a Homologação das APIs
OPIN Comunica #D22-003 017 – Esclarecimentos sobre Produtos com Coberturas em APIs Distintas
OPIN Comunica #D22-002 016 – Liberação do Motor de Conformidade - Versão v1.03 de Swaggers
OPIN Comunica #D22-001 014 – Publicação da Versão V1.03 de Swaggers
OPIN Comunica #D22-000 008 – Estratégia para Cadastro de APIs - Formulário e Orientações

Comunicados Open Insurance 2021

OPIN Comunica #D21-011 044 – Atualização - Inconsistências Testes de Conformidade
OPIN Comunica #D21-010 043 – Inconsistências Testes de Conformidade
OPIN Comunica #D21-009 042 – Tutorial Testes de Conformidade APIs v2
OPIN Comunica #D21-008 041 – Tutorial Cadastro Contatos Técnicos Diretório
OPIN Comunica #D21-007 040 – Tutorial Testes de Conformidade APIs
OPIN Comunica #D21-006 038A – Concessão de Prazo Complementar para Certificação Funcional das APIs
OPIN Comunica #D21-005 037 – Informações referentes ao problemas tecnicos para liberação do diretorio
OPIN Comunica #D21-004 034 – Tratativas Service Desk
OPIN Comunica #D21-003 032 – Informações Diretório de Participantes e Tutorial de Cadastro
OPIN Comunica #D21-002 031 – Disponibilização de Cadastro via Forms
OPIN Comunica #D21-001 007 – Disponibilização dos Manuais e Swaggers

Manuais para participantes

Nesta sessão encontra-se os principais materiais orientativos para as participantes do Open Insurance

Documentos

Passo a passo para cadastro de Endpoint’s - dados públicos Fase 1
Passo a passo de cadastro no diretório
Passo a passo Cadastro Contatos Técnicos Diretório
Passo a passo testes de confomidade APIs
Orientação de homologação de API
Recomendações Cadastro APIs Diretório
Passo a passo de cadastro no diretório (Ambiente de SandBox)
Criando uma Declaração de Software
Gerando o Certificado BRCAC
Gerando o Certificado BRSEAL
Obtendo um token para acesso as APIs do Diretório
Processo de Segurança
Guia de Experiência do Usuário Completo
Guia para incorporar a Certificação no diretório
Guia para certificação APIs da Fase 2
Relatório Anual de Direcionamento ao Mercado.
Cartilha Orientativa - Fluxo de Validação em Produção.
Passo a passo para cadastro de Endpoint’s
Manual Governança de Acessos - Área Logada - PCM

Certificação de conformidade

O Test Plan da Fase 2 Versão 2 de dados transacionais é uma série de test plans que foram construídos para testar se as implementaçãos de cada instituição estão em linha com a última versão das APIs de dados transacionais da fase 2 do Open Insurance Brasil, e também estão em linha dos requisitos funcionais esperados

Os testes são divididos em duas diferentes classes:

- Testes Estruturais - Testes que validarão a estrutura do JSON structure para as respostas 20X de cada endpoint de dados. Já que a camada de segurança não será testada, o payload não deve ser protegido via MTLS. Haverão um módulo de teste por API dentro do mesmo test plan.

- Teste Funcionais - Testes que validarão o comportamente funcional da API, com um test plan específico para cada API.

Como os testes estão em desenvolvimento contínuo, até que as certificações iniciem podem ser encontrados erros durante as execuções pelas instituições. Estes erros podem ser relacionados a especificações incertas ou porque o teste está executando um comportamento que não está em linha com o definido nas especificacões. Em ambos os casos, as instituições devem abrir um ticket da issue no Service Desk para que o erro possa ser avaliado pelo time de engenharia da Conformance Suite.

Requisitos de amostra de dados

Todos os testes necessitam que as instituições provisionem pelo menos um cliente Pessoa Física ou Pessoa Jurídica com o produto que está sendo testado. O CPF ou par de CPF/CNPJ do cliente testado deve ser provisionado na configuração do teste para que as APIs possam ser acessadas e o payload de resposta possa ser validado no escopo do teste.

Quando dados além dos definidos acima forem necessários, o sumário do teste definirá o que deve ser provisionado para que o teste execute com sucesso. Os seguintes test plans contém módulos que necessitam de amostras de dados:

1. Resources API Test 1.1.0 - entre 3 a 25 recursos acessíveis devem ser provisionados para que o usuário passe no teste de paginação que requer o acesso a uma segunda página.

Execução dos test plans

To execute the tests the user will have to follow a three-step process: Para executar os testes, o usuário deve seguir um processo de 4 passos:

1. Acessar o Open Insurance Conformance Suite
2. Selecionar um Test Plan
3. Preencher os campos de configuração
4. Executar os módulos de teste

O detalhe de cada passo é definido a seguir:

Acesso a Conformance Suite

The Customer Data tests are available on the Open Insurance Brasil Conformance Suite. To access the conformance suite, the user must have an active account at the Open Insurance Brasil Sandbox Directory.

Os testes de dados transacionais estão disponíveis na Open Insurance Brasil Conformance Suite. Para acessar a Conformance Suite, o usuário deve ter uma conta ativa no Diretório de Sandbox do Open Insurance Brasil.

Após o acesso o usuário será direcionado a uma página inicial com 6 botões:

Para executar os testes, o usuário deve clicar no botão "Create a new test plan". O usuário pode também verificar logs de testes ou planos publicados nas outras opções.

Selecionar um Test Plan

Ao criar um test plan, o usuário deverá prencher as informações pertinentes a execução:

A lista completa de test plans é disponibilizada no menu "Test Plans". Nele o usuário pode selecionar qualquer um dos testes apresentados na lista. Tanto os testes Estruturais quanto os Funcionais estarão disponíveis nesta lista:

Após selecionar um test plan, o usuário também será solicitado a preencher três opções:

1. Client Authentication Type - Como o cliente se autenticará no servidor para obter o token. FAPI suporta somente private_key_jwt e tls_client_auth dos Métodos de Autenticação OAuth 2.0 disponíveis

2. Request Object Method - Se PAR será ou não utilizado

Preencher os campos de configuração

Dependendo do tipo de teste a ser executado (Funcional ou Estrutural) o usuário será solicitado a providenciar informações adicionais para prosseguir com a execução do teste. As informações são detalhes tanto sobre o cliente que será utilizado pela Conformance Suite, quanto detalhes sobre o servidor que será certificado pelos testes

Configuração dos testes estruturais

O usuário deve providenciar as seguintes informações para executar os testes estruturais:

Test Information:

Estes campos são usados para definir informações gerais utilizadas pela Conformance Suite quando executando e salvando os testes.

alias: Este campo será utilizado para criar o redirect_uri que será utilizado ao executar o fluxo de autorização no escopo dos testes. Este é um campo padrão, e não será utilizado nos testes estruturais.

description: Campo de texto livre que será utilizado para identificar este teste posteriormente.

publish: Selecione se os resultados dos testes devem ser publicados ou mantidos privados - Caso sejam publicados será possível que outros usuários acessem seus test plans ao pesquisar por logs de testes públicos.

Server:

discoveryUrl: Providencie a URI de Meta Dados do Authorisation Server, também conhecido como endereço well-known. Esse valor também deve ser registrado no Diretório de Sandbox do Open Insurance Brasil.

Resource:

resourceUrl: Providencie um URL que será utilizado para acessar o endpoint via Regex. É importante notar que o URL providenciado neste campo deve ser o que hospede as payloads que serão validadas no teste estrutural, portanto não deve ser protegido via MTLS. Exemplo: https://www.example.dummypayload.com/open-insurance/consents/v1/

Configuração dos testes funcionais

Os testes funcionais requerem informações adicionais que devem ser preenchidas na configuração do teste. As seções que devem ser preenchidas são:

• Test Information
• Server
  • Client
  • Resource
  • Directory

A descrição de cada campo é detalhada abaixo:

Test Information:

Estes campos são usados para definir informações gerais utilizadas pela Conformance Suite quando executando e salvando os testes.

alias: Este campo será utilizado para criar o redirect_uri que será utilizado ao executar o fluxo de autorização no escopo dos testes. A redirect_uri terá o seguinte formato: "https://web.conformance.directory.openbankingbrasil.org.br/test/a/alias/callback" no qual alias é o valor definido no campo alias. Certifique-se de que este redirect_uri foi adicionado ao software_statement utilizado no DCR.

description: Campo de texto livre que será utilizado para identificar este teste posteriormente.

publish: Selecione se os resultados dos testes devem ser publicados ou mantidos privados - Caso sejam publicados será possível que outros usuários acessem seus test plans ao pesquisar por logs de testes públicos.

Server Details

Estes campos são relacionados à configuração do servidor e suas URIs, incluindo tanto as URIs do Authorisation Server as URIs do Resource Server.

discoveryUrl: Providencie a URI de Meta Data do Authorisation Server, também conhecida como o endereço well-known. Este campo também deve ser cadastrado no diretório de Sandbox do Open Insurance Brasil.

Client Details:

Estes detalhes são relacionados ao Software Statement que deve ser criado no ambiente de Sandbox do Open Insurance Brasil e que será utilizado pela Conformance Suite para conectar-se ao servidor que será testado. Antes de gerar os certificados e realizar o DCR para gerar o client_id necessário, certifique-se de que o redirect_uri correto e o papel de DADOS foi adicionado ao Software Statement.

jwks: Providencie as chaves de assinatura utilizadas pelo cliente em um formato JWKS. Nós sugerimos utilizar a PKI do Diretório de Sandbox para gerar estas chaves. Para criar uma chave de assinatura (BRSEAL) na PKI do Diretório de Sandbox, refira-se ao guia de geração do certificado BRSEAL

As chaves geradas seguindos as instruções do diretório serão geradas em um formato que não é JSON. Porém os testes necessitam que as chaves estejam no formato JWKS. Há diversas maneiras de realizar a conversão. Dado que esta chave será publicada durante a execução do teste, é possível utilizar um conversor online para obter o JWKS, com o procedimento a seguir:

1. Converta o arquivo .key obtido do diretório para RSA com OpenSSL openssl rsa -in server.key -out server_new.key
2. Converta a chave RSA para JWK em https://8gwifi.org/jwkconvertfunctions.jsp
3. Antes de adicionar a Private Key na Conformance Suite, certifique-se de o objeto "alg": "PS256" foi adicionado ao jwks, e que o campo "kid" está atualizado com o kid correto do diretório, e que o campo "use" tem o valor "sig".

mtls.cert: Providencie o conteúdo do certificado Public Transport (BRCAC) gerado no Diretório de Sandbox em formato PEM. Aqui você pode abrir o arquivo .pem com um editor de texto comum e colar os conteúdos neste campo. Para criar um certificado BRCAC na PKI do Diretório de Sandbox, refira-se ao guia de geração do certificado BRCAC

mtls.key: Providencie o conteúdo da chave pública em formato .PEM. Similar ao campo mtls.cert, porém aqui deve ser providenciado o conteúdo da chave que foi gerada junto ao .csr.

client_id: Neste campo, você deve providenciar o client_id que foi gerado ao realizar um DCR contra o servidor a ser testado com as credenciais preenchidas acima.

Certifique-se de que o Software Statemen utilizado foi registrado com o papel de DADOS.

Resouce

consentUrl: Providencie a URI utilizada para acessar a API de Consent de dados transacionais.

brazilCpf: Providencie o CPF do cliente teste criado para o escopo dos testes. Este CPF será utilizado ao criar o ConsentID em cada um dos planos executados pela Conformance Suite.

brazilCnpj: Caso a instituição deseje testar com um cliente do tipo Pessoa Jurídica, providencie também o CNPJ que será utilizado para criar o Consentimento. Este campo não é obrigatório.

Business or Personal Products: Selecione se a Conformance Suite utilizará as permissões de Customer Personal Permissions (Pessoas Físicas) ou Business Personal Permission (Pessoa Jurídica) ao obter dados do servidor. Caso o campo brazilCnpj seja preenchido, selecione Business Personal Permission.

Directory

Directory ClientID: ID do cliente (Software Statement) no Diretório. Este valor é utilizado para obter o access token, que é utilizado para obter o Software Statement.

Quando todas as configurações estiverem preenchidas, clique em "Create Test Plan":

Executar os módulos de teste

Após a criação dos test plans, você será redirecionado à página de test plan. Para começar a execução dos testes, selecione o módulo de teste a ser executado, e clique em "Run test":

Por favor leia a descrição do teste na caixa de texto azul claro próxima ao topo dos logs da página - essa seção pode conter instruções específicas ao teste; por exemplo, um teste requer que o usuário rejeite o processo de autenticação. Se aplicável, o teste pode pedir que seja aceito (ou negado, ou ignorado) o pedido no dispositivo de autenticação em questão.

Quando o teste for completado, pressione “Continue Plan” para iniciar o próximo teste, ou “Return to Plan” para visualizar seu progresso.

Se você necessitar de suporte, por favor crie um issue no GitLab da Conformance Suite, visitando este link.

Caso seja relacionado a falha de um teste, por favor inclua um link para o log-detail.html relacionado, ou caso esteja utilizando uma instalação local, o arquivo de log baixado.

Lista de Test Plans

26 módulos de testes distintos já foram disponibilizados para a Certificação da Versão das APIs da Fase 2. Estes testes estão separados em seis diferentes test plans, um para cada teste Funcional mais um para os testes Estruturais. Os módulos disponíveis estão listados a seguir:

• Functional tests for Consents API - version 1.0.0
  • opin-preflight-check-test
  • opin-consent-api-test
  • opin-consent-api-status-test
  • opin-consent-api-test-negative
  • opin-consent-api-test-permission-groups
  • opin-consent-api-test-client-limits
  • opin-consent-api-status-declined-test
  • opin-consent-api-expired-consent-test
  • opin-consents-api-delete-test
  • opin-consent-inavlid-user-test
• Functional tests for Resources API - version 1.0.0
  • opin-resources-api-test
  • opin-resources-api-test-404-customer-data
  • opin-resources-api-pagination-test
• Functional tests for Customer Personal API - version 1.1.0
  • opin-customer-personal-data-api-test
  • opin-customer-personal-api-wrong-permissions-test
• Functional tests for Customer Business API - version 1.1.0
  • opin-customer-business-data-api-test
  • opin-customer-business-api-wrong-permissions-test
• Functional tests for Patrimonial API - version 1.1.0
  • opin-patrimonial-api-test
  • opin-patrimonial-api-wrong-permissions-test
  • opin-patrimonial-resources-api-test
  • opin-patrimonial-residencial-api-branch-test
• Structural tests
  • opin-consents-api-structural-test
  • opin-resources-api-structural-test
  • opin-customer-personal-api-structural-test
  • opin-customer-business-api-structural-test
  • opin-patrimonial-api-structural-test

Workshops

• 1º Workshop Processo de Certificação Funcional das APIs Fase 2 com a Raidiam (23/11/2022)

Workshops

Certificação FAPI:

FAPI Transmissora / DCR

• Treinamento de Capacitação da certificação FAPI Transmissora (FAPI OP + DCR) 1º Workshop Processo de Certificação FAPI com OpenID Foundation
• Treinamento de Capacitação da certificação FAPI Transmissora (FAPI OP + DCR) 2º Workshop Processo de Certificação FAPI com Open ID Foundation

FAPI Receptora

• Treinamento de Capacitação da certificação FAPI Receptora (FAPI RP) 3º Workshop Processo de Certificação FAPI com Open ID Foundation

Certificados ICP BRASIL

• Plantão de dúvidas dos certificados: 1º Workshop - Plantão de Dúvidas com as Autoridades Certificadoras - Certificados ICP Brasil
• Treinamento de capacitação das participantes: 2º Workshop - Plantão de Dúvidas - Certificados ICP Brasil

Mock Insurance:

• Treinamento de utilização da Plataforma do Mock Insurance: 1º Workshop de Apresentação do Mock Insurance
• Apresentação dos aprimoramentos, recursos e funcionalidades de utilização da Plataforma: 2º Workshop de Apresentação da Plataforma Mock Insurance

Motor de Conformidade

• Treinamento de capacitação das participantes nos testes estruturais e funcionais: 1º Workshop Processo de Certificação Funcional das APIs Fase 2 com a Raidiam
• Treinamento do Processo de Certificação de Conformidade: 2º Workshop Processo de Certificação de Conformidade
• Treinamento de capacitação das participantes o Processo de certificação das APIs de Fase 2: 3º Workshop de Instruções do Processo de Certificação de Conformidade

Plataforma de Coleta de Métricas:

• Treinamento de utilização da API de Métricas Transacionais: 1º Workshop de Apresentação da Plataforma de Métricas
• Apresentação do funcionamento da PCM e das APIs de Métricas Transacionais e Funil de Consentimento do Open Insurance, overview para dúvidas das participantes. 2º Workshop de Instruções Técnicas da Plataforma de Coleta de Métricas (PCM)

Plataforma Service Desk:

• Treinamento dos Representantes N2 das Participantes na Plataforma Service Desk: 1º Workshop de Treinamento N2 da Plataforma Service Desk

Fluxo de Validação em Produção

• Treinamento do Fluxo de Validação em Produção (FVP): 1º Workshop de Instruções do Fluxo de Validação em Produção (FVP)

Documentos de referência SUSEP

Documentos de Referência

Redirecionamento App To App

O redirecionamento 'App-to-App' permite que o Participante redirecione um usuário do seu aplicativo (em um navegador ou app) para o App do Participante, instalado no dispositivo do usuário. Nesse caso, a receptora é capaz de transmitir detalhes de sua solicitação junto com as preferências do usuário (por exemplo, tipo de produto, one-step authentication, etc) e ligar diretamente o seu usuário à tela ou função de login do aplicativo da transmissora, através de um deep-link. O usuário é então autenticado no aplicativo usando as mesmas credenciais/métodos normalmente usados quando ele acessa diretamente sua conta. Isso não deve envolver nenhuma etapa adicional (como, por exemplo, ser redirecionado primeiro para uma página da web para selecionar qual aplicativo da instituição transmissora usar) e não deve exigir que o usuário forneça qualquer identificador ou outras credenciais diferentes das já exigidas pelo Participante em seu App. Quando o usuário não tem o App da transmissora, eles devem experimentar um fluxo de redirecionamento que também não deve envolver etapas adicionais do que seria o caso quando ele autentica diretamente na transmissora (por exemplo, ser redirecionado para o site mobile da transmissora).

Como funciona o fluxo de redirecionamento

Ao usar um serviço baseado no padrão de APIs Open Isurance Brasil para redirecionamento, o usuário será redirecionado duas vezes:

1. Da interface instituição receptora para a interface da transmissora (para autenticar e autorizar). O URI do servidor de autorização é especificado por cada transmissora em seu endpoint conhecido.

2. Na volta da interface da transmissora para a interface da receptora (para completar qualquer operação com a receptora). Este redirecionamento é especificado pela receptora como parte do primeiro redirecionamento.

Implementação de deep links

Uma jornada perfeita para o usuário, que ignora o navegador integrado (por exemplo, Safari) em seu dispositivo mobile, pode ser implementada para qualquer URL, ou seja, ambos: a) para o redirecionamento inicial para o qual a transmissora envia o usuário para os servidores da transmissora, E b) a URL de redirecionamento para o qual a transmissora envia o usuário de volta para a receptora após a autenticação/autorização.

Tanto transmissoras quanto receptoras devem seguir as orientações da Apple e do Google abaixo:

- iOS: Universal Links - Apple Developer (cobre mais de 99% de todos os usuários iOS, que estão no iOS 9 ou superior).

- Android: Handling Android App Links | Android Developers (cobre 65% de todos os usuários do Android, que estão no Android 6.0 ou posterior).

No caso de um usuário não ter o aplicativo instalado em seu dispositivo, ou se ele tiver um sistema operacional mais antigo ou sem suporte (por exemplo, Windows Mobile), esses métodos permitirão que o usuário seja redirecionado para uma página web mobile.

Calendário

Este anexo tem como objetivo detalhar quando a versão das APIs do Open Insurance é alterada, conforme a classificação da modificação.Ele poderá ser acessado clicando  aqui..

Major: Versão gerada para mudanças de legislação e atualização de documentações oficiais que só poderão ser lançadas com a anuência da SUSEP, por exemplo, v1.0.0 e v2.0.0;

Minor: Versão gerada quando forem realizadas atualizações que descompatibilizam o mercado, mas que não se tratam de versões major, por exemplo, v1.1.0 e v1.2.0;

Patch : Versão gerada quando há correção de bug ou alteração da documentação que não impacta ou descompatibiliza a API (v1.1.1).

OBS: A instituição deve obrigatoriamente refazer a certificação das APIs no Diretório de Participantes conforme release de uma versão major, minor ou patch.

Padrões

Estes padrões representam a versão 1.0.0, a qual fornece uma visão alto nível dos padrões.

Observe que, nesta proposta, as palavras-chave DEVEM, NÃO DEVEM, NECESSÁRIAS, RECOMENDADO, PODE e OPCIONAL, devem ser interpretadas conforme descrito na RFC2119.

Princípios

Os seguintes princípios técnicos não exaustivos constituem a base para o desenvolvimento e implementação das APIs para o Open Insurance no Brasil.

Princípio 1: Segurança

A adoção de mecanismos de segurança no design e implementação das APIs do Open Insurance no Brasil deverá considerar os padrões aplicáveis a cada uma de suas fases, visando a proteção e a disponibilidade do ecossistema como um todo, considerando clientes, participantes e os dados específicos compartilhados em cada fase.

Princípio 2: RESTful APIs

A API irá aderir aos conceitos de RESTful API sempre que for possível e sensato.

Princípio 3: Padrões existentes

Os padrões existentes serão adotados sempre que sua aplicação for relevante/apropriada e desde que não violem nenhum dos demais princípios, com foco na experiência do desenvolvedor e do usuário, e ainda, prevendo a extensibilidade, resiliência e a evolução do Open Insurance no Brasil.

Princípio 4: ISO 20022

Os payloads das APIs serão desenvolvidos utilizando como base os elementos e componentes de mensagem ISO 20022, que poderão ser modificados, caso necessário, para deixar o payload mais simples e/ou atender às características locais, tal como implementado em diferentes jurisdições.

Princípio 5: Extensibilidade

Os fluxos das APIs serão estendidos para atender a casos de uso mais complexos em futuros releases, e, portanto, esse princípio será mantido em mente durante o design, e os procedimentos serão detalhados durante a implementação.

Princípio 6: Códigos de Status

A API usará dois códigos de status que atendem a dois propósitos diferentes: (i) o HTTP status code reflete o resultado da chamada da API e (ii) um campo status em alguns resource payloads reflete o status dos resources nos casos de acesso write (p.ex. iniciação de pagamento).

Princípio 7: Identificadores únicos

Um recurso REST deverá ter um identificador exclusivo que possa ser usado para identificar o recurso alvo da API. Este identificador será usado para criar URLs que permitam endereçar recursos específicos, obedecendo aos padrões definidos nesta documentação, no item Formação e estabilidade do ID.

Princípio 8: Categorização dos requisitos de implementação

Quando um requisito estiver sendo implementado por um transmissor e/ou um receptor, uma categorização diferente será aplicada. As funcionalidades, endpoints e campos em cada recurso serão categorizados como 'Obrigatório', 'Condicional' ou 'Opcional'.

Princípio 9: Agnósticas

As APIs serão agnósticas à implementação onde elas poderão ser consumidas independente das tecnologias adotadas no ecossistema, porém com aderência aos princípios contidos nesta documentação.

Princípio 10: Idempotência

As APIs serão definidas como idempotentes para não causar uma experiência ruim ao consumidor ou aumentar os indicadores de risco falso positivo. Trata-se de recurso necessário para garantir que não haja duplicidade em caso de perda de comunicação e não deve se limitar aos verbos HTTP, devendo ser aplicado ao design completo da API.

Versionamento

Os padrões de versionamento das APIs do Open Insurance Brasil estão dispostos na seção Calendário

Estrutura da URI

A estrutura da URI para os endpoints deve ser implementada conforme abaixo:
<host> / open-insurance / <api> / <versão> / <recurso>

Os componentes desta estrutura de URI estão descritos abaixo:

• Host: O host de API da seguradora implementadora é um endereço base definido pela entidade transmissora de dados.
• “open-insurance”: Esta é uma string constante que representa a finalidade desta API.
• API: A API que será consumida (p.ex. channels).
• Versão: O número da versão da API. Na URI a versão deve ser precedida pela letra "v" seguida pelo número da versão a ser consumida (p.ex. v1, v2, v25).
• Recurso: O recurso a ser consumido dentro de uma API. Utilizando como exemplo a API channels, a mesma possui 5 recursos:
  • branches
  • electronic-channels
  • phone-channels

A versão minor será repassada apenas no header do payload de resposta, orientando a instituição receptora sobre quais serão os dados no retorno.

Como exemplo, para realizar o consumo do método electronic-channels da API channels na versão 1, a URI ficaria com a seguinte estrutura:

<host>/open-insurance/channels/v1/electronic-channels

Cabeçalhos HTTP

Cabeçalhos HTTP suportados e suas funções.

Cabeçalho de requisição

Cabeçalho de resposta

Códigos de resposta HTTP

Os códigos de resposta HTTP devem ser utilizados conforme tabela mais abaixo. Observação: com a implementação do cadastro por endpoint no diretório de participantes e conforme orientação do regulador, as instituições participantes NÃO DEVEM cadastrar endpoints de produtos ou serviços que não ofertem. Neste caso específico - a consulta em um endpoint não cadastrado - o status code esperado na resposta é o 404 - NOT FOUND.

Códigos

Convenções de payload

Esta seção do padrão descreve as estruturas padrões de requisição e resposta para todos os endpoints das APIs, assim como as convenções de nomenclatura para os atributos.

Estrutura de requisição

{
  "data": {
    "..."
  }
}

Cada requisição deve ser um objeto JSON contendo um objeto data para armazenar os dados primários da requisição.

No mesmo nível do objeto data, poderá existir um objeto meta se assim for especificado pelo endpoint. O objeto meta é usado para fornecer informações adicionais ao endpoint, como parâmetros de paginação, contagens de paginação ou outros propósitos complementares ao funcionamento da API.

A definição do conteúdo para o objeto data será definida separadamente para cada endpoint.

Estrutura de resposta

{
  "data": {
    "..."
  },
  "links":{
    "..."
  },
  "meta": {
    "..."
  }
}

Cada endpoint retornará um objeto JSON contendo os atributos abaixo:

• Se a resposta for bem-sucedida (200 OK), o objeto JSON irá conter:
  • obrigatóriamente um objeto data
  • obrigatóriamente um objeto links
  • opcionalmente um objeto meta, se necessário pela definição do endpoint requisitado
• Se a resposta for malsucedida (não 200 OK), o objeto JSON poderá conter:
  • um objeto errors (conforme a definição específica do endpoint)

A definição do conteúdo para os objetos data e meta será definida separadamente para cada endpoint.

O objeto links irá conter hypermedia (referências para recursos relacionados) para outros recursos da API requisitada.

O objeto de links sempre irá conter o atributo self que irá apontar para a URI da solicitação atual.

Estrutura de resposta de erros

{
  "errors": [
    {
        "code": "...",
        "title": "...",
        "detail": "..."
    }
  ],
  "meta":{
    "..."
  }
}

• O objeto errors será um array de zero ou mais objetos. Os atributos deste objeto serão os descritos abaixo:
  • obrigatoriamente o atributo code contendo um código de erro específico do endpoint;
  • obrigatoriamente o atributo title contendo um título legível por humanos do erro deste erro específico;
  • obrigatoriamente o atributo detail contendo uma descrição legível por humanos deste erro específico;
  • opcionalmente o objeto meta contendo dados adicionais sobre o endpoint que seja relevante para o erro.

Convenções de nomenclatura de atributos

Caracteres válidos em nomes de atributos

Todos os nomes de objetos e atributos definidos nos objetos JSON de requisição e resposta devem ser nomeados seguindo o padrão camelCase, tendo seu nome composto apenas por letras (a-z, A-Z) e números (0-9).

Qualquer outro caractere não deve ser usado nos nomes dos objetos e atributos, com exceção do caractere - (hífen), que poderá ser utilizado apenas conforme descrito na seção Extensibilidade.

Estilo de nomeação de atributos

Os nomes dos objetos e atributos devem ser nomes significativos e em língua inglesa. Quando houver diferença entre inglês americano e inglês britânico no termo a ser utilizado, deverá ser utilizado o termo em inglês britânico. P.ex. Utilizar o termo Post Code (Reino Unido) ao invés de Zip Code (Estados Unidos).

Arrays devem ser nomeados no plural. Demais atributos deverão ser nomeados no singular.

Convenções de propriedade dos atributos

Tipos de dados dos atributos

Cada atributo deverá estar associado a um tipo de dado. A lista de tipos de dados válidos está definida na seção tipos de dados comuns. Se um tipo de dado personalizado é necessário para um atributo, o mesmo deverá ser classificado como uma string com uma descrição clara de como o valor da propriedade deve ser interpretado.

Atributos Obrigatórios / Opcionais

Os atributos obrigatórios devem estar presentes e ter um valor não nulo, seja em uma requisição ou resposta, para que payload seja considerado válido.

Os atributos condicionais devem ter uma marcação de restrição vinculada a eles na documentação da API (Swagger), no campo 'description'.

Atributos vazios / nulos

Um atributo omitido (ou seja, um atributo que não está presente no payload) será considerado equivalente a um atributo que esteja presente com o valor null.

Uma string vazia (“”) não será considerada equivalente a null.

O valor booleano false não será considerado equivalente a null. Os atributos booleanos opcionais, por definição, possuirão três valores possíveis: verdadeiro (true), falso (false) e indeterminado (null).

Na situação onde o campo a ser informado no payload seja obrigatório e a Instituição, seja consumidora no envio ou transmissora no retorno, não a possuir, deve-se implementar o valor padronizado: “NA” - Não se Aplica, com exceção dos campos declarados como ENUM que deverão ser sempre preenchidos com os valores válidos para o ENUM correspondente.

Convenções de nomenclatura

Todos os nomes devem ser autoexplicativos, sem redundância de termos e sem ambiguidade de entendimento, além de seguir o padrão Lower Camel Case (primeira letra de cada termo maiúscula, com exceção do primeiro termo, que fica todo em minúsculas e sem espaços ou pontuações entre os termos). Ex: “areaCode”.

Os nomes das estruturas (composição de atributos sobre um assunto) que podem ter mais de uma ocorrência devem sempre estar no plural.

Os nomes dos atributos devem:

• Sempre estar no singular

• Nos casos em que o nome não ficar claro, devem ser incluídos mais termos para esclarecer o entendimento

• Para garantir o entendimento e a padronização, nos casos de atributos que tratem dados específicos, sempre devem ser usados termos complementares no fim dos nomes. São esses:

  • nomes = Name (p.ex. ownerName)
  • datas = Date (p.ex. openingDate)
  • horários = Time (p.ex. openingTime)
  • quantidades = Quantity (p.ex. eventLimitQuantity)
  • textos explicativos = Info* (p.ex. additionalInfo)

  *Para textos explicativos de informações complementares, o nome completo do atributo é “additionalInfo”

• Em atributos que sejam indicadores binários (flags), o nome deve estar formatado como pergunta, com um verbo como primeiro termo. Ex: "hasDeductibleOverTotalCompensation"

Tipos de dados comuns

Propriedades (em construção)

Paginação

Cada recurso de cada API pode possuir ou não paginação, caso a quantidade de registros retornados justifique a mesma. A paginação estará disponível e deverá funcionar independente se o recurso permite filtros por query ou POST. Isso é, filtros e paginação são aplicados de forma independente.

Parâmetros de Requisição

Exemplo de query com paginação

GET {uri}?page=1&page-size=25

Quando existir paginação para o recurso deverão ser utilizados os parâmetros de query abaixo para a navegação dos resultados:

Atributos de Resposta

Exemplo de paginação - Apenas uma página

A paginação das APIs são feitas no objeto principal da API. Por exemplo na API de branches, conforme exemplo abaixo, os registros a serem paginados são os objetos "branches". O mesmo deve ser seguido para as demais APIs, por exemplo, "products" nas APIs de produtos, "resources" na API de resources etc.

{
    "data": {
        "brand": {
            "name": "EXEMPLO",
            "companies": [
                {
                    "name": "SEGURADORA EXEMPLO",
                    "cnpjNumber": "123456",
                    "branches": [
                        {...},
                        {...},
                        {...}
                    ]
                }
            ]
        }
    },
    "links": {
        "self": "https://api.seguradora.com.br/open-insurance/channels/v1/branches",
    },
    "meta": {
        "totalRecords": 3,
        "totalPages": 1
    }
}

Exemplo de paginação - Primeira página

{
    "data": {
        "..."
    },
    "links": {
        "self": "https://api.seguradora.com.br/open-insurance/channels/v1/branches?page=1&page-size=25",
        "next": "https://api.seguradora.com.br/open-insurance/channels/v1/branches?page=2&page-size=25",
        "last": "https://api.seguradora.com.br/open-insurance/channels/v1/branches?page=10&page-size=25"
    },
    "meta": {
        "totalRecords": 250,
        "totalPages": 10
    }
}

Exemplo de paginação - Última Página

{
"data": {
    "..."
},
"links": {
    "self": "https://api.seguradora.com.br/open-insurance/channels/v1/branches?page=10&page-size=25",
    "first": "https://api.seguradora.com.br/open-insurance/channels/v1/branches?page=1&page-size=25",
    "prev": "https://api.seguradora.com.br/open-insurance/channels/v1/branches?page=9&page-size=25"
},
"meta": {
    "totalRecords": 250,
    "totalPages": 10
}

Além dos dados requisitados, as respostas paginadas também terão em sua estrutura dois objetos adicionais que incluirão parâmetros para facilitar a navegação das páginas:

Links

Os links devem sempre ser validados de acordo com o pattern publicado no swagger.

Quando preenchidos devem ter a mesma estrutura (schema, host, api, versão e recurso) do que esta sendo paginado.

No objeto links, serão retornadas hypermedia (referências para os recursos relacionados) de paginação conforme parâmetros abaixo:

Meta

No objeto meta, serão retornadas informações sobre o total de registros disponíveis

Regras Adicionais

• O tamanho máximo da página (page-size) é 1000 registros para qualquer endpoint (a menos que na API esteja especificado outros valores).
• A instituição transmissora/detentora pode definir um tamanho máximo da página (page-size) inferior ao tamanho máximo permitido pela API, caso entenda necessário diminuir o limite para atender o SLA de resposta.
• Caso a instituição transmissora/detentora defina um tamanho máximo de página (page-size) inferior, se for requisitado uma quantidade de registros maior do que seu limite operacional, e desde que o valor esteja de acordo o tamanho máximo permitido pela API, esta deverá responder entregando os dados e utilizando o page-size do seu limite operacional definido.
• A instituição transmissora/detentora deve realizar os ajustes de paginação antes de efetivar a consulta:
• Ex: Ao solicitar a segunda pagina 1000 registros, para uma instituição que trabalha com max size 800, a transmissora deve retornar os itens de 801 a 1600.
• Se for requisitado uma quantidade de registros maior que o suportado pela API, o retorno será o código HTTP status code 422 Unprocessable Entity, indicando que o servidor entendeu a requisição, mas não é possível processá-la conforme foi solicitado.

Formação e Estabilidade do ID

Dentro desses padrões, a serem melhor especificados a partir da Fase 2 do Open Insurance no Brasil, os IDs de recursos são necessários para atender ao seguinte:

• O ID de um recurso deve ser especificado no endpoint de uma API apenas para obter detalhes do recurso ou para realizar alterações no mesmo.
• Se o ID for especificado nos padrões do Open Insurance, então ele é obrigatório e deverá ser fornecido pela entidade implementadora da API de acordo com o padrão definido.
• Se um ID for especificado, o mesmo deverá ser totalmente desconectado de significados com outras entidades. Por exemplo, um ID não deve ser uma combinação de outros campos ou uma string que possa ter conteúdo sensível que possa ser extraído.
• Os IDs devem ser únicos, e sua padronização será detalhada a partir da Fase 2 do Open Insurance no Brasil, porém sua unicidade pode estar dentro de um contexto. Por exemplo, um ID de apólice deve ser único, porém apenas dentro do contexto de apólice.
• Nos payloads o nome de campo "id" nunca deverá ser utilizado. Cada campo ID deverá ter um nome significativo, dessa forma independentemente de onde o ID for utilizado entre múltiplos endpoints, ele sempre irá se referir ao seu objeto principal. Por exemplo, IDs para apólices deverão ser representados no JSON como "policyId".

Princípios para a formação de IDs (identificadores) de recursos nas APIs

• O ID DEVE ser uma string com limitação de 100 caracteres - limite que poderá ser revisitado em caso de necessidade apresentada por quaisquer dos participantes do Open Insurance Brasil e - aderente aos padrões apresentados na seção 2.1 da RFC 2141;
• Uma vez que será trafegado nas chamadas de interface, o ID NÃO DEVE conter dados classificados como PII - Personally identifiable information (Informação Pessoalmente Identificável) ou Informação de Identificação Pessoal;
• DEVE ser garantida a unicidade do ID dentro do contexto da API assim como a estabilidade do mesmo, sendo a estabilidade condicionada à manutenção das características de identificação natural do recurso em questão. A alteração das características de identificação natural implica na geração de um novo identificador associado ao recurso;
• A utilização de meios técnicos razoáveis e disponíveis para a formação do ID é de livre implementação por parte da instituição transmissora dos dados, de forma que apenas a aderência aos princípios elencados nesta documentação é mandatória.

Extensibilidade

Os padrões do Open Insurance podem não cobrir todas as possibilidades de objetos retornados ou APIs que os participantes desejam expor. Os participantes podem ter o desejo de realizar inovações sobre os padrões definidos oferecendo mais dados afim de atender demandas específicas de mercado. É nossa intenção que os padrões definidos não apenas permitam estas extensões como também sirvam como base para futuras alterações na própria definição dos padrões.

No entanto, é importante que um participante que esteja querendo estender as APIs não impeça um consumidor que foi projetado para consumir apenas o endpoint padrão funcione corretamente.

Para atender tanto as demandas de quem deseja estender as APIs (participantes) quanto as demandas de quem irá realizar o consumo (consumidor das APIs), foram definidos os critérios abaixo.

É possível estender os padrões nos seguintes aspectos:

• O participante pode oferecer uma API completamente nova que não está coberta nos padrões definidos
• O participante pode oferecer novos endpoints em uma API que já foi definida no padrão
• O participante pode oferecer campos de entrada e retorno opcionais para um endpoint que já foi definido no padrão

ID dos participantes

Cada participantes terá um ID que representa a sua instituição. Os participantes da atual versão estão listados abaixo:

• ALLI - ALLIANZ SEGUROS S.A.
• AUST - AUSTRAL SEGURADORA S.A.
• BRAS - BRADESCO SEGUROS S.A.
• BRCA - BRASILCAP CAPITALIZAÇÃO S.A.
• BRPR - BRASILPREV SEGUROS E PREVIDÊNCIA S.A.
• BRSE - BRASILSEG COMPANHIA DE SEGUROS
• BTGS - BTG PACTUAL SEGUROS S.A.
• CAIS - CAIXA SEGURADORA S.A.
• CAIV - CAIXA VIDA E PREVIDÊNCIA S.A.
• CARD - CARDIF DO BRASIL VIDA E PREVIDÊNCIA S.A.
• CHUB - CHUBB SEGUROS BRASIL S.A.
• EULE - EULER HERMES SEGUROS S.A.
• HDIG - HDI GLOBAL SEGUROS S.A
• HDIS - HDI SEGUROS S.A.
• ICAT - ICATU SEGUROS S.A
• ITAS - ITAU SEGUROS S.A.
• LIBE - LIBERTY SEGUROS S.A.
• MAPF - MAPFRE SEGUROS GERAIS S.A.
• PORT - PORTO SEGURO COMPANHIA DE SEGUROS GERAIS
• PRUD - PRUDENTIAL DO BRASIL SEGUROS DE VIDA S.A
• SAFR - SAFRA SEGUROS GERAIS S.A.
• STDA - SANTANDER AUTO S.A.
• STDC - SANTANDER CAPITALIZAÇÃO S.A.
• SOMP - SOMPO SEGUROS S.A.
• SULA - SUL AMÉRICA SEGUROS DE PESSOAS E PREVIDÊNCIA S.A.
• TOKI - TOKIO MARINE SEGURADORA S.A.
• TOOS - TOO SEGUROS S.A.
• XPVP - XP VIDA E PREVIDÊNCIA S.A.
• XS3S - XS3 SEGUROS S.A.
• XS4C - XS4 CAPITALIZAÇÃO S.A.
• ZURB - ZURICH BRASIL COMPANHIA DE SEGUROS
• ZURS - ZURICH SANTANDER BRASIL SEGUROS S.A.

Participantes que desejam estender os padrões devem adicionar seu prefixo para identificar todas as extensões. Campos adicionais no retorno de endpoints existentes ou em novos endpoints devem usar o prefixo do participante. O prefixo deve ser no formato exposto ao lado (4 letras) e não devem haver prefixos duplicados entre os participantes.

Nesta documentação, quando tivermos que nos referir ao prefixo do participante, o termo <PID> será utilizado.

Novas APIs

Quando a extensão for a criação de uma nova API, o participante deve adicionar seu prefixo a URI antes do nome da nova API, conforme exemplo abaixo.

Por exemplo, uma API definida pelo padrão seguirá o seguinte formato: <host> / open-insurance / <api> / <versão> / <recurso>

Uma API estendida por um participante deverá estar no formato abaixo: <host> / open-insurance / <PID> / <api> / <versão> / <recurso>

Para os endpoints definidos dentro da estrutura acima, os atributos dos payloads não precisam conter o prefixo do participante, pois entende-se que todos os recursos da API estendida não conflitam de nenhum modo com as definidas pelo padrão.

Novos endpoints em APIs existentes

Quando o participante desejar adicionar um novo endpoint em uma API já especificada no padrão, o participante deve incluir seu <PID> como prefixo do recurso que será implementado.

Por exemplo, assumindo a existência do endpoint abaixo para consulta dos sinistros de um seguro de automóvel: <host>/open-insurance/insurance-auto/v1/{policyId}/claim

Se o participante deseja adicionar um novo endpoint que resume os sinistros por um período, então este endpoint poderia ser definido como: <host>/open-insurance/insurance-auto/v1/{policyId}/<PID>-claims-movement

Campos de retorno adicionais em um endpoint existente

Quando o participante desejar adicionar um novo campo ao payload de resposta, o atributo deverá receber o prefixo do participante seguido por um hífen <PID>-.

Se um objeto estiver sendo adicionado ao payload de resposta, apenas o nome do objeto precisa receber o prefixo. Qualquer atributo dentro do novo objeto pode ser nomeado normalmente.

Parâmetros query adicionais

Quando for adicionado um novo parâmetro de query a um endpoint existente, o novo parâmetro deve ter o prefixo <PID>-, evitando assim colisões com parâmetros já existentes.

Filtro de Dados

Opcionalmente, a entidade transmissora de dados poderá realizar filtro de dados através de query de entrada, baseado em campos que julgue relevante para a melhor experiência do cliente.
A informação de quais possibilidades estarão disponíveis (query parameter) deverá constar em documentação adicional disponibilizada pela entidade transmissora.

Extensão do versionamento

Como descrito na seção calendário, o versionamento existe apenas no nível das APIs e não no nível dos endpoints, no entanto caso seja necessário realizar versionamento de um endpoint customizado, o participante poderá utilizar o header x-<PID>-v para que o consumidor possa especificar qual versão do endpoint está requisitando.

Requisitos Não Funcionais

Este material tem como principal objetivo apresentar ao usuário quais são os requisitos não funcionais presentes no OPIN (Open Insurance). Assim as sociedades participantes devem observar tais pontos na implementação das APIs relacionadas ao OPIN.

Limites de tráfego

As APIs deverão suportar, no mínimo:

I - 300 requisições por segundo globalmente, ou seja, independente do endereço IP (Internet Protocol) do qual provêm as requisições;

II - 500 requisições por minuto originadas de um mesmo endereço IP.

As requisições que excederem os limites poderão ser enfileiradas ou recusadas, caso em que deverão ser respondidas com o código de status HTTP 429 (Too Many Requests). Por fim, as requisições que ultrapassarem os limites deverão ser desprezadas no cálculo do tempo de resposta das implementações das APIs.

Desempenho

Deverá ser medido o tempo de resposta de cada requisição, ou seja, o tempo transcorrido entre o recebimento de uma requisição que não ultrapassa os limites de tráfego e o momento em que a requisição é completamente respondida. Adicionalmente, esta medição deverá ser feita de maneira que os tempos medidos sejam os mais próximos possíveis dos tempos de resposta experimentados por quem fez a requisição. Neste contexto, as APIs deverão manter o percentil 95 do tempo de resposta em no máximo:

I - 1000ms, caso sejam classificadas como APIs de alta prioridade;

II - 1500ms, caso sejam classificadas como APIs de média prioridade;

III - 4000ms, caso sejam APIs administrativas.

Por exemplo, em um dia que uma API da alta prioridade receba 10.000 requisições, o tempo de resposta de pelo menos 9.500 requisições deve ser inferior a 1.000ms.

Disponibilidade

As APIs “Produtos e Serviços”, “Canais de Atendimento” e “Situação do Ambiente” deverão satisfazer requisitos mínimos de disponibilidade. Cada um de seus endpoints deverá estar disponível:

I - 85% do tempo a cada 24 horas;

II - 95% do tempo a cada 1 mês;

III - 99,5% do tempo a cada 3 meses.

Há perspectiva de elevação dos requisitos mínimos de disponibilidade das APIs destinadas ao compartilhamento de outros dados e serviços do escopo do Open Insurance, conforme necessidade futura. O Portal do Open Insurance deverá conter uma especificação detalhada de como a disponibilidade de cada endpoint será calculada.

Link para a última versão do manual de APIs

Manual de APIs do Open Insurance

Segurança

Introdução - Segurança

Esta seção tem como finalidade auxiliar na auto avaliação aos cumprimentos dos requisitos de segurança da informação relacionados a autorização e autenticação de APIs e End-Users, emissão de certificados digitais e requisitos para o onboarding no Diretório de participantes para as Instituições participantes do Open Insurance.

As instituições participantes do Open Insurance possuem a obrigação de acompanhar a edição e a revogação de eventuais normas com impacto no tema de forma a estar permanentemente em dia com as determinações legais. Compõem, de forma não exaustiva, o rol de atos normativos cuja observância é essencial pelas instituições participantes do Open Insurance:

Estas especificações baseiam-se, referenciam, e complementam, quando aplicável, os seguintes documentos:

Além desse guia, foi elaborado um checklist para auxiliar os participantes do Open Insurance a alcançar um nível adequado de Segurança da Informação, esse checklist pode ser baixado em formato Excel a seguir:

Download Autoavaliação dos requisitos de SI - 1.0.xlsx

Visão geral

As APIs de Open Insurance estão dividas em dois escopos:

• open-data
• customer-data

Segue, a continuação, um overview das camadas de segurança básicas para atender os contextos Open-data:

Manual de Segurança

A documentação que detalha os controles técnicos de segurança que serão implementados na arquitetura do Open Insurance junto do conjunto padronizado de regras e requisitos para formação do framework de confiança para acesso de recursos protegidos pode ser acessado aqui

Diretrizes Técnicas de Certificação

Para a entrada segura e assertiva no Ecossistema do Open Insurance Brasil, a Estrutura Inicial disponibilizou um conjunto de ferramentas e infraestrutura para suportar o processo de testes e homologação dos produtos e serviços desenvolvidos pelas Instituições Participantes. Foram disponibilizados ambientes que habilitam ao participante:

• Realizar testes da camada de segurança de suas aplicações e posterior certificação dessas aplicações, utilizando a estrutura criada e mantida pela Open ID Foundation (“Motor de Conformidade de Segurança”);

• Submeter, ainda em tempo de desenvolvimento, suas implementações das APIs do Open Insurance a testes automatizados funcionais (“Motor de Conformidade Funcional”).

Lembramos que uma implementação de versão de API do Open Insurance só poderá ser registrada no ambiente produtivo do Diretório caso tenha sido certificada nos testes de segurança e funcionais.

Todos os detalhes para a execução dos testes e obtenção dos certificados podem ser encontrados no material de orientações do Processo de Segurança. Estes materiais estão em processo contínuo de atualização, podendo sofrer alterações. Qualquer dúvida em relação ao processo, fique à vontade para a submissão de tickets através do Service Desk .

Materiais complementares

1. Certificação de segurança, OP
   1. Documentação: https://openid.net/certification/op_submission
   2. Termos: https://openid.net/certification/instructions/#:~:text=OpenID%20Certification%20Terms%20and%20Conditions
   3. Solicitação: https://openid.atlassian.net/servicedesk/customer/portal/3/group/3/create/10016
   4. Abertura de chamados: https://gitlab.com/openid/conformance-suite/-/issues
2. Certificação de segurança, RP
   1. Documentação: https://openid.net/certification/connect_rp_submission/
   2. Termos: https://openid.net/certification/instructions/#:~:text=OpenID%20Certification%20Terms%20and%20Conditions
   3. Solicitação: https://openid.atlassian.net/servicedesk/customer/portal/3/group/3/create/10016
   4. Abertura de chamados: https://gitlab.com/openid/conformance-suite/-/issues

Workshops

• 1º Workshop Plantão de Dúvidas com as Autoridades Certificadoras - Certificados ICP Brasil (13/07/2022)

• 2º Workshop Plantão de Dúvidas com as Autoridades Certificadoras - Certificados ICP Brasil (20/07/2022)

• 1º Workshop Processo de Certificação FAPI com OpenID Foundation (28/07/2022)

• 2º Workshop Processo de Certificação FAPI com Open ID Foundation (18/11/2022)

• 3º Workshop Processo de Certificação FAPI com Open ID Foundation (09/01/2023)

Visão Geral do Ecossistema

Em sua essência, o Open Finance Brasil é um ecossistema de compartilhamento de dados onde os clientes de bancos e outras instituições financeiras desejam compartilhar suas informações de conta ou dar permissão para que os pagamentos sejam executados em seu nome com serviços de terceiros e o Open Insurance Brasil utiliza os padrões de segurança do Open Finance Brasil.

Há uma série de funções necessárias para vincular qualquer sistema de identificação, autenticação e autorização, independentemente do setor. Todas essas funções são necessárias, mas várias funções podem ser desempenhadas por cada participante. Em geral, o usuário final (“Subject”), está dando a um sistema (“Client”) uma autorização (“Access Token”) para acessar um recurso protegido mantido pelo provedor (“Resource Server”). Isso exige que o Subject e o Client sejam identificados e autenticados e que a autorização seja confirmada.

As regras exatas e os requisitos legais para cada função em um setor específico formam um framework de confiança ("Trust Framework"). Cada ecossistema requer um conjunto padronizado de regras e requisitos legais que abrangem todas as funções e obrigações das interações acima. A combinação de quem fornece qual(is) função(ões), os níveis aos quais eles devem desempenhar essas funções e os padrões pelos quais essas operações devem ser definidas por um framework de confiança específico do setor.

Diferentes frameworks de confiança terão diferentes opções de implementação, mas um framework de confiança comum é um pré-requisito para transformar um ‘setor’ em um ‘ecossistema’. Um framework de confiança comum reduz significativamente a complexidade e custos, aumenta a escalabilidade e a interoperabilidade dentro do setor, bem como abre opções para o tipo de padronização intersetorial que o Open Insurance Brasil está buscando.

Diferentes implementações podem ser definidas para setores, com diferentes prós / contras e custos associados para diferentes participantes. Cada uma das implementações propostas pode ser usada para qualquer setor se os pré-requisitos corretos estiverem em vigor. A solução certa dependerá do apetite e alinhamento de cada conjunto de participantes.

A implementação de um mecanismo comum para o Open Insurance Brasil exigirá um compromisso com a simetria entre os setores para incluir detalhes específicos do setor nos princípios do framework de confiança.

É necessário fazer escolhas técnicas para garantir que qualquer implementação forneça uma base estrita e consistente para ter credibilidade, mas mantenha a flexibilidade para se adaptar às necessidades futuras. Isso implica padrões de código-fonte aberto amplamente disponíveis, amplamente compreendidos e que foram experimentados e testados. Além de habilitar um gama de parceiros e fornecedores que podem apoiar qualquer construção técnica, o que significa que continuará havendo espaço para desenvolvimento comercial de soluções.

Participantes de um Ecossistema de Compartilhamento de Dados

Nos ecossistemas de Open Insurance voltados para o consumidor que estamos considerando, temos três participantes principais:

• O cliente (user)
• A instituição transmissora de dados (provider), que oferece serviços de seguros
• A instituição receptora de dados (TPP - Third Party Provider), que oferece uma proposta de Open Insurance para o cliente:

Em todos os casos a seguir, assumimos:

• Um cliente possui uma conta para um serviço principal ou conjunto de recursos numa instituição transmissora de dados
• Uma instituição receptora de dados oferece ao cliente uma proposta habilitada por meio do compartilhamento inteligente de dados
• O cliente dá consentimento à instituição receptora de dados para fins de entrega dessa proposta
• A instituição transmissora de dados tem a obrigação de salvaguardar os dados do cliente, mas também de compartilhá-los quando instruído.

O ecossistema também possui provedores de serviços de confiança, que são entidades que fornecem garantia técnica a ambas instituições (transmissoras e receptoras) de que todos estão autorizados a participar do ecossistema.

Os padrões técnicos necessários para dar suporte ao framework de confiança devem atender todos os requisitos a seguir:

• Identificação de todos os participantes do ecossistema
• Autenticação quando exigida de todos os participantes entre si
• Confirmação de autorização de todos os participantes em um ecossistema de compartilhamento de dados

Os serviços técnicos necessários para suportar um ecossistema devem habilitar todos os requisitos acima em uma base e modo contínuos, isto é, não apenas em um único ponto de registro.

Princípios de Especificação e Requisitos de Alto Nível

O Open Insurance Brasil adotou os seguintes princípios e requisitos de alto nível no que diz respeito às normas técnicas.

• Consentimento
  • Os clientes devem estar sempre no controle de quem tem acesso aos seus dados e para quais fins eles estão sendo usados.
• Minimização de dados
  • Os clientes devem ser capazes de compartilhar apenas os dados de que precisam, pelo tempo que for necessário.
• Segurança
  • Uma modelagem de ameaças foi produzido avaliando todas as fraquezas potenciais nos processos de comunicação.
  • Todos os pontos fracos identificados foram corrigidos.
• Identificação
  • Todos os participantes devem ter segurança na identificação de todos os atores do ecossistema.
• Autenticação
  • Todos os participantes devem comunicar as etapas que foram executadas para autenticar cada participante no ecossistema e em que nível isso foi executado.
• Integridade e não repúdio
  • Todos os participantes devem ser capazes de provar que as mensagens não foram adulteradas e, na verdade, foram enviadas apenas por um participante legítimo.

Além dos requisitos de alto nível, os seguintes princípios também foram adotados.

• Não reinventar a roda, se existir uma especificação que seja adequada para o propósito, amplamente adotada e publicamente disponível, deve-se adotá-la.
• Envolver-se com outros órgãos de normalização para aprender com experiências anteriores sobre o que funcionou, o que não funcionou, e o que pode ser feito melhor.
• Assegurar o amplo suporte da indústria para garantir o máximo de chances de sucesso e, mais importante, a segurança do cliente.
• Solicitar feedback com antecedência e com frequência, reconhecer que serão necessárias várias iterações para desenvolver um padrão.
• O framework de confiança que sustenta o ecossistema de compartilhamento de dados, que é o Open Insurance Brasil, é um framework técnico que precisa ser flexível o suficiente para permitir que os participantes e o ecossistema inovem, cresçam e se desenvolvam, enquanto permanecem interoperáveis.

Todos os participantes devem ter certeza de que todos os atores do ecossistema estão lidando com seus dados com segurança tempo todo. Isso requer que todos os participantes testem publicamente seus sistemas quanto à conformidade com as especificações e disponibilizem os resultados de seus testes de conformidade para exame público de outros participantes.

Este é um requisito aplicável à instituições participantes transmissoras e receptoras de dados.

Principais Padrões de Segurança

Estrutura de Autorização OAuth 2.0

O ecossistema de compartilhamento de dados definido pelo Brasil consiste em muitos padrões diferentes, todos girando em torno de conceitos, funções e obrigações que foram tecnicamente definidos no OAuth 2.0 Authorization Framework.

A estrutura de autorização OAuth 2.0 permite uma aplicação de terceiros (third-party application) obter acesso limitado a um serviço HTTP, seja em nome do proprietário de recurso (resource owner) por meio da orquestração de uma interação de aprovação entre o proprietário do recurso e o serviço HTTP, ou permitindo a aplicação de terceiros obter acesso em seu próprio nome.

A especificação base OAuth 2.0 não fornece, por si só, informações suficientes para atender a todas as necessidades definidas pelo framework de confiança do Open Insurance Brasil. Mais notavelmente, não possui uma maneira de transmitir informações de identidade do cliente em um formato padronizado de uma instituição transmissora para uma receptora, e os mecanismos de autenticação que foram definidos na especificação original não são seguros o suficiente para atender aos requisitos de uma indústria altamente regulamentada.

OpenID Connect - A Camada de Identidade para a Internet

Este perfil herda todas as obrigações do OAuth 2.0

OpenID Connect é um conjunto de especificações simplificadas que fornecem uma estrutura para interações de identidade por meio de APIs do tipo REST. A implementação mais simples do OpenID Connect permite que clients de todos os tipos, incluindo baseados em navegador, celulares e clients javascript, solicitem e recebam informações sobre identidades e sessões atualmente autenticadas. O conjunto de especificações é extensível, permitindo que os participantes também suportem, opcionalmente, criptografia de dados de identidade, descoberta do OpenID Provider e gerenciamento avançado de sessão, incluindo logout.

O grupo de trabalho OpenID Foundations Connect tem sido o guardião do Padrão de Identidade “de fato” da Internet por muitos anos, trabalhando em várias especificações que se baseiam no framework de autorização OAuth 2.0, adicionando recursos e requisitos de suporte para melhorar a segurança do framework em si.

Open ID Connect Core: é um perfil do OAuth 2.0, o que significa que herda todos os requisitos e obrigações do OAuth 2.0, mas define o conceito de um id_token e introduz novos mecanismos de autenticação.

Open ID Connect Discovery: apresenta o conceito de um documento de descoberta usado por OpenID Connect (OIDC) Providers para anunciar como os clients OAuth 2.0 podem se comunicar com eles e quais recursos e opções o OIDC Provider oferece suporte.

RFC7591: além de definir o processo de registro dinâmico de clients OAuth, esta especificação apresenta o conceito de Software Statement (“Declaração de Software”), que pode ser usada para fornecer informações sobre um client que é atestado por um serviço de terceiros. Outros atributos de metadados também são definidos no OpenID Connect Registration Specification:

Esta especificação define mecanismos para registrar dinamicamente clients OAuth 2.0 com Authorization Servers (servidores de autorização). Pedidos de registro enviam um conjunto de valores de metadados do client desejado para o Authorization Server. As respostas de registro resultantes retornam um client identifier para ser usado no Authorization Server e os valores de metadados registrados para o client. O client pode então usar esta informação de registro para se comunicar com o Authorization Server usando o protocolo OAuth 2.0. Esta especificação também define um conjunto de campos de metadados do client e valores para os clients usarem durante o registro.

RFC7592: Esta especificação define métodos de gerenciamento de dynamic client registration (registros de cliente dinâmico) do OAuth 2.0 para casos de uso em que as propriedades de um client registrado necessitam ser alteradas durante a vida do client.

As especificações acima são especificações básicas cuja leitura obrigatória sustenta o framework de confiança do Open Insurance Brasil. Entretanto, eles ainda são insuficientes para atender a todos os requisitos e princípios descritos anteriormente.

OpenID Financial Grade 1.0: Baseline

Este perfil herda todas as obrigações do OpenID Connect Core

Reconhecendo as ameaças e riscos restantes que não foram tratados pelo OpenID Connect Core, o grupo de trabalho Financial Grade tem como foco criar uma especificação que visa identificar e endereçar os pontos fracos na especificação OpenID Connect, essencialmente criando um perfil para casos de uso que exigem alto nível segurança.

O perfil Baseline foi originalmente planejado para ser mais facilmente implementado por clients e OpenID Providers às custas de alguns elementos de segurança e, como tal, não oferece o mesmo grau de proteção contra violação de solicitação e resposta.

OpenID Financial Grade 1.0: Avançado

Este perfil herda todas as obrigações do OpenID FAPI 1.0: Baseline

O FAPI 1.0: Advanced profile é atual padrão ouro para API Security, fornecendo um framework de especificação que foi usado como ponto de partida para a criação de uma especificação para o Open Insurance Brasil.

Este padrão especifica um perfil de segurança avançado do OAuth que é adequado para ser usado para proteger APIs com alto risco inerente. Os exemplos incluem APIs que dão acesso a dados altamente confidenciais ou que podem ser usados para acionar transações financeiras (por exemplo, início de pagamento). Este padrão especifica os controles contra ataques, como: violação de solicitação de autorização, violação de resposta de autorização, incluindo injeção de código, injeção de estado e phishing de solicitação de token.

Sobre o uso de JARM

O suporte ao JARM é opcional aos transmissores e detentores de contas (ASPSP) e, portanto, as instituições que optarem pelo uso do JARM devem, no processo de certificação de segurança, atestar também o suporte a outro profile que não considere o uso do padrão JARM, ou seja, deve também se certificar com um dos profiles listados na tabela a seguir.

Guia do Usuário para Entidades Transmissoras de Dados

1.0 Registrando um Participante

1.1 Visão Geral do Diretório

Os serviços do framework de confiança providos pelo Open Insurance Brasil fornecem todos os serviços de descoberta necessários para que instituiçoes transmissores e receptoras interajam entre si, sem que seja preciso validar individualmente a autenticidade de cada participante.

Um Authorization Server ou AS, conforme definido por RFC 6749 - The OAuth 2.0 Authorization Framework, executa várias funções em um ecossistema de compartilhamento de dados como o Open Insurance Brasil. Antes de prosseguir, certifique-se de que os conceitos de funções e responsabilidades definidos na RFC original sejam bem compreendidos. Além disso, certifique-se de que os conceitos, funções e responsabilidades definidos no OpenID Connect Core e como eles estendem os conceitos definidos no RFC 6749 são igualmente bem compreendidos.

1.2 Registrando um Authorization Server e OpenID Provider

As seguradoras, geralmente grandes seguradoras, não serão uma entidade única do ponto de vista das operações de tecnologia. Eles podem ter marcas, segurança e infraestrutura de TI diferentes para diferentes segmentos de clientes, ou podem ter alguma infraestrutura de TI que ofereça suporte a várias marcas ou segmentos de clientes. Isso significa que o ecossistema técnico precisa ser flexível o suficiente para suportar uma ampla variedade de implantações de infraestrutura de seguradoras, garantindo que os serviços necessários possam ser descobertos por clientes de instituições receptoras que precisam interagir com ele.

Um modelo flexível para anunciar serviços de autenticação / autorização e os recursos protegidos pelo AuthN e AuthZ é suportado pelo Diretório.

• Customer Friendly Name - Será exibido aos clientes pelas instituições receptoras, e já deve ser reconhecido pelos clientes da seguradora.
• Customer Friendly Logo - Será exibido aos clientes pelos instituições receptoras para auxiliar no reconhecimento da marca.
• Description - Isso pode ser exibido aos clientes pelas instituições receptoras para auxiliar no reconhecimento da marca.
• Terms of Service - Este é um link para os Termos de Serviço da seguradora, que podem ser incluídos pelas instituições receptoras.
• Notification WebHook - Authorization Servers podem registrar um WebHook que receberá atualizações por push sobre as alterações dos participantes, seus softwares ou certificados.
• OpenID Well Known Document Uri - Link para o documento de descoberta do Authorization Server.

Uma seguradora pode optar por ter um Authorization Server ou muitos, desde que satisfaça os seguintes requisitos:

• Um cliente pode reconhecer o Authorization Server como um local com o qual normalmente faria interação com a sua seguradora.
• O Authorization Server pode emitir tokens para os recursos e serviços que um cliente ou insituição receptora está procurando.
• O Authorization Server das instituições transmissoras/detentoras de contas que atenda mais de uma marca deve aceitar mais de um cadastro (criação de client_ids) para um mesmo software statement. Caso a solução de Authorization Server não suporte este comportamento, deverá ser adequado para suportar múltiplas marcas e o cadastramento das marcas no diretório deverá sofrer apontamento de acordo com cada marca.

1.3 Registrando Recursos

Depois que uma seguradora registra um Authorization Server, ela precisa anunciar para quais recursos, APIs ou serviços ele pode fornecer autorização.

No exemplo acima, a Seguros Incríveis está anunciando dois serviços que devem ser reconhecidos pelos clientes. “Seguros Incríveis - Empresas" e “Seguros Incríveis". Estes podem ou não estar diretamente relacionados a “Marcas”, pois seguradoras diferentes podem precisar anunciar serviços de autenticação diferentes, mesmo dentro de uma submarca.

Além disso, a seguradora anuncia quais recursos cada um dos servidores de autorização está protegendo ou oferecendo. No exemplo acima, a Seguros Incríveis é compatível com a versão 1 e a versão 2 da API de seguros de automóveis, e o “Amazing Insurances” tem dois sistemas separados de consentimento e informações dos clientes de seguros.

Anunciar corretamente quais recursos são oferecidos por cada servidor é importante para atingir a escala prevista pelo Open Insurance Brasil, além de ser fundamental para garantir que os clientes possam identificar sua seguradora facilmente e que as instituições receptoras possam encaminhar os clientes para o Authorization Server correto com base nos recursos protegidos por cada serviço.

2.0 Validando uma Solicitação de Registro de Cliente

Usando o OpenID Connect Discovery e a especificação de Dynamic Client Registration (DCR) do Open Insurance Brasil. Uma instituição receptora pode registrar seu aplicativo em cada um dos Authorization Servers disponíveis no ecossistema.

2.1 Registro OpenID Connect e OAuth 2.0 Dynamic Client Registration

Consulte a Cláusula 7 da Especificação de Dynamic Client Registration (DCR) do Open Insurance Brasil para obter detalhes.

2.2 Processamento de declaração de software (Software Statement Assertion)

Consulte a Cláusula 8 da Especificação de Dynamic Client Registration (DCR) do Open Insurance Brasil para obter detalhes.

3.0 Validando um Pedido de Autorização

Consulte a Cláusula 5 do Perfil de Segurança do Open Finance Brasil (Financial-grade API Security Profile) para obter detalhes.

Guia do Usuário para Instituições Receptores de Dados

1.0 Registrando um Aplicativo

Em um alto nível, as seguintes etapas principais são necessárias para integrar um novo aplicativo no ecossistema Open Insurance Brasil.

1. Cadastre sua organização no Diretório de Participantes (Interface do Usuário)
2. Cadastre seu aplicativo no Diretório de Participantes (Interface do Usuário)
3. Obtenha credenciais para sua aplicação junto à uma autoridade certificadora ICP-Brasi)(fora do escopo deste documento)
4. Registre suas credenciais para o seu aplicativo no Diretório de Participantes (Interface do Usuário)
5. Identifique provedores de informações de conta ou serviços de pagamento de interesse dos clientes de seu aplicativo, pesquisando o Diretório de Participantes (API)
6. Registre seu aplicativo com cada provedor (API)

1.1 Diagrama de Sequência

1.2 Visão Geral do Diretório

O framework de confiança do Open Insurance Brasil fornece todos os serviços de descoberta necessários para que instituições participantes (receptoras e transmissoras de dados, iniciadoras de serviçoes de seguros) interajam entre si sem serem obrigadas a validarem a autenticidade de identidades, autorizações, Apps, APIs ou credenciais para acessos por aplicativos uns dos outros. Além disso, fornece um único registro de todas propostas ao consumidor sendo oferecidas no mercado e um único ambiente de controle para as autoridades regulatórias que concedem permissões para gerenciar participantes dentro do ecossistema.

O framework de confiança não tem visibilidade ou visão das interações que ocorrem entre instituições participantes receptoras ou transmissoras de dados. Ele é projetado para fornecer confiança e garantia de identidade e autorização apenas. Ele não se enquadra no fluxo de comunicação entre um consumidor e um provedor e não tem conhecimento ou visibilidade de quaisquer dados do cliente. Este modelo de framework de confiança é conhecido como confiança transitiva onde duas partes, uma transmissora e uma receptora, concordam em confiar nas declarações e atestados de legitimidade uns dos outros emitidos por um provedor de confiança comum e, em seguida, prossigam comunicando o que quiserem, sem qualquer validação adicional onerosa ou outro tipo de verificação.

1.3 Acessando o Diretório

Este guia do usuário assume que as organizações participantes já passaram pelo processo de iniciação com a Estrutura Inicial do Open Insurance Brasil e já concluíram todas as integrações necessárias, processos de assinatura de contrato e inclusão de administrador individual.

1.4 Criação de uma Nova Declaração de Software (SSA)

Uma declaração de software descreve um aplicativo inserido naquilo que pode ser considerado a ‘App Store’ do Open Insurance Brasil. Este registro de aplicativo contém todas as informações necessárias para que uma seguradora identifique tecnicamente e interaja com o aplicativo, além de conter todas as informações que auxiliam os clientes que estejam utilizando-o a confirmar sua legitimidade.

Um novo aplicativo ou declaração de software pode ser registrado fazendo logon no Diretório, acessando sua organização, navegando até ‘Declarações de software’, clicando em ‘Declarações de novo software’ e preenchendo o formulário. Lembre-se de que a maioria dessas informações será exibida aos clientes pelas Seguradoras como parte do processo de redirecionamento ou autorização. Como tal, é importante que todas as URIs e descrições sejam relevantes para o público.

1.4.1 Atribuição de Funções Regulatórias de Software

Em um ecossistema de compartilhamento de dados complexo e diversificado, as funções regulatórias de uma organização podem mudar. Eles podem ser adicionados e revogados. Isso significa que o software adicionado ao Diretório pode receber permissão de ter zero (0) ou mais funções regulatórias. Um administrador pode atribuir a um determinado software todo e qualquer permissões que a organização proprietária do software pode ter.

Se uma organização perder uma função regulatória, todo software com essa função regulatória será revogado do ecossistema, portanto, é muito importante que um aplicativo receba apenas as funções de que realmente precisa para funcionar.

1.5 Criação e Upload de Certificados

1.5.1 Sandbox

O serviço de Diretório do Open Insurance Brasil inclui uma infraestrutura de chave pública que pode ser usada para criar certificados para os aplicativos sendo registrados no ambiente Sandbox. Basta selecionar certificados no menu e seguir as instruções.

O Diretório suporta vários certificados, tipos de chave e um comando e configuração openssl será disponibilizado como um exemplo. Depois de criar a solicitação de assinatura de certificado (Certificate Signing Request - CSR) para um certificado de “Transporte” e “Assinatura”, você pode enviá-los ao diretório para serem validados e transformados em certificados.

Lembre-se de seguir as práticas de gerenciamento de chaves de sua organização para a geração de certificados. Essas credenciais e chaves precisam ser manuseadas com cuidado. Um evento significativo de comprometimento de chave pode levar ao comprometimento dos dados do cliente.

1.5.2 Produção

Os certificados para acesso e assinatura em ambiente de produção devem ser fornecidos pelo ICP Brasil. Os detalhes sobre os certificados e os requisitos para os certificados estão detalhados no Padrão de Certificados Open Insurance Brasil.

1.5.3 O que é um JWT, JWE, JWS e JWK

Quando os certificados são carregados para o Diretório, o framework de confiança os anuncia em JSON Web Key Sets com cada JSON Web Key (JWK) tendo um ‘KID’ ou um Key ID. Os JWKs, além de ter propriedades específicas que descrevem o algoritmo e os conjuntos de criptografia que eles suportam, também anunciam seu “uso”, que pode ser do tipo ‘enc’ para criptografia ou ‘sig’ para assinatura.

Essas chaves ‘sig’ e pares de chaves ‘enc’ são usadas em muitos lugares dentro do ecossistema do Open Insurance Brasil para criptografar ou assinar dados usando os padrões definidos em RFC 7519 JSON Web Token, que deve ser lido em detalhes pelos desenvolvedores.

Tipos de JWT incluem

• OpenID Connect Request Objects definidos em Open ID Connect Core
• OpenID Connect id_token definido em Open ID Connect Core

Entre muitos outros.

Esses JWTs podem ser criptografados também usando o JSON Web Encryption (JWE). Na maioria dos casos, as chaves que devem ser usadas para validar uma assinatura da Web JSON (JWS) ou a chave que foi usada para criptografar um JWE são geralmente publicadas como uma JSON Web Key em um JSON Web Key Set com a referência à chave que está sendo carregada no campo de cabeçalho ‘kid’ (Key ID).

Exemplo de Request Object JWT assinado

eyJhbGciOiJQUzI1NiIsInR5cCI6Im9hdXRoLWF1dGh6LXJlcStqd3QiLCJraWQiOiJ4U2tpbXRFa2EyUzFrdDBFQUV4MlJmNkZLendHSi1zUzRReHYzN2xiU2l3In0
.
eyJzY29wZSI6Im9wZW5pZCBvcGVuaW5zdXJhbmNlYnJhc2lsOmdyYW50OkdERVJaR1JXby1lT0V5UTdDVWZqZiIsInJlc3BvbnNlX3R5cGUiOiJjb2RlIGlkX3Rva2VuIiwicmVkaXJlY3RfdXJpIjoiaHR0cHM6Ly90cHAubG9jYWxob3N0L2NiIiwiY29kZV9jaGFsbGVuZ2UiOiJTMmZ4QlVMS2lQUDdxTnZrN2Z5WlBUcUwtYWtJYnJXcU96WlpYU3I1VTZjIiwiY29kZV9jaGFsbGVuZ2VfbWV0aG9kIjoiUzI1NiIsInJlc3BvbnNlX21vZGUiOiJmb3JtX3Bvc3QiLCJzdGF0ZSI6IjAzNTE4MTk2NTA1NTM3ZTIxMWRkMDhjZWRiMTI3MTE4NzBhNTZlYTQ4ODg5MjRkNTk4YzRiMDY0MDMwMTA2M2IiLCJub25jZSI6Ijg5ODFjOGE1NjBjMjFjMGY4NzQ2ZTliOTc4YmZjMDA0YjkyNzRmMmJjZjc4NmEzZTE1YWE5NmM4ZGQ1NDk0ZGQiLCJjbGFpbXMiOnsiaWRfdG9rZW4iOnsiYXV0aF90aW1lIjp7ImVzc2VudGlhbCI6dHJ1ZX0sIm5hdGlvbmFsX2lkIjp7ImVzc2VudGlhbCI6dHJ1ZX0sImdpdmVuX25hbWUiOnsiZXNzZW50aWFsIjp0cnVlfSwiYWNyIjp7InZhbHVlcyI6WyJ1cm46b3Blbmluc3VyYW5jZWJyYXNpbDp0cnVzdGZyYW1ld29yazpnb2xkIl0sImVzc2VudGlhbCI6dHJ1ZX19LCJ1c2VyaW5mbyI6eyJhdXRoX3RpbWUiOnsiZXNzZW50aWFsIjp0cnVlfSwibmF0aW9uYWxfaWQiOnsiZXNzZW50aWFsIjp0cnVlfSwiZ2l2ZW5fbmFtZSI6eyJlc3NlbnRpYWwiOnRydWV9LCJhY3IiOnsidmFsdWVzIjpbInVybjpvcGVuaW5zdXJhbmNlYnJhc2lsOnRydXN0ZnJhbWV3b3JrOmdvbGQiXSwiZXNzZW50aWFsIjp0cnVlfX19LCJtYXhfYWdlIjozMDAsImlzcyI6ImFDbkJIalpCdkQ2a3UzS1ZCYXNsTCIsImF1ZCI6Imh0dHBzOi8vYXV0aC5sb2NhbGhvc3QiLCJjbGllbnRfaWQiOiJhQ25CSGpaQnZENmt1M0tWQmFzbEwiLCJqdGkiOiJxOF9OU2NKb3F1OG5kcmNYZmo3TlRDVUNTZDZjUEk5ZzVJN3FFeUlLa1NVIiwiaWF0IjoxNjE4NjY0NzM4LCJleHAiOjE2MTg2NjUwMzgsIm5iZiI6MTYxODY2NDczOH0
.
I-75Ev8Swlk3AXEXevFEyV3FVA40VjjIJQu3sImcVGrxdA3qFzw-gxIMCEHamC94TktI_mv6jebwJa_WCfpTipRdnuT_6f24hjTHCDb261t_uWSu3xZgiJrXvmxtQKykLKe6AVheIfldDPszu3bUmUeg9J3ZF6ilDGcCkphmMXLIPpEFkesOQpkw45mCXuhKLfoCnznax7bN6nlD-cHH0Cd0e2XExy3rmSUJ4CljLkpiJ-aK53WDJDocX2mkcFohRJ6zJOHUWZphZ89qpYCq-8jnCOV-YblG9P4KkzUH7EfdVchVzp8V5FlOfmXZhB2pS5REHBjfsmXrdBChlF4Tig

O exemplo acima é apresentado decodificado logo abaixo. No cabeçalho está incluso o atributo ‘kid’ (id da chave) com o valor xSkimtEka2S1kt0EAEx2Rf6FKzwGJ-sS4Qxv37lbSiw, que pode ser localizado no JSON Web KeySet para este cliente aqui

{
  "alg": "PS256",
  "typ": "oauth-authz-req+jwt",
  "kid": "PWAi5ruQcHfzPzq2JFdpY7nAUh6LzTTQtDBUpOM37JQ"
}
{
  "scope": "openid opinbrasil:grant:GDERZGRWo-eOEyQ7CUfjf",
  "response_type": "code id_token",
  "redirect_uri": "https://tpp.localhost/cb",
  "code_challenge": "S2fxBULKiPP7qNvk7fyZPTqL-akIbrWqOzZZXSr5U6c",
  "code_challenge_method": "S256",
  "response_mode": "form_post",
  "state": "03518196505537e211dd08cedb12711870a56ea4888924d598c4b0640301063b",
  "nonce": "8981c8a560c21c0f8746e9b978bfc004b9274f2bcf786a3e15aa96c8dd5494dd",
  "claims": {
    "id_token": {
      "auth_time": {
        "essential": true
      },
      "national_id": {
        "essential": true
      },
      "given_name": {
        "essential": true
      },
      "acr": {
        "values": [
          "urn:opinbrasil:trustframework:gold"
        ],
        "essential": true
      }
    },
    "userinfo": {
      "auth_time": {
        "essential": true
      },
      "national_id": {
        "essential": true
      },
      "given_name": {
        "essential": true
      },
      "acr": {
        "values": [
          "urn:opinbrasil:trustframework:gold"
        ],
        "essential": true
      }
    }
  },
  "max_age": 300,
  "iss": "aCnBHjZBvD6ku3KVBaslL",
  "aud": "https://auth.localhost",
  "client_id": "aCnBHjZBvD6ku3KVBaslL",
  "jti": "q8_NScJoqu8ndrcXfj7NTCUCSd6cPI9g5I7qEyIKkSU",
  "iat": 1618664738,
  "exp": 1618665038,
  "nbf": 1618664738
}

O JWK público do JWKS retirado da uri fornecido anteriormente

{
  "kty":"RSA",
  "use":"sig",
  "x5c":["MIIG9DCCBdygAwIBAgIUHy/za0mwr7eUEasj2fXtS4sekZkwDQYJKoZIhvcNAQELBQAwdzELMAkGA1UEBhMCQlIxHjAcBgNVBAoTFU9wZW4gSW5zdXJhbmNlIEJyYXNpbDEXMBUGA1UECxMOT3BlbiBJbnN1cmFuY2UxLzAtBgNVBAMTJk9wZW4gSW5zdXJhbmNlIFNBTkRCT1ggSXNzdWluZyBDQSAtIEcxMB4XDTIyMDcxNDE3NDkwMFoXDTIzMDgxMzE3NDkwMFowgcMxCzAJBgNVBAYTAkJSMRMwEQYDVQQKEwpJQ1AtQnJhc2lsMUEwDAYDVQQLEwVUZXN0ZTAVBgNVBAsTDjE0NzIzMzc5MDAwMTcyMBoGA1UECxMTY2VydGlmaWNhZG8gZGlnaXRhbDEmMCQGA1UEAxMdT1BFTiBJTlNVUkFOQ0UgQlJBU0lMIC0gUEVFUlMxNDAyBgoJkiaJk/IsZAEBEyQ0Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWMwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC8IHx8C4J7Eyis1G25VbTvAqpa5ny0FJBZVP+K7m0F+hCLxvPhC5ZZDL4dY5pAb6EozKU/Tg70/XGNVbhZvjOvOWgNLOxYI6hiOdRfuy/8GEUQxWEoFqfS9Q24E+aw7miBacUjg9RiVvfhMRPKIZ8Qjhjd1sefI2blcCfKF8exqPcDNP3EyLuS3Ny2Hyq/ZGKXt4rpitahbpBBFnwUpDC4qfBXZ4w55OW4T1sI1+QJA8y5A4QUe2iewSmd8rOXtymiEZLTJ910R/0gRaf9Qv6pb2jzTfABRJbPUlkn5MD/h8bRljZobu/AS2v/XD+rfSdYq6/ZjCvMz20JuXdZEvqLAgMBAAGjggMpMIIDJTAMBgNVHRMBAf8EAjAAMB0GA1UdDgQWBBTY8mtqsrwa73AgQ/jxr6tXhKj3aDAfBgNVHSMEGDAWgBQe6nJx8bsl1+pttR0hY3JNExWkfjBFBggrBgEFBQcBAQQ5MDcwNQYIKwYBBQUHMAGGKWh0dHA6Ly9vY3NwLnNhbmRib3gucGtpLm9waW5icmFzaWwuY29tLmJyMEQGA1UdHwQ9MDswOaA3oDWGM2h0dHA6Ly9jcmwuc2FuZGJveC5wa2kub3BpbmJyYXNpbC5jb20uYnIvaXNzdWVyLmNybDCBkgYDVR0RBIGKMIGHoEAGBWBMAQMCoDcMNTxOYW1lIG9mIHRoZSBwZXJzb24gcmVzcG9uc2libGUgZm9yIHRoZSBvcmdhbml6YXRpb24+oBkGBWBMAQMDoBAMDjE0NzIzMzc5MDAwMTcyoBYGBWBMAQMEoA0MCzExMTExMTExMTMyoBAGBWBMAQMHoAcMBTEyMzQ1MA4GA1UdDwEB/wQEAwIGwDCCAaEGA1UdIASCAZgwggGUMIIBkAYKKwYBBAGDui9kATCCAYAwggE2BggrBgEFBQcCAjCCASgMggEkVGhpcyBDZXJ0aWZpY2F0ZSBpcyBzb2xlbHkgZm9yIHVzZSB3aXRoIFJhaWRpYW0gU2VydmljZXMgTGltaXRlZCBhbmQgb3RoZXIgcGFydGljaXBhdGluZyBvcmdhbmlzYXRpb25zIHVzaW5nIFJhaWRpYW0gU2VydmljZXMgTGltaXRlZHMgVHJ1c3QgRnJhbWV3b3JrIFNlcnZpY2VzLiBJdHMgcmVjZWlwdCwgcG9zc2Vzc2lvbiBvciB1c2UgY29uc3RpdHV0ZXMgYWNjZXB0YW5jZSBvZiB0aGUgUmFpZGlhbSBTZXJ2aWNlcyBMdGQgQ2VydGljaWNhdGUgUG9saWN5IGFuZCByZWxhdGVkIGRvY3VtZW50cyB0aGVyZWluLjBEBggrBgEFBQcCARY4aHR0cDovL3JlcG9zaXRvcnkuc2FuZGJveC5wa2kub3BpbmJyYXNpbC5jb20uYnIvcG9saWNpZXMwDQYJKoZIhvcNAQELBQADggEBAG/o37oQuU9QyFdQxiP2tRVlfgQn7Khj1xamIcuxfzhug9ztgu6dwxELkjhxsjcTxn2ynUcK3+rqg9FHZVV7pise/lGuW9HvWzzOd9nGEtKv0UmEdHidpHQ8lAnpsn2cAA+Fs1LiZqGmvvfVouIrqEM2kjnpTSpn05yj0VK83CnUsPm4aUnd1BeacqXI2GU9U6yULI0Y6ooNVkAcRq/yqjyKlo6ik70I3eK39OH4dkkgE1ooF8Qzxl1q0kVUHqjKlJiXu3VsIgihr5Sr9tDtneXEwTrMdA6vuqIQEUQWkohZCqD0m4E/j+NMwvt6lQtiJQwy8RrN6RHFiqeuTg8Mk7Q="],
  "n":"vCB8fAuCexMorNRtuVW07wKqWuZ8tBSQWVT_iu5tBfoQi8bz4QuWWQy-HWOaQG-hKMylP04O9P1xjVW4Wb4zrzloDSzsWCOoYjnUX7sv_BhFEMVhKBan0vUNuBPmsO5ogWnFI4PUYlb34TETyiGfEI4Y3dbHnyNm5XAnyhfHsaj3AzT9xMi7ktzcth8qv2Ril7eK6YrWoW6QQRZ8FKQwuKnwV2eMOeTluE9bCNfkCQPMuQOEFHtonsEpnfKzl7cpohGS0yfddEf9IEWn_UL-qW9o803wAUSWz1JZJ-TA_4fG0ZY2aG7vwEtr_1w_q30nWKuv2YwrzM9tCbl3WRL6iw",
  "e":"AQAB",
  "kid":"xSkimtEka2S1kt0EAEx2Rf6FKzwGJ-sS4Qxv37lbSiw",
  "x5u":"https://keystore.sandbox.directory.opinbrasil.com.br/4b75db2e-a0c0-4359-a077-684e88fa695c/xSkimtEka2S1kt0EAEx2Rf6FKzwGJ-sS4Qxv37lbSiw.pem",
  "x5t#256":"xSkimtEka2S1kt0EAEx2Rf6FKzwGJ-sS4Qxv37lbSiw"
}

A chave privada que foi usada para criar o JWS

-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC8IHx8C4J7Eyis
1G25VbTvAqpa5ny0FJBZVP+K7m0F+hCLxvPhC5ZZDL4dY5pAb6EozKU/Tg70/XGN
VbhZvjOvOWgNLOxYI6hiOdRfuy/8GEUQxWEoFqfS9Q24E+aw7miBacUjg9RiVvfh
MRPKIZ8Qjhjd1sefI2blcCfKF8exqPcDNP3EyLuS3Ny2Hyq/ZGKXt4rpitahbpBB
FnwUpDC4qfBXZ4w55OW4T1sI1+QJA8y5A4QUe2iewSmd8rOXtymiEZLTJ910R/0g
Raf9Qv6pb2jzTfABRJbPUlkn5MD/h8bRljZobu/AS2v/XD+rfSdYq6/ZjCvMz20J
uXdZEvqLAgMBAAECggEAHwDZkxXQgJj1NJpjpM4HnfYZ/hYLCiBzc41q+cn2RKxj
6q00huuCcRWFBVHjW2gqLo+fUhH6rAxSmOC+G2gZm3CCAd3b62ChAOMX6VjvfQPA
6hUlQFaPfNgu1R3OgG0h4uX7+7DfoP9FJaMRaFfnH3LTjUe2qTbL39b+b7NAkToH
ZdylNWGQUagROIXT0t7uCUgACRU7Xd/OORPja7uKtRySdjvRClk75q8Nvqa2H44j
X0mIGNOd3j1u3TBPDwmCDO0ud9+FZUi3tGLSaqUnRcG0nfFqrw6qUsRJbrQIA37A
V9jzis7v+kHaxZS/bPqehbQ7Y3+/oH+Mipjbybz9ZQKBgQDReXv+50m1uvmiTEIH
Ja+HA/O2oXP+QC62g4qaaCoy6PBpkF4ZuUQXEuWCy//d90BcUwIh0wgQ64qF38KE
v3DeiOay3UK158DE36yzLJ9Lf78UuhNaUFyj3WJmk6jLfOvzUzay7reerr8gE8Jb
5F2vvrBy1toXS15EH7qyaFIXlwKBgQDl6TIaNJ7ZxmLMa2EwnsvpJFaQhpYwTVvd
XqN3Neq/BQNt8RcwM80vNmdDRhbCDGaDw+fSw3FDlHbJy2kBDhb7GoNV4TP4nEyy
wb2R1Wz7/cGrop8m4cjOffg9H7yck899ZD7v3H9G5UB4owX2LXItaqEhc2X0ySNk
AE09T9RzLQKBgHDJf5kNQaPnC7h2ZOriQLNqzlOcdQ8F0eEVzJA829PTlnbQc8pX
9bCSzR7y5k7GbVIIo9JAhUxO9qQEigDd71Dy13yhI+U75pBaeutycEa/fswTMI5l
TKwybGQcxzrhhU3blU0cuaNoJaKI4RKHUGZrPyhmRMFcJGJ7zxN2lhT7AoGBAOL5
gZkVce2VSVx+dgjF/JFCaqNr+0HcXWECWWcLN6E1ldkoNrhDq8F8eB2WSElybJKR
CYCtqlgJbexygEumWVG1LwvNtL0vsRiY5Eng5iMwtc54UZ7VMKWK/1N4zX/W/PTR
zsCGcrDPCwMODoim/R2RM1oOzw0GtYW4NojdEuRRAoGBALL8Zr7Yqqn/j473ib9q
/kDhv4qitzi0gl4HMeXseOPvtHeOze8+MwBKTNWd81N5rkLKzXhyLYXg0GSsRbpe
tWKNkwngOBb7oiMhklUWsWEKmFScUfYqPheArh6OYWrJCxxXptrQw/H4t8Ocf+8R
tRPcXAoDj8SIs7XBDzdSNIuS
-----END PRIVATE KEY-----

Se quiser conhecer um pouco mais e exercitar, visite o site JWT-IO e conheça um pouco mais.

2.0 Interagindo com as APIs de Serviços de Confiança

Quando um aplicativo é registrado no Diretório, o serviço central usa os metadados e certificados fornecidos para criar para o software um cliente OAuth 2.0 que tem um grant type do tipo client credentials, conforme definido em RFC6749 e com um mecanismo de autenticação de cliente definido como tls_client_auth, conforme definido em RFC 8705.

Usando o ClientID listado na declaração do software (software statement) no Diretório, OpenID Connect Discovery e a configuração do OpenID Provider Issuer abaixo, um participante tem todos das informações necessárias para descobrir, autenticar e interagir com as APIs do Diretório

2.1 Emissores do Framework de Confiança do Diretório

Produção: https://auth.directory.opinbrasil.com.br/

Sandbox: https://auth.sandbox.directory.opinbrasil.com.br/

Os certificados para acesso às APIs publicadas pelas instituições participantes devem ser obrigatoriamente certificados emitidos no âmbito da ICP-Brasil.

2.2 Como se Comunicar com o Authorization Server do Diretório

• Use o OpenID Issuer e a Cláusula 4 da especificação OpenID Connect Discovery para obter o documento openid-configuration.

curl https://auth.directory.opinbrasil.com.br/.well-known/openid-configuration

{
  "authorization_endpoint": "https://auth.directory.opinbrasil.com.br/auth",
  "device_authorization_endpoint": "https://auth.directory.opinbrasil.com.br/device/auth",
  "claims_parameter_supported": true,
  "claims_supported": [
    "sub",
    "email",
    "email_verified",
    "phone_number",
    "phone_number_verified",
    "address",
    "birthdate",
    "family_name",
    "gender",
    "given_name",
    "locale",
    "middle_name",
    "name",
    "nickname",
    "picture",
    "preferred_username",
    "profile",
    "updated_at",
    "website",
    "zoneinfo",
    "sid",
    "auth_time",
    "iss"
  ],
  "code_challenge_methods_supported": [
    "S256"
  ],
  "end_session_endpoint": "https://auth.directory.opinbrasil.com.br/session/end",
  "check_session_iframe": "https://auth.directory.opinbrasil.com.br/session/check",
  "grant_types_supported": [
    "implicit",
    "authorization_code",
    "refresh_token",
    "client_credentials"
  ],
  "id_token_signing_alg_values_supported": [
    "PS256"
  ],
  "issuer": "https://auth.directory.opinbrasil.com.br",
  "jwks_uri": "https://auth.directory.opinbrasil.com.br/jwks",
  "registration_endpoint": "https://auth.directory.opinbrasil.com.br/reg",
  "response_modes_supported": [
    "form_post",
    "fragment",
    "query",
    "jwt",
    "query.jwt",
    "fragment.jwt",
    "form_post.jwt"
  ],
  "response_types_supported": [
    "code id_token",
    "code",
    "id_token",
    "none"
  ],
  "scopes_supported": [
    "openid",
    "offline_access",
    "profile",
    "email",
    "address",
    "phone",
    "directory:software"
  ],
  "subject_types_supported": [
    "public",
    "pairwise"
  ],
  "token_endpoint_auth_methods_supported": [
    "private_key_jwt",
    "tls_client_auth"
  ],
  "token_endpoint_auth_signing_alg_values_supported": [
    "PS256"
  ],
  "token_endpoint": "https://auth.directory.opinbrasil.com.br/token",
  "pushed_authorization_request_endpoint": "https://auth.directory.opinbrasil.com.br/request",
  "request_object_signing_alg_values_supported": [
    "PS256"
  ],
  "request_parameter_supported": true,
  "request_uri_parameter_supported": true,
  "require_request_uri_registration": true,
  "userinfo_endpoint": "https://auth.directory.opinbrasil.com.br/me",
  "userinfo_signing_alg_values_supported": [
    "PS256"
  ],
  "authorization_signing_alg_values_supported": [
    "PS256"
  ],
  "introspection_endpoint": "https://auth.directory.opinbrasil.com.br/token/introspection",
  "introspection_endpoint_auth_methods_supported": [
    "private_key_jwt",
    "tls_client_auth"
  ],
  "introspection_endpoint_auth_signing_alg_values_supported": [
    "PS256"
  ],
  "revocation_endpoint": "https://auth.directory.opinbrasil.com.br/token/revocation",
  "revocation_endpoint_auth_methods_supported": [
    "private_key_jwt",
    "tls_client_auth"
  ],
  "revocation_endpoint_auth_signing_alg_values_supported": [
    "PS256"
  ],
  "frontchannel_logout_supported": true,
  "frontchannel_logout_session_supported": true,
  "tls_client_certificate_bound_access_tokens": true,
  "claim_types_supported": [
    "normal"
  ],
  "mtls_endpoint_aliases": {
    "token_endpoint": "https://matls-auth.directory.opinbrasil.com.br/token",
    "revocation_endpoint": "https://matls-auth.directory.opinbrasil.com.br/token/revocation",
    "introspection_endpoint": "https://matls-auth.directory.opinbrasil.com.br/token/introspection",
    "device_authorization_endpoint": "https://matls-auth.directory.opinbrasil.com.br/device/auth",
    "pushed_authorization_request_endpoint": "https://matls-auth.directory.opinbrasil.com.br/request",
    "userinfo_endpoint": "https://matls-auth.directory.opinbrasil.com.br/me"
  }
}

• Obtenha o alias do endpoint do Mutual TLS Token, conforme definido por RFC8705 - OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens

 "mtls_endpoint_aliases": {
    "token_endpoint": "https://matls-auth.directory.opinbrasil.com.br/token",
  }

• Estabeleça uma conexão TLS mútua usando o certificado de transporte registrado anteriormente e solicite um token de acesso com o escopo directory:software

curl --cert transport.pem --key transport.key https://matls-auth.directory.opinbrasil.com.br/token -X POST -d 'client_id=cd080791-9f2b-4b0d-b6a4-953be52b5971&grant_type=client_credentials&scope=directory:software'

{"access_token":"O9lA1EsQM7sAEOgmNdjcIwXAjeBqqFCDnYALhg7bysJ","expires_in":600,"token_type":"Bearer","scope":"directory:software"}

2.3 Como se Comunicar com as APIs do Diretório

As APIs do Diretório são recursos RESTful protegidos usando o Perfil de Segurança do Open Insurance Brasil. Isso significa que eles têm a mesma postura de segurança das APIs publicadas pelas seguradoras. Todas as APIs de Diretório requerem o escopo do recurso OAuth 2.0 de directory:software e são protegidos usando Mutual TLS (mTLS).

Consulte a especificação do Diretório OpenAPI v3 para o conjunto completo de endpoints disponíveis.

2.4 Descobrindo Authorization Servers de Seguradoras

Faça uma busca pelo recurso de participantes (informações públicas) e obtenha uma lista de todos os participantes e seus Authorization Servers.

curl https://data.directory.opinbrasil.com.br/participants

{
  "content": [
    {
      "OrganisationId": "c20ae180-e660-43c3-90e6-2914ace51974",
      "Status": "Active",
      "OrganisationName": "OPEN INSURANCE BRASIL",
      "CreatedOn": "2022-01-26T21:05:03.381Z",
      "LegalEntityName": "Open insurance Brasil",
      "CountryOfRegistration": "BR",
      "CompanyRegister": "VAT Number",
      "Tags": [
          "Technical Service Provider"
      ],
      "Size": "50",
      "RegistrationNumber": "123456",
      "RegistrationId": "12345678910",
      "RegisteredName": "Open insurance Brasil",
      "AddressLine1": "199 Bishopsgate",
      "AddressLine2": "string",
      "City": "London",
      "Postcode": "BA",
      "Country": "BR",
      "RequiresParticipantTermsAndConditionsSigning": true
    }

  -- resultados filtrados para brevidade

  ]
}

Filtre os participantes por aqueles que possuem Authorization Servers protegendo os recursos que você está interessado em acessar para o seu produto. No exemplo acima, existem dois Authorization Servers para ‘_’, um para o negócio de varejo e um para o corporativo.

O aplicativo agora descobriu a lista de seguradoras que estão oferecendo APIs que podem ser úteis para os usuários do aplicativo e pode gerar uma lista de ‘customer friendly names’ de seguradoras e logotipos para exibir aos clientes para permitir que eles selecionem a seguradora a partir do qual desejam compartilhar dados.

3.0 Registrando o Aplicativo com um Provedor

A partir do exemplo dado acima, podemos ver que a localização do "OpenIDDiscoveryDocument" é anunciada por cada um dos Authorization Server.

3.1 Criação de uma Declaração de Software (SSA)

Uma afirmação de declaração de software (software statement assertion - SSA) é um JWT assinado pelo Diretório que contém todas as informações sobre um aplicativo que existe em um determinado momento no Diretório. Inclui a localização de todas as chaves públicas vinculadas à esta declaração de software e todos os outros metadados de que uma seguradora precisa para validar a legitimidade do aplicativo.

Um SSA não tem período de validade, é simplesmente um registro pontual do que existia como atributos válidos no momento em que foi criado. As seguradoras devem aceitar um SSA com menos de alguns minutos, mas a janela exata pode ser diferente entre os provedores.

• Obtenha um token de acesso e, em seguida, carregue a declaração do software para um aplicativo no Diretório.

curl --cert transport.pem --key transport.key https://matls-auth.directory.opinbrasil.com.br/token -X POST -d 'client_id=cd080791-9f2b-4b0d-b6a4-953be52b5971&grant_type=client_credentials&scope=directory:software'

{"access_token":"O9lA1EsQM7sAEOgmNdjcIwXAjeBqqFCDnYALhg7bysJ","expires_in":600,"token_type":"Bearer","scope":"directory:software"}

curl --cert transport.pem --key transport.key https://matls-api.directory.opinbrasil.com.br/organisations/4b75db2e-a0c0-4359-a077-684e88fa695c/softwarestatements/cd080791-9f2b-4b0d-b6a4-953be52b5971/assertion -H 'Authorization: Bearer O9lA1EsQM7sAEOgmNdjcIwXAjeBqqFCDnYALhg7bysJ'

eyJraWQiOiJzaWduZXIiLCJ0eXAiOiJKV1QiLCJhbGciOiJQUzI1NiJ9.eyJzb2Z0d2FyZV9qd2tzX2luYWN0aXZlX3VyaSI6Imh0dHBzOlwvXC9rZXlzdG9yZS5zYW5kYm94LmRpcmVjdG9yeS5vcGluYnJhc2lsLmNvbS5iclwvNGI3NWRiMmUtYTBjMC00MzU5LWEwNzctNjg0ZTg4ZmE2OTVjXC9jZDA4MDc5MS05ZjJiLTRiMGQtYjZhNC05NTNiZTUyYjU5NzFcL2luYWN0aXZlXC9hcHBsaWNhdGlvbi5qd2tzIiwic29mdHdhcmVfbW9kZSI6IkxpdmUiLCJzb2Z0d2FyZV9yZWRpcmVjdF91cmlzIjpbImh0dHBzOlwvXC93d3cubmFvdmFsaWRvLmNvbS5iciJdLCJzb2Z0d2FyZV9zdGF0ZW1lbnRfcm9sZXMiOltdLCJvcmdfandrc190cmFuc3BvcnRfdXJpIjoiaHR0cHM6XC9cL2tleXN0b3JlLnNhbmRib3guZGlyZWN0b3J5Lm9waW5icmFzaWwuY29tLmJyXC80Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWNcL3RyYW5zcG9ydC5qd2tzIiwic29mdHdhcmVfY2xpZW50X25hbWUiOiJUZXN0ZSBTYW5kYm94Iiwib3JnX3N0YXR1cyI6IkFjdGl2ZSIsImlzcyI6Ik9wZW4gSW5zdXJhbmNlIEJyYXNpbCBTYW5kYm94IFNTQSBpc3N1ZXIiLCJvcmdfandrc190cmFuc3BvcnRfaW5hY3RpdmVfdXJpIjoiaHR0cHM6XC9cL2tleXN0b3JlLnNhbmRib3guZGlyZWN0b3J5Lm9waW5icmFzaWwuY29tLmJyXC80Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWNcL2luYWN0aXZlXC90cmFuc3BvcnQuandrcyIsInNvZnR3YXJlX2p3a3NfdHJhbnNwb3J0X2luYWN0aXZlX3VyaSI6Imh0dHBzOlwvXC9rZXlzdG9yZS5zYW5kYm94LmRpcmVjdG9yeS5vcGluYnJhc2lsLmNvbS5iclwvNGI3NWRiMmUtYTBjMC00MzU5LWEwNzctNjg0ZTg4ZmE2OTVjXC9jZDA4MDc5MS05ZjJiLTRiMGQtYjZhNC05NTNiZTUyYjU5NzFcL2luYWN0aXZlXC90cmFuc3BvcnQuandrcyIsInNvZnR3YXJlX3BvbGljeV91cmkiOiJodHRwczpcL1wvd3d3Lm5hb3ZhbGlkby5jb20uYnIiLCJzb2Z0d2FyZV9pZCI6ImNkMDgwNzkxLTlmMmItNGIwZC1iNmE0LTk1M2JlNTJiNTk3MSIsInNvZnR3YXJlX3N0YXR1cyI6IkFjdGl2ZSIsInNvZnR3YXJlX2Vudmlyb25tZW50IjoiU2FuZGJveCIsInNvZnR3YXJlX3ZlcnNpb24iOiIxLjAwIiwib3JnX25hbWUiOiJPUEVOIElOU1VSQU5DRSBCUkFTSUwgLSBQRUVSUyIsImlhdCI6MTY1NzgyOTExNCwic29mdHdhcmVfc2VjdG9yX2lkZW50aWZpZXJfdXJpIjoiaHR0cHM6XC9cL2tleXN0b3JlLnNhbmRib3guZGlyZWN0b3J5Lm9waW5icmFzaWwuY29tLmJyXC80Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWNcL2NkMDgwNzkxLTlmMmItNGIwZC1iNmE0LTk1M2JlNTJiNTk3MVwvcmVkaXJlY3RfdXJpcy5qc29uIiwic29mdHdhcmVfY2xpZW50X2lkIjoiY2QwODA3OTEtOWYyYi00YjBkLWI2YTQtOTUzYmU1MmI1OTcxIiwib3JnX2p3a3NfaW5hY3RpdmVfdXJpIjoiaHR0cHM6XC9cL2tleXN0b3JlLnNhbmRib3guZGlyZWN0b3J5Lm9waW5icmFzaWwuY29tLmJyXC80Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWNcL2luYWN0aXZlXC9hcHBsaWNhdGlvbi5qd2tzIiwic29mdHdhcmVfandrc190cmFuc3BvcnRfdXJpIjoiaHR0cHM6XC9cL2tleXN0b3JlLnNhbmRib3guZGlyZWN0b3J5Lm9waW5icmFzaWwuY29tLmJyXC80Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWNcL2NkMDgwNzkxLTlmMmItNGIwZC1iNmE0LTk1M2JlNTJiNTk3MVwvdHJhbnNwb3J0Lmp3a3MiLCJzb2Z0d2FyZV9jbGllbnRfdXJpIjoiaHR0cHM6XC9cL3d3dy5uYW92YWxpZG8uY29tLmJyIiwic29mdHdhcmVfbG9nb191cmkiOiJodHRwczpcL1wvd3d3Lm5hb3ZhbGlkby5jb20uYnIiLCJvcmdfaWQiOiI0Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWMiLCJvcmdfandrc191cmkiOiJodHRwczpcL1wva2V5c3RvcmUuc2FuZGJveC5kaXJlY3Rvcnkub3BpbmJyYXNpbC5jb20uYnJcLzRiNzVkYjJlLWEwYzAtNDM1OS1hMDc3LTY4NGU4OGZhNjk1Y1wvYXBwbGljYXRpb24uandrcyIsIm9yZ19udW1iZXIiOiIxNDcyMzM3OTAwMDE3MiIsInNvZnR3YXJlX2p3a3NfdXJpIjoiaHR0cHM6XC9cL2tleXN0b3JlLnNhbmRib3guZGlyZWN0b3J5Lm9waW5icmFzaWwuY29tLmJyXC80Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWNcL2NkMDgwNzkxLTlmMmItNGIwZC1iNmE0LTk1M2JlNTJiNTk3MVwvYXBwbGljYXRpb24uandrcyIsInNvZnR3YXJlX3JvbGVzIjpbXSwib3JnYW5pc2F0aW9uX2NvbXBldGVudF9hdXRob3JpdHlfY2xhaW1zIjpbXX0.bdWayyhABvNGnT7Vmsdd5ZTht1oYBm_hHRAAyRGD-lCmNi08HDFH-8RzjFsMJ5ZWzS99mwwVrCBph0YcbwfzWuSu9uFdd-bwvfhXFhkNDzQHuRMOF1QTHd0C8r3N-_CkBtYWyXXNFGiREyXjFn8Muvw3fGSr98sy01PDlNyZlxxpBTU9-nz2r-WxwwVyTJyVfz8wVXrrX3_H19Ty3vwiqAbf0tSPyfXFEe3XQE6XJ8W93Ec9M2CzB3PuaaNvgsa2f4T6tT3yHqUfnRQuqf1FCc3raxxn7tVAB-G1yJ9bz-ZaKdsjX2nWCGhJR41rIPlAGv85EsESAo_JSHpfZW0EbA

3.2 Enviando uma Solicitação de Dynamic Client Registration (RFC7591)

Consulte o Dynamic Client Registration do Open Insurance Brasil

3.3 Salvando o Token de Dynamic Registration Management (RFC7592)

Consulte o Dynamic Client Registration do Open Insurance Brasil

3.4 Modificando um cliente usando Dynamic Client Management Token (RFC7592)

Consulte o Dynamic Client Registration do Open Insurance Brasil

4.0 Obtendo Acesso aos Recursos dos Clientes

Para todas as opções, incluindo todos os códigos de permissão, consulte o Consent API. Os exemplos a seguir são exemplos mínimos, mas funcionais para demonstrar o fluxo de ponta a ponta. Esses exemplos pressupõem que o cliente está se comunicando com um provedor de OpenID, aproveitando o mecanismo de autenticação de endpoint do token tls_client_auth. Exemplos alternativos estão disponíveis no apêndice.

4.1 Pré-requisitos

Esses exemplos não normativos presumem que o cliente OAuth descobriu os locais de todos os 'endpoints' necessários para se comunicar com os recursos das seguradoras do Diretório, incluindo o recurso de consentimento, os recursos de dados e o documento de descoberta de autorização OpenID do Diretório.

4.2 Criando Consentimento

1. Obtendo um Token de Acesso com escopo 'consents'

curl --cert transport.pem --key transport.key https://matls-auth.amazinginsurance.com.br/token -X POST -d 'client_id=clientIdFromAmazingInsurance&grant_type=client_credentials&scope=consents'

{"access_token":"2Pjwts8m1KRZmm0aJyXbOTB8zRosN55fo8Ewdulhxxa","expires_in":600,"token_type":"Bearer","scope":"consents"}

1. Criando um recurso de consentimento

curl --cert transport.pem --key transport.key -H 'Authorization: Bearer 2Pjwts8m1KRZmm0aJyXbOTB8zRosN55fo8Ewdulhxxa'
-H "Content-Type: application/json"
 https://matls-api.amazinginsurance.com.br/consents/v1/consents
--data
'{
  "data": {
    "loggedUser": {
      "document": {
        "identification": "11111111111",
        "rel": "CPF"
      }
    },
    "businessEntity": {
      "document": {
        "identification": "11111111111111",
        "rel": "CNPJ"
      }
    },
    "permissions": [
      CUSTOMERS_PERSONAL_IDENTIFICATIONS_READ,
      CUSTOMERS_PERSONAL_QUALIFICATION_READ,
      CUSTOMERS_PERSONAL_ADITTIONALINFO_READ
    ],
    "expirationDateTime": "2022-02-01T23:59:59Z",
    "transactionFromDateTime": "2021-01-01T00:00:00Z",
    "transactionToDateTime": "2022-02-01T23:59:59Z"
  }
}'

Resposta

{
  "data": {
    "consentId": "urn:seguradoraex:C1DD33123",
    "creationDateTime": "2021-05-21T08:30:00Z",
    "status": "AWAITING_AUTHORISATION",
    "statusUpdateDateTime": "2021-05-21T08:30:00Z",
    "permissions": [
      CUSTOMERS_PERSONAL_IDENTIFICATIONS_READ,
      CUSTOMERS_PERSONAL_QUALIFICATION_READ,
      CUSTOMERS_PERSONAL_ADITTIONALINFO_READ
    ],
    "expirationDateTime": "2022-02-01T23:59:59Z",
    "transactionFromDateTime": "2021-01-01T00:00:00Z",
    "transactionToDateTime": "2022-02-01T23:59:59Z"
  },
  "links": {
    "self": "https://matls-api.amazinginsurance.com.br/consents/urn:seguradoraex:C1DD33123"
  },
  "meta": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDateTime": "2021-05-21T08:30:00Z"
  }
}

4.3 Autorizando Consentimento - Redirecionar

4.3.1 Criar OpenID Connect Request Object

Diferentes métodos de autenticação (private_key_jwt e tls_client_auth) e de encaminhamento do Request Object (com e sem uso de PAR) podem ser suportados pelos Authorization Servers de acordo com a especificação FAPI-1.0 Part 2 - Advanced.

Portanto, como reforça o perfil de segurança para o Open Finance Brasil (item 8 da seção 5.2.3 dos requisitos de segurança para o cliente confidencial), todas as 4 combinações de métodos devem ser suportados pelos clientes de API.

A tabela abaixo reflete os diferentes profiles de segurança e combinações que devem ser suportados por todos os clientes de API (conforme os profiles certificados pela OIDF para o Open Insurance Brasil).

Todos os requisitos para o OpenID Request Object estão incluídos no Perfil de Segurança do Open Finance Brasil. Veja o exemplo com JWS a seguir:

{
 "alg": "PS256",
 "typ": "oauth-authz-req+jwt",
 "kid": "PWAi5ruQcHfzPzq2JFdpY7nAUh6LzTTQtDBUpOM37JQ"
}
.
{
  "scope": "openid consent:urn:amazinginsurance:0be7a3bb-33e6-4d73-b60a-9523aee6cc0d insurance-auto",
  "response_type": "code id_token",
  "redirect_uri": "https://tpp.localhost/cb",
  "code_challenge": "0q5idWeuyFAGeHHpawD3k4mjE7WzPhw6hOdKbnAQY7s",
  "code_challenge_method": "S256",
  "state": "19a1456013b8be71e6ce89916c9723e0642e1eb42a9360146cc84178f2bc928e",
  "nonce": "8dedaf2c53f7ba7294825ca25e45aa544c3feda8fd4ac16220c216e973ad5fd7",
  "claims": {
    "id_token": {
      "auth_time": {
        "essential": true
      },
      "cpf": {
        "essential": true
      },
      "given_name": {
        "essential": true
      },
      "acr": {
        "values": [
          "brasil:openinsurance:standard"
        ],
        "essential": true
      }
    }
  },
  "max_age": 300,
  "iss": "clientIdFromAmazingInsurance",
  "aud": "https://auth.amazinginsurance.com.br",
  "client_id": "clientIdFromAmazingInsurance",
  "jti": "_fj7iamgC1wDzh8KXaJ7XzJiEK_s25DhoDs7uAxpU-k",
  "iat": 1618672338,
  "exp": 1618672638,
  "nbf": 1618672338
}
Assinatura omitida por questões de brevidade

4.3.1.1 Solicitação de Claims Específicas

Também é opcional para receptoras solicitar claims de identidade ('Identity Claims') adicionais, incluindo CPF e CNPJ. Essas claims são definidas no Perfil de Segurança do Open Insurance Brasil. Também é possível para um receptor solicitar que uma claim corresponda a um determinado valor, baseando-se em OpenID Connect Core Clause 5.5.1 para solicitar claims individuais.

Por exemplo:

"cpf": {
        "essential": true,
        value: 12345678123
      },

Nesse exemplo seria exigido que o provedor OpenID retornasse apenas uma autenticação e autorização bem-sucedidas se o usuário que estava autenticando poderia ser confirmado pela seguradoras que eles tinham um número de CPF de 12345678123. Se a seguradora não puder confirmar este número, então a autenticação deve falhar.

Solicitar reivindicações de valor específico é totalmente opcional para o receptor.

4.3.2 Redirecionar o Usuário ao Authorization Server para Autorização

De acordo com o OpenID Connect Core.

https://auth.amazinginsurance.com.br/auth?client_id=clientIdFromAmazingInsurance&scope=openid&request=eyJhbGciOiJQUzI1NiIsInR5cCI6Im9hdXRoLWF1dGh6LXJlcStqd3QiLCJraWQiOiJQV0FpNXJ1UWNIZnpQenEySkZkcFk3bkFVaDZMelRUUXRE...j1CpNMT7NtDerEl32E8plGnsuA

4.3.3 Obtenção de Token de Acesso por Meio de Troca de Código de Autorização

Conforme RFC 7636 Proof Key for Code Exchange

4.3.4 Verificação do Status do Recurso de Consentimento

Neste ponto, um receptor pode, opcionalmente, verificar o status da solicitação de consentimento para ver se mudou para totalmente autorizado. Esta etapa não deverá ser necessária para recursos que não requerem consentimento de múltiplos indivíduos, entretanto, para contas comerciais ou contas conjuntas com requisitos de acesso especiais, a seguradora pode demorar um pouco para obter as autorizações adicionais necessárias para que esse consentimento seja totalmente autorizado. Os receptores não devem abusar da verificação do status da API de consentimento.

curl --cert transport.pem --key transport.key -H 'Authorization: Bearer 2Pjwts8m1KRZmm0aJyXbOTB8zRosN55fo8Ewdulhxxa'
 https://matls-api.amazinginsurance.com.br/consents/v1/consents/urn:amazinginsurance:0be7a3bb-33e6-4d73-b60a-9523aee6cc0d

{
  "data": {
    "consentId": "urn:seguradoraex:C1DD33123",
    "creationDateTime": "2021-05-21T08:30:00Z",
    "status": "AWAITING_AUTHORISATION",
    "statusUpdateDateTime": "2021-05-21T08:30:00Z",
    "permissions": [
      CUSTOMERS_PERSONAL_IDENTIFICATIONS_READ,
      CUSTOMERS_PERSONAL_QUALIFICATION_READ,
      CUSTOMERS_PERSONAL_ADITTIONALINFO_READ..
    ],
    "expirationDateTime": "2022-02-01T23:59:59Z",
    "transactionFromDateTime": "2021-01-01T00:00:00Z",
    "transactionToDateTime": "2022-02-01T23:59:59Z"
  },
  "links": {
    "self": "https://matls-api.amazinginsurance.com.br/consents/urn:seguradoraex:C1DD33123"
  },
  "meta": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDateTime": "2021-05-21T08:30:00Z"
  }
}

4.3.5 Acesso aos Recursos

Com o token de acesso que foi retornado em 4.3.3, o receptor agora tem a capacidade de chamar os recursos dos clientes.

Dynamic Client Registration (DCR)

Prefácio

A Estrutura Inicial do Open Insurance Brasil é responsável por criar os padrões e especificações necessários para atender aos requisitos e obrigações da Legislação do Open Insurance do Brasil, conforme originalmente delineado pela SUSEP. É possível que alguns dos elementos deste documento estejam sujeitos a direitos de patente. A Estrutura Inicial não se responsabiliza pela identificação de qualquer ou todos os direitos de patente.

O Perfil de Segurança Financial-grade API 1.0 do Open Insurance Brasil consiste nas seguintes partes:

• Open Finance Brasil Financial-grade API Security Profile 1.0
• Open Insurance Brasil Dynamic Client Registration Profile 1.0

Essas partes devem ser usadas com RFC6749, RFC6750, RFC7636, OIDC, OIDR, RFC7591, RFC7592, FAPI-1-Baseline e FAPI-1-Advanced

Introdução

O Perfil de Registro de Cliente Dinâmico (DCR - Dynamic Client Registration) do Financial-grade API (FAPI) do Open Insurance Brasil é um perfil de RFC7591, RFC7592 e OIDR que visa fornecer diretrizes de implementação específicas para segurança e interoperabilidade que podem ser aplicadas à identificação, registro e gerenciamento de Clients OAuth operando no ecossistema Open Insurance Brasil.

Embora seja possível codificar um OpenID Provider e Relying Party desde o princípio usando esta especificação, o principal público para esta especificação são as partes que já possuem uma implementação certificada do OpenID Connect e desejam obter a certificação para o Open Insurance Brasil.

Convenções Notacionais

As palavras-chave "deve" (shall), "não deve" (shall not), "deveria" (should), "não deveria" (should not) e "pode" (may) presentes nesse documento devem ser interpretadas conforme as diretrizes descritas em ISO Directive Part 2 observando seguinte equivalência:

• "deve" => equivalente ao termo "shall" e expressa um requerimento definido no documento (nas traduções é similar ao termo "must", que pode denotar um requerimento externo ao documento);
• "não deve" => equivalente ao termo "shall not" e também expressa um requerimento definido no documento;
• "deveria" e "não deveria"=> equivalente ao termo "should" e "should not" e expressa uma recomendação
• "pode" => equivalente ao termo "may" indica uma permissão

Estas palavras-chave não são usadas como termos de dicionário, de modo que qualquer ocorrência deles deve ser interpretada como palavras-chave e não devem ser interpretados com seus significados de linguagem natural.

1. Escopo

Este documento especifica o método de

• aplicativos cadastrados no Diretorio de Participantes do Open Insurance para descobrir OpenID Providers que oferecem serviços no ecossistema Open Insurance Brasil;
• aplicativos para usar o OpenID Connect Registration para integrar seus aplicativos com OpenID Providers das seguradoras; e
• aplicativos para usar OAuth 2.0 Dynamic Client Registration Management Protocol para gerenciar seus aplicativos com OpenID Providers;

Este documento é aplicável a todos os participantes do Open Insurance no Brasil.

2. Referências normativas

Os seguintes documentos referenciados são indispensáveis para a aplicação deste documento. Para referências datadas, apenas a edição citada se aplica. Para referências não datadas, a última edição do documento referenciado (incluindo quaisquer emendas) se aplica.

• ISODIR2 - ISO/IEC Directives Part 2

• RFC6749 - The OAuth 2.0 Authorization Framework

• RFC6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage

• RFC7636 - Proof Key for Code Exchange by OAuth Public Clients

• RFC6819 - OAuth 2.0 Threat Model and Security Considerations

• RFC7519 - JSON Web Token (JWT)

• RFC7591 - OAuth 2.0 Dynamic Client Registration Protocol

• RFC7592 - OAuth 2.0 Dynamic Client Registration Management Protocol

• BCP195 - Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)

• OIDC - OpenID Connect Core 1.0 incorporating errata set 1

• FAPI-CIBA - Financial-grade API: Client Initiated Backchannel Authentication Profile

• RFC4514 - Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names

• RFC4517 - Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules

• OIDD - OpenID Connect Discovery 1.0 incorporating errata set 1

• OIDR - OpenID Connect Registration 1.0 incorporating errata set 1

• RFC8705 - OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens

• JARM - Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)

• PAR - OAuth 2.0 Pushed Authorization Requests

• JAR - OAuth 2.0 JWT Secured Authorization Request

• FAPI-1-Baseline - Financial-grade API Security Profile 1.0 - Part 1: Baseline

• FAPI-1-Advanced - Financial-grade API Security Profile 1.0 - Part 2: Advanced

• OFB-FAPI - Open Finance Brasil Financial-grade API Security Profile 1.0

• OFB-Cert-Standards - Open Insurance Brasil x.509 Certificate Standards

• OFB-DCR/DCM-Swagger - DCR & DCM Swagger

3. Termos e definições

Para efeitos deste documento, aplicam-se os termos definidos em RFC6749, RFC6750, RFC7636, OpenID Connect Core e ISO29100.

4. Símbolos e Termos abreviados

• API – Application Programming Interface (Interface de Programação da Aplicação)
• DCR – Dynamic Client Registration (Registro de Cliente Dinâmico)
• FAPI - Financial-grade API
• HTTP – Hyper Text Transfer Protocol
• OIDF - OpenID Foundation
• REST – Representational State Transfer
• SS – Software Statement (Declaração de Software)
• SSA – Software Statement Assertion (Afirmação de Declaração de Software)
• TLS – Transport Layer Security

5. Introdução

O ecossistema Open Insurance Brasil apoia-se em um provedor de confiança ou diretório de participantes como a fonte mais valiosa de informações sobre participantes credenciados e softwares que estão autorizados a participar do ecossistema Open Insurance Brasil.

Os serviços do Diretório incluem:

• Registro e gerenciamento de software
• Registro e gerenciamento de credenciais de software usando certificados ICP
• Geração de Software Statement Assertion (SSA)

Os participantes do ecossistema devem aproveitar esses serviços para facilitar o registro de cliente OAuth orientado por API usando o processo descrito na cláusula 3.1.1 do RFC7591 com metadados adicionais necessários para oferecer suporte ao OpenID Connect definido em OpenID Connect Registration.

É importante reforçar que o payload de registro de clientes possui a maior parte de seus atributos não obrigatórios, e que os atributos cujos valores conflitem com os presentes no software statement assertion serão sobrepostos pelos valores do próprio software statement assertion emitido pelo diretório central. Nem todos os metadados que um cliente deseja fornecer podem estar contidos em um software statement, por exemplo, alternativa Metadata Languages and Script values. Há casos ainda de metadados de cliente que são um subconjunto dos valores existentes no SSA, como por exemplo os redirect_URIs.

6. Provisionamentos do OpenID Connect Discovery do Open Insurance Brasil

6.1 Servidor de Autorização

O servidor de autorização deve suportar OpenID Connect Discovery conforme exigido pelo Financial-grade API Security Profile 1.0 - Part 1: Baseline. Este suporte deve estar explicito tanto na forma como o Servidor de Autorização está registrado no Diretório de Participantes quanto na declaração dos seus atributos no arquivo de Discovery (well-known), respeitando os mecanismos de autenticação certificados pela institição através dos testes de conformidade do Open Insurance Brasil.

Adicionalmente, o Servidor de Autorização:

1. deve anunciar sua presença no ecossistema Open Insurance Brasil, sendo listada no Diretório de Participantes;
2. deve anunciar todos os recursos API REST do Open Insurance Brasil protegidos pelo Provedor OpenID no Diretório de Participantes;
3. deve anunciar suporte para todos os mecanismos de assinatura, criptografia, autenticação e padrões necessários para suportar o Open Finance Brasil Financial API;
4. deve anunciar suporte para OpenID Dynamic Client Registration;
5. deve anunciar mtls_endpoint_aliases de acordo com a cláusula 5 RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication e Certificate-Bound Access Tokens o token_endpoint, registration_endpoint e userinfo_endpoint;
6. se suportar OAuth 2.0 Pushed Authorisation Requests, deve anunciar por meio de OIDD mtls_endpoint_aliases o push_authorization_request_endpoint;
7. se suportar Financial API - Client Initiated Back Channel Authentication, deve anunciar através de OIDD mtls_endpoint_aliases o backchannel_authentication_endpoint;

6.2 Cliente

O cliente deve suportar OpenID Connect Discovery conforme exigido pelo Financial-grade API Security Profile 1.0 - Part 1: Baseline.

Além disso, o Cliente

1. deve contar com serviços de descoberta do ecossistemas fornecidos apenas pelo Diretório de Participantes;
2. deve derivar os metadados necessários do Authorization Server somente por meio do serviço OpenID Connect Discovery dos Authorization Servers;
3. quando presente, deve usar endpoints anunciados em mtls_endpoint_aliases conforme a cláusula 5 RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication e Certificate-Bound Access Tokens;

7. Provisionamento de registro OpenID Connect do Open Insurance Brasil

7.1 Servidor de Autorização

O servidor de autorização deve suportar as RFCs de Dynamic Client Registration (DCR) RFC7591, Dynamic Client Management (DCM) RFC7592 e OpenID Registration

Além disso, o servidor de autorização

1. deve rejeitar as solicitações de registro de cliente dinâmico não realizadas em uma conexão protegida com mTLS usando certificados emitidos pelo Brasil ICP (produção) ou o Diretório de Participantes (sandbox);
2. deve validar que a solicitação contém software_statement JWT assinado usando o algoritmo PS256 emitido pelo Diretório de Participantes do Open Insurance Brasil;
3. deve validar que o software_statement foi emitido (iat - issued at) não mais de 5 minutos antes do pedido ser recebido;
4. deve validar que um atributo jwks (definida por valor) não foi incluído, e sim declarado como referência no atributo jwks_uri;
5. deve, quando informado, validar que o jwks_uri corresponda ao software_jwks_uri fornecido na declaração do software;
6. deve exigir e validar que o redirect_uris corresponda ou contenha um subconjunto dos valores de software_redirect_uris fornecidos no software_statement;
7. deve exigir e validar que todos os mecanismos de autenticação de cliente cumpram os requisitos definidos nas RFC7591 e RFC7592, através da validação do registration_access_token e, como conexão segura, da cadeia de certificados confiáveis ICP-Brasil.
8. deve validar se os escopos solicitados são adequados para as permissões regulatórias autorizadas da instituição e contidas no software_statement. A relação de permissões regulatórias e os escopos correspondentes está descrita nas seções a seguir.
9. deve, sempre que possível, validar os metadados declarados pelo cliente em relação aos metadados fornecidos no software_statement, adotando os valores presentes no SSA com precedência.
10. deve aceitar todos os nomes x.500 AttributeType definidas no Distinguished Name dos Perfis de Certificado x.509 definidos em Open Insurance Brasil x.509 Certificate Standards;
11. se for compatível com o mecanismo de autenticação do cliente tls_client_auth, conforme definido em RFC8705, somente deve aceitar tls_client_auth_subject_dn como uma indicação do valor do atributo subject do certificado, conforme definido na cláusula 2.1.2 RFC8705;
12. o valor do campo UID do certificado deve coincidir com o enviado no SSA, onde o campo UID deve conter o valor do campo software_id do SSA.
13. o valor do campo organizationIdentifier do certificado deve conter o prefixo correspondente ao Registration Reference OPIBR- seguido do valor do campo org_id do SSA.
14. deve, durante o processo de handshake TLS, usar a regra distinguishedNameMatch para comparar os valores DN conforme definido na RFC4517.
15. deve garantir a integridade do estoque de consentimentos ativos, mesmo após eventuais mudanças sistêmicas, para que taís alterações sejam transparentes para as instituições receptora de dados.
16. deve realizar recertificação FAPI e DCR da OIDF após eventuais mudanças sistêmicas.

Estas disposições aplicam-se igualmente ao processamento de pedidos RFC7591, RFC7592 e OpenID Registration

7.1.1 Aplicando Server Defaults

Quando as propriedades de uma solicitação DCR não estão incluídas e não são obrigatórias na especificação, o Authorization Server deve aplicar os padrões do cliente da seguinte maneira:

1. deve selecionar e aplicar o algoritmo de criptografia e a escolha da cifra a partir dos conjuntos mais recomendados de cifra da IANA que são suportados pelo Servidor de Autorização;
2. deve preencher defaults a partir de valores da afirmação de software_statement, sempre que possível;
3. deve conceder ao cliente permissão para o conjunto completo de escopos potenciais com base nas permissões regulatórias de softwares incluídas no software_statement;

7.1.2 Análise do Distinguished Name do Certificado

A cláusula 3 do Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names define os OIDs obrigatórios cujas as strings do AttributeType (descritores) devem ser reconhecidos pelos implementadores. Esta lista obrigatória não inclui vários dos OIDs definidos em Open Insurance Brasil x.509 Certificate Standards, nem existe um mecanismo definido para os Servidores de Autorização publicarem informações sobre o formato que eles esperam de uma Solicitação Dinâmica de Registro do Cliente (Dynamic Client Registrarion) que inclui um tls_client_auth_subject_dn.

Para resolver essa ambiguidade, o Servidor de Autorização deve aceitar exclusivamente os AttributeType (descritores) definidas no último parágrafo da cláusula 3 RFC4514 em formato string, também deve aceitar em formato OID, com seus valores em ASN.1, todos os AttributeTypes definidos no Distinguished Name Open Insurance Brasil x.509 Certificate Standards ou adicionados pela Autoridade Certificadora.

Em caso de não atendimento destes requisitos o Servidor de Autorização deverá rejeitar o registro.

Segue na tabela abaixo como deve ser feita a decodificação:

• Obtenha na ordem reversa os atributos do certificado
• Concatene cada RDN (RelativeDistinguishedName) com uma virgula (',')
• Use as strings da RFC (CN, L, ST, O, OU, C, Street, DC, UID) com o valor dos seus atributos legível para humanos
• Use os OIDs dos atributos definidos nesta especificação para uso no OFB (businessCategory = OID 2.5.4.15, jurisdictionCountryName = OID 1.3.6.1.4.1.311.60.2.1.3, serialNumber = OID 2.5.4.5) com o valor dos seus atributos em formato ASN.1 seguindo a RFC4514, sendo que:
  • Os nomes dos atributos devem ser definidos seguindo a notação ponto-decimal, sem adição de prefixo “OID”, ex. “2.5.4.15”, seguido dos sinais de (‘=#’) mais o valor hexadecimal do atributo, exemplo final: 2.5.4.15=#0C1450726976617465204F7267616E697A6174696F6E
  • Não há qualquer restrição para as codificações/formatações utilizadas nos valores dos atributos. Deve ser respeitado o uso em hexadecimal apresentado na codificação utilizada no atributo do certificado (PrintableString, UTF8String, etc). Este item atende à opcionalidade do formato já estabelecido pela AC frente aos normativos ICP e ao itens 2.3, 2.4 e 5.2 da RFC4514.

Seguem abaixo exemplos para os atributos obrigatórios da CAs atualmente ativas:

7.2 Funções regulatórias para mapeamentos OpenID e OAuth 2.0

Para participar do ecossistema do Open Insurance, as instituições credenciadas devem se cadastrar no Diretório de Participantes de acordo com seus papéis regulatórios. Essas funções refletem a autorização do SUSEP para as instituições e, consequentemente, as APIs que podem utilizar.

A tabela a seguir descreve as funções regulatórias do Open Insurance e o mapeamento de escopos do OAuth 2.0 relacionado. Se os escopos forem omitidos durante o processo de DCR, o Servidor de Autorização deve conceder o conjunto completo de escopos potenciais com base nas funções regulatórias registradas para a seguradora, conforme descrito na seção Server Defaults.

É necessário validar as roles ativas no software_statement da aplicação. Na validação dessa informação deve ser utilizado o campo software_statement_roles, e deve ser verificado se as roles listadas estão ativas.

7.3 Registro do Cliente

No processo de registro do cliente, utilizando-se o método de autenticação tls_client_auth, o cliente deve encaminhar o campo tls_client_auth_subject_dn com os AttibuteTypes(Descritores) em formato definido no item 7.1.2 Análise do Distinguished Name do Certificado. Em caso de não aderencia a este padrão o registro será rejeitado.

8. Declaração de Software

Uma declaração de software (software_statement) é um JSON Web Token (JWT) que afirma valores de metadados sobre o software cliente como um todo. Na estrutura do Open Insurance Brasil, esse software_statement é assinado pelo Diretório de Participantes, e sua assinatura DEVE ser validada pelos Servidores de Autorizacao usando as chaves públicas disponíveis na seção a seguir.

8.1 Atributos da Declaração de Software (Claims)

O exemplo a seguir contém todos os atributos atualmente incluídos em um software_statement:

{
  "software_mode": "Live",
  "software_redirect_uris": [
    "https://www.raidiam.com/insurance/cb"
  ],
  "software_statement_roles": [
    {
      "role": "DADOS",
      "authorisation_domain": "Open Insurance",
      "status": "Active"
    }
  ],
  "software_client_name": "Raidiam Insurance",
  "org_status": "Active",
  "software_client_id": "Cki1EbvjwyhPB12NGLlz2",
  "iss": "Open Insurance Brasil prod SSA issuer",
  "software_tos_uri": "https://www.raidiam.com/insurance/tos.html",
  "software_client_description": "Raidiam Insurance leverage cutting edge open insurance access to bring you real time up to date views of your insurances",
  "software_jwks_uri": "https://keystore.directory.opinbrasil.com.br/b961c4eb-509d-4edf-afeb-35642b38185d/25556d5a-b9dd-4e27-aa1a-cce732fe74de/application.jwks",
  "software_policy_uri": "https://www.raidiam.com/insurance/policy.html",
  "software_id": "25556d5a-b9dd-4e27-aa1a-cce732fe74de",
  "software_client_uri": "https://www.raidiam.com/insurance.html",
  "software_jwks_inactive_uri": "https://keystore.directory.opinbrasil.com.br/b961c4eb-509d-4edf-afeb-35642b38185d/25556d5a-b9dd-4e27-aa1a-cce732fe74de/inactive/application.jwks",
  "software_jwks_transport_inactive_uri": "https://keystore.directory.opinbrasil.com.br/b961c4eb-509d-4edf-afeb-35642b38185d/25556d5a-b9dd-4e27-aa1a-cce732fe74de/inactive/transport.jwks",
  "software_jwks_transport_uri": "https://keystore.directory.opinbrasil.com.br/b961c4eb-509d-4edf-afeb-35642b38185d/25556d5a-b9dd-4e27-aa1a-cce732fe74de/transport.jwks",
  "software_logo_uri": "https://www.raidiam.com/insurance/logo.png",
  "org_id": "b961c4eb-509d-4edf-afeb-35642b38185d",
  "org_number": "112233445566",
  "software_environment": "production",
  "software_version": "1.1",
  "software_roles": [
    "DADOS"
  ],
  "org_name": "Open Insurance Brasil",
  "iat": 1620060821,
  "organisation_competent_authority_claims": [
    {
      "authorisation_domain": "Open Insurance",
      "authorisations": [],
      "registration_id": "13353236-OIB-DADOS",
      "authority_id": "687a1c94-b360-4e04-9589-0fa5cb16451b",
      "authority_name": "SUSEP",
      "authorisation_role": "DADOS",
      "authority_code": "SUSEP",
      "status": "Active"
    }
  ]
}

9. Processamento de solicitação de registro de cliente dinâmico

9.1 Enviar uma solicitação com uma declaração de software

Este exemplo inclui vários campos opcionais, alguns dos quais podem não ser aplicáveis a algumas implantações. Para um guia completo dos atributos e sua obrigatoriedade, consultar o Swagger DCR. A quebra de linha dentro dos valores são apenas para fins de exibição.

POST /reg HTTP/1.1
Host: auth.raidiam.com
Content-Type: application/json
{
"application_type": "web",
"grant_types": [
    "client_credentials",
    "authorization_code",
    "refresh_token",
    "implicit"
],
"id_token_signed_response_alg": "PS256",
"require_auth_time": false,
"response_types": [
    "code id_token",
    "id_token"
],
"software_statement": "eyJraWQiOiJzaWduZXIiLCJ0eXAiOiJKV1QiLCJhbGciOiJQUzI1NiJ9.eyJzb2Z0d2FyZV9qd2tzX2luYWN0aXZlX3VyaSI6Imh0dHBzOlwvXC9rZXlzdG9yZS5zYW5kYm94LmRpcmVjdG9yeS5vcGluYnJhc2lsLmNvbS5iclwvNGI3NWRiMmUtYTBjMC00MzU5LWEwNzctNjg0ZTg4ZmE2OTVjXC9jZDA4MDc5MS05ZjJiLTRiMGQtYjZhNC05NTNiZTUyYjU5NzFcL2luYWN0aXZlXC9hcHBsaWNhdGlvbi5qd2tzIiwic29mdHdhcmVfbW9kZSI6IkxpdmUiLCJzb2Z0d2FyZV9yZWRpcmVjdF91cmlzIjpbImh0dHBzOlwvXC93d3cubmFvdmFsaWRvLmNvbS5iciJdLCJzb2Z0d2FyZV9zdGF0ZW1lbnRfcm9sZXMiOltdLCJvcmdfandrc190cmFuc3BvcnRfdXJpIjoiaHR0cHM6XC9cL2tleXN0b3JlLnNhbmRib3guZGlyZWN0b3J5Lm9waW5icmFzaWwuY29tLmJyXC80Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWNcL3RyYW5zcG9ydC5qd2tzIiwic29mdHdhcmVfY2xpZW50X25hbWUiOiJUZXN0ZSBTYW5kYm94Iiwib3JnX3N0YXR1cyI6IkFjdGl2ZSIsImlzcyI6Ik9wZW4gSW5zdXJhbmNlIEJyYXNpbCBTYW5kYm94IFNTQSBpc3N1ZXIiLCJvcmdfandrc190cmFuc3BvcnRfaW5hY3RpdmVfdXJpIjoiaHR0cHM6XC9cL2tleXN0b3JlLnNhbmRib3guZGlyZWN0b3J5Lm9waW5icmFzaWwuY29tLmJyXC80Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWNcL2luYWN0aXZlXC90cmFuc3BvcnQuandrcyIsInNvZnR3YXJlX2p3a3NfdHJhbnNwb3J0X2luYWN0aXZlX3VyaSI6Imh0dHBzOlwvXC9rZXlzdG9yZS5zYW5kYm94LmRpcmVjdG9yeS5vcGluYnJhc2lsLmNvbS5iclwvNGI3NWRiMmUtYTBjMC00MzU5LWEwNzctNjg0ZTg4ZmE2OTVjXC9jZDA4MDc5MS05ZjJiLTRiMGQtYjZhNC05NTNiZTUyYjU5NzFcL2luYWN0aXZlXC90cmFuc3BvcnQuandrcyIsInNvZnR3YXJlX3BvbGljeV91cmkiOiJodHRwczpcL1wvd3d3Lm5hb3ZhbGlkby5jb20uYnIiLCJzb2Z0d2FyZV9pZCI6ImNkMDgwNzkxLTlmMmItNGIwZC1iNmE0LTk1M2JlNTJiNTk3MSIsInNvZnR3YXJlX3N0YXR1cyI6IkFjdGl2ZSIsInNvZnR3YXJlX2Vudmlyb25tZW50IjoiU2FuZGJveCIsInNvZnR3YXJlX3ZlcnNpb24iOiIxLjAwIiwib3JnX25hbWUiOiJPUEVOIElOU1VSQU5DRSBCUkFTSUwgLSBQRUVSUyIsImlhdCI6MTY1NzgyOTExNCwic29mdHdhcmVfc2VjdG9yX2lkZW50aWZpZXJfdXJpIjoiaHR0cHM6XC9cL2tleXN0b3JlLnNhbmRib3guZGlyZWN0b3J5Lm9waW5icmFzaWwuY29tLmJyXC80Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWNcL2NkMDgwNzkxLTlmMmItNGIwZC1iNmE0LTk1M2JlNTJiNTk3MVwvcmVkaXJlY3RfdXJpcy5qc29uIiwic29mdHdhcmVfY2xpZW50X2lkIjoiY2QwODA3OTEtOWYyYi00YjBkLWI2YTQtOTUzYmU1MmI1OTcxIiwib3JnX2p3a3NfaW5hY3RpdmVfdXJpIjoiaHR0cHM6XC9cL2tleXN0b3JlLnNhbmRib3guZGlyZWN0b3J5Lm9waW5icmFzaWwuY29tLmJyXC80Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWNcL2luYWN0aXZlXC9hcHBsaWNhdGlvbi5qd2tzIiwic29mdHdhcmVfandrc190cmFuc3BvcnRfdXJpIjoiaHR0cHM6XC9cL2tleXN0b3JlLnNhbmRib3guZGlyZWN0b3J5Lm9waW5icmFzaWwuY29tLmJyXC80Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWNcL2NkMDgwNzkxLTlmMmItNGIwZC1iNmE0LTk1M2JlNTJiNTk3MVwvdHJhbnNwb3J0Lmp3a3MiLCJzb2Z0d2FyZV9jbGllbnRfdXJpIjoiaHR0cHM6XC9cL3d3dy5uYW92YWxpZG8uY29tLmJyIiwic29mdHdhcmVfbG9nb191cmkiOiJodHRwczpcL1wvd3d3Lm5hb3ZhbGlkby5jb20uYnIiLCJvcmdfaWQiOiI0Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWMiLCJvcmdfandrc191cmkiOiJodHRwczpcL1wva2V5c3RvcmUuc2FuZGJveC5kaXJlY3Rvcnkub3BpbmJyYXNpbC5jb20uYnJcLzRiNzVkYjJlLWEwYzAtNDM1OS1hMDc3LTY4NGU4OGZhNjk1Y1wvYXBwbGljYXRpb24uandrcyIsIm9yZ19udW1iZXIiOiIxNDcyMzM3OTAwMDE3MiIsInNvZnR3YXJlX2p3a3NfdXJpIjoiaHR0cHM6XC9cL2tleXN0b3JlLnNhbmRib3guZGlyZWN0b3J5Lm9waW5icmFzaWwuY29tLmJyXC80Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWNcL2NkMDgwNzkxLTlmMmItNGIwZC1iNmE0LTk1M2JlNTJiNTk3MVwvYXBwbGljYXRpb24uandrcyIsInNvZnR3YXJlX3JvbGVzIjpbXSwib3JnYW5pc2F0aW9uX2NvbXBldGVudF9hdXRob3JpdHlfY2xhaW1zIjpbXX0.bdWayyhABvNGnT7Vmsdd5ZTht1oYBm_hHRAAyRGD-lCmNi08HDFH-8RzjFsMJ5ZWzS99mwwVrCBph0YcbwfzWuSu9uFdd-bwvfhXFhkNDzQHuRMOF1QTHd0C8r3N-_CkBtYWyXXNFGiREyXjFn8Muvw3fGSr98sy01PDlNyZlxxpBTU9-nz2r-WxwwVyTJyVfz8wVXrrX3_H19Ty3vwiqAbf0tSPyfXFEe3XQE6XJ8W93Ec9M2CzB3PuaaNvgsa2f4T6tT3yHqUfnRQuqf1FCc3raxxn7tVAB-G1yJ9bz-ZaKdsjX2nWCGhJR41rIPlAGv85EsESAo_JSHpfZW0EbA",
"subject_type": "public",
"token_endpoint_auth_method": "private_key_jwt",
"request_object_signing_alg": "PS256",
"require_signed_request_object": true,
"require_pushed_authorization_requests": false,
"tls_client_certificate_bound_access_tokens": true,
"client_id": "aCnBHjZBvD6ku3KVBaslL",
"client_name": "Raidiam Insurance",
"client_uri": "https://www.raidiam.com/insurance.html",
"request_object_encryption_alg": "RSA-OAEP",
"request_object_encryption_enc": "A256GCM"
"jwks_uri": "https://keystore.directory.opinbrasil.com.br/b961c4eb-509d-4edf-afeb-35642b38185d/25556d5a-b9dd-4e27-aa1a-cce732fe74de/application.jwks",
"redirect_uris": [
    "https://www.raidiam.com/insurance/cb"
]
}

9.2 Open Insurance Brasil SSA Key Store e detalhes do emissor

As links a seguir apontam para as chaves públicas do Diretório de Participantes, e devem ser usadas para verificar a validadade da assinatura dos software_statements apresentados durante o processo de registro de cliente.

Producão

https://keystore.directory.opinbrasil.com.br/openinsurance.jwks

Emissor do Open Insurance Open Insurance Brasil SSA de produção

Sandbox

https://keystore.sandbox.directory.opinbrasil.com.br/openinsurance.jwks

Emissor do Open Insurance Open Insurance Brasil SSA de sandbox

9.3 Sobre os mecanismos de autenticação e autorização dos serviços de DCR e DCM

Por serem serviços auxiliares ao fluxo principal do Open Insurance Brasil, os serviços de registro e manutenção dinâmica de clientes não utilizam os mesmos mecanismos de controle de acesso. Por exemplo: não é possível exigir um access_token OAuth 2.0 de uma aplicação cliente que ainda não está registrada na instituição transmissora. Para estender as RFC7591 e RFC7592, que recomendam mecanismos mínimos para autenticação dos seus serviços, as instituições que suportam os fluxos de registro e manutenção dinâmica de clientes devem implementar em seus Servidores de Autorização os controles a seguir:

9.3.1 Registro de cliente - POST /register

1. validar que o certificado apresentado pela aplicação cliente é subordinado às cadeias do ICP-Brasil definidas no Padrão de Certificados do Open Insurance Brasil;
2. assegurar que a assinatura do software_statement apresentado pela aplicação cliente durante o registro tenha sido feita pelo Diretório de Participantes através das chaves públicas descritas na seção anterior;
3. assegurar que o software_statement apresentado pela aplicação cliente durante o registro corresponda à mesma instituição do certificado de cliente apresentado, validando-o através dos atributos que trazem organization_id no certificado X.509.
4. emitir, na resposta do registro, um registration_access_token para ser usado como token de autenticação nas operações de manutenção da aplicação cliente registrada, seguindo as especificações descritas na RFC7592.
5. não devem ser permitidos múltiplos cadastros DCR para o mesmo Software Statement, de forma que em caso de tentativa de novo registro para um Software Statement já cadastrado, deve se utilizar o procedimento de Error Response definido no item 3.2.2 da RFC7591.

9.3.2 Manutenção de cliente - GET /register - PUT /register - DELETE /register

1. validar que o certificado apresentado pela aplicação cliente é subordinado às cadeias do ICP-Brasil definidas no Padrão de Certificados do Open Insurance Brasil;
2. validar a presença e a correspondência do header Bearer Authorization contendo o valor do atributo registration_access_token retornado durante o registro do cliente correspondente.

Observação: A RFC7592 prevê a possibilidade de rotação do registration_access_token emitido pelo Servidor de Autorização a cada uso, tornando-o um token de uso único. As instituições devem considerar esse aspecto no registro de suas aplicações cliente para receber e atualizar o registration_access_token pelo novo valor recebido nas chamadas de manutenção de cliente.

FAPI Security Profile 1.0

O Open Insurance adere ao padrão do Open Finance Brasil grade API Security Profile 1.0 Implementers Draft 3.

Padrão de Certificados

Prefácio

A Estrutura Inicial do Open Insurance Brasil é responsável por criar os padrões e especificações necessários para atender aos requisitos e obrigações da Legislação do Open Insurance do Brasil, conforme originalmente delineado pela SUSEP. É possível que alguns dos elementos deste documento estejam sujeitos a direitos de patente. A Estrutura Inicial não se responsabiliza pela identificação de qualquer ou todos os direitos de patente.

Objetivo

Especificar o conjunto de certificados necessários que devem ser utilizados pelas entidades participantes do Open Insurance Brasil para garantir interoperabilidade para autenticação, confidencialidade, integridade e não repúdio entre os participantes, bem como para os usuários e consumidores destas entidades. O público desta especificação são entidades participantes do Open Insurance Brasil que necessitam fazer a emissão de certificados para se autenticar junto a outras entidades, bem como oferecer a seus clientes um canal de autenticação seguro.

Convenções Notacionais

As palavras-chave "deve" (shall), "não deve" (shall not), "deveria" (should), "não deveria" (should not) e "pode" (may) presentes nesse documento devem ser interpretadas conforme as diretrizes descritas em ISO Directive Part 2 observando a seguinte equivalência:

• "deve" => equivalente ao termo "shall" e expressa um requerimento definido no documento (nas traduções é similar ao termo "must", que pode denotar um requerimento externo ao documento);
• "não deve" => equivalente ao termo "shall not" e também expressa um requerimento definido no documento;
• "deveria" e "não deveria"=> equivalente ao termo "should" e "should not" e expressa uma recomendação
• "pode" => equivalente ao termo "may" indica uma permissão

Estas palavras-chave não são usadas como termos de dicionário, de modo que qualquer ocorrência deles deve ser interpretada como palavras-chave e não devem ser interpretados com seus significados de linguagem natural.

1. Escopo

Este documento especifica os tipos de certificados necessários para:

• Autenticar mutuamente (MTLS - Mutual TLS) as aplicações dos participantes;
• Assinatura de Mensagens (JWS - JSON Web Signature) de aplicações para garantir a autenticidade e não repúdio de mensagens entre os participantes;
• Apresentar um canal seguro e confiável para clientes do Open Insurance Brasil;
• Autenticar participantes no Diretório de participantes do Open Insurance Brasil.

2. Referências Normativas

Os seguintes documentos referenciados são indispensáveis para a aplicação deste documento. Para referências datadas, apenas a edição citada se aplica. Para referências não datadas, a última edição do documento referenciado (incluindo quaisquer emendas) se aplica.

• ISODIR2 - ISO/IEC Directives Part 2
• RFC5280 - Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile
• RFC7519 - JSON Web Token (JWT)
• RFC7515 - JSON Web Signature (JWS)
• RFC7591 - OAuth 2.0 Dynamic Client Registration Protocol
• RFC7592 - OAuth 2.0 Dynamic Client Registration Management Protocol
• BCP195 - Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)
• RFC8705 - OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens
• OFB-FAPI - Open Finance Brasil Financial-grade API Security Profile 1.0
• OPIN-FAPI-DCR - Open Insurance Brasil Financial-grade API Dynamic Client Registration Profile 1.0
• DOC-ICP-01 - DECLARAÇÃO DE PRÁTICAS DE CERTIFICAÇÃO DA AUTORIDADE CERTIFICADORA RAIZ DA ICP-BRASIL
• RFC6749 - The OAuth 2.0 Authorization Framework
• RFC2818 - HTTP Over TLS
• RFC5246 - The Transport Layer Security (TLS) Protocol Version 1.2

3. Termos e Definições

Para o propósito deste documento os termos definidos na RFC5280, BCP195, RFC8705, e ISO29100 são aplicáveis.

4. Glossário

• API – Application Programming Interface
• DCR – Dynamic Client Registration
• HTTP – Hyper Text Transfer Protocol
• ICP - Infraestrutura de Chave Públicas Brasileira
• SS – Software Statement
• SSA – Software Statement Assertion
• TLS – Transport Layer Security
• mTLS – Mutual Transport Layer Security

5. Padrão de Certificados Open Insurance Brasil

5.1 Introdução

O ecossistema do Open Insurance Brasil faz uso de cadeias de certificados e protocolo TLS para garantir a confidencialidade, autenticação e integridade do canal de comunicação utilizado pelas APIs das instituições participantes, bem como dos clientes de cada um dos participantes.

Os certificados utilizados pelo Open Insurance Brasil também são necessários para autenticar as aplicações através do oAuth 2.0 mTLS ou private_key_jwt, além de também servirem para realizar a assinatura de payloads pelo uso de JWS. Outra atribuição importante dos certificados é autenticar e apresentar um canal seguro para o usuário final no ato de autenticação e uso dos serviços prestados pela entidade participante.

5.2 Certificados ICP-Brasil

Os certificados emitidos pelas Autoridades Certificadoras autorizadas pelo ICP-Brasil são utilizados apenas na comunicação entre as entidades participantes do ecossistema do Open Insurance Brasil.

Os processos de emissão e revogação dos certificados são de responsabilidade das próprias Autoridades Certificadores, sendo regulamentados por Declarações de Prática de Certificação, e supervisionadas pelo Comitê Gestor da Infraestrutura de Chaves Públicas Brasileira.

As práticas, processos, disponibilização e valores praticados pelas Autoridades Certificadoras não são de responsabilidade do Estrutura Inicial do Open Insurance Brasil.

Algoritmos

Todos os certificados emitidos junto ao ICP-Brasil devem possuir as seguintes características:

• Tipo A do ICP-Brasil;
• Algoritmo de Chaves: RSA 2048 bits;
• Message Digest: SHA 256 bits.

5.2.1 Certificado Servidor

O Certificado Servidor deve ser emitido para proteger e autenticar o canal TLS utilizado pelas APIs que serão consumidas pelas aplicações cliente de entidades participantes do Open Insurance.

O padrão de certificado utilizado deve seguir as práticas de emissão de certificados existentes de "CERTIFICADO PARA SERVIDOR WEB – ICP-Brasil".

O certificado de servidor precisa ser enviado com a cadeia intermediária, conforme RFC5246 (itens 7.4.2).

5.2.2 Certificado Cliente

Os Certificados de Aplicação Cliente (Transporte) são utilizados para autenticar o canal mTLS e para realizar a autenticação da aplicação cliente através de oAuth2.0 mTLS ou private_key_jwt, de acordo com o cadastro da aplicação realizado pelo processo de Dynamic Client Registration junto à entidade transmissora. Sobre o mTLS, o certificado cliente precisa ser enviado com a cadeia intermediária, conforme RFC5246 (itens 7.4.2 e 7.4.6).

Para emissão de Certificado Cliente é necessário que a instituição participante do Open Insurance Brasil tenha realizado o cadastro da aplicação no Serviço de Diretório, através do processo de emissão de Software Statement Assertion, e com isso já tenha obtido o valor de Software Statement ID.

5.2.2.1 Atributos Open Insurance Brasil

• serialNumber: Cadastro Nacional de Pessoal Jurídica (CNPJ) da pessoa jurídica titular do certificado e associado ao atributo UID e Software Statement ID, durante validação junto ao Serviço de Diretório do Open Insurance Brasil;
• organizationIdentifier: Código de Participante associado ao CNPJ listado no Serviço de Diretório do Open Insurance Brasil;
• UID: Software Statement ID cadastrado no Serviço de Diretório do Open Insurance Brasil e pertencente ao CNPJ e Código de Participante.

O Certificado Cliente deve ser emitido através de cadeia V10, e deve obrigatoriamente conter os seguintes atributos:

Distinguished Name

• businessCategory (OID 2.5.4.15): Tipo de categoria comercial, devendo conter: "Private Organization" ou "Government Entity" ou "Business Entity" ou "Non-Commercial Entity"
• jurisdictionCountryName (OID: 1.3.6.1.4.1.311.60.2.1.3): BR
• serialNumber (OID 2.5.4.5): CNPJ
• countryName (OID 2.5.4.6): BR
• organizationName (OID 2.5.4.10): Razão Social
• stateOrProvinceName (OID 2.5.4.8): Unidade da federação do endereço físico do titular do certificado
• localityName (OID 2.5.4.7): Cidade do endereço físico do titular
• organizationIdentifier (OID 2.5.4.97): Código de Participante associado ao CNPJ listado no Serviço de Diretório do Open Insurance Brasil e prefixo de identificação do diretório
• UID (OID 0.9.2342.19200300.100.1.1): Software Statement ID gerado pelo Diretório do Open Insurance Brasil
• commonName (OID 2.5.4.3): FQDN ou Wildcard

Certificate Extensions

• keyUsage: critical,digitalSignature,keyEncipherment
• extendedKeyUsage: clientAuth

Subject Alternative Name

• dNSName: FQDN ou Wildcard

5.2.3 Certificado de Assinatura

Os Certificados de Assinatura são utilizados para realizar assinatura do payload através do uso de JWS (JSON Web Signature).

5.2.3.1 Atributos Open Insurance Brasil Presentes no Certificado

• UID: Código de Participante associado ao CNPJ listado no Serviço de Diretório do Open Insurance Brasil;
• commonName: Razão Social cadastrado no Serviço de Diretório do Open Insurance Brasil e pertencente ao CNPJ e Código de Participante.

O Certificado de Assinatura deve ser emitido através de cadeia V5, e deve obrigatoriamente conter os seguintes atributos:

Distinguished Name

• UID (OID 0.9.2342.19200300.100.1.1): Código de Participante associado ao CNPJ listado no Serviço de Diretório do Open Insurance Brasil
• countryName (OID 2.5.4.6): BR
• organizationName (OID 2.5.4.10): ICP-Brasil
• organizationalUnitName (OID 2.5.4.11): Nome da Autoridade Certificadora
• organizationalUnitName (OID 2.5.4.11): CNPJ da Autoridade de Registro
• organizationalUnitName (OID 2.5.4.11): Tipo de identificação utilizada (presencial, videoconferência ou certificado digital)
• commonName (OID 2.5.4.3): Nome da Razão Social

Certificate Extensions

• keyUsage: critical,digitalSignature,nonRepudiation

Subject Alternative Name

• otherName (OID 2.16.76.1.3.2 – ICP-Brasil): Nome do responsável pelo certificado
• otherName (OID 2.16.76.1.3.3 – ICP-Brasil): Cadastro Nacional de Pessoa Jurídica (CNPJ) da pessoa jurídica titular do certificado;
• otherName (OID 2.16.76.1.3.4 – ICP-Brasil): Responsável pelo certificado de pessoa jurídica titular do certificado (data de nascimento, CPF, PIS/PASEP/CI, RG);
• otherName (OID 2.16.76.1.3.7 – ICP-Brasil): Número do Cadastro Especifico do INSS (CEI) da pessoa jurídica titular do certificado.

5.2.3.2 Autoridades Certificadoras Participantes

As seguintes autoridades certificadoras realizaram o processo de onboarding ao Open Insurance Brasil e estão habilitadas para realizar a emissão de certificados do Open Insurance Brasil utilizando para tal os certificados nível 1 aqui listados:

• CertiSign (Cadeia v5 e v10)

• Serasa (Cadeia v5 e v10)

• Serpro (Cadeia v5 e v10)

• Soluti (Cadeia v5 e v10)

• Valid (Cadeia v5 e v10)

Apenas deverá ser aceito certificados indicados com "Situação: válido" nestes repositórios do ITI acima referenciados que são de Cadeia ICP-Brasil v5 e v10.

5.2.4 Certificado para Front-End

Os certificados para Front-End são utilizados para disponibilizar serviços, em geral páginas Web, com uso de TLS, que são acessados pelo usuário final. Dado a sua finalidade, e para garantir maior interoperabilidade, os certificados devem ser do tipo EV (Extended Validation) e devem ser ser gerados através de uma autoridade certificadora válida, seguindo as regras definidas na RFC 5280 e RFC 2818, em conformidade com os princípios e critérios WebTrust.

Apêndice

Modelo de Configuração de Certificado Cliente - OpenSSL

[req]
oid_section = OIDs

default_bits = 2048
default_md = sha256
encrypt_key = yes
prompt = no
string_mask = utf8only
distinguished_name = client_distinguished_name
req_extensions = req_cert_extensions

[ OIDs ]
organizationIdentifier = 2.5.4.97

[ client_distinguished_name ]
businessCategory = <tipo de organização>
jurisdictionCountryName = BR
serialNumber = <CNPJ>
countryName = BR
organizationName = <Razão Social>
stateOrProvinceName = <UF>
localityName = <Cidade>
organizationIdentifier = OPIBR-<Código de Participante>
UID = <Software Statement ID emitido pelo diretório>
commonName = <FQDN|Wildcard>

[ req_cert_extensions ]
basicConstraints = CA:FALSE
subjectAltName = @alt_name
keyUsage = critical,digitalSignature,keyEncipherment
extendedKeyUsage = clientAuth

[ alt_name ]
DNS = <FQDN|Wildcard>

Modelo de Configuração de Certificado de Assinatura - OpenSSL

[req]
default_bits = 2048
default_md = sha256
encrypt_key = yes
prompt = no
string_mask = utf8only
distinguished_name = client_distinguished_name
req_extensions = req_cert_extensions

[ client_distinguished_name ]
UID = <Código de Participante>
countryName = BR
organizationName = ICP-Brasil
0.organizationalUnitName = <Certificate Authority>
1.organizationalUnitName = <CNPJ da Registration Authority>
2.organizationalUnitName = <Validation type>
commonName = <Company Name>

[ req_cert_extensions ]
basicConstraints = CA:FALSE
subjectAltName = @alt_name
keyUsage = critical,digitalSignature,nonRepudiation

[ alt_name ]
otherName.0 = 2.16.76.1.3.2;UTF8:<Name of the person responsible for the organization>
otherName.1 = 2.16.76.1.3.3;UTF8:<CNPJ>
otherName.2 = 2.16.76.1.3.4;UTF8:<CPF/PIS/RF of responsible person>
otherName.3 = 2.16.76.1.3.7;UTF8:<INSS Number>

Tabela com Endpoints vs Tipo de Certificado e mTLS

Abaixo apresentamos quais endpoints podem ser publicados utilizando certificado EV como autenticação do consentimento e os endpoints de autenticação de APIs privadas/negócios que devem ser publicadas usando certificado ICP. Você também poderá verificar quais endpoints devem proteger suas conexões utilizando mTLS.

Fica a critério da instituição a escolha do certificado que deve ser adotado para os endpoints da Fase 1, os quais, por natureza, são de acesso público.

Assinaturas

Sobre os certificados exigidos para assinatura de mensagens: Padrões de certificados digitais Open Insurance Brasil

Sobre os algoritmos usados para assinatura de mensagens JWS: Perfil de segurança FAPI - Open Finance Brasil

Sobre mensagens assinadas, JWS e JWKS: Guia do Usuário para Instituições Receptores de Dados

Glossário de Segurança

Referências Normativas

Referências Informativas

Diretório de Participantes

Participantes Open Insurance Brasil

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Informações sobre os servidores de autorização dos participantes do Open Insurance Brasil que estão registrados no Diretório.

Base URLs:

• https://data.directory.opinbrasil.com.br/participants

License: MIT

A especificação do arquivo de participantes pode ser acessada aqui.

Organisations

Recupera informações técnicas sobre Participantes registrados no diretório, essas informações permitem identificar e consumir as APIs dos participantes

Code samples

const data = null;

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://data.directory.opinbrasil.com.br/participants");
xhr.setRequestHeader("Accept", "application/json");

xhr.send(data);

import http.client

conn = http.client.HTTPSConnection("data.directory.opinbrasil.com.br")

headers = { 'Accept': "application/json" }

conn.request("GET", "/participants", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.get("https://data.directory.opinbrasil.com.br/participants")
  .header("Accept", "application/json")
  .asString();

GET /participants

Example responses

200 Response

[
  {
    "OrganisationId": "string",
    "Status": "Active",
    "OrganisationName": "string",
    "CreatedOn": "string",
    "LegalEntityName": "string",
    "CountryOfRegistration": "string",
    "CompanyRegister": "string",
    "RegistrationNumber": "string",
    "RegistrationId": "string",
    "RegisteredName": "string",
    "AddressLine1": "string",
    "AddressLine2": "string",
    "City": "string",
    "Postcode": "string",
    "Country": "string",
    "ParentOrganisationReference": "string",
    "Contacts": [
      {
        "ContactId": "string",
        "OrganisationId": "string",
        "ContactType": "Business",
        "FirstName": "string",
        "LastName": "string",
        "Department": "string",
        "EmailAddress": "string",
        "PhoneNumber": "string",
        "AddressLine1": "string",
        "AddressLine2": "string",
        "City": "string",
        "Postcode": "string",
        "Country": "string",
        "AdditionalInformation": "string",
        "PgpPublicKey": "string"
      }
    ],
    "AuthorisationServers": [
      {
        "AuthorisationServerId": "string",
        "OrganisationId": "string",
        "AutoRegistrationSupported": true,
        "ApiResources": [
          {
            "ApiResourceId": "string",
            "ApiFamilyType": "string",
            "ApiVersion": 0,
            "ApiDiscoveryEndpoints": [
              {
                "ApiDiscoveryId": "string",
                "ApiEndpoint": "http://example.com"
              }
            ]
          }
        ],
        "CustomerFriendlyDescription": "string",
        "CustomerFriendlyLogoUri": "http://example.com",
        "CustomerFriendlyName": "string",
        "DeveloperPortalUri": "http://example.com",
        "TermsOfServiceUri": "http://example.com",
        "NotificationWebhook": "http://example.com",
        "NotificationWebhookStatus": "string",
        "OpenIDDiscoveryDocument": "http://example.com",
        "PayloadSigningCertLocationUri": "http://example.com",
        "ParentAuthorisationServerId": "string"
      }
    ],
    "OrgDomainClaims": [
      {
        "OrganisationAuthorityDomainClaimId": "string",
        "AuthorisationDomainName": "string",
        "AuthorityId": "string",
        "AuthorityName": "string",
        "RegistrationId": "string",
        "Status": "Active"
      }
    ],
    "OrgDomainRoleClaims": [
      {
        "OrganisationId": "string",
        "OrganisationAuthorityClaimId": "string",
        "AuthorityId": "string",
        "Status": "Active",
        "AuthorisationDomain": "string",
        "Role": "string",
        "Authorisations": [
          {
            "Status": "Active",
            "MemberState": "st"
          }
        ],
        "RegistrationId": "string",
        "UniqueTechnicalIdenifier": [
          "string"
        ]
      }
    ]
  }
]

Responses

Especificações de APIs Diretório

O Diretório Central do Open Insurance Brasil pode ser acessado tanto via interface gráfica quanto por meio de integração por APIs.

Para acessar as APIs do Diretório, verifique os manuais para criação de certificados.

Criando uma Declaração de Software

Gerando o Certificado BRCAC

Gerando o Certificado BRSEAL

Obtendo um token para acesso as APIs do Diretório

Para entender como usar cada API, leia a especificação do Swagger da API do Diretório disponível nesse link.

Guia de operação do diretório central

1. Introdução

O Open Insurance, ou Sistema de Seguros Aberto, é a possibilidade de consumidores de produtos e serviços de seguros, previdência complementar aberta e capitalização permitirem o compartilhamento de suas informações entre diferentes sociedades autorizadas/credenciadas pela SUSEP de forma segura, ágil, precisa e conveniente. Para entregar esses benefícios ao consumidor, o Open Insurance operacionaliza e padroniza o compartilhamento de dados e serviços por meio de abertura e integração de sistemas, com privacidade e segurança. Acesse o site oficial da SUSEP

Antes de Começar

Esse guia tem como objetivo demonstrar, de forma prática, a operação do Diretório Central do Open Insurance Brasil. Além disso, ele é complementar a outras documentações disponibilizadas pela governança e não faz parte do escopo quaisquer detalhamentos relacionados à experiência do usuário e desenvolvedor, definições de segurança e especificação de APIs. Todas as funcionalidades estão disponíveis em sandbox e podem ser testadas em: https://web.sandbox.directory.opinbrasil.com.br/. Procedimentos em produção pendentes serão disponibilizados assim que possível. As ações aqui apresentadas podem ser realizadas tanto por administradores quanto por contatos técnicos primários e secundários. Para ilustrar este guia e tentar deixar as situações de uso mais palpáveis, foram criadas instituições e telas fictícias.

• As instituições e marcas não são reais.

• As telas desenvolvidas, os softwares e sites são meramente ilustrativos, para que seja possível ver um exemplo de como os requisitos e as recomendações podem ser aplicados em situações de uso real.

• Nomenclaturas e imagens ilustrativas estão descritas na língua inglesa, devido sua ampla abrangência e por conter terminologia técnica que, em algumas situações, não dispõe de tradução literal. O ajuste do idioma no Diretório fica a critério do usuário, podendo ser ajustado a qualquer momento.
  

Tipos de Usuários

Neste exemplo, mostramos as diversas possibilidades suportadas de atribuições de função para um usuário cadastrado no Diretório.

	Administrativo	Usuários com poderes de administração no Diretório, podendo realizar todas ações.
	Operação	Usuários com permissão em ferramentas específicas no Diretório.
	Plataforma	Usuários para gestão e operação das plataformas do ecossistema, como o Service Desk, Portal, Plataforma de Resolução de Disputas e Plataforma Centralizada (Ressarcimento).

Relação Organização vs. Marcas

Neste exemplo, mostramos as diversas possibilidades suportadas para se realizar cadastros de organizações no Diretório. Assim, uma organização pode ser cadastrada de forma independente ou pertencente a um conglomerado. Já as marcas são uma forma mais amigável, democrática e fácil para identificação das instituições participantes. Uma Marca de um conglomerado pode estar correlacionada a mais de uma Instituição Participante, assim como uma Instituição Participante pode estar correlacionada a mais de uma marca.

Importante: a Marca cadastrada no diretório será a mesma apresentada para escolha do usuário na Jornada de Compartilhamento de Dados e Iniciação de Pagamentos. As Instituições Participantes (ou organizações) também serão apresentadas em tela, apenas em caráter informativo. Para maiores detalhes, consulte o Guia de Experiência do Usuário.

Pontos de atenção no cadastramento de marca/authorisation server

• Uma marca é representada por um Authorisation Server e o mesmo sempre deve ser cadastrado associado a uma organização.
• O vinculo entre uma organização master (mãe) e uma organização que pertence ao conglomerado é realizado via preenchimento do campo Parent Organization Reference ID no cadastro da organização filha, informando o CNPJ da organização mãe (caso seja necessário ajuste, favor entrar em contato via Service Desk em https://servicedesk.opinbrasil.com.br/servicePortal).
• Quando a estrutura for de um conglomerado (uma organização master e uma ou mais organizações relacionadas) é recomendado o cadastro da marca na instituição mãe, caso as filhas venham a utilizar somente a mesma marca e arquitetura de autenticação. Importante ressaltar que, caso não seja cadastrada uma marca exclusiva para o organização filha, a mesma irá herdar a(s) marca(s) da organização mãe.
• Caso uma marca pertença a uma organização filha, o cadastro deve ser exclusivamente realizado na filha.
• Caso a mesma marca pertença a mais de uma organização, deve ser realizado um cadastro de Authorisation Servers para cada uma das organizações. É recomendado que as configurações dos Authorisation Servers sejam iguais, principalmente o campo Customer Friendly Server Name (marca).
• Quando for necessário cadastrar uma marca exclusiva para uma organização filha, ela deixa de herdar a(s) marca(s) da organização mãe. Caso uma filha tenha que estar relacionada a uma marca exclusiva e também a da mãe, é necessário cadastrar a marca da mãe na filha.

Alternativas para atualização da marca

	Importante! Caso a instituição queira utilizar alguma chave forte, recomendamos utilizar o AuthorisationServerID. Os campos Customer Friendly Server Name e Description são especialmente suscetíveis a atualizações pelas organizações e não devem ser utilizados para esse fim.

Cadastramento Fase 1 x Fase 2

• Se o cadastramento do Authorisation Server na Fase 1 já foi realizado com uma marca válida para a Fase 2, é necessário cadastrar os recursos de Fase 2 no mesmo Authorisation Server, mantendo o Customer Friendly Server Name (marca) da Fase 1.
• Se o cadastramento do Authorisation Server na Fase 1 não foi realizado com uma marca válida para a Fase 2: é necessário atualizar o Customer Friendly Server Name (marca) para a Fase 2 e cadastrar os recursos de Fase 2 no mesmo.
• Os recursos da Fase 1 devem estar declarados em pelo menos um Authorisation Server do participante válido para a Fase 2.
• Após esse processo, caso a instituição venha a ter Authorisation Servers / marcas oferecendo recursos exclusivos de fase 2, recomenda-se a criação de novos registros sem os recursos de Fase 1.
  

2. Registrando um usuário no diretório

Para acessar o Diretório de participantes você precisa estar registrado com um usuário válido. Esta seção descreve as etapas necessárias para realizar o registro de um novo usuário.

ETAPA 1: Registrando um usuário no Diretório

Requisitos

1. No navegador, digite a URL de acordo com o ambiente a ser acessado:

   Sandbox: https://web.sandbox.directory.opinbrasil.com.br/
   

   Produção: https://web.directory.opinbrasil.com.br/

2. Clique no link Register

   

3. Na tela Register for an account, preencha os campos do formulário.

   

4. Clique no botão Register

Nota: E-mails sociais não são permitidos. Você deve utilizar um endereço de e-mail válido da instituição. O cadastro pode ser realizado por qualquer colaborador da organização, identificado aqui como um Iniciador de Cadastro, podendo esse ser tanto um contato administrativo quanto técnico da instituição.

ETAPA 2: Verificando os dados informados

Requisitos

1. Nesta etapa, o Diretório irá enviar uma senha de uso único (OTP), que será encaminhada ao endereço de e-mail e número de telefone informado na etapa anterior.
2. No e-mail recebido, selecione, copie e cole o código OTP no campo EMAIL VERIFICATION CODE.
3. Na mensagem SMS recebida no telefone celular, copie o código OTP e informe no campo PHONE NUMBER VERIFICATION CODE.
4. Clique no botão Verify.

Nota: Caso você não tenha recebido o e-mail com o código de confirmação, verifique sua caixa de SPAM e as políticas de bloqueio de mensagens. O envio das mensagens poderá sofrer algum atraso. Contudo, se o problema persistir, clique no botão Resend OTP para reenvio das mensagens.

ETAPA 3: Confirmando o progresso de registro

Requisitos

1. Nesta etapa, faça o download de um aplicativo de autenticação de sua preferência. É possível utilizar o Google Authenticator, Microsoft Authenticator, LastPass Authenticator, 1Password entre outros.
2. Digitalize o QR Code que aparece na página e no aplicativo de autenticação. Copie e cole a senha de uso único (OTP).
3. Clique no botão Sign-In.

ETAPA 4: Confirmação da assinatura eletrônica

Requisitos

1. Nesta etapa, será enviado um e-mail contendo um link para análise e assinatura do Termo de Aceite.
2. Selecione e copie o código de acesso apresentado na janela Upload e-signature confirmation.
3. Na mensagem recebida na caixa de entrada em nome da DocuSign, clique no link ANALISAR DOCUMENTO. Ao clicar, você será redirecionado para o website da DocuSign.
4. No navegador, cole o valor copiado no passo 2 no campo Código de acesso.
5. Clique no botão Validar.

ETAPA 5: Análise e confirmação do Termo de Aceite

Requisitos

1. Nesta etapa, no website da DocuSign, clique no botão Continuar.
2. Role o documento para baixo e, na página seguinte, clique no ícone Rubricar. No final das páginas, clique no ícone Assinar.
3. Clique no botão Concluir.
4. Na janela "Salvar uma cópia do seu documento", você pode se inscrever para obter uma conta DocuSign gratuita e assinar todos os seus documentos eletronicamente. Nesta janela, também é possível clicar no ícone Fazer Download e baixar uma cópia do documento assinado.
5. Clique no botão Submeter. Ao clicar no botão Submeter, você aceita os Termos e Condições e reconhece que seus dados serão utilizados conforme descrito na Política de Privacidade da DocuSign.
6. Na caixa de entrada, você receberá um e-mail enviado pela DocuSign contendo uma cópia do documento Termo de Aceite assinado eletronicamente.
7. Retorne ao Diretório e, na janela Upload esignature confirmation, clique no botão Check status. Se todas as etapas anteriores forem validadas com sucesso, você será automaticamente redirecionado à página inicial do Diretório.

3. Acessando uma Organisation

Esta seção descreve as etapas necessárias para exibir detalhes de uma organização.

ETAPA 1: Exibindo detalhes de uma organização

Requisitos

1. No Diretório, localize e selecione a sua organização.
2. Revise as informações previamente cadastradas.

Nota: Os cadastrados foram realizados de forma antecipada a partir de informações fornecidas junto a SUSEP. É fundamental que as organizações verifiquem as informações cadastradas. Caso exista alguma divergência, entre em contato pelo e-mail secretariado@opinbrasil.com.br .

Cadastramento de Conglomerado

No diretório de participantes há o conceito de conglomerado. Assim, uma organização mãe poderá ser referenciada em um cadastro de uma organização filha atribuindo-se o CNPJ da organização mãe no campo PARENT ORGANISATION REFERENCE ID da organização filha.

Importante: se a sua organização faz parte de um conglomerado, é fundamental referenciar as organizações filhas com a organização mãe.

4. Cadastrando contatos

Após o onboarding da instituição e do representante da mesma, é necessário realizar o cadastro da equipe de contatos de notificação no Diretório Central. Esses contatos são para possíveis comunicações entre os participantes e a estrutura central.

ETAPA 1: Cadastrando um novo contato

Requisitos

1. No Diretório, localize e selecione a sua organização.
2. Selecione o menu Contacts e clique no botão New Contact.
3. Na janela New Contact preencha os campos do formulário. A tabela a seguir apresenta cada um dos campos em mais detalhes.
4. Clique no botão Save.

Nota: Os usuários de notificação não possuem ações dentro do Diretório e nas demais plataformas do perímetro central.

(*) Campo obrigatório

DETALHAMENTO DOS TIPOS DE CONTATO

Nota: É de inteira responsabilidade da instituição manter os contatos sempre atualizados para que a comunicação entre as instituições participantes não seja prejudicada.

5. Cadastrando reivindicações de domínio de autoridade

Esta seção explica as etapas para cadastrar reivindicações de domínio de autoridade.

ETAPA 1: Cadastrando uma nova reivindicação de domínio

Requisitos

1. No Diretório, localize e selecione a sua organização.
2. Selecione o menu Authority Domain Claims e clique no botão New Domain Claim.
3. Na janela New Authority Domain Claim preencha os campos do formulário. A seguir serão apresentados maiores detalhes sobre os campos.
   
4. Clique no botão Save.

(*) Campo obrigatório

6. Cadastrando reivindicações autoridade

Esta seção explica as etapas para cadastrar reivindicações de autoridade e como adicionar usuários com suas respectivas funções que serão desempenhadas pela organização dentro do Open Insurance.

Nota: As modalidades assumidas pelos participantes no âmbito do Open Insurance são auto declaratórias e podem ser exercidas simultaneamente. Contudo, tais modalidades deverão estar em conformidade com o modelo de negócio do participante e estarão sujeitas à verificação pela fiscalização da SUSEP, especialmente com relação ao cumprimento do princípio da reciprocidade no compartilhamento de dados no Open Insurance Brasil.

ETAPA 1: Cadastrando uma nova reivindicação de função

Requisitos

1. Necessário realizar a seção "Cadastrando reivindicações de domínio de autoridade".
2. No Diretório, localize e selecione a sua organização.
3. Selecione o menu Authority Domain Role Claims e clique no botão New Role Claim.
4. Na janela New Authority Domain Role Claim preencha os campos do formulário. A seguir serão apresentados os campos em mais detalhes.
5. Clique no botão Save.

(*) Campo obrigatório

ETAPA 2: Cadastrando um usuário de domínio de autorização

Requisitos

1. Necessário ter realizado o cadastro de uma nova reivindicação de domínio.
2. No Diretório, localize e selecione a sua organização.
3. Selecione o menu Authority Domain Role Claims. será carregado um submenu na parte superior esquerda. Então, clique no link Authorisation Domain User.
4. Na janela, clique no botão New Authorisation Domain User.
5. Na janela New Authorisation Domain User, preencha os campos do formulário.
6. Clique no botão Save.

(*) Campo obrigatório

Sistemas e funções de um usuário/contato

Notas

• Os perfis para os sistemas Directory, Service Desk e Dispute Resolution são obrigatórios.
• Para obter mais detalhes dos poderes do usuário verifique a tabela "Modelo de Segurança".
• Podem existir quantos contatos primários e secundários a instituição achar necessário.
• Contatos primários podem acessar o Diretório e adicionar contatos secundários. Já os Contatos secundários não conseguem acessar o Diretório e, consequentemente, não conseguem adicionar novos usuários secundários.
• A implementação dos poderes de acesso de contatos primários e secundários dependem e podem variar de plataforma.

7. Cadastrando servidores de autorização (authorisation servers)

Durante a jornada de consentimento do usuário, os receptores exibirão a marca e o servidor de autorização que está sendo solicitado o acesso aos dados do usuário. Esta seção descreve as etapas necessárias para cadastrar as marcas e os servidores de autorização da organização.

ETAPA 1: Criando um novo servidor de autorização

Requisitos

1. No Diretório, localize e selecione a sua organização.
2. Selecione o menu Authorisation Servers. No canto superior esquerdo será carregado um submenu. Para cadastrar um novo Authorisation Server clique no botão New Authorisation Server localizado no lado direito da tela.
3. Na janela New Authorisation Server, preencha os campos do formulário. A seguir serão apresentados cada um dos campos em mais detalhes. Atenção 1: Tendo em vista a ausência de análise de impacto para o ecossistema da retirada de um Authorisation Server, recomenda-se que os(as) responsáveis por consentimentos não sejam retirados do diretório até a expiração/revogação dos consentimentos pelos quais é responsável. Atenção 2: Caso a instituição queira utilizar alguma chave forte, recomendamos utilizar o AuthorisationServerID. Os campos Customer Friendly Server Name e Description são especialmente suscetíveis a atualizações pelas organizações e não devem ser utilizados para esse fim.

(*) Campo obrigatório

Nota: O campo Customer Friendly Logo URI é o que a receptora deverá utilizar para apresentar a logomarca da transmissora.

(*) Campo obrigatório

Detalhamento do Logotipo

O logotipo das instituições participantes deverá ser aplicado no Portal do Cidadão e também poderá ser aplicado no redirecionamento entre instituições durante a Jornada de Compartilhamento de Dados. Por isso foram deliberadas práticas para uso e disponibilização:
• Utilizar preferencialmente logotipo prioritário, que os clientes reconheçam nos canais.
• Versão reduzida do logo, símbolo ou favicon de site.
• Enviar arquivo SVG contendo a área de proteção do logo da instituição para garantir a leitura e o espaçamento correto.
• Formato de envio:
_{SVG
 Dimensão mínima: 512px x 512px
 Sem sombra}
• Peso máximo do arquivo: 1 mega.

ETAPA 2: Cadastrando certificação de segurança no servidor

Requisitos

1. No Diretório, localize e selecione a sua organização.
2. Selecione o menu Authorisation Servers. Depois selecione o servidor de autorização que deseja. Após selecionar, vá no submenu do lado superior esquerdo e clique em Server Certifications.
3. Dentro dessa área, para cadastrar uma nova certificação, clique no botão Add New Certification localizado no lado direito da tela.
4. Na janela New certification preencha os campos do formulário. A seguir serão apresentados os campos em mais detalhes.

As informações da certificação do Authorisation Server são referentes à certificação FAPI obtida através da OpenID Foundation. Dentro do site é possível encontrar uma tabela Open Insurance Brazil (Based on FAPI 1 Advanced Final) que contém as informações que devem ser refletidas no formulário para adição da certificação de segurança.

(*) Campo obrigatório

8. Cadastrando recursos de uma API (endpoints)

Esta seção explica as etapas para cadastrar os endpoints de recursos de uma API.

Cadastramento de Recursos

Para cada uma das famílias de APIs devem ser adicionados todos os endpoints disponíveis. Segue abaixo um exemplo de disponibilização do cadastramento de recursos:

Nota: Na Fase 2 o padrão de cadastramento continua como na Fase 1. Seguem, aqui, alguns pontos de atenção:
• Na API de consentimento é necessário apenas o cadastramento de uma entrada para o GET e o DELETE;
• A API de customers foi dividida em duas famílias para facilitar o consumos pelos receptores. Customers-business onde é cadastrado os Endpoints PJ e customers-personal onde será cadastrado os endpoints PF. Cabendo aqui o cadastramento conforme a disponibilização do produto pela instituição;

Tabela Exemplo Recursos Fase 1

Observação: a tabela acima não é exaustiva, ou seja, não contém todas as APIs da Fase 1 para o Open Insurance Brasil.

Tabela Exemplo Recursos Fase 2

Observação: a tabela acima não é exaustiva, ou seja, não contém todas as APIs da Fase 2 para o Open Insurance Brasil.

ETAPA 1: Cadastrando um novo recurso de uma API

Requisitos

1. No Diretório, localize e selecione a sua organização.
2. Selecione o menu Authorisation Servers e clique no link do servidor de autorização na qual se deseja cadastrar os recursos.
3. No canto superior esquerdo da página clique em API Resources.
4. Na página que será carregada, clique no botão New API Resources para abrir a janela New API Resource.
5. Na janela New API Resource, clique na caixa de seleção API Family Type e selecione uma das opções disponíveis.
6. No campo ao lado, em Version especifique o valor apropriado utilizando versionamento semântico (major.minor.patch, exemplo: 1.0.7)
7. No campo Certification URI é necessário informar a URI onde se encontra a localização do certificado publicado no GitHub. Este preenchimento é obrigatório para famílias de APIs a partir da Fase 2.

8. Clique no botão Save.

   Nota: No ambiente de Sandbox do Diretório, caso não exista uma certificação, é possível incluir um endereço para testes: https://openinsurance-brasil.github.io/teste.zip

9. De volta à tela API Resources, informe URI principal no campo API Discovery Endpoints e, em seguida, pressione a tecla Enter.

10. Para cada uma das famílias de APIs repita os passos 4 a 8.

Nota: Todos os endpoints deverão ser preenchidos, incluindo os respectivos recursos. Para obter mais detalhes sobre o padrão do endpoints e versão consulte o Portal do Desenvolvedor do Open Insurance

9. Cadastrando declarações de software (software statements)

Aqui apresentamos a configuração necessária para criar uma nova declaração de software no Diretório.

ETAPA 1: Criando uma nova declaração de software

Requisitos

1. No Diretório, localize e selecione a sua organização.
2. Selecione o menu Software Statements e clique no botão New Software Statement.
3. Na janela New Software Statement preencha os campos do formulário. A seguir serão apresentados cada um dos campos em mais detalhes.

Nota: O campo Logo URI é o que a transmissora deverá utilizar para apresentar a logomarca da receptora.

(*) Campo obrigatório.

ETAPA 2: Cadastrando certificação de declaração de software

Requisitos

1. No Diretório, localize e selecione a sua organização.
2. Selecione o menu Software Statements. Em seguida, selecione a declaração de software que deseja. Após selecionar, vá no submenu à esquerda em cima e clique em Certifications.
3. Dentro dessa área, para cadastrar uma nova certificação, clique no botão Add New Certification localizado no lado direito da tela.
4. Na janela New certification preencha os campos do formulário. A seguir serão apresentados cada um dos campos em mais detalhes.
   As informações da certificação do Software Statement são referentes a certificação FAPI obtida através da OpenID Foundation . Dentro do site é possível encontrar a tabela Brasil Open Insurance (Based on FAPI Relying Parties) que contém as informações que devem ser refletidas no formulário para adição da certificação de segurança.

(*) Campo obrigatório

10. Criando uma nova reivindicação de autoridade de software

Esta seção explica as etapas para criar uma reivindicação de autoridade de software. Esta etapa será necessária para definir as funções regulatórias que serão inseridas no Software Statement Assertion.

ETAPA 1: Criando reivindicação de autoridade de software

Requisitos

1. Necessário realizar a seção "Cadastrando reivindicações de domínio de autoridade".
2. Necessário realizar a seção "Cadastrando reivindicações de autoridade".
3. Necessário ter criado um Software Statements para sua organização.
4. No Diretório, selecione a sua organização e, no menu lateral, clique em Software Statements.
5. No menu lateral, selecione a opção Authority Claims. Na janela Software Statements Details, role a página para baixo, selecione o menu Authority Claims e clique no botão New Software Authority Claims.
6. Na janela New Software Authority Claims preencha os campos do formulário. Os campos serão apresentados, a seguir, em mais detalhes.

(*) Campo obrigatório

11. Criando certificados de transporte e assinatura em Sandbox

As etapas para criar uma Solicitação de Assinatura de Certificado para certificados de transporte e assinatura que não foram emitidos por uma autoridade de certificação e para uso exclusivo em ambiente de Sandbox do Diretório, podem ser acessadas através dos links:

http://hml-dev-portal.s3-website.us-east-2.amazonaws.com/files/OpenInsurance_Gerando_o_Certificado_BRCAC.pdf

http://hml-dev-portal.s3-website.us-east-2.amazonaws.com/files/OpenInsurance_Gerando_o_Certificado_BRSEAL.pdf

12. Carregando certificados emitidos por autoridade de certificação em Produção

Esta seção explica as etapas para importar certificados que foram emitidos por uma autoridade de certificação e para uso exclusivo em ambiente de Produção do Diretório.

ETAPA 1: Carregando certificado de transporte