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.
- 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
- 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
- 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
- Liberação Mock Insurance e Motor de Conformidade
- Cronograma de Implementação das Fases II e III
- Status do plano de correção
- Mailing de Comunicado e Boletins do Open Insurance
- 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
- 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
- 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
- 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
- 1º Workshop de Treinamento da Plataforma Service Desk
- Plataforma de Coleta de Métricas
- 1º Workshop de Treinamento da Plataforma Service Desk
- Cronogramas de Datas Intermediarias Fase 2 e 3
- 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
- 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
- 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
- Próximas entregas Open Insurance (30-jan)
- Workshop de apresentação do Mock Insurance
- Próximas entregas Open Insurance (13/01/2023)
- Certificação FAPI de Receptora
Boletim OPIN 2022
- Próximas entregas Open Insurance
- Dúvidas sobre à Certificação de Receptora
- 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
- 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.
- 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
- 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
- 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)
- 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:
- 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:
- Acessar o Open Insurance Conformance Suite
- Selecionar um Test Plan
- Preencher os campos de configuração
- 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:
Client Authentication Type - Como o cliente se autenticará no servidor para obter o token. FAPI suporta somente
private_key_jwt
etls_client_auth
dos Métodos de Autenticação OAuth 2.0 disponíveisRequest 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:
- Converta o arquivo .key obtido do diretório para RSA com OpenSSL
openssl rsa -in server.key -out server_new.key
- Converta a chave RSA para JWK em https://8gwifi.org/jwkconvertfunctions.jsp
- 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
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
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:
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.
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.
Alteração | Versionamento |
---|---|
Adição de obrigatoriedade de campo | minor |
Alteração de pattern que impacta a validação | |
Retirada de campo | minor |
Adição de campo | minor |
Ajuste na grafia do campo | minor |
Alteraçao do tipo do campo | minor |
Diminuição de número de caracteres | minor |
Atualizações de REGEX para início de validação de campos antes não validados | minor |
Atualização de patterns que não impactam a validação | patch |
Retirada de obrigatoriedade de campo | patch |
Aumento no número de caracteres | patch |
Adição de enum | patch |
Ajuste na descrição do campo | patch |
Alteração nos exemplos do campo | patch |
Atualizações de REGEX que não impactam a validação | patch |
Alteração de pattern que não impacta a validação | patch |
Retirada de campo não obrigatório | patch |
Adição de campo não obrigatório | patch |
Retirada da obrigatoriedade de um Campo | 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
Nome do cabeçalho | Descrição | Obrigatório |
---|---|---|
Content-Type | Representa o formato do payload de requisição, por padrão/default definido como application/json;charset UTF-8. Obrigatório para chamadas PUT e POST. Os transmissores poderão implementar tratamento para outros padrões, sendo obrigatório apenas o suporte ao padrão. | Não |
Accept | Especifica o tipo de resposta. Se especificado, deve ser definido como application/json , a menos que o endpoint explicitamente suporte outro formato.Se for definido um valor não suportado pelo endpoint, será retornado o código HTTP 406. Se não especificado, o padrão será application/json . |
Não |
Accept-Encoding | Especifica os tipos de encoding(geralmente algoritmo de compressão) que são suportados pelo cliente, com previsão de suporte ao gzip por parte dos transmissores, sendo que o padrão é a transmissão dos dados não compactados e esta orientação aplica-se aos Dados Abertos. | Não |
If-Modified-Since | Condiciona o resultado da requisição para que o recurso só seja enviado caso tenha sido atualizado após a data fornecida. Utiliza o padrão da RFC 7232, sessão 3.3: If-Modified-Since do protocolo HTTP. | Não |
x-fapi-auth-date | Data em que o usuário logou pela última vez com o receptor | Condicional |
x-fapi-customer-ip-address | O endereço IP do usuário se estiver atualmente logado com o receptor | Condicional |
x-fapi-interaction-id | Um UUID RFC4122 usado como um ID de correlação. Se fornecido, o transmissor deve "reproduzir" esse valor no cabeçalho de resposta | Não |
Authorization | Cabeçalho HTTP padrão. Permite que as credenciais sejam fornecidas dependendo do tipo de recurso solicitado | Sim |
x-idempotency-key | Cabeçalho HTTP personalizado. Identificador de solicitação exclusivo para suportar a idempotência | Condicional |
x-customer-user-agent | Indica o user agent que o usuário utiliza | Condicional |
Cabeçalho de resposta
Nome do cabeçalho | Descrição | Obrigatório |
---|---|---|
Content-Encoding | Cabeçalho que indica o tipo de encoding (geralmente algoritmo de compressão) que foi utilizado para envio da resposta. | Não |
Content-Type | Representa o formato do payload de resposta. Deverá ser application/json a menos que o endpoint requisitado suporte outro formato e este formato tenha sido solicitado através do cabeçalho Accept no momento da requisição. |
Sim |
x-v | Cabeçalho que indica a versão implementada da API pela instituição transmissora. Deve ser preenchido de forma completa, por exemplo: x-v : 1.0.2 |
Sim |
Retry-After | Cabeçalho que indica o tempo (em segundos) que o cliente deverá aguardar para realizar uma nova tentativa de chamada. Este cabeçalho deverá estar presente quando o código HTTP de retorno for 429 Too many requests |
Não |
Last-Modified | Informa a data e hora em que o recurso foi modificado pela última vez. Utiliza o padrão da RFC 7232, sessão 2.2: Last-Modified do protocolo HTTP. | Não |
x-fapi-interaction-id | Um UUID RFC4122 usado como um ID de correlação. O transmissor deve usar o mesmo valor recebido na requisição para o cabeçalho de resposta recebido na requisição, caso não tenha sido fornecido, deve se usar um UUID RFC4122 | Não |
x-rate-limit | Indica o limite de requisições na API no tempo | Condicional |
x-rate-limit-remaining | Indica o número de requisições restantes | Condicional |
x-rate-limit-time | Informa o tempo do limite ou tempo para reset desse limite | Condicional |
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
Situação | Código HTTP | Notas | POST | GET | DELETE |
---|---|---|---|---|---|
Consulta concluída com sucesso. | 200 OK. | No caso de POST, retornar 200 apenas quando não acarretar alteração de recurso | Sim | Sim | Não |
Execução normal. A solicitação foi bem sucedida. | 201 Created. | A operação resulta na criação de um novo recurso. | Sim | Não | Não |
Operação de exclusão concluída com sucesso. | 204 No Content. | Não | Não | Sim | |
A resposta não foi modificada desde a última chamada | 304 Not Modified | Não | Sim | Não | |
A requisição foi malformada, omitindo atributos obrigatórios, seja no payload ou através de atributos na URL. | 400 Bad Request. | A operação solicitada não será realizada. | Sim | Sim | Sim |
Cabeçalho de autenticação ausente/inválido ou token inválido. | 401 Unauthorized. | A operação foi recusada devido a um problema de autenticação. | Sim | Sim | Sim |
O token tem escopo incorreto ou uma política de segurança foi violada. | 403 Forbidden. | A operação foi recusada devido a falta de permissão para execução. | Sim | Sim | Sim |
O recurso solicitado não existe ou não foi implementado. | 404 Not Found. | Sim | Sim | Sim | |
O consumidor tentou acessar o recurso com um método não suportado. | 405 Method Not Allowed. | Sim | Sim | Sim | |
A solicitação continha um cabeçalho Accept diferente dos tipos de mídia permitidos ou um conjunto de caracteres diferente de UTF-8. | 406 Not Acceptable. | Sim | Sim | Sim | |
Indica que o recurso não está mais disponível. | 410 Gone. | Sim | Sim | Sim | |
A operação foi recusada porque o payload está em um formato não suportado pelo endpoint. | 415 Unsupported Media Type. | Sim | Não | Não | |
A solicitação foi bem formada, mas não pôde ser processada devido à lógica de negócios específica da solicitação. | 422 Unprocessable Entity. | Se aplicável ao endpoint, espera-se que esse erro resulte em um payload de erro. | Sim | Sim | Não |
A operação foi recusada, pois muitas solicitações foram feitas dentro de um determinado período ou o limite global de requisições concorrentes foi atingido. | 429 Too Many Requests. | A limitação é um requisito não funcional. O titular dos dados deve incluir o cabeçalho Retry-After na resposta indicando quanto tempo o consumidor deve esperar antes de tentar novamente a operação. |
Sim | Sim | Sim |
Ocorreu um erro no gateway da API ou no microsserviço. | 500 Internal Server Error. | A operação falhou. | Sim | Sim | Sim |
O serviço está indisponível no momento. | 503 Service Unavailable. | Sim | Sim | Sim | |
O servidor não pôde responder em tempo hábil. | 504 Gateway Timeout. | Retornado se ocorreu um tempo limite, mas um reenvio da solicitação original é viável (caso contrário, use 500 Internal Server Error). | Sim | Sim | Sim |
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
- obrigatóriamente um objeto
- 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)
- um objeto
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.
- obrigatoriamente o atributo
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)
Tipo | Descrição | Exemplos válidos |
---|---|---|
AmountString | - Uma string que representa um valor monetário. - Um número positivo, zero ou negativo. - Sem o símbolo da moeda. - Com pelo menos 1 e no máximo 16 dígitos antes do ponto decimal. - Com no mínimo 2 dígitos (mais dígitos são permitidos, porém não obrigatórios). - Sem formatação adicional. Ex: Separador de milhar. |
"1.37" "54.85" "3456928.98" "-2387.02" |
Boolean | - Valor booleano padrão. | true false |
CurrencyString | - Uma string que representa a abreviação da moeda conforme especificação ISO-4217. | "BRL" "USD" "EUR" |
DateTimeString | - Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC(UTC time format). | "2020-07-21T08:30:00Z" |
DurationString | - Uma string que representa um período de duração conforme especificação ISO-8601. | "P23DT23H" "PT2H30M" |
Enum | - Uma string que representa um domínio de valores - Todos os possíveis valores são definidos. - Os valores devem estar em letras maiúsculas. - Espaços em branco devem ser substituídos por _. - Artigos e preposições devem ser removidos. - Não devem possuir caracteres acentuados. |
"PRIMEIRA_OPCAO" "OUTRA_OPCAO_EXISTENTE" |
Integer | - Números inteiros. | -1 0 1 |
RateString | - Uma string que representa um valor percentual, tendo como referência que 100% é igual ao valor 1. - Com pelo menos 1 e no máximo 16 dígitos antes do ponto decimal. - Com no máximo 16 dígitos após o ponto decimal. - Sem formatação adicional. Ex: Separador de milhar. |
"0.01" "0.1" "-0.05" "-0.98365" "0.1023" |
String | - Padrão de texto UTF-8 sem restrição de conteúdo. | "Uma string qualquer." |
TimeString | - Uma string que representa a hora conforme especificação RFC-3339,sempre com a utilização de timezone UTC(UTC time format). | "00:39:57Z" |
URIString | - Uma string que representa URI válida. | "http://www.google.com.br" |
CountryCode | - Código do pais de acordo com o código “alpha3” do ISO-3166. | "BRA" |
IbgeCode | - Código IBGE de Município. A Tabela de Códigos de Municípios do IBGE apresenta a lista dos municípios brasileiros associados a um código composto de 7 dígitos, sendo os dois primeiros referentes ao código da Unidade da Federação. | "3550308" |
DateString | - Uma string com data conforme especificação RFC-3339 | "2014-03-19" |
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:
Parâmetro | Descrição | Valor Padrão |
---|---|---|
page | Número da página que está sendo requisitada (o valor da primeira página é 1). | 1 |
page-size | Quantidade total de registros por páginas. | 25 |
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:
Parâmetro | Descrição | Restrição |
---|---|---|
first | A URI para requisitar a primeira página. | Obrigatório se a resposta não for a primeira página. |
last | A URI para requisitar a última página. | Obrigatório se a resposta não for a última página. |
prev | A URI para requisitar a página anterior. | Obrigatório quando houver página anterior. Não deve ser enviado quando for a primeira página. |
next | A URI para requisitar a próxima página. | Obrigatório quando houver página posterior. Não deve ser enviado quando for a última página. |
Meta
No objeto meta
, serão retornadas informações sobre o total de registros disponíveis
Parâmetro | Descrição | Restrição |
---|---|---|
totalRecords | O número total de registros da requisição. | Este atributo é obrigatório. |
totalPages | O número total de páginas da requisição. | Este atributo é obrigatório. Se não possuir nenhum registro o valor deve ser 0. |
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 opage-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 size800
, a transmissora deve retornar os itens de801
a1600
. - 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:
Normativa |
---|
Resolução CNSP nº 415, de 2021 |
Circular Susep nº 635, de 2021 |
Circular Susep nº 638, de 2021 |
Lei Geral de Proteção de Dados (LGPD – Lei nº 13.709, de 2018) |
Estas especificações baseiam-se, referenciam, e complementam, quando aplicável, os seguintes documentos:
Referência |
---|
BCP 195/RFC 7525 |
Owasp API Top 10 |
Sans Top 25 Software Errors |
CWE Top 25 Software Weaknesses |
NIST 800-88 |
DOD 5220.22-M |
ICP Brasil - Manual de Condutas Técnicas 7 - Volume I |
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:
Camada | Descrição | Explicação |
---|---|---|
Física | Firewall | Equipamentos e produtos como filtros, proxys e firewalls direcionados ao controle e segurança da rede física. |
Transporte | HTTP - TLS 1.2 | Protocolo de criptografia que fornece segurança na comunicação sobre a rede física. |
Gestão | API Gateway / Manager | Gateway e Manager para gerenciar a publicação da API com controles de throttling, quotas e outros. |
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
- Certificação de segurança, OP
- Documentação: https://openid.net/certification/op_submission
- Termos: https://openid.net/certification/instructions/#:~:text=OpenID%20Certification%20Terms%20and%20Conditions
- Solicitação: https://openid.atlassian.net/servicedesk/customer/portal/3/group/3/create/10016
- Abertura de chamados: https://gitlab.com/openid/conformance-suite/-/issues
- Certificação de segurança, RP
- Documentação: https://openid.net/certification/connect_rp_submission/
- Termos: https://openid.net/certification/instructions/#:~:text=OpenID%20Certification%20Terms%20and%20Conditions
- Solicitação: https://openid.atlassian.net/servicedesk/customer/portal/3/group/3/create/10016
- Abertura de chamados: https://gitlab.com/openid/conformance-suite/-/issues
Workshops
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.
Perfil da certificação OIDF |
---|
BR-OB Adv. OP w/ MTLS |
BR-OB Adv. OP w/ Private Key |
BR-OB Adv. OP w/ MTLS, PAR |
BR-OB Adv. OP w/ Private Key, PAR |
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.
Auth Id | Auth Customer Friendly Name | Well Known | Resource | Version |
---|---|---|---|---|
1 | Seguros Incríveis - Empresas | https://auth.empresas.amazinginsurance.org.br/.well-known/openid-configuration | consents | 1 |
1 | Seguros Incríveis - Empresas | https://auth.empresas.amazinginsurance.org.br/.well-known/openid-configuration | customers | 1 |
2 | Seguros Incríveis | https://auth.amazinginsurance.org.br/.well-known/openid-configuration | consents | 1 |
2 | Seguros Incríveis | https://auth.amazinginsurance.org.br/.well-known/openid-configuration | customers | 1 |
2 | Seguros Incríveis | https://auth.amazinginsurance.org.br/.well-known/openid-configuration | insurance-auto | 1 |
2 | Seguros Incríveis | https://auth.amazinginsurance.org.br/.well-known/openid-configuration | insurance-auto | 2 |
2 | Seguros Incríveis | https://auth.amazinginsurance.org.br/.well-known/openid-configuration | insurance-patrimonial | 1 |
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.
- Cadastre sua organização no Diretório de Participantes (Interface do Usuário)
- Cadastre seu aplicativo no Diretório de Participantes (Interface do Usuário)
- Obtenha credenciais para sua aplicação junto à uma autoridade certificadora ICP-Brasi)(fora do escopo deste documento)
- Registre suas credenciais para o seu aplicativo no Diretório de Participantes (Interface do Usuário)
- 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)
- 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
- 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"}
- 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).
Perfil da certificação OIDF |
---|
BR-OB Adv. OP w/ MTLS |
BR-OB Adv. OP w/ Private Key |
BR-OB Adv. OP w/ MTLS, PAR |
BR-OB Adv. OP w/ Private Key, PAR |
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)
RFC7592 - OAuth 2.0 Dynamic Client Registration Management Protocol
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)
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:
- deve anunciar sua presença no ecossistema Open Insurance Brasil, sendo listada no Diretório de Participantes;
- deve anunciar todos os recursos API REST do Open Insurance Brasil protegidos pelo Provedor OpenID no Diretório de Participantes;
- 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;
- deve anunciar suporte para OpenID Dynamic Client Registration;
- 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 otoken_endpoint
,registration_endpoint
euserinfo_endpoint
; - se suportar OAuth 2.0 Pushed Authorisation Requests, deve anunciar por meio de OIDD
mtls_endpoint_aliases
opush_authorization_request_endpoint
; - se suportar Financial API - Client Initiated Back Channel Authentication, deve anunciar através de OIDD
mtls_endpoint_aliases
obackchannel_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
- deve contar com serviços de descoberta do ecossistemas fornecidos apenas pelo Diretório de Participantes;
- deve derivar os metadados necessários do Authorization Server somente por meio do serviço OpenID Connect Discovery dos Authorization Servers;
- 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
- 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);
- 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; - deve validar que o software_statement foi emitido (iat - issued at) não mais de 5 minutos antes do pedido ser recebido;
- deve validar que um atributo
jwks
(definida por valor) não foi incluído, e sim declarado como referência no atributojwks_uri
; - deve, quando informado, validar que o
jwks_uri
corresponda aosoftware_jwks_uri
fornecido na declaração do software; - deve exigir e validar que o
redirect_uris
corresponda ou contenha um subconjunto dos valores desoftware_redirect_uris
fornecidos no software_statement; - 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. - 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.
- 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.
- 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;
- se for compatível com o mecanismo de autenticação do cliente
tls_client_auth
, conforme definido em RFC8705, somente deve aceitartls_client_auth_subject_dn
como uma indicação do valor do atributo subject do certificado, conforme definido na cláusula 2.1.2 RFC8705; - 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.
- 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.
- deve, durante o processo de handshake TLS, usar a regra
distinguishedNameMatch
para comparar os valores DN conforme definido na RFC4517. - 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.
- 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:
- 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;
- deve preencher defaults a partir de valores da afirmação de software_statement, sempre que possível;
- 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:
subject_dn | Issuer |
---|---|
UID=67c57882-043b-11ec-9a03-0242ac130003, 1.3.6.1.4.1.311.60.2.1.3=#13024252, 2.5.4.15=#131450726976617465204f7267616e697a6174696f6e, 2.5.4.5=#130e3133333533323336303030313839, CN=mycn.insurance.gov.br,2.5.4.97=OPIBR-497e1ffe-b2a2-4a4e-8ef0-70633fd11b59, O=My Public Insurance, L=BRASILIA, ST=DF, C=BR | issuer=CN=Open Insurance SANDBOX Issuing CA - G1,OU=Open Insurance,O=Open Insurance Brasil,C=BR |
UID=67c57882-043b-11ec-9a03-0242ac130003, 1.3.6.1.4.1.311.60.2.1.3=#13024252, 2.5.4.15=#131450726976617465204f7267616e697a6174696f6e, 2.5.4.5=#130e3133333533323336303030313839, CN=mycn.insurance.gov.br,2.5.4.97=OPIBR-497e1ffe-b2a2-4a4e-8ef0-70633fd11b59, O=My Public Insurance, L=BRASILIA, ST=DF, C=BR | issuer=CN=Autoridade Certificadora do SERPRO SSLv1,OU=Autoridade Certificadora Raiz Brasileira v10,O=ICP-Brasil,C=BR |
UID=67c57882-043b-11ec-9a03-0242ac130003, 1.3.6.1.4.1.311.60.2.1.3=#13024252, 2.5.4.15=#131450726976617465204f7267616e697a6174696f6e, 2.5.4.5=#130e3133333533323336303030313839, CN=mycn.insurance.gov.br,2.5.4.97=OPIBR-497e1ffe-b2a2-4a4e-8ef0-70633fd11b59, O=My Public Insurance, L=BRASILIA, ST=DF, C=BR | issuer=CN=AC SOLUTI SSL EV,OU=Autoridade Certificadora Raiz Brasileira v10,O=ICP-Brasil,C=BR |
UID=67c57882-043b-11ec-9a03-0242ac130003, 1.3.6.1.4.1.311.60.2.1.3=#13024252, 2.5.4.15=#131450726976617465204f7267616e697a6174696f6e, 2.5.4.5=#130e3133333533323336303030313839, CN=mycn.insurance.gov.br,2.5.4.97=OPIBR-497e1ffe-b2a2-4a4e-8ef0-70633fd11b59, O=My Public Insurance, L=BRASILIA, ST=DF, C=BR | issuer=CN=AC SERASA SSL EV,OU=Autoridade Certificadora Raiz Brasileira v10,O=ICP-Brasil,C=BR |
UID=67c57882-043b-11ec-9a03-0242ac130003, 1.3.6.1.4.1.311.60.2.1.3=#13024252, 2.5.4.15=#131450726976617465204f7267616e697a6174696f6e, 2.5.4.5=#130e3133333533323336303030313839, CN=mycn.insurance.gov.br,2.5.4.97=OPIBR-497e1ffe-b2a2-4a4e-8ef0-70633fd11b59, O=My Public Insurance, L=BRASILIA, ST=DF, C=BR | issuer=CN=AC Certisign ICP-Brasil SSL G2,OU=Autoridade Certificadora Raiz Brasileira v10,O=ICP-Brasil,C=BR |
UID=67c57882-043b-11ec-9a03-0242ac130003, 1.3.6.1.4.1.311.60.2.1.3=#13024252, 2.5.4.15=#131450726976617465204f7267616e697a6174696f6e, 2.5.4.5=#130e3133333533323336303030313839, CN=mycn.insurance.gov.br,2.5.4.97=OPIBR-497e1ffe-b2a2-4a4e-8ef0-70633fd11b59, O=My Public Insurance, L=BRASILIA, ST=DF, C=BR | issuer=CN=AC VALID SSL EV,OU=Autoridade Certificadora Raiz Brasileira v10,O=ICP-Brasil,C=BR |
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.
Papel Regulador | Descrição | Escopos Permitidos (em construção) | Fase-alvo |
---|---|---|---|
DADOS | Instituição transmissora / receptora de dados | openid consents resources customers insurance-acceptance-and-branches-abroad insurance-auto insurance-financial-risk insurance-housing insurance-patrimonial insurance-rural insurance-responsibility insurance-transport | Fase 2 |
ICS | Iniciadora de Compartilhamento de Serviços | openid claim-notification endorsement quote-patrimonial-lead quote-patrimonial-home quote-patrimonial-condominium quote-patrimonial-business quote-patrimonial-diverse-risks | Fase 3 |
TCS | Transmissora de Compartilhamento de Serviços | openid | Fase 3 |
É 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
- 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;
- 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;
- 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. - 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. - 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
- 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;
- validar a presença e a correspondência do header Bearer
Authorization
contendo o valor do atributoregistration_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.
Fase | Grupo | APIs (em construção) | Certificado | mTLS |
---|---|---|---|---|
NA | OIDC | .well-known/openid-configuration | EV ou ICP WEB SSL | |
NA | OIDC | jwks_uri | EV ou ICP WEB SSL | |
NA | OIDC | authorization_endpoint | EV | |
NA | OIDC | token_endpoint | ICP WEB SSL | Obrigatório |
NA | OIDC | userinfo_endpoint | ICP WEB SSL | Obrigatório |
NA | OIDC | pushed_authorization_request_endpoint | ICP WEB SSL | Obrigatório |
NA | DCR | registration_endpoint | ICP WEB SSL | Obrigatório |
NA | OIDC | revocation_endpoint | ICP WEB SSL | Obrigatório |
2 | Consentimentos | /consents/* | ICP WEB SSL | Obrigatório |
2 | Resources | /resources/* | ICP WEB SSL | Obrigatório |
2 | Dados | /customers/* | ICP WEB SSL | Obrigatório |
2 | Transacionais | /insurance-*/* | ICP WEB SSL | Obrigatório |
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
Sigla | Descrição | Informação |
---|---|---|
API | Interface de programação de aplicativo | Uma interface de programação de aplicativo é um conjunto de rotinas, protocolos e ferramentas para construir aplicativos de software. Uma API especifica como os componentes de software devem interagir |
FAPI | Financial API | Especificação técnica de API e define requisitos técnicos adicionais para o setor financeiro |
CIBA | Client Initiated Backchannel Authentication | A autenticação de backchannel iniciada pelo cliente (CIBA) é um dos padrões mais recentes da OpenID Foundation. São categorizados como "fluxo desacoplado". Permite novas maneiras de obter o consentimento do usuário final |
OAuth | O OAuth é um protocolo de autorização para APIs web voltado a permitir que aplicações client acessem um recurso protegido em nome de um usuário | |
OIDC | OpenID Connect | OpenID Connect é um protocolo de identidade simples com padrão aberto |
JWT | JSON Web Token | Uma técnica definida na RFC 7519 para autenticação remota entre duas partes. Ele é uma das formas mais utilizadas para autenticar usuários em APIs RESTful |
JWS | JSON Web Signature | Uma forma de garantir a integridade das informações em um formato altamente serializado |
SHA256 | Secure Hash Algorithm | Um conjunto de funções criptográficas de hash |
PKCE | Proof Key for Code Exchange | Chave de prova para troca de código por clientes públicos Oauth |
MAC | Código de Autenticação de Mensagem | Permite que as declarações sejam assinadas digitalmente ou protegidas por integridade utilizando JWS |
ICP-Brasil | Infraestrutura de Chaves Públicas Brasileira | Na definição oficial, “uma cadeia hierárquica de confiança que viabiliza a emissão de certificados digitais para identificação virtual do cidadão" |
AC | Autoridade Certificadora | |
AR | Autoridade de Registro | |
TLS | Transport Layer Security | |
ECDSA | Elliptic Curve Digital Signature Algorithm | Algoritmo de método de assinatura digital de documentos utilizando criptografia baseada em curvas elípticas |
ECDHE | Elliptic-curve Diffie–Hellman | Protocolo de contrato chave que permite que duas partes, cada uma com um par de chaves público-privado de curva elíptica, estabeleçam um segredo compartilhado em um canal inseguro |
AES | Advanced Encryption Standard | Algoritmos de criptografia de bloco simétrico com uma chave de criptografia de 256 bits |
Autenticação mútua | Chamamos de autenticação mútua quando ambos cliente e servidor apresentam certificados para serem validados pelo par | |
CSR | Certificate Signing Request | Contém informação que irá ser incluída no seu certificado como o nome da empresa/organização, common name (domínio), localidade e país. Também contém a chave pública (public key) que será incluída no seu certificado. Normalmente é também criada uma chave privada (private key) ao mesmo tempo que é criado o CSR |
SSA | Software Statement Assertion | SSA é um JSON Web Token (JWT) que contém metadados sobre uma instância de aplicativo client desenvolvida por um TPP. O JWT é emitido e assinado pelo Diretório do Open Insurance Brasil |
End User | Identificação de usuário final que possui as informações que se deseja acessar | |
Back-End | Aplicação ou código que da inteligência de negocio as ações solicitadas via API , código que efetivamente realiza a função desejada | |
Json | JavaScript Object Notation | Modelo para armazenamento e transmissão de informações no formato texto. |
Claims | Escopos/declarações usadas em uma API durante a autenticação para autorizar o acesso aos detalhes de um usuário, como nome e imagem por exemplo. Cada escopo retorna um conjunto de atributos do usuário, que são chamados de declarações | |
Header | Cabeçalho de uma solicitação ou resposta que transmite contexto e metadados adicionais sobre a solicitação ou resposta. Por exemplo, em uma mensagem de solicitação podem ser usados para fornecer credenciais de autenticação | |
Payload | Carga Útil do token JWT. É aqui que você coloca informações como a quem o token pertence, qual a expiração dele, quando ele foi criado, entre outras coisas |
Referências Normativas
Referências | Descrição | Versão |
---|---|---|
JSON | The JavaScript Object Notation (JSON) Data Interchange Format: https://tools.ietf.org/html/rfc8259 | Dec 2017 |
JWT | JSON Web Token (JWT): https://tools.ietf.org/html/rfc7519 | May 2015 |
JWS | JSON Web Signature (JWS): https://tools.ietf.org/html/rfc7797 | Feb 2016 |
Referências Informativas
Referências | Descrição |
---|---|
BCP195 | Recomendações para o uso seguro do Transport Layer Security (TLS) e Datagram Transport Layer Security (DTLS): BCP 195 |
DOS-G | Guia de segurança sobre DDoS attacks: Denial of Service (DoS) guidance |
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:
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
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Export the open-data for all the organisations | OrganisationsExportOpenData |
401 | Unauthorized | Unauthorized | None |
403 | Forbidden | Forbidden | None |
404 | Not Found | The specified key does not exist | None |
500 | Internal Server Error | Internal Server Error | None |
502 | Bad Gateway | Bad Gateway | None |
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
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
API Participants | Prefira por consumir dados da API Participants. Ela permite que o conteúdo seja fornecido ao usuário através de um servidor mais próximo, acelerando a distribuição e melhorando a experiência de consumo. |
Webhook do Diretório | Inscreva-se no webhook do Diretório para receber os eventos de notificação das principais atualizações, como alteração de cadastro, atualização de marca, entre outros. |
Cache local | Alguns participantes optam pela utilização de estruturas de cache local. Assim, recomenda-se a revalidação diária dos dados, de modo a mantê-los íntegros e com a versão mais recente possível. |
![]() |
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
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/
Clique no link Register
Na tela Register for an account, preencha os campos do formulário.
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.
Nome do campo | Descrição | Exemplo |
---|---|---|
First Name | Deve ser preenchido com o primeiro nome do usuário. | Maria |
Family Name | Deve ser preenchido com o sobrenome do usuário. | Gomes |
E-mail Address | Deve ser informado um endereço de e-mail corporativo. | maria.gomes@semicredi.com.br |
Phone Number | Informar o número de telefone de contato do usuário. | +55 11 900000000 |
Password | Definir uma senha que deve conter entre 8 e 24 caracteres com letras maiúsculas, minúsculas, números e ao menos um carácter especial. | <senha_secreta> |
Confirm Password | Repetir a mesma senha informada no campo anterior. | <senha_secreta> |
National ID (CPF) | Informar o número de registro do Cadastro de Pessoa Física (CPF). | 999999999-00 |
Do you possess an e-signature certificate? | O seletor deve estar assinalado caso o usuário possua um eCPF |
ETAPA 2: Verificando os dados informados
Requisitos
- 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.
- No e-mail recebido, selecione, copie e cole o código OTP no campo EMAIL VERIFICATION CODE.
- Na mensagem SMS recebida no telefone celular, copie o código OTP e informe no campo PHONE NUMBER VERIFICATION CODE.
- 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
- 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.
- Digitalize o QR Code que aparece na página e no aplicativo de autenticação. Copie e cole a senha de uso único (OTP).
- Clique no botão Sign-In.
ETAPA 4: Confirmação da assinatura eletrônica
Requisitos
- Nesta etapa, será enviado um e-mail contendo um link para análise e assinatura do Termo de Aceite.
- Selecione e copie o código de acesso apresentado na janela Upload e-signature confirmation.
- 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.
- No navegador, cole o valor copiado no passo 2 no campo Código de acesso.
- Clique no botão Validar.
ETAPA 5: Análise e confirmação do Termo de Aceite
Requisitos
- Nesta etapa, no website da DocuSign, clique no botão Continuar.
- Role o documento para baixo e, na página seguinte, clique no ícone Rubricar. No final das páginas, clique no ícone Assinar.
- Clique no botão Concluir.
- 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.
- 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.
- Na caixa de entrada, você receberá um e-mail enviado pela DocuSign contendo uma cópia do documento Termo de Aceite assinado eletronicamente.
- 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
- No Diretório, localize e selecione a sua organização.
- 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 .
Nome do campo | Descrição | Exemplo |
---|---|---|
Status | Define o estado atual do cadastro, se está ativo ou não. | Active |
Organisation Name | Deve ser informado o nome da organização. | Seg. Semicredi S.A. |
Registration Number-CNPJ | Deve ser informado o número de Cadastro Nacional da Pessoa Jurídica (CNPJ) da organização. | 22.222.222/0002-22 |
Date of Creation | Data de criação do registro de cadastro da organização. | 2021-01-07T11:13:08.531Z |
Company Registrar | Cadastro Nacional da Pessoa Jurídica | |
Organisation ID | Identificador da organização. Esta informação será gerada automaticamente. | cdc674fd-b019-5110-af5d-0268ed8227371 |
Parent Organisation Reference ID | Deve ser informado o número de Cadastro Nacional da Pessoa Jurídica (CNPJ) da organização mãe para casos em que seja necessária a constituição de um conglomerado. A seção de Cadastramento de conglomerados ilustra este cenário em mais detalhes. | 11.111.111/0001-11 |
Legal Name | Deve ser informado o nome legal de cadastro da instituição. | Seguradora Semicredi S.A. |
Address Line 1 | Deve ser informado o logradouro da organização. | Rua ABC 123 |
Address Line 2 | Deve ser informado o logradouro da organização. | Cidades Monções |
City | Deve ser informada a cidade da organização. | São Paulo, SP |
Country | Deve ser informado o país da organização. | 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
- No Diretório, localize e selecione a sua organização.
- Selecione o menu Contacts e clique no botão New Contact.
- Na janela New Contact preencha os campos do formulário. A tabela a seguir apresenta cada um dos campos em mais detalhes.
- 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.
Nome do campo | Descrição | Exemplo |
---|---|---|
Contact Type* | Tipo do contato (Business/Negócio, Technical/Técnico, Billing/Cobrança, Incident/Incidente e Security/Segurança). | Incident |
Department | Deve ser informado o departamento do contato. | Operações de TI |
First Name | Deve ser informado o primeiro nome do contato. | Maria |
Last Name | Deve ser informado o sobrenome do contato. | Gomes |
E-mail* | O endereço de e-mail do contato. | maria.gomes@semicredi.com.br |
Phone Number* | Deve ser informado o número de telefone do contato. | +55 51 900000000 |
Additional Information | Deve ser informado o e-mail para o grupo de notificação do contato. | openinsurance@semicredi.com.br |
PGP Public Key | Deve ser preenchido com uma chave alfanumérica para comunicação de dados de incidentes de segurança entre instituições. | Como esta chave tem extensão muito grande para adicionar como exemplo, segue link para documentações para documentações que definem a chave PGP (RFC 488). |
Address Line 1 | Deve ser informado o endereço (Rua, Avenida ou Alameda). | Rua ABC 123 |
Address Line 2 | Deve ser informado o bairro. | Cidades Monções |
City | Deve ser informado a cidade de domicílio. | São Paulo |
Post Code | Deve ser informado o código portal. | 99.999-99 |
Country | Deve ser informado o país de domicílio. | Brasil |
(*) Campo obrigatório
DETALHAMENTO DOS TIPOS DE CONTATO
Nome do campo | Descrição |
---|---|
Business/Negócio | Contato responsável pela gestão de negócio do Open Insurance na instituição. |
Technical/Técnico | Contato para tratativa de problemas técnicos de performance, disponibilidade e em relação a APIs de forma geral. |
Billing/Cobrança | Contato responsável pela cobrança dos custos da estrutura central do Open Insurance Brasil. |
Incident/Incidente | Contato responsável pelo atendimento de incidentes relacionados ao Open Insurance na instituição. |
Security/Segurança | Contato para tratativas relacionadas a problemas de caráter de segurança como DCR, certificados, entre outros. |
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
- No Diretório, localize e selecione a sua organização.
- Selecione o menu Authority Domain Claims e clique no botão New Domain Claim.
- Na janela New Authority Domain Claim preencha os campos do formulário. A seguir serão apresentados maiores detalhes sobre os campos.
- Clique no botão Save.
Nome do campo | Descrição | Exemplo |
---|---|---|
Authority Name* | Informe o nome da autoridade. | Seguradora Semicredi |
Authorisation Domain Name* | Informe o nome de domínio de autorização. | Open Insurance Brasil |
Authority ID | Exibe o identificador de autoridade única. Esta informação será gerada automaticamente. | 5360d5bf-5024-47cd-bd18-daab08df38ba |
Registration ID | ID de registro de reivindicação de domínio exclusivo. Não é necessário preencher esta informação. | CNPJ-OIB |
(*) 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.
Nome da modalidade no diretório | Descrição |
---|---|
DADOS | Instituição transmissora e/ou receptora de dados é a instituição que sendo: • Transmissora de dados: instituição participante que compartilha os dados com a instituição receptora; • Receptora de dados: instituição participante que apresenta solicitação de compartilhamento à instituição transmissora para recepção dos dados. |
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
- Necessário realizar a seção "Cadastrando reivindicações de domínio de autoridade".
- No Diretório, localize e selecione a sua organização.
- Selecione o menu Authority Domain Role Claims e clique no botão New Role Claim.
- Na janela New Authority Domain Role Claim preencha os campos do formulário. A seguir serão apresentados os campos em mais detalhes.
- Clique no botão Save.
Nome do campo | Descrição | Exemplo |
---|---|---|
Authority Name* | Selecione o nome da autoridade. | Seguradora Semicredi |
Authorisation Domain Name* | Selecione o nome de domínio de autorização. | Open Insurance Brasil |
Role* | Selecione a modalidade (função). | |
Unique Technical Identifier | Selecione o identificador técnico único. | |
Registration ID* | Deve ser informado o número de registro único [ISPB-OBBFUNÇÃO]. Substitua o [ISPB] pelos primeiros 8 dígitos do seu CNPJ e o [FUNÇÃO] pela sigla da função que você está inserindo. | 12345678-OBB-DADOS |
(*) Campo obrigatório
ETAPA 2: Cadastrando um usuário de domínio de autorização
Requisitos
- Necessário ter realizado o cadastro de uma nova reivindicação de domínio.
- No Diretório, localize e selecione a sua organização.
- Selecione o menu Authority Domain Role Claims. será carregado um submenu na parte superior esquerda. Então, clique no link Authorisation Domain User.
- Na janela, clique no botão New Authorisation Domain User.
- Na janela New Authorisation Domain User, preencha os campos do formulário.
- Clique no botão Save.
Nome do campo | Descrição | Exemplo |
---|---|---|
Domain Name | É apresentado o domínio de autorização para o qual esta reivindicação de domínio está mapeada. | Open Insurance Brasil |
Authorisation Domain Role | É apresentada a função mapeada para o domínio de autorização. | DADOS |
System* | Selecione o sistema de contato: Directory, Service Desk, Dispute Resolution, Portal ou Centralized Platform. Para obter mais detalhes, verifique em "Sistemas e Funções de um usuário/contato". | Directory |
Contact Role* | Selecione o papel assumido pelo contato. Para obter mais detalhes, verifique em "Sistemas e Funções de um usuário/contato". | PBC |
E-mail* | Deve ser informado o endereço de e-mail corporativo do contato. | maria.gomes@semicredi.com.br |
(*) 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
- No Diretório, localize e selecione a sua organização.
- 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.
- 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.
Nome do campo | Descrição | Exemplo |
---|---|---|
Customer Friendly Server Name* | Deve ser definido o valor da marca que será exibido no receptor. Apresentar seu nome por inteiro, sem abreviações, de forma a ser reconhecido pelo cliente e aderente a interfaces menores. • Limite de caracteres: 40 (padrão do campo) Para mais informações sobre marca, consulte o Guia de Experiência de Usuário. |
Semicredi |
OpenID Discovery Document URI* |
O URI para a localização do documento de descoberta OpenID. | https://www.semicredi.com.br/.well-known/openidconfiguration |
Payload Signing Certificate URI* |
O URI para a localização do certificado de assinatura. | https://www.semicredi.com.br/jwks |
(*) Campo obrigatório
Nome do campo | Descrição | Exemplo |
---|---|---|
Customer Friendly Logo URI* | Deve ser definida a URI para o logotipo da marca. Para obter mais detalhes sobre formato, dimensão e peso máximo do arquivo consulte o Guia de Experiencia Fase 2. | https://wwww.semicredi.com.br/logo.svg |
Developer Portal URI | O URI do portal do desenvolvedor. | https://developers.semicredi.com.br |
Terms Of Service URI | A URI de localização do documento de termos e serviços da organização. | https://wwww.semicredi.com.br/tos.html |
Notification Webhook Endpoint | Endpoint do Webhook de notificação. A seção Configurando Eventos de Notificação no Diretório descreve esta configuração em mais detalhes. | https://webhook.site/9d84a827-c200-4170-b0f8-f830170037bb |
Description* | Esse é um texto de marcação onde deverá ser descrita a marca, trazendo informações adicionais para que o cidadão não tenha dúvidas sobre a escolha feita. 1. Limite de caracteres: 256 (padrão do campo). 2. Não deve ser permitido que a descrição traga links. 3. Orientações sobre o que pode conter: • Texto institucional de apresentação. • Desde quanto atua. • Diferenciais de atuação. • Canais de atendimento. |
“A instituição Semicredi atua desde 1999 sendo uma das maiores seguradoras do Brasil, seja na web ou pelo App oferecemos produtos para sua família, empresa, carro e casa.” |
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
- No Diretório, localize e selecione a sua organização.
- 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.
- Dentro dessa área, para cadastrar uma nova certificação, clique no botão Add New Certification localizado no lado direito da tela.
- 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.
Nome do campo | Descrição | Exemplo |
---|---|---|
Certification type* |
O tipo de certificação que foi efetuada com a OpenID Foundation – Deve ser adicionado ao menos uma certificação Redirect (FAPI) e uma DCR. | Redirect DCR CIBA – certificação ainda não disponível |
Certification type variant* |
As variantes dependem do tipo de certificação escolhida. | Dentro da tabela da OpenID Foundation, cada coluna representa as possíveis variações nas certificações. Para a certificação DCR, a instituição deve avaliar se certificou utilizando APIs de Dados do consumidor – Unsigned, ou de Pagamentos - Signed. |
Profile version* |
A versão da certificação selecionado – Campo livre, apenas para controle da própria instituição. | 1 |
Certification payload* |
O URI que aponta para o arquivo hospedado pela OpenID Foundation com o pacote de certificação. Formato zip. | https://openid.net/wordpresscontent/uploads/2021/08/BR-OB_Adv._OP_MTLSexemplo.zip |
Start date of certification* | A data de certificação inicial – é a mesma data que consta na tabela da OpenID Foundation. Formato dd/mm/yyyy | 09/05/2022 |
(*) 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
API | Diretório (Family Type) | Recursos (resources) |
---|---|---|
discovery | discovery | https://api.organizacao.com.br/open-insurance/discovery/v1/status https://api.organizacao.com.br/open-insurance/discovery/v1/outages |
data_channels | data_channels | https://api.organizacao.com.br/open-insurance/data_channels/v1/electronic-channels https://api.organizacao.com.br/open-insurance/data_channels/v1/branches https://api.organizacao.com.br/open-insurance/data_channels/v1/phone-channels |
admin_metrics | admin_metrics | https://api.organizacao.com.br/open-insurance/admin_metrics/v1/admin_metrics |
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
API | Diretório (Family Type) | Recursos (resources) |
---|---|---|
resources | resources | https://api.organizacao.com.br/open-insurance/resources/v1/ |
customers | customers | https://api.organizacao.com.br/open-insurance/customers/v1/personal/identifications https://api.organizacao.com.br/open-insurance/customers/v1/business/identifications |
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
- No Diretório, localize e selecione a sua organização.
- Selecione o menu Authorisation Servers e clique no link do servidor de autorização na qual se deseja cadastrar os recursos.
- No canto superior esquerdo da página clique em API Resources.
- Na página que será carregada, clique no botão New API Resources para abrir a janela New API Resource.
- Na janela New API Resource, clique na caixa de seleção API Family Type e selecione uma das opções disponíveis.
- No campo ao lado, em Version especifique o valor apropriado utilizando versionamento semântico (major.minor.patch, exemplo: 1.0.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.
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
De volta à tela API Resources, informe URI principal no campo API Discovery Endpoints e, em seguida, pressione a tecla Enter.
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
- No Diretório, localize e selecione a sua organização.
- Selecione o menu Software Statements e clique no botão New Software Statement.
- Na janela New Software Statement preencha os campos do formulário. A seguir serão apresentados cada um dos campos em mais detalhes.
Nome do campo | Descrição | Exemplo |
---|---|---|
Version* | A versão do software deve ser definida para um valor numérico, um número inteiro (por exemplo, 1) ou um número de ponto flutuante (1,2; 2,2; 3,2 , etc.) | 1 |
Client Name* | Para registro de software da instituição receptora (software statement), no campo Client Name, recomenda-se usar o nome da Marca de conhecimento do cliente. Se o nome da marca foi declarado no Authorisation Server, por exemplo, pode-se usar o nome da marca que foi utilizado no cadastro (customer friendly server name). Este é o nome que a transmissora irá receber e declarar ao cliente durante a jornada. | Seguradora Semicredi |
Client URI* | O site ou URI raiz do recurso, podendo ser o site institucional da organização. | https://www.semicredi.com.br/info.html. |
Policy URI | Deve ser definido como uma sequência de texto que representa uma URI única de política. | https://www.semicredi.com.br/policy.html |
Logo URI* | Deve ser definida a URI para o logotipo da marca. Para obter mais detalhes sobre formato, dimensão e peso máximo do arquivo consulte o Guia de Experiencia Fase 2 | https://www.semicredi.com.br/logo.svg |
Redirect URI* | Os URIs de redirecionamento devem ser definidos como uma string de texto que representa uma URI única de redirecionamento. | https://www.semicredi.com.br/cb1 https://www.semicredi.com.br/cb2 |
Terms of Service | URI | Deve ser definido como uma string de texto que representa uma URI única dos Termos de Serviço. https://www.semicredi.com.br/tos.html |
Description | Deve ser definido como uma string de texto de sua escolha. | Aplicativo Seguradora Semicredi para o segmento de varejo. |
On Behalf Of | O campo “Em nome de” é classificado como opcional para implementação. | Não se aplica para o contexto do Open Insurance Brasil |
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
- No Diretório, localize e selecione a sua organização.
- 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.
- Dentro dessa área, para cadastrar uma nova certificação, clique no botão Add New Certification localizado no lado direito da tela.
- 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.
Nome do campo | Descrição | Exemplo |
---|---|---|
Certification type* | O tipo de certificação que foi efetuada com a OpenID Foundation – Deve ser adicionada, ao menos, uma certificação Redirect (FAPI e DCR). | Redirect DCR CIBA – certificação ainda não disponível |
Certification type variant* | As variantes dependem do tipo de certificação escolhida. Dentro da tabela da OpenID Foundation cada coluna representa as possíveis variações nas certificações. Vale notar que JARM não é requisitado segundo a especificação de segurança, portanto não está presente como uma opção a ser adicionada. Para a certificação DCR a instituição deve avaliar se certificou utilizando APIs de Dados do consumidor – Unsigned, ou de Pagamentos - Signed. | Se escolheu Redirect: • FAPI Adv. OP w/ MTLS • FAPI Adv. OP w/ MTLS, PAR • FAPI Adv. OP w/ Private Key • FAPI Adv. OP w/ Private Key, PAR Se escolheu DCR: • DCR Signed payload – JWT • DCR Unsigned payload - JSON |
Profile version* | A versão da certificação selecionado – Campo livre, apenas para controle da própria instituição. | 1 |
Certification payload* | O URI que aponta para o arquivo hospedado pela OpenID Foundation com o pacote de certificação. Formato zip. | https://openid.net/wordpresscontent/uploads/2021/08/BR-OB_Adv._OP_MTLSexemplo.zip |
Start date of certification* | A data de certificação inicial – é a mesma data que consta na tabela da OpenID Foundation. Formato dd/mm/yyyy | 09/05/2022 |
(*) 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
- Necessário realizar a seção "Cadastrando reivindicações de domínio de autoridade".
- Necessário realizar a seção "Cadastrando reivindicações de autoridade".
- Necessário ter criado um Software Statements para sua organização.
- No Diretório, selecione a sua organização e, no menu lateral, clique em Software Statements.
- 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.
- Na janela New Software Authority Claims preencha os campos do formulário. Os campos serão apresentados, a seguir, em mais detalhes.
Nome do campo | Descrição | Exemplo |
---|---|---|
Authorisation Domain Name | É apresentado o domínio de autorização para o qual esta a reivindicação de domínio está mapeada. | Open Insurance Brasil |
Role | É apresentada a função mapeada para o domínio de autorização. | DADOS |
(*) 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
Requisitos
- Necessário ter criado um Software Statements para sua organização.
- No Diretório, selecione a sua organização e, em seguida, selecione o menu Software Statements.
- Na tela Software Statement, clique no botão New Certificate.
- Na janela New Certificate, na caixa de seleção Select Certificate Type, selecione a opção EXTERNAL BRCAC e clique no botão Continue.
- No passo seguinte, em "Generate CSR", clique no botão Continue.
- Na opção "Upload CSR/PEM", localize o arquivo.csr e clique no botão Continue.
- Aguarde o carregamento do arquivo para o Diretório e, em seguida, clique no botão Done.
- Na tela anterior de certificates, vá até actions e clique na seta de download. Salve o arquivo.pem em uma pasta local.
ETAPA 2: Carregando certificado de assinatura
Requisitos
- No Diretório, selecione a sua organização e clique em Organisations Certificate no menu lateral.
- Na janela New Organisations Certificate, na caixa de seleção Select Certificate Type, selecione a opção BRSEAL EXTERNAL e clique no botão Continue.
- No passo seguinte, em Generate CSR, clique no botão Continue.
- Na opção Upload CSR/PEM, localize o arquivo.csr e clique no botão Continue.
- Aguarde o carregamento do arquivo para o Diretório e no passo seguinte clique no botão Done.
- Na tela anterior em Organisation Certificates, vá até actions e clique na seta de download. Salve o arquivo.pem em uma pasta local.
13. Cadastrando administradores da organização
Esta seção explica as etapas necessárias para realizar o cadastro de um novo administrador da organização.
ETAPA 1: Cadastrando um administrador da organização
Requisitos
- No Diretório, localize e selecione a sua organização.
- Selecione o menu Organisation Administrator e clique no botão New Organisation Administrators.
- Na janela New Organisation Administrator preencha o campo do formulário.
- Clique no botão Save.
Nota: somente administradores da organização podem cadastrar novos administradores.
14. Obtendo um Software Statements Assertion
Uma Software Statements Assertion (SSA) é um JWT assinado do 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 a esta declaração de software e todos os outros metadados de que um banco precisa para validar a legitimidade do aplicativo.
ETAPA 1: Criando uma nova declaração de software assinada
Requisitos
- Necessário ter criado um Software Statements para sua organização.
- No Diretório, localize e selecione a sua organização.
- Vá até o menu Software Statement, acesse o artefato criado anteriormente clicando no link CLIENT NAME.
- Na janela Software Statement Details, role a página para baixo e selecione o menu Software Statements Assertion.
- Clique no botão Copy to Clipboard para copiar o SSA gerado pelo Diretório.
15. Configurando eventos de notificação no Diretório
Aqui apresentamos a configuração de Webhook no Diretório.
ETAPA 1: Inscrever-se em um tópico
Requisitos
- Em seu navegador, navegue até webhook.site e uma URL única e aleatória será gerada automaticamente. Ela poderá ser utilizada para testar e depurar Webhooks e solicitações HTTP.
- Selecione a URL e a copie.
ETAPA 2: Solicitando uma subscrição
Requisitos
- No Diretório, selecione a sua organização e vá até a página "detalhes da organização".
- Selecione o menu Authorisation Servers e, em actions, clique no ícone de edição.
- Na página Authorisation Server Information, cole a URL obtida na Etapa 1 no campo Notification Webhook Endpoint.
ETAPA 3: Confirmando uma subscrição
Requisitos
- De volta ao webhook.site, role para baixo e no campo de texto Raw Context selecione e copie a URL em SubscribeURL para se subscrever no tópico.
- Em uma nova aba do navegador, cole a URL obtida no passo anterior.
- Pronto! A partir daqui, toda e qualquer modificação que ocorra no Diretório será notificada através de eventos.
ETAPA 4: Analisando um evento de notificação
Requisitos
- No Diretório, selecione a sua organização e vá até a página detalhes da organização.
- Selecione o menu Software Statement e em actions clique no ícone editar.
- Na janela Software Statement Details vá até o campo description e digite qualquer valor e clique no botão Salvar.
- Neste momento, o Diretório irá enviar uma notificação push.
- De volta ao webhook.site, clique no primeiro evento que surge na lista a esquerda da tela.
- Role a tela para baixo e no campo de texto Raw Context localize o novo valor adicionado no atributo description.
16. Obtendo um token de acesso para as APIs do Diretório
Para acessar as APIs do Diretório do Open Insurance, você precisará de um token de acesso. Esta seção descreve as etapas necessárias para adquirir tokens de acesso.
ETAPA 1: Localizando o identificador do cliente
Requisitos
- Necessário ter criado um Software Statements para sua organização.
- No Diretório, localize e selecione a sua organização.
- Vá até o menu Software Statement, acesse o artefato criado anteriormente clicando no símbolo do lápis.
- Na janela Software Statement Details localize o campo CLIENT ID, selecione e copie o valor.
ETAPA 2: Localizando a URI de token no Diretório
Requisitos
- No navegador, acesse a URI de descoberta de conexão OpenID de acordo com o ambiente utilizado:
Sandbox
https://auth.sandbox.directory.opinbrasil.com.br/.well-known/openid-configuration
Produção
https://auth.directory.opinbrasil.com.br/.well-known/openid-configuration
- Localize o endpoint de token que será utilizado para trocar as credenciais de autenticação para tokens de acesso.
ETAPA 3: Adicionando certificados SSL por domínio
Requisitos
- Necessário ter criado uma Solicitação de Assinatura de Certificado (CSR).
- Será utilizado o Postman, com fins ilustrativos, para acessar as APIs do Diretório do Open Insurance Brasil. Assim, no Postman, selecione o menu File e em seguida o menu Settings. Um atalho para acessar esta janela é o comando: Ctrl + Vírgula.
- Na janela Settings, selecione o menu Certificates e clique no link Add Certificate.
Na aba Certificates, no campo Host insira um dos valores descritos a seguir de acordo com o ambiente utilizado:
Sandbox
matls-auth.sandbox.directory.opinbrasil.com.br
e
matls-api.sandbox.directory.opinbrasil.com.br
Produção
Matls-auth.directory.opinbrasil.com.br
e
Matls-api.directory.opinbrasil.com.br
Em CRT file, clique no botão Select file, e localize o arquivo.pem obtido na seção Criando uma solicitação de Assinatura de Certificado (CSR).
No passo seguinte, clique no botão KEY File e localize o arquivo.Key criado no processo de geração de chaves na seção "Criando uma solicitação de Assinatura de Certificado (CSR)".
Clique no botão Add.
ETAPA 4: Obtendo um token de acesso
Requisitos
- Para adicionar uma nova requisição a uma coleção, vá no canto superior esquerdo em Collection, clique em ‘...’ na coleção e escolha Add Request. Você também pode criar uma solicitação clicando no menu File > New, e em seguida Request.
- No campo Enter request URL, digite o valor obtido da URI de token mencionado na etapa 2.
- Defina o tipo da operação para POST.
- Vá para a guia Body e selecione o botão de opção‘x-www-form-urlencoded’.
Insira os parâmetros como descritos a seguir:
client_id =
grant_type = client_credentials
scope = directory:software
Uma vez que todos os parâmetros e valores estejam preenchidos, clique no botão Send.
Selecione e copie o valor retornado no atributo access_token.
17. Listando as organizações cadastradas no Diretório via API
Você precisará de um token de acesso para acessar a API Organisations no Diretório. Esta seção descreve as etapas necessárias para listar e visualizar os detalhes das organizações cadastradas no Diretório.
ETAPA 1: Obtendo detalhes das organizações
Requisitos
- Necessário ter um token de acesso. Veja mais detalhes em "Obtendo um token de acesso para acessar as APIs do Diretório".
- Para fins ilustrativos será utilizado o Postman para acessar as APIs do Diretório do Open Insurance Brasil. Assim, para adicionar uma nova requisição a uma coleção, vá no canto superior esquerdo em Collection, clique em ‘...’ na coleção e escolha Add Request. Você também pode criar uma solicitação clicando no menu File > New, e em seguida Request.
No campo Enter request URL, insira um dos valores descritos a seguir de acordo com o ambiente utilizado:
Sandbox
https://matls-api.sandbox.directory.opinbrasil.com.br/organisations
Produção
https://matls-api.directory.opinbrasil.com.br/organisations
Defina o tipo da operação para GET.
Vá para a guia Authorisation e na caixa de seleção Type selecione a opção Bearer Token.
Na coluna ao lado, no campo Token cole o access_token obtido na seção "Obtendo um token de acesso para acessar as APIs do Diretório".
Uma vez que todos os valores estejam preenchidos, clique no botão Send. Você verá a resposta de dados JSON do servidor no painel inferior.
Nota: Para localizar uma organização mãe que pertença a um conglomerado, você poderá percorrer na lista de resposta de dados JSON do servidor, capturando o identificador no atributo ParentOrganisationReference das organizações filhas e localizar o mesmo ID na organização cujo o atributo RegistrationId contenha este mesmo valor.
18. Listando os servidores de autorização de uma organização via API
Aqui apresentamos os passos para listar os servidores de autorização de uma organização.
ETAPA 1: Listando os servidores de autorização
Requisitos
- Necessário ter um token de acesso. Veja mais detalhes em "Obtendo um Token de Acesso para acessar as APIs do Diretório".
- Necessário ter realizado os passos da seção "Listando as organizações cadastradas no Diretório via API".
- Será utilizado o Postman, com fins ilustrativos, para acessar as APIs do Diretório do Open Insurance Brasil. Assim, para adicionar uma nova requisição a uma coleção, vá no canto superior esquerdo em Collection, clique em ‘...’ na coleção e escolha Add Request. Você também pode criar uma solicitação clicando no menu File > New, e em seguida Request.
No campo Enter request URL, insira um dos valores descritos a seguir de acordo com o ambiente utilizado:
Sandbox
matls-api.sandbox.directory.opinbrasil.com.br/organisations/
/authorisationservers Produção
matls-api.directory.opinbrasil.com.br/organisations/
/authorisationservers Defina o tipo da operação para GET.
Vá para a guia Authorisation e na caixa de seleção Type selecione a opção Bearer Token.
Na coluna ao lado, no campo Token, cole o access_token obtido na seção Obtendo um Token de Acesso para acessar as APIs do Diretório.
Uma vez que todos os valores estejam preenchidos, clique no botão Send. Você verá a resposta de dados JSON do servidor no painel inferior.
Nota: Na resposta de dados JSON do servidor o atributo customerFriendlyName contém o valor da marca e o CustomerFriendlyLogoUri o logotipo vinculado à marca.
19. Obtendo um Software Statement via API
Aqui apresentamos os passos para obter um Software Statement (SS) no Diretório via API.
ETAPA 1: Obtendo um SS no Diretório via API
Requisitos
- Necessário ter um token de acesso. Veja mais detalhes em Obtendo um token de acesso para acessar as APIs do Diretório.
- Necessário ter realizado os passos da seção "Listando as Organizações Cadastradas no Diretório via API".
- Para fins ilustrativos será utilizado o Postman para acessar as APIs do Diretório do Open Insurance Brasil. Assim, para adicionar uma nova requisição a uma coleção, vá no canto superior esquerdo em Collection, clique em ‘...’ na coleção e escolha Add Request. Você também pode criar uma solicitação clicando no menu File > New, e em seguida Request.
No campo Enter request URL, insira um dos valores descritos a seguir de acordo com o ambiente utilizado:
Sandbox
matls-api.sandbox.directory.opinbrasil.com.br/organisations/
/softwarestatements Produção
matls-api.directory.opinbrasil.com.br/organisations/
/softwarestatement Defina o tipo da operação para GET.
Vá para a guia Authorisation e na caixa de seleção Type selecione a opção Bearer Token.
Na coluna ao lado, no campo Token cole o access_token obtido na seção "Obtendo um Token de Acesso para acessar as APIs do Diretório".
Uma vez que todos os valores estejam preenchidos, clique no botão Send. Você verá a resposta de dados JSON do servidor no painel inferior.
20. Obtendo um Software Statement Assertion via API
Aqui apresentamos os passos para obter um Software Statement Assertion (SSA) no Diretório via API.
ETAPA 1: Obtendo um SSA do Diretório via API
Requisitos
- Necessário ter um token de acesso. Veja mais detalhes em "Obtendo um Token de Acesso para acessar as APIs do Diretório".
- Necessário ter realizado os passos da seção "Listando as organizações cadastradas no Diretório via API".
- Necessário ter realizado os passos da seção "Obtendo um Software Statement via API".
- Será utilizado o Postman, com fins ilustrativos, para acessar as APIs do Diretório do Open Insurance Brasil. Assim, para adicionar uma nova requisição a uma coleção, vá no canto superior esquerdo em Collection, clique em ‘...’ na coleção e escolha Add Request. Você também pode criar uma solicitação clicando no menu File > New, e em seguida Request.
No campo Enter request URL, insira um dos valores descritos a seguir de acordo com o ambiente utilizado:
Sandbox
matls-api.sandbox.directory.opinbrasil.com.br/organisations/
/softwarestatements/ /assertion Produção
matls-api.directory.opinbrasil.com.br/organisations/
/softwarestatements/ /assertion Defina o tipo da operação para GET.
Vá para a guia Authorisation e na caixa de seleção Type selecione a opção Bearer Token.
Na coluna ao lado, no campo Token, cole o access_token obtido na seção "Obtendo um Token de Acesso para acessar as APIs do Diretório".
Uma vez que todos os valores estejam preenchidos, clique no botão Send. Você verá a resposta de dados JSON do servidor no painel inferior.
21. Como se inscrever nas atualizações de lançamento do Diretório
Constantemente são realizados aprimoramentos e atualizações no Diretório. Estas mudanças são registradas em uma página Web onde reside todo o conteúdo do Release Notes. Esta seção descreve as etapas necessárias de inscrição para o recebimento de notificação do release notes do Diretório quando publicado.
ETAPA 1: Cadastrando o recebimento de release notes.
Requisitos
- Em seu navegador, navegue até site de monitoramento de disponibilidade do Diretório.
- Clique em “Subscrever atualizações”.
- Na tela seguinte, adicione seu e-mail e clique no botão "Subscrever". O Diretório irá enviar uma mensagem de confirmação, que será encaminhada ao endereço de e-mail informado.
- No e-mail recebido, clique no botão "Sim, subscreve-me".
- Em uma página da Web será apresentada a mensagem informando que seu e-mail encontra-se, agora, subscrito para atualizações de estado Open Insurance Brasil.
Nota: Caso você não tenha recebido o e-mail 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 "Subscrever Alterações" para reenvio das mensagens.
ETAPA 2: Acessando o Release Notes
Requisitos
- No navegador, digite a URL de acordo com o ambiente a ser acessado:
Sandbox
https://data.sandbox.directory.opinbrasil.com.br/release-notes
Produção
https://data.directory.opinbrasil.com.br/release-notes
22. Como obter suporte ao Diretório
Aqui apresentamos as formas de contato para suporte ao Diretório Central.
Service Desk
Todas as consultas, problemas ou solicitações de suporte precisam ser roteados por meio do Service Desk.
O Service Desk do Open Insurance Brasil pode ser acessado pelo endereço: https://servicedesk.opinbrasil.com.br/
É possível abrir chamados de Solicitação de Informações, Melhorias, Incidentes de Indisponibilidade e Problemas de Performance.
Schemas
BadRequest
{
"errors": [
"string"
]
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
errors | [string] | false | none | Validation Error messages |
PageableRequest
{
"page": 0,
"size": 2,
"sort": "status,desc"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
page | integer | false | none | Page index starts from 0 |
size | integer | false | none | This sets the page size |
sort | string | false | none | Used to sort based on Model Parameters |
UserUpdateRequest
{
"Status": "Active"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
Status | StatusEnum | false | none | none |
StatusEnum
"Active"
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | none |
Enumerated Values
Property | Value |
---|---|
anonymous | Active |
anonymous | Inactive |
OrganisationAuthorityClaims
[
{
"OrganisationId": "string",
"OrganisationAuthorityClaimId": "string",
"AuthorityId": "string",
"Status": "Active",
"AuthorisationDomain": "string",
"Role": "string",
"Authorisations": [
{
"Status": "Active",
"MemberState": "st"
}
],
"RegistrationId": "string",
"UniqueTechnicalIdenifier": [
"string"
]
}
]
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | [OrganisationAuthorityClaim] | false | none | none |
OrganisationAuthorityClaim
{
"OrganisationId": "string",
"OrganisationAuthorityClaimId": "string",
"AuthorityId": "string",
"Status": "Active",
"AuthorisationDomain": "string",
"Role": "string",
"Authorisations": [
{
"Status": "Active",
"MemberState": "st"
}
],
"RegistrationId": "string",
"UniqueTechnicalIdenifier": [
"string"
]
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
OrganisationId | OrganisationId | false | none | Unique ID associated with the organisation |
OrganisationAuthorityClaimId | OrganisationAuthorityClaimId | false | none | Unique ID associated with the authority claims |
AuthorityId | AuthorityId | false | none | Unique ID associated with the Authorisation reference schema |
Status | string | false | none | Is this software statement Active/Inactive |
AuthorisationDomain | string | false | none | Authorisation Domain for the authority |
Role | string | false | none | Roles for the Authority i.e. ASPSP, AISP, PISP, CBPII |
Authorisations | [object] | false | none | none |
» Status | string | false | none | Is this authorsation Active/Inactive |
» MemberState | string | false | none | Abbreviated states information i.e. GB, IE, NL etc |
RegistrationId | string | false | none | Registration ID for the organisation |
UniqueTechnicalIdenifier | [string] | false | none | none |
Enumerated Values
Property | Value |
---|---|
Status | Active |
Status | Inactive |
Status | Active |
Status | Inactive |
OrganisationAuthorityClaimRequest
{
"AuthorityId": "string",
"Status": "Active",
"AuthorisationDomain": "string",
"Role": "string",
"RegistrationId": "string",
"UniqueTechnicalIdenifier": [
"string"
]
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
AuthorityId | AuthorityId | true | none | Unique ID associated with the Authorisation reference schema |
Status | string | true | none | Is this authority claim Active/Inactive, default is Active |
AuthorisationDomain | string | true | none | Authorisation domain for the authority |
Role | string | true | none | Role for the authority |
RegistrationId | string | true | none | Registration ID for the organisation |
UniqueTechnicalIdenifier | [string] | false | none | none |
Enumerated Values
Property | Value |
---|---|
Status | Active |
Status | Inactive |
OrganisationAuthorityClaimAuthorisations
[
{
"OrganisationAuthorisationId": "string",
"OrganisationAuthorityClaimId": "string",
"Status": "Active",
"MemberState": "string"
}
]
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | [OrganisationAuthorityClaimAuthorisation] | false | none | none |
OrganisationAuthorityClaimAuthorisation
{
"OrganisationAuthorisationId": "string",
"OrganisationAuthorityClaimId": "string",
"Status": "Active",
"MemberState": "string"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
OrganisationAuthorisationId | OrganisationAuthorisationId | false | none | Unique ID associated with authorisations for organisation's authority claims |
OrganisationAuthorityClaimId | OrganisationAuthorityClaimId | false | none | Unique ID associated with the authority claims |
Status | string | false | none | Is this authority claim Active/Inactive |
MemberState | string | false | none | Abbreviated states information i.e. GB, IE, NL etc |
Enumerated Values
Property | Value |
---|---|
Status | Active |
Status | Inactive |
OrganisationAuthorityClaimAuthorisationRequest
{
"Status": "Active",
"MemberState": "string"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
Status | string | true | none | Is this Active/Inactive - default is Active |
MemberState | string | true | none | Abbreviated states information i.e. GB, IE, NL etc |
Enumerated Values
Property | Value |
---|---|
Status | Active |
Status | Inactive |
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"
}
]
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | [AuthorisationServer] | false | none | none |
AuthorisationServer
{
"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"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
AuthorisationServerId | AuthorisationServerId | false | none | none |
OrganisationId | OrganisationId | false | none | Unique ID associated with the organisation |
AutoRegistrationSupported | boolean | false | none | none |
ApiResources | [ApiResource] | false | none | none |
CustomerFriendlyDescription | string | false | none | none |
CustomerFriendlyLogoUri | string(uri) | false | none | A compliant URI |
CustomerFriendlyName | string | false | none | none |
DeveloperPortalUri | string(uri) | false | none | A compliant URI |
TermsOfServiceUri | string(uri) | false | none | A compliant URI |
NotificationWebhook | string(uri) | false | none | A compliant URI |
NotificationWebhookStatus | string | false | none | If the webhook has confirmed subscription |
OpenIDDiscoveryDocument | string(uri) | false | none | A compliant URI |
PayloadSigningCertLocationUri | string(uri) | false | none | A compliant URI |
ParentAuthorisationServerId | AuthorisationServerId | false | none | none |
AuthorisationServerRequest
{
"AutoRegistrationSupported": true,
"CustomerFriendlyDescription": "string",
"CustomerFriendlyLogoUri": "string",
"CustomerFriendlyName": "string",
"DeveloperPortalUri": "string",
"TermsOfServiceUri": "string",
"NotificationWebhook": "string",
"OpenIDDiscoveryDocument": "string",
"PayloadSigningCertLocationUri": "string",
"ParentAuthorisationServerId": "string"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
AutoRegistrationSupported | boolean | true | none | Default is true |
CustomerFriendlyDescription | string | false | none | A customer friendly description |
CustomerFriendlyLogoUri | string | true | none | A compliant URI |
CustomerFriendlyName | string | true | none | none |
DeveloperPortalUri | string | true | none | A compliant URI |
TermsOfServiceUri | string | true | none | A compliant URI |
NotificationWebhook | string | false | none | A compliant URI |
OpenIDDiscoveryDocument | string | true | none | A compliant URI |
PayloadSigningCertLocationUri | string | true | none | A compliant URI |
ParentAuthorisationServerId | AuthorisationServerId | false | none | none |
AuthorisationServerId
"string"
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | none |
CertificateOrKeyOrJWT
"string"
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | none |
CertificateOrKeyId
"string"
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | none |
CertificatesOrKeys
[
{
"OrganisationId": "string",
"SoftwareStatementIds": [
"string"
],
"ClientName": "string",
"Status": "string",
"ValidFromDateTime": "string",
"ExpiryDateTime": "string",
"e": "string",
"keyType": "string",
"kid": "string",
"kty": "string",
"n": "string",
"use": "string",
"x5c": [
"string"
],
"x5t": "string",
"x5thashS256": "string",
"x5u": "string",
"SignedCertPath": "string",
"JwkPath": "string",
"OrgJwkPath": "string"
}
]
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | [CertificateOrKey] | false | none | none |
CertificateOrKey
{
"OrganisationId": "string",
"SoftwareStatementIds": [
"string"
],
"ClientName": "string",
"Status": "string",
"ValidFromDateTime": "string",
"ExpiryDateTime": "string",
"e": "string",
"keyType": "string",
"kid": "string",
"kty": "string",
"n": "string",
"use": "string",
"x5c": [
"string"
],
"x5t": "string",
"x5thashS256": "string",
"x5u": "string",
"SignedCertPath": "string",
"JwkPath": "string",
"OrgJwkPath": "string"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
OrganisationId | OrganisationId | false | none | Unique ID associated with the organisation |
SoftwareStatementIds | [SoftwareStatementId] | false | none | [Unique Software Statement Id] |
ClientName | string | false | none | none |
Status | string | false | none | none |
ValidFromDateTime | string | false | none | none |
ExpiryDateTime | string | false | none | none |
e | string | false | none | none |
keyType | string | false | none | none |
kid | string | false | none | none |
kty | string | false | none | none |
n | string | false | none | none |
use | string | false | none | none |
x5c | [string] | false | none | none |
x5t | string | false | none | none |
x5thashS256 | string | false | none | none |
x5u | string | false | none | none |
SignedCertPath | string | false | none | Used to display location of the signed certificate in PEM format |
JwkPath | string | false | none | Used to display path to JWKS containing this certificate |
OrgJwkPath | string | false | none | Used to display path to Org JWKS containing org certificates |
AmendCertificateRequest
{
"RevokeReason": "unspecified"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
RevokeReason | string | true | none | Specify a reason for revokation of the certificate. |
Enumerated Values
Property | Value |
---|---|
RevokeReason | unspecified |
RevokeReason | keycompromise |
RevokeReason | superseded |
RevokeReason | cessationofoperation |
RevokeReason | privilegewithdrawn |
ContactRequest
{
"ContactType": "Business",
"FirstName": "string",
"LastName": "string",
"Department": "string",
"EmailAddress": "string",
"PhoneNumber": "stringst",
"AddressLine1": "string",
"AddressLine2": "string",
"City": "string",
"Postcode": "string",
"Country": "string",
"AdditionalInformation": "string",
"PgpPublicKey": "string"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
ContactType | string | true | none | The type of Contact, default contact type is Business. |
FirstName | string | false | none | none |
LastName | string | false | none | none |
Department | string | false | none | none |
EmailAddress | string | true | none | none |
PhoneNumber | string | true | none | none |
AddressLine1 | string | false | none | Address line 1 |
AddressLine2 | string | false | none | Address line 2 |
City | string | false | none | City |
Postcode | string | false | none | Postcode |
Country | string | false | none | Country |
AdditionalInformation | string | false | none | Any additional user information |
PgpPublicKey | string | false | none | A PGP Public Key in text form |
Enumerated Values
Property | Value |
---|---|
ContactType | Business |
ContactType | Technical |
ContactType | Billing |
ContactType | Incident |
ContactType | Security |
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"
}
]
The list of contacts
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | [Contact] | false | none | The list of contacts |
Contact
{
"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"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
ContactId | string | false | none | Unique contact ID for the row. |
OrganisationId | OrganisationId | false | none | Unique ID associated with the organisation |
ContactType | string | false | none | none |
FirstName | string | false | none | none |
LastName | string | false | none | none |
Department | string | false | none | none |
EmailAddress | string | false | none | none |
PhoneNumber | string | false | none | none |
AddressLine1 | string | false | none | Address line 1 |
AddressLine2 | string | false | none | Address line 2 |
City | string | false | none | City |
Postcode | string | false | none | Postcode |
Country | string | false | none | Country |
AdditionalInformation | string | false | none | Any additional user information |
PgpPublicKey | string | false | none | A PGP Public Key in text form |
Enumerated Values
Property | Value |
---|---|
ContactType | Business |
ContactType | Technical |
ContactType | Billing |
ContactType | Incident |
ContactType | Security |
ContactId
"string"
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | none |
OrganisationRequest
{
"OrganisationId": "string",
"Status": "Active",
"OrganisationName": "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"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
OrganisationId | OrganisationId | true | none | Unique ID associated with the organisation |
Status | string | false | none | Status of the directory registration of an organisation |
OrganisationName | string | true | none | none |
LegalEntityName | string | true | none | Legal Entity name for the org. Usually the same as org name |
CountryOfRegistration | string | true | none | Country of registration for the org |
CompanyRegister | string | true | none | Legal company register for the country, i.e. Companies House |
RegistrationNumber | string | true | none | Company registration number from company register i.e. Companies House registration number |
RegistrationId | string | false | none | Registered ID for the organisation i.e. Legal Entity identifier number |
RegisteredName | string | false | none | Registered legal name |
AddressLine1 | string | true | none | Address line 1 |
AddressLine2 | string | false | none | Address line 2 |
City | string | true | none | City |
Postcode | string | true | none | Postcode |
Country | string | true | none | Country |
ParentOrganisationReference | string | false | none | Parent Organisation Reference |
Enumerated Values
Property | Value |
---|---|
Status | Active |
Status | Pending |
Status | Withdrawn |
OrganisationUpdateRequest
{
"Status": "Active",
"OrganisationName": "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"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
Status | string | false | none | Status of the directory registration of an organisation |
OrganisationName | string | true | none | none |
LegalEntityName | string | true | none | Legal Entity name for the org. Usually the same as org name |
CountryOfRegistration | string | true | none | Country of registration for the org |
CompanyRegister | string | true | none | Legal company register for the country, i.e. Companies House |
RegistrationNumber | string | true | none | Company registration number from company register i.e. Companies House registration number |
RegistrationId | string | false | none | Registered ID for the organisation i.e. Legal Entity identifier number |
RegisteredName | string | false | none | Registered legal name |
AddressLine1 | string | true | none | Address line 1 |
AddressLine2 | string | false | none | Address line 2 |
City | string | true | none | City |
Postcode | string | true | none | Postcode |
Country | string | true | none | Country |
ParentOrganisationReference | string | false | none | Parent Organisation Reference |
Enumerated Values
Property | Value |
---|---|
Status | Active |
Status | Pending |
Status | Withdrawn |
OrganisationEnrol
{
"RedirectUris": [
"http://example.com"
],
"TokenEndpointAuthMethod": "string",
"GrantTypes": [
"string"
],
"ResponseTypes": [
"string"
],
"ClientName": "string",
"ClientUri": "http://example.com",
"LogoUri": "http://example.com",
"Scope": "string",
"TosUri": "http://example.com",
"PolicyUri": "http://example.com"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
RedirectUris | [string] | true | none | none |
TokenEndpointAuthMethod | string | true | none | none |
GrantTypes | [string] | true | none | none |
ResponseTypes | [string] | true | none | none |
ClientName | number | true | none | ORG name as per eIDAS certificate |
ClientUri | string(uri) | true | none | A compliant URI |
LogoUri | string(uri) | true | none | A compliant URI |
Scope | string | true | none | none |
TosUri | string(uri) | true | none | A compliant URI |
PolicyUri | string(uri) | true | none | A compliant URI |
OrganisationEnrolments
[
{
"OrganisationId": "string",
"ClientSecret": "string",
"RedirectUris": [
"http://example.com"
],
"TokenEndpointAuthMethod": "string",
"GrantTypes": [
"string"
],
"ResponseTypes": [
"string"
],
"ClientName": "string",
"ClientUri": "http://example.com",
"LogoUri": "http://example.com",
"TosUri": "http://example.com",
"PolicyUri": "http://example.com",
"JwksUri": "http://example.com",
"Jwks": {}
}
]
A JSON object DCR response returned when client gets created.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
OrganisationId | OrganisationId | false | none | Unique ID associated with the organisation |
ClientSecret | string | false | none | Client secret generated by Directory |
RedirectUris | [string] | false | none | none |
TokenEndpointAuthMethod | string | false | none | none |
GrantTypes | [string] | false | none | none |
ResponseTypes | [string] | false | none | none |
ClientName | string | false | none | ORG name as per eIDAS certificate |
ClientUri | string(uri) | false | none | A compliant URI string of a web page providing information about the client |
LogoUri | string(uri) | false | none | A compliant URI |
TosUri | string(uri) | false | none | A compliant URI string that points to a human-readable terms of service document for the client |
PolicyUri | string(uri) | false | none | A compliant URI string that points to a human-readable privacy policy document |
JwksUri | string(uri) | false | none | A compliant URI string referencing the client's JSON Web Key (JWK) Set |
Jwks | object | false | none | Client's JSON Web Key Set [RFC7517] document value |
OrganisationCertificateType
"qwac"
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | none |
Enumerated Values
Property | Value |
---|---|
anonymous | qwac |
anonymous | qseal |
anonymous | rtswac |
anonymous | rtsseal |
OrganisationId
"string"
Unique ID associated with the organisation
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | Unique ID associated with the organisation |
OrganisationAuthorityClaimId
"string"
Unique ID associated with the authority claims
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | Unique ID associated with the authority claims |
OrganisationAuthorisationId
"string"
Unique ID associated with authorisations for organisation's authority claims
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | Unique ID associated with authorisations for organisation's authority claims |
SoftwareAuthorityClaimId
"string"
Unique ID associated with the authority claims for a software statement
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | Unique ID associated with the authority claims for a software statement |
AuthorityId
"string"
Unique ID associated with the Authorisation reference schema
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | Unique ID associated with the Authorisation reference schema |
Organisations
[
{
"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",
"RequiresSigning": true,
"TnCUpdated": true,
"TnCsToBeSigned": [
{
"TnCId": 0,
"Version": 0,
"Name": "string",
"Type": "string",
"Content": "string",
"Status": "Active",
"ExternalSigningService": {
"ExternalSigningServiceName": "DocuSign",
"ExternalSigningServiceSignerTemplateConfig": {
"TemplateIdSigner1": "string",
"TemplateIdSigner2": "string",
"TemplateIdSigner3": "string",
"TemplateIdSigner4": "string",
"TemplateIdSigner5": "string",
"TemplateIdSigner6": "string"
},
"ExternalSigningServiceSubject": "string"
}
}
]
}
]
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | [Organisation] | false | none | none |
Organisation
{
"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",
"RequiresSigning": true,
"TnCUpdated": true,
"TnCsToBeSigned": [
{
"TnCId": 0,
"Version": 0,
"Name": "string",
"Type": "string",
"Content": "string",
"Status": "Active",
"ExternalSigningService": {
"ExternalSigningServiceName": "DocuSign",
"ExternalSigningServiceSignerTemplateConfig": {
"TemplateIdSigner1": "string",
"TemplateIdSigner2": "string",
"TemplateIdSigner3": "string",
"TemplateIdSigner4": "string",
"TemplateIdSigner5": "string",
"TemplateIdSigner6": "string"
},
"ExternalSigningServiceSubject": "string"
}
}
]
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
OrganisationId | OrganisationId | false | none | Unique ID associated with the organisation |
Status | string | false | none | Status of the directory registration of an organisation |
OrganisationName | string | false | none | Name of the organisation. |
CreatedOn | string | false | none | JSONDatetime of organisation creation. |
LegalEntityName | string | false | none | Legal Entity name for the org. Usually the same as org name |
CountryOfRegistration | string | false | none | Country of registration for the org |
CompanyRegister | string | false | none | Legal company register for the country, i.e. Companies House |
RegistrationNumber | string | false | none | Company registration number from company register i.e. Companies House registration number |
RegistrationId | string | false | none | Registered ID for the organisation i.e. Legal Entity identifier number |
RegisteredName | string | false | none | none |
AddressLine1 | string | false | none | Address line 1 |
AddressLine2 | string | false | none | Address line 2 |
City | string | false | none | City |
Postcode | string | false | none | Postcode |
Country | string | false | none | Country |
ParentOrganisationReference | string | false | none | Parent Organisation Reference |
RequiresSigning | boolean | false | none | true - one of the attached tncs has to be signed. false - no tnc present |
TnCUpdated | boolean | false | none | true - attached tnc has been update. false - no tnc present |
TnCsToBeSigned | TnCsToBeSigned | false | none | none |
Enumerated Values
Property | Value |
---|---|
Status | Active |
Status | Pending |
Status | Withdrawn |
OrgTermsAndConditionsDetail
{
"InitiatedBy": "string",
"Role": "string",
"TermsAndConditionsDetail": {
"TermsAndConditionsItem": {
"TnCId": 0,
"Version": 0,
"Name": "string",
"Type": "string",
"Content": "string",
"Status": "Active",
"ExternalSigningService": {
"ExternalSigningServiceName": "DocuSign",
"ExternalSigningServiceSignerTemplateConfig": {
"TemplateIdSigner1": "string",
"TemplateIdSigner2": "string",
"TemplateIdSigner3": "string",
"TemplateIdSigner4": "string",
"TemplateIdSigner5": "string",
"TemplateIdSigner6": "string"
},
"ExternalSigningServiceSubject": "string"
}
},
"InititatedDate": "string",
"ExternalSigningServiceEnvelopeId": "string",
"ExternalSigningServiceEnvelopeStatus": "Completed",
"ExternalSigningServiceEnvelopePasscode": "string"
}
}
Participant TnC details
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
InitiatedBy | string | false | none | Email of the user who initiated the External signing for this participant |
Role | string | false | none | Role of the user who initiated the External signing for this participant |
TermsAndConditionsDetail | TermsAndConditionsDetail | false | none | TnC details Parent |
TermsAndConditionsDetail
{
"TermsAndConditionsItem": {
"TnCId": 0,
"Version": 0,
"Name": "string",
"Type": "string",
"Content": "string",
"Status": "Active",
"ExternalSigningService": {
"ExternalSigningServiceName": "DocuSign",
"ExternalSigningServiceSignerTemplateConfig": {
"TemplateIdSigner1": "string",
"TemplateIdSigner2": "string",
"TemplateIdSigner3": "string",
"TemplateIdSigner4": "string",
"TemplateIdSigner5": "string",
"TemplateIdSigner6": "string"
},
"ExternalSigningServiceSubject": "string"
}
},
"InititatedDate": "string",
"ExternalSigningServiceEnvelopeId": "string",
"ExternalSigningServiceEnvelopeStatus": "Completed",
"ExternalSigningServiceEnvelopePasscode": "string"
}
TnC details Parent
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
TermsAndConditionsItem | TermsAndConditionsItem | false | none | none |
InititatedDate | string | false | none | Terms and Conditions initiated date |
ExternalSigningServiceEnvelopeId | ExternalSigningServiceEnvelopeId | false | none | The envelope id of the ess signing request |
ExternalSigningServiceEnvelopeStatus | ExternalSigningServiceEnvelopeStatus | false | none | none |
ExternalSigningServiceEnvelopePasscode | string | false | none | Access code for the specifier to fill in the signer details. This will be populated only once, when signing is initiated |
ExternalSigningServiceEnvelopeStatus
"Completed"
Properties
None
OrganisationSnapshotPage
{
"totalPages": 0,
"totalSize": 0,
"pageable": {
"number": 0,
"sort": {
"sorted": true,
"orderBy": [
{
"property": "createdAt",
"direction": "ASC",
"ignoreCase": true,
"ascending": true
}
]
},
"size": 0,
"offset": 0,
"sorted": true
},
"numberOfElements": 0,
"size": 0,
"content": [
{
"OrganisationDetails": {
"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",
"RequiresSigning": true,
"TnCUpdated": true,
"TnCsToBeSigned": [
{
"TnCId": 0,
"Version": 0,
"Name": "string",
"Type": "string",
"Content": "string",
"Status": "Active",
"ExternalSigningService": {
"ExternalSigningServiceName": "DocuSign",
"ExternalSigningServiceSignerTemplateConfig": {
"TemplateIdSigner1": "string",
"TemplateIdSigner2": "string",
"TemplateIdSigner3": "string",
"TemplateIdSigner4": "string",
"TemplateIdSigner5": "string",
"TemplateIdSigner6": "string"
},
"ExternalSigningServiceSubject": "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"
]
}
],
"SoftwareStatements": {
"property1": {
"SoftwareDetails": {
"Status": "Active",
"ClientId": "string",
"ClientName": "string",
"Description": "string",
"Environment": "string",
"OrganisationId": "string",
"SoftwareStatementId": "string",
"Mode": "Live",
"RtsClientCreated": true,
"OnBehalfOf": "string",
"PolicyUri": "string",
"ClientUri": "string",
"LogoUri": "http://example.com",
"RedirectUri": [
"http://example.com"
],
"TermsOfServiceUri": "http://example.com",
"Version": 0,
"Locked": true
},
"SoftwareAuthorityClaims": [
{
"SoftwareStatementId": "string",
"SoftwareAuthorityClaimId": "string",
"Status": "Active",
"AuthorisationDomain": "string",
"Role": "string"
}
],
"SoftwareCertificates": [
{
"OrganisationId": "string",
"SoftwareStatementIds": [
"string"
],
"ClientName": "string",
"Status": "string",
"ValidFromDateTime": "string",
"ExpiryDateTime": "string",
"e": "string",
"keyType": "string",
"kid": "string",
"kty": "string",
"n": "string",
"use": "string",
"x5c": [
"string"
],
"x5t": "string",
"x5thashS256": "string",
"x5u": "string",
"SignedCertPath": "string",
"JwkPath": "string",
"OrgJwkPath": "string"
}
]
},
"property2": {
"SoftwareDetails": {
"Status": "Active",
"ClientId": "string",
"ClientName": "string",
"Description": "string",
"Environment": "string",
"OrganisationId": "string",
"SoftwareStatementId": "string",
"Mode": "Live",
"RtsClientCreated": true,
"OnBehalfOf": "string",
"PolicyUri": "string",
"ClientUri": "string",
"LogoUri": "http://example.com",
"RedirectUri": [
"http://example.com"
],
"TermsOfServiceUri": "http://example.com",
"Version": 0,
"Locked": true
},
"SoftwareAuthorityClaims": [
{
"SoftwareStatementId": "string",
"SoftwareAuthorityClaimId": "string",
"Status": "Active",
"AuthorisationDomain": "string",
"Role": "string"
}
],
"SoftwareCertificates": [
{
"OrganisationId": "string",
"SoftwareStatementIds": [
"string"
],
"ClientName": "string",
"Status": "string",
"ValidFromDateTime": "string",
"ExpiryDateTime": "string",
"e": "string",
"keyType": "string",
"kid": "string",
"kty": "string",
"n": "string",
"use": "string",
"x5c": [
"string"
],
"x5t": "string",
"x5thashS256": "string",
"x5u": "string",
"SignedCertPath": "string",
"JwkPath": "string",
"OrgJwkPath": "string"
}
]
}
}
}
],
"offset": 0,
"empty": true,
"pageNumber": 0
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
totalPages | integer | false | none | none |
totalSize | integer | false | none | none |
pageable | Pageable | false | none | none |
numberOfElements | integer | false | none | none |
size | integer | false | none | none |
content | [OrganisationSnapshot] | false | none | none |
offset | integer | false | none | none |
empty | boolean | false | none | none |
pageNumber | integer | false | none | none |
Pageable
{
"number": 0,
"sort": {
"sorted": true,
"orderBy": [
{
"property": "createdAt",
"direction": "ASC",
"ignoreCase": true,
"ascending": true
}
]
},
"size": 0,
"offset": 0,
"sorted": true
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
number | integer | false | none | Page number |
sort | Sort | false | none | none |
size | integer | false | none | Size of the page |
offset | integer | false | none | Offset |
sorted | boolean | false | none | Is the page sorted |
Sort
{
"sorted": true,
"orderBy": [
{
"property": "createdAt",
"direction": "ASC",
"ignoreCase": true,
"ascending": true
}
]
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
sorted | boolean | false | none | none |
orderBy | [object] | false | none | none |
» property | string | false | none | Name of the property used for sorting |
» direction | string | false | none | Direction of sort, i.e. ascending or descending |
» ignoreCase | boolean | false | none | Was the case ignored |
» ascending | boolean | false | none | Whether ascending |
Enumerated Values
Property | Value |
---|---|
direction | ASC |
direction | DESC |
OrganisationsSnapshot
{
"property1": {
"OrganisationDetails": {
"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",
"RequiresSigning": true,
"TnCUpdated": true,
"TnCsToBeSigned": [
{
"TnCId": 0,
"Version": 0,
"Name": "string",
"Type": "string",
"Content": "string",
"Status": "Active",
"ExternalSigningService": {
"ExternalSigningServiceName": "DocuSign",
"ExternalSigningServiceSignerTemplateConfig": {
"TemplateIdSigner1": "string",
"TemplateIdSigner2": "string",
"TemplateIdSigner3": "string",
"TemplateIdSigner4": "string",
"TemplateIdSigner5": "string",
"TemplateIdSigner6": "string"
},
"ExternalSigningServiceSubject": "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"
]
}
],
"SoftwareStatements": {
"property1": {
"SoftwareDetails": {
"Status": "Active",
"ClientId": "string",
"ClientName": "string",
"Description": "string",
"Environment": "string",
"OrganisationId": "string",
"SoftwareStatementId": "string",
"Mode": "Live",
"RtsClientCreated": true,
"OnBehalfOf": "string",
"PolicyUri": "string",
"ClientUri": "string",
"LogoUri": "http://example.com",
"RedirectUri": [
"http://example.com"
],
"TermsOfServiceUri": "http://example.com",
"Version": 0,
"Locked": true
},
"SoftwareAuthorityClaims": [
{
"SoftwareStatementId": "string",
"SoftwareAuthorityClaimId": "string",
"Status": "Active",
"AuthorisationDomain": "string",
"Role": "string"
}
],
"SoftwareCertificates": [
{
"OrganisationId": "string",
"SoftwareStatementIds": [
"string"
],
"ClientName": "string",
"Status": "string",
"ValidFromDateTime": "string",
"ExpiryDateTime": "string",
"e": "string",
"keyType": "string",
"kid": "string",
"kty": "string",
"n": "string",
"use": "string",
"x5c": [
"string"
],
"x5t": "string",
"x5thashS256": "string",
"x5u": "string",
"SignedCertPath": "string",
"JwkPath": "string",
"OrgJwkPath": "string"
}
]
},
"property2": {
"SoftwareDetails": {
"Status": "Active",
"ClientId": "string",
"ClientName": "string",
"Description": "string",
"Environment": "string",
"OrganisationId": "string",
"SoftwareStatementId": "string",
"Mode": "Live",
"RtsClientCreated": true,
"OnBehalfOf": "string",
"PolicyUri": "string",
"ClientUri": "string",
"LogoUri": "http://example.com",
"RedirectUri": [
"http://example.com"
],
"TermsOfServiceUri": "http://example.com",
"Version": 0,
"Locked": true
},
"SoftwareAuthorityClaims": [
{
"SoftwareStatementId": "string",
"SoftwareAuthorityClaimId": "string",
"Status": "Active",
"AuthorisationDomain": "string",
"Role": "string"
}
],
"SoftwareCertificates": [
{
"OrganisationId": "string",
"SoftwareStatementIds": [
"string"
],
"ClientName": "string",
"Status": "string",
"ValidFromDateTime": "string",
"ExpiryDateTime": "string",
"e": "string",
"keyType": "string",
"kid": "string",
"kty": "string",
"n": "string",
"use": "string",
"x5c": [
"string"
],
"x5t": "string",
"x5thashS256": "string",
"x5u": "string",
"SignedCertPath": "string",
"JwkPath": "string",
"OrgJwkPath": "string"
}
]
}
}
},
"property2": {
"OrganisationDetails": {
"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",
"RequiresSigning": true,
"TnCUpdated": true,
"TnCsToBeSigned": [
{
"TnCId": 0,
"Version": 0,
"Name": "string",
"Type": "string",
"Content": "string",
"Status": "Active",
"ExternalSigningService": {
"ExternalSigningServiceName": "DocuSign",
"ExternalSigningServiceSignerTemplateConfig": {
"TemplateIdSigner1": "string",
"TemplateIdSigner2": "string",
"TemplateIdSigner3": "string",
"TemplateIdSigner4": "string",
"TemplateIdSigner5": "string",
"TemplateIdSigner6": "string"
},
"ExternalSigningServiceSubject": "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"
]
}
],
"SoftwareStatements": {
"property1": {
"SoftwareDetails": {
"Status": "Active",
"ClientId": "string",
"ClientName": "string",
"Description": "string",
"Environment": "string",
"OrganisationId": "string",
"SoftwareStatementId": "string",
"Mode": "Live",
"RtsClientCreated": true,
"OnBehalfOf": "string",
"PolicyUri": "string",
"ClientUri": "string",
"LogoUri": "http://example.com",
"RedirectUri": [
"http://example.com"
],
"TermsOfServiceUri": "http://example.com",
"Version": 0,
"Locked": true
},
"SoftwareAuthorityClaims": [
{
"SoftwareStatementId": "string",
"SoftwareAuthorityClaimId": "string",
"Status": "Active",
"AuthorisationDomain": "string",
"Role": "string"
}
],
"SoftwareCertificates": [
{
"OrganisationId": "string",
"SoftwareStatementIds": [
"string"
],
"ClientName": "string",
"Status": "string",
"ValidFromDateTime": "string",
"ExpiryDateTime": "string",
"e": "string",
"keyType": "string",
"kid": "string",
"kty": "string",
"n": "string",
"use": "string",
"x5c": [
"string"
],
"x5t": "string",
"x5thashS256": "string",
"x5u": "string",
"SignedCertPath": "string",
"JwkPath": "string",
"OrgJwkPath": "string"
}
]
},
"property2": {
"SoftwareDetails": {
"Status": "Active",
"ClientId": "string",
"ClientName": "string",
"Description": "string",
"Environment": "string",
"OrganisationId": "string",
"SoftwareStatementId": "string",
"Mode": "Live",
"RtsClientCreated": true,
"OnBehalfOf": "string",
"PolicyUri": "string",
"ClientUri": "string",
"LogoUri": "http://example.com",
"RedirectUri": [
"http://example.com"
],
"TermsOfServiceUri": "http://example.com",
"Version": 0,
"Locked": true
},
"SoftwareAuthorityClaims": [
{
"SoftwareStatementId": "string",
"SoftwareAuthorityClaimId": "string",
"Status": "Active",
"AuthorisationDomain": "string",
"Role": "string"
}
],
"SoftwareCertificates": [
{
"OrganisationId": "string",
"SoftwareStatementIds": [
"string"
],
"ClientName": "string",
"Status": "string",
"ValidFromDateTime": "string",
"ExpiryDateTime": "string",
"e": "string",
"keyType": "string",
"kid": "string",
"kty": "string",
"n": "string",
"use": "string",
"x5c": [
"string"
],
"x5t": "string",
"x5thashS256": "string",
"x5u": "string",
"SignedCertPath": "string",
"JwkPath": "string",
"OrgJwkPath": "string"
}
]
}
}
}
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
additionalProperties | OrganisationSnapshot | false | none | none |
OrganisationSnapshot
{
"OrganisationDetails": {
"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",
"RequiresSigning": true,
"TnCUpdated": true,
"TnCsToBeSigned": [
{
"TnCId": 0,
"Version": 0,
"Name": "string",
"Type": "string",
"Content": "string",
"Status": "Active",
"ExternalSigningService": {
"ExternalSigningServiceName": "DocuSign",
"ExternalSigningServiceSignerTemplateConfig": {
"TemplateIdSigner1": "string",
"TemplateIdSigner2": "string",
"TemplateIdSigner3": "string",
"TemplateIdSigner4": "string",
"TemplateIdSigner5": "string",
"TemplateIdSigner6": "string"
},
"ExternalSigningServiceSubject": "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"
]
}
],
"SoftwareStatements": {
"property1": {
"SoftwareDetails": {
"Status": "Active",
"ClientId": "string",
"ClientName": "string",
"Description": "string",
"Environment": "string",
"OrganisationId": "string",
"SoftwareStatementId": "string",
"Mode": "Live",
"RtsClientCreated": true,
"OnBehalfOf": "string",
"PolicyUri": "string",
"ClientUri": "string",
"LogoUri": "http://example.com",
"RedirectUri": [
"http://example.com"
],
"TermsOfServiceUri": "http://example.com",
"Version": 0,
"Locked": true
},
"SoftwareAuthorityClaims": [
{
"SoftwareStatementId": "string",
"SoftwareAuthorityClaimId": "string",
"Status": "Active",
"AuthorisationDomain": "string",
"Role": "string"
}
],
"SoftwareCertificates": [
{
"OrganisationId": "string",
"SoftwareStatementIds": [
"string"
],
"ClientName": "string",
"Status": "string",
"ValidFromDateTime": "string",
"ExpiryDateTime": "string",
"e": "string",
"keyType": "string",
"kid": "string",
"kty": "string",
"n": "string",
"use": "string",
"x5c": [
"string"
],
"x5t": "string",
"x5thashS256": "string",
"x5u": "string",
"SignedCertPath": "string",
"JwkPath": "string",
"OrgJwkPath": "string"
}
]
},
"property2": {
"SoftwareDetails": {
"Status": "Active",
"ClientId": "string",
"ClientName": "string",
"Description": "string",
"Environment": "string",
"OrganisationId": "string",
"SoftwareStatementId": "string",
"Mode": "Live",
"RtsClientCreated": true,
"OnBehalfOf": "string",
"PolicyUri": "string",
"ClientUri": "string",
"LogoUri": "http://example.com",
"RedirectUri": [
"http://example.com"
],
"TermsOfServiceUri": "http://example.com",
"Version": 0,
"Locked": true
},
"SoftwareAuthorityClaims": [
{
"SoftwareStatementId": "string",
"SoftwareAuthorityClaimId": "string",
"Status": "Active",
"AuthorisationDomain": "string",
"Role": "string"
}
],
"SoftwareCertificates": [
{
"OrganisationId": "string",
"SoftwareStatementIds": [
"string"
],
"ClientName": "string",
"Status": "string",
"ValidFromDateTime": "string",
"ExpiryDateTime": "string",
"e": "string",
"keyType": "string",
"kid": "string",
"kty": "string",
"n": "string",
"use": "string",
"x5c": [
"string"
],
"x5t": "string",
"x5thashS256": "string",
"x5u": "string",
"SignedCertPath": "string",
"JwkPath": "string",
"OrgJwkPath": "string"
}
]
}
}
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
OrganisationDetails | Organisation | false | none | none |
Contacts | Contacts | false | none | The list of contacts |
AuthorisationServers | AuthorisationServers | false | none | none |
OrgDomainClaims | OrganisationAuthorityDomainClaims | false | none | none |
OrgDomainRoleClaims | OrganisationAuthorityClaims | false | none | none |
SoftwareStatements | object | false | none | none |
» additionalProperties | object | false | none | none |
»» SoftwareDetails | SoftwareStatement | false | none | none |
»» SoftwareAuthorityClaims | SoftwareAuthorityClaims | false | none | none |
»» SoftwareCertificates | CertificatesOrKeys | false | none | none |
OrganisationsExportOpenData
[
{
"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"
]
}
]
}
]
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | [OrganisationExportOpenData] | false | none | none |
OrganisationExportOpenData
{
"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"
]
}
]
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
OrganisationId | OrganisationId | false | none | Unique ID associated with the organisation |
Status | string | false | none | Status of the directory registration of an organisation |
OrganisationName | string | false | none | Name of the organisation. |
CreatedOn | string | false | none | JSONDatetime of organisation creation. |
LegalEntityName | string | false | none | Legal Entity name for the org. Usually the same as org name |
CountryOfRegistration | string | false | none | Country of registration for the org |
CompanyRegister | string | false | none | Legal company register for the country, i.e. Companies House |
RegistrationNumber | string | false | none | Company registration number from company register i.e. Companies House registration number |
RegistrationId | string | false | none | Registered ID for the organisation i.e. Legal Entity identifier number |
RegisteredName | string | false | none | none |
AddressLine1 | string | false | none | Address line 1 |
AddressLine2 | string | false | none | Address line 2 |
City | string | false | none | City |
Postcode | string | false | none | Postcode |
Country | string | false | none | Country |
ParentOrganisationReference | string | false | none | Parent Organisation Reference |
Contacts | Contacts | false | none | The list of contacts |
AuthorisationServers | AuthorisationServers | false | none | none |
OrgDomainClaims | OrganisationAuthorityDomainClaims | false | none | none |
OrgDomainRoleClaims | OrganisationAuthorityClaims | false | none | none |
Enumerated Values
Property | Value |
---|---|
Status | Active |
Status | Pending |
Status | Withdrawn |
Authorities
[
{
"AuthorityId": "string",
"AuthorityName": "string",
"AuthorityCode": "string",
"AuthorityUri": "string",
"AuthorityCountry": "string",
"Status": "Active"
}
]
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | [Authority] | false | none | none |
Authority
{
"AuthorityId": "string",
"AuthorityName": "string",
"AuthorityCode": "string",
"AuthorityUri": "string",
"AuthorityCountry": "string",
"Status": "Active"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
AuthorityId | AuthorityId | false | none | Unique ID associated with the Authorisation reference schema |
AuthorityName | string | false | none | Name of the Authority i.e. FCA, etc |
AuthorityCode | string | false | none | Code of the Authority i.e. FCA, etc |
AuthorityUri | string | false | none | URI of the authority |
AuthorityCountry | string | false | none | country of the Authority |
Status | string | false | none | Is this Authority Active/Inactive |
Enumerated Values
Property | Value |
---|---|
Status | Active |
Status | Inactive |
AuthorityRequest
{
"AuthorityName": "string",
"AuthorityCode": "string",
"AuthorityUri": "string",
"AuthorityCountry": "string"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
AuthorityName | string | true | none | The ID of the Authority i.e GBFCA, etc |
AuthorityCode | string | true | none | Code of the Authority i.e. GBFCA, etc |
AuthorityUri | string | true | none | URI of the authority |
AuthorityCountry | string | true | none | Country of the authority |
SoftwareStatementCertificateOrKeyType
"rtstransport"
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | none |
Enumerated Values
Property | Value |
---|---|
anonymous | rtstransport |
anonymous | rtssigning |
anonymous | sigkey |
anonymous | enckey |
SoftwareStatements
[
{
"Status": "Active",
"ClientId": "string",
"ClientName": "string",
"Description": "string",
"Environment": "string",
"OrganisationId": "string",
"SoftwareStatementId": "string",
"Mode": "Live",
"RtsClientCreated": true,
"OnBehalfOf": "string",
"PolicyUri": "string",
"ClientUri": "string",
"LogoUri": "http://example.com",
"RedirectUri": [
"http://example.com"
],
"TermsOfServiceUri": "http://example.com",
"Version": 0,
"Locked": true
}
]
The list of Software Statements
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | [SoftwareStatement] | false | none | The list of Software Statements |
SoftwareStatement
{
"Status": "Active",
"ClientId": "string",
"ClientName": "string",
"Description": "string",
"Environment": "string",
"OrganisationId": "string",
"SoftwareStatementId": "string",
"Mode": "Live",
"RtsClientCreated": true,
"OnBehalfOf": "string",
"PolicyUri": "string",
"ClientUri": "string",
"LogoUri": "http://example.com",
"RedirectUri": [
"http://example.com"
],
"TermsOfServiceUri": "http://example.com",
"Version": 0,
"Locked": true
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
Status | string | false | none | Is this software statement Active/Inactive |
ClientId | string | false | none | Software Statement client Id |
ClientName | string | false | none | Software Statement client name |
Description | string | false | none | Software Statement description |
Environment | string | false | none | The additional check for software statement, this field can avoid |
OrganisationId | OrganisationId | false | none | Unique ID associated with the organisation |
SoftwareStatementId | SoftwareStatementId | false | none | Unique Software Statement Id |
Mode | string | false | none | Software Statement mode |
RtsClientCreated | boolean | false | none | Client created flag |
OnBehalfOf | string | false | none | A reference to fourth party organisation resource on the RTS Directory if the registering Org is acting on behalf of another |
PolicyUri | string | false | none | The Software Statement policy compliant URI |
ClientUri | string | false | none | The Software Statement client compliant URI |
LogoUri | string(uri) | false | none | The Software Statement logo compliant URI |
RedirectUri | [string] | false | none | The Software Statement redirect compliant URI |
TermsOfServiceUri | string(uri) | false | none | The Software Statement terms of service compliant URI |
Version | number | false | none | Software Statement version as provided by the organisation's PTC |
Locked | boolean | false | none | Flag shows if assertion has been generated on the software statement - will be set to true when assertion is generated |
Enumerated Values
Property | Value |
---|---|
Status | Active |
Status | Inactive |
Mode | Live |
Mode | Test |
SoftwareStatementRequest
{
"ClientName": "string",
"Description": "string",
"OnBehalfOf": "string",
"PolicyUri": "string",
"ClientUri": "string",
"LogoUri": "string",
"Environment": "string",
"Mode": "Live",
"RedirectUri": [
"string"
],
"TermsOfServiceUri": "string",
"Version": 1
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
ClientName | string | true | none | Software Statement client name |
Description | string | false | none | Software Statement description |
OnBehalfOf | string | false | none | A reference to fourth party organisation resource on the RTS Directory if the registering Org is acting on behalf of another |
PolicyUri | string | true | none | The Software Statement compliant policy URI |
ClientUri | string | true | none | The Software Statement compliant client URI |
LogoUri | string | true | none | The Software Statement compliant logo URI |
Environment | string | false | none | The additional check for software statement, this field can avoid environment checks. |
Mode | string | false | none | The additional check to see if the environment reflected above is live or test. |
RedirectUri | [string] | true | none | The Software Statement redirect URIs |
TermsOfServiceUri | string | true | none | The Software Statement terms of service compliant URI |
Version | number | true | none | Software Statement version as provided by the organisation's PTC |
Enumerated Values
Property | Value |
---|---|
Mode | Live |
Mode | Test |
SoftwareStatementId
"string"
Unique Software Statement Id
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | Unique Software Statement Id |
SoftwareStatementAssertion
"string"
A signed JWT (JWS)
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | A signed JWT (JWS) |
SoftwareAuthorityClaims
[
{
"SoftwareStatementId": "string",
"SoftwareAuthorityClaimId": "string",
"Status": "Active",
"AuthorisationDomain": "string",
"Role": "string"
}
]
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | [SoftwareAuthorityClaim] | false | none | none |
SoftwareAuthorityClaim
{
"SoftwareStatementId": "string",
"SoftwareAuthorityClaimId": "string",
"Status": "Active",
"AuthorisationDomain": "string",
"Role": "string"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
SoftwareStatementId | SoftwareStatementId | false | none | Unique Software Statement Id |
SoftwareAuthorityClaimId | SoftwareAuthorityClaimId | false | none | Unique ID associated with the authority claims for a software statement |
Status | string | false | none | Is this authority claim Active/Inactive |
AuthorisationDomain | string | false | none | Authorisation domain for the authority |
Role | string | false | none | Roles for the Authority i.e. ASPSP, AISP, PISP, CBPII |
Enumerated Values
Property | Value |
---|---|
Status | Active |
Status | Inactive |
SoftwareAuthorityClaimRequest
{
"Status": "Active",
"AuthorisationDomain": "string",
"Role": "string"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
Status | string | true | none | Is this authority claim Active/Inactive, default is active |
AuthorisationDomain | string | true | none | Authorisation domain for the authority |
Role | string | true | none | Roles for the Authority i.e. ASPSP, AISP, PISP, CBPII |
Enumerated Values
Property | Value |
---|---|
Status | Active |
Status | Inactive |
SoftwareAuthorityClaimUpdateRequest
{
"Status": "Active"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
Status | string | true | none | This is used to set the status - Active/Inactive |
Enumerated Values
Property | Value |
---|---|
Status | Active |
Status | Inactive |
ClientCreationRequest
{
"id_token_signed_response_alg": "PS256",
"token_endpoint_auth_method": "private_key_jwt",
"jwks_uri": "string",
"tls_client_auth_subject_dn": "string",
"redirect_uris": [
"string"
],
"response_types": [
"string"
],
"grant_types": [
"string"
],
"scope": "string"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
id_token_signed_response_alg | string | true | none | Signing algorithim that a client expects the server to return an id_token with. Must be PS256 |
token_endpoint_auth_method | string | true | none | Token endpoint authentication method |
jwks_uri | string | true | none | Link to the application active jwks |
tls_client_auth_subject_dn | string | false | none | The DN of the certificate that will be used to authenticate to this client |
redirect_uris | [string] | true | none | redirect_uris uri must be provided. For client_credentials this should be an empty array. |
response_types | [string] | true | none | response_types uri must be provided. For client_credentials this should be an empty array |
grant_types | [string] | true | none | grant_types uri must be provided. For client_credentials this should be array containing ["client_credentials"] |
scope | string | true | none | scopes to be tagged |
Enumerated Values
Property | Value |
---|---|
id_token_signed_response_alg | PS256 |
token_endpoint_auth_method | private_key_jwt |
token_endpoint_auth_method | tls_client_auth |
token_endpoint_auth_method | client_secret_basic |
ClientCreationResponse
{
"application_type": "web",
"tls_client_auth_subject_dn": "string",
"grant_types": [
"string"
],
"id_token_signed_response_alg": "string",
"require_auth_time": true,
"subject_type": "string",
"response_types": [
"string"
],
"post_logout_redirect_uris": [
"string"
],
"token_endpoint_auth_method": "string",
"introspection_endpoint_auth_method": "string",
"revocation_endpoint_auth_method": "string",
"client_id_issued_at": 0,
"client_id": "string",
"jwks_uri": "string",
"registration_client_uri": "string",
"registration_access_token": "string",
"redirect_uris": [
"string"
],
"request_uris": [
"string"
]
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
application_type | string | false | none | OIDC application type response |
tls_client_auth_subject_dn | string | false | none | the subject dn used to authenticate this client |
grant_types | [string] | false | none | grant_types |
id_token_signed_response_alg | string | false | none | none |
require_auth_time | boolean | false | none | none |
subject_type | string | false | none | none |
response_types | [string] | false | none | response_types |
post_logout_redirect_uris | [string] | false | none | post_logout_redirect_uris |
token_endpoint_auth_method | string | false | none | none |
introspection_endpoint_auth_method | string | false | none | none |
revocation_endpoint_auth_method | string | false | none | none |
client_id_issued_at | number | false | none | none |
client_id | string | false | none | none |
jwks_uri | string | false | none | none |
registration_client_uri | string | false | none | management uri location to manage client post creation |
registration_access_token | string | false | none | token used to manage client post creation |
redirect_uris | [string] | false | none | redirect_uris |
request_uris | [string] | false | none | request_uris |
Enumerated Values
Property | Value |
---|---|
application_type | web |
AccessTokenRequest
{
"grant_type": "client_credentials",
"client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
"assertion": "string"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
grant_type | string | true | none | The Grant Type |
client_assertion_type | string | true | none | Restrict to private_key_jwt |
assertion | string | true | none | The assertion that is used to get a token |
Enumerated Values
Property | Value |
---|---|
grant_type | client_credentials |
client_assertion_type | urn:ietf:params:oauth:client-assertion-type:jwt-bearer |
AccessTokenResponse
{
"access_token": "string",
"expires_in": 0,
"token_type": "string",
"scope": "string"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
access_token | string | false | none | Access token |
expires_in | integer | false | none | lifetime in seconds |
token_type | string | false | none | none |
scope | string | false | none | none |
UserEmailId
"string"
User email address
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | User email address |
SuperUserCreationRequest
{
"Email": "string"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
string | true | none | The super user email address |
SuperUsers
[
{
"Email": "string",
"Status": "Active"
}
]
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | [SuperUser] | false | none | none |
SuperUser
{
"Email": "string",
"Status": "Active"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
string | false | none | The super user email address | |
Status | string | false | none | Is this super user Active or Inactive |
Enumerated Values
Property | Value |
---|---|
Status | Active |
Status | Inactive |
AuthorisationDomainName
"string"
Authorisation Domain Name
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | Authorisation Domain Name |
AuthorisationDomainRoleName
"string"
Authorisation Domain Role Name
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | Authorisation Domain Role Name |
AuthorityAuthorisationDomainId
"string"
Mapping ID between Authority and Authorisation Domain
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | Mapping ID between Authority and Authorisation Domain |
AuthorisationDomainUserCreateRequest
{
"Email": "string",
"AuthorisationDomainRole": "string",
"ContactRole": "PTC"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
string | true | none | The user email address | |
AuthorisationDomainRole | string | true | none | The authorisation domain role for this user |
ContactRole | ContactRoleEnum | true | none | The role of the contact |
AuthorisationDomainUsers
[
{
"AuthorisationDomainUserId": "string",
"Email": "string",
"AuthorisationDomain": "string",
"AuthorisationDomainRole": "string",
"Status": "Active",
"ContactRole": "PTC"
}
]
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | [AuthorisationDomainUser] | false | none | none |
AuthorisationDomainUser
{
"AuthorisationDomainUserId": "string",
"Email": "string",
"AuthorisationDomain": "string",
"AuthorisationDomainRole": "string",
"Status": "Active",
"ContactRole": "PTC"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
AuthorisationDomainUserId | string | false | none | Unique record ID |
string | false | none | The user email address | |
AuthorisationDomain | string | false | none | The authorisation domain for this user |
AuthorisationDomainRole | string | false | none | The authorisation domain role for this user |
Status | string | false | none | Is this user Active or Inactive |
ContactRole | string | false | none | Type of role for this user |
Enumerated Values
Property | Value |
---|---|
Status | Active |
Status | Inactive |
ContactRole | PTC |
ContactRole | STC |
ContactRole | PBC |
ContactRole | SBC |
AuthorisationDomainRequest
{
"AuthorisationDomainName": "string",
"AuthorisationDomainRegion": "string",
"AuthorisationDomainDescription": "string"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
AuthorisationDomainName | string | true | none | The authorisation domain name |
AuthorisationDomainRegion | string | true | none | The authorisation domain region |
AuthorisationDomainDescription | string | false | none | The authorisation domain description |
AuthorisationDomains
[
{
"AuthorisationDomainName": "string",
"AuthorisationDomainRegion": "string",
"AuthorisationDomainDescription": "string",
"Status": "Active"
}
]
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | [AuthorisationDomain] | false | none | none |
AuthorisationDomain
{
"AuthorisationDomainName": "string",
"AuthorisationDomainRegion": "string",
"AuthorisationDomainDescription": "string",
"Status": "Active"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
AuthorisationDomainName | string | false | none | The authorisation domain name |
AuthorisationDomainRegion | string | false | none | The authorisation domain region |
AuthorisationDomainDescription | string | false | none | The authorisation domain description |
Status | string | false | none | Is this Domain Active or Inactive |
Enumerated Values
Property | Value |
---|---|
Status | Active |
Status | Inactive |
AuthorisationDomainRoleRequest
{
"AuthorisationDomainName": "string",
"AuthorisationDomainRoleName": "string",
"AuthorisationDomainRoleDescription": "string"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
AuthorisationDomainName | string | true | none | The authorisation domain name |
AuthorisationDomainRoleName | string | true | none | The authorisation domain role name |
AuthorisationDomainRoleDescription | string | false | none | The authorisation domain role description |
AuthorisationDomainRoles
[
{
"AuthorisationDomainName": "string",
"AuthorisationDomainRoleName": "string",
"AuthorisationDomainRoleDescription": "string",
"Status": "Active"
}
]
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | [AuthorisationDomainRole] | false | none | none |
AuthorisationDomainRole
{
"AuthorisationDomainName": "string",
"AuthorisationDomainRoleName": "string",
"AuthorisationDomainRoleDescription": "string",
"Status":