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":["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"],
  "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

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

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.