Requisitos e Recomendações para implementação do fluxo CIBA 

• O tempo de aceite / ação do Usuário Pagador sobre o pedido de Autorização recebido via CIBA deverá se manter o mesmo definido para o fluxo via Hybrid Flow, de 5 minutos.

• Recomenda-se que os Participantes Detentores de Conta desenvolvam o fluxo com a possibilidade de tipificar/identificar unicamente transações realizadas via CIBA ou Hybrid Flow, permitindo o monitoramento e reporte dessas transações.

...

Opção 1: Iniciação de pagamento usando um Token de Identificação (id_token) na Iniciadora

O fluxo apresentado a seguir é de um caso de uso prioritário para pagamentos consecutivos com a conta cadastrada na iniciadora que foi priorizado.

Neste fluxo, assume-se que o Participante Iniciador de Pagamentos já possui um id_token que identifica o usuário (id_token conforme definido em https://openid.net/specs/openid-connect-core-1_0.html#IDToken ). O id_token pode ser obtido através de uma Iniciação de Pagamento prévia, se houver sido retornado na resposta da chamada ao recurso /token, onde se obtém também os access_token e refresh_token para o pagamento.

Para facilitar a implementação deste fluxo, esta especificação RECOMENDA que os Participantes Detentores incluam um passo na jornada de Confirmação de Pagamento para solicitar ao Usuário Pagador a geração de um id_token que será compartilhado com o Iniciador. Este passo poderá exibir ao usuário uma experiência que remeta ao conceito de “salvar conta para transações futuras”.Open Finance Brasil oferece um serviço de iniciação de pagamento, que requer o consentimento do usuário para cada transação

Diretrizes para essa opção:

1. Iniciadores de pagamento e detentores de conta devem considerar o id_token, obtido no fluxo de FAPI Hybrid Flow como identificação de usuário e conta a ser utilizado em endpoint para recuperar token de autenticação do pagamento;

2. O id_token deverá ter no mínimo 180 dias de expiração;

3. Os iniciadores de pagamento deverão mostrar no fluxo de pagamento os dados do usuário e conta para ser selecionado, essa consulta poderá ser feita buscando os dados do endpoint de Consentimento de Pagamentos (GET /payments/v2/consents/{consentId}, dado /data/debtorAccount/number).

4.  Utilizar como base de experiência o guia de UX onde existirá um checkbox para “salvar conta para transações futuras” (link do guia de UX e figma);

5. O id_token deve ser utilizado na chamada de autorização através do parâmetro “id_token_hint”

...

Recomenda-se que o Participante Iniciador de Pagamentos exponha em sua interface uma identificação mascarada da conta utilizada na primeira transação, ao obter o id_token referente a essa conta. A identificação da conta pode ser obtida consultando o endpoint de Consentimento de Pagamentos (GET /payments/v2/consents/{consentId}, dado /data/debtorAccount/number).

Image Removed

Descrição do Diagrama de Sequência - Detalhamento do fluxo de Primeiro Pagamento com CIBA

Fluxo de BIND

Debtor (Usuário) inicia o processo de pagamento na iniciadora.

Na iniciadora, o debtor seleciona a detentora e os dados de pagamentos.
A iniciadora solicita ao usuário que informe o código de autorização de pagamento (padrão a definir) obtido na detentora.
O usuario deve ir até a detentora, realizar sua autenticação e fazer o fluxo de BIND do dispositivo, registrando um vinculo entre o dispositivo e a detentora de conta. Depois do BIND realizado com sucesso, a detentora emite um código e mostra na tela para o usuário.

O usuário volta para o ambiente da iniciadora e insere o código gerado. Nesse momento acontece o fluxo de autenticação MTLS, gerando o access_token e o atributo de consentimento.

*é importante ressaltar que o fluxo mencionado acima é premissa para que os próximos casos de uso sejam possíveis, pois por meio desse BIND é que registramos o dispositivo e salvamos o registro do usuário na Iniciadora. Ele só deve ser repetido em casos que o usuário mude de dispositivo ou detentora de conta.

Fluxo de Pagamentos com ID Token cadastrado na Iniciadora

Debtor (Usuário) inicia o processo de pagamento na iniciadora.

A iniciadora solicita ao usuário que informe o código de autorização de pagamento (padrão a definir) obtido na detentora.

O usuário volta para o ambiente da iniciadora e insere o código gerado. Nesse momento acontece o fluxo de autenticação MTLS, gerando o access_token e o atributo de consentimento.
Na requisicao de POST /bc-authorize/, adicionamos um campo que é o login_hint, com o OTP da detentora:
Exemplo:

Requisição

...

2. Apenas o “poll mode” será utilizado para obter token para o envio do pagamento via endpoint bc-authorize.

3. O cancelamento do id_token poderá ser realizado pela detentora de conta em casos de fraude ou por motivos de segurança.

Tabela de erros “HTTP 400 Bad Request”:

1. invalid_request: The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, contains more than one of the hints, or is otherwise malformed.

2. invalid_scope: The requested scope is invalid, unknown, or malformed.

3. expired_id_token_hint: The id_token hint provided in the authentication request is not valid because it has expired.

4. unknown_user_id: The OpenID Provider is not able to identify which end-user the Client wishes to be authenticated by means of the hint provided in the request (id_token_hint).

5. unauthorized_client: The Client is not authorized to use this authentication flow.

6. invalid_id_token_hint: The id_token is invalid and can’t be used in the flow

8. O cancelamento do id_token poderá ser realizado pela iniciadora de pagamentos em caso de fraude ou por motivos de segurança, através da remoção do id_token do cliente em sua base de dados. Com base nos protocolos FAPI e OIDF, apenas a remoção do id_token é suficiente para interromper o uso do fluxo CIBA, uma vez que,  após a remoção, a iniciadora de pagamentos não será capaz de referenciar o cliente.

9. Validação dos parâmetros do payload

10. Parâmetros para validação de assinatura

Todos os parâmetros devem estar presentes no cabeçalho (header) do JWT.

Passo a passo para salvar id_token:

1. Seguir fluxo descrito na página de Diagrama de Sequência 

2. Na etapa de recebimento do code no redirect (redirecionamento de volta da detentora para a iniciadora) a iniciadora deve salvar o id_token que também vem nos parâmetros da url de redirect.

3. Realizar o pagamento normalmente, pois apenas no próximo pagamento será possível realizar o fluxo sem redirecionamento CIBA

<<<<Replicar diagrama com ponto de atenção para salvar o id_token na etapa em que recebe o code, ver locallização abaixo >>>>

...

Passo a passo com o id_token salvo:

4. Criação do consentimento;

5. Resposta da criação do consentimento  com status awaiting_authorization

6. Chamada ao Backchannel Authentication Endpoint do CIBA para autorização do consentimento:

POST {BackchannelAuthenticationEndpoint} HTTP/1.1

 Host: {AuthorizationServer}

 Content-Type: application/x-www-form-urlencoded

...

scope=payment consent:[id_consent]&binding_message=<código_vinculo>
&client_notification_token=[8d67dc78-7faa-4d41-aabd-67707b374255]&login_hint=[OTP]

...

 scope=openid consent:urn:bancoex:C1DD33123&

 id_token_hint=eyJhbGciOiJSUzI1NiIsImtpZCI6IjE2Nzcy

    NiJ9.eyJpc3MiOiJodHRwczovL3NlcnZlci5leGFtcGxlLmNvbSI

    sInN1YiI6IjI0ODI4OTc2MTAwMSIsImF1ZCI6InM2QmhkUmtxdDM

    iLCJlbWFpbCI6ImphbmVkb2VAZXhhbXBsZS5jb20iLCJleHAiOjE

    1Mzc4MTk4MDMsImlhdCI6MTUzNzgxOTUwM30.aVq83mdy72ddIFV

    JLjlNBX-5JHbjmwK-Sn9Mir-blesfYMceIOw6u4GOrO_ZroDnnbJ

    XNKWAg_dxVynvMHnk3uJc46feaRIL4zfHf6Anbf5_TbgMaVO8icz

    D16A5gNjSD7yenT5fslrrW-NU_vtmi0s1puoM4EmSaPXCR19vRJy

    WuStJiRHK5yc3BtBlQ2xwxH1iNP49rGAQe_LHfW1G74NY5DaPv-V

    23JXDNEIUTY-jT-NbbtNHAxnhNPyn8kcO2WOoeIwANO9BfLF1EFW

    tjGPPMj6kDVrikec47yK86HArGvsIIwk1uExynJIv_tgZGE0eZI7

    MtVb2UlCwDQrVlg&

7. Os campos devem ser codificados para url (URL Encoded). No exemplo foi deixado como plain text para facilitar o entendimento.
   O BackchannelAuthenticationEndpoint deve ser encontrado no .well-known da detentora.
   A iniciadora deve enviar o id do consentimento no campo scope junto com o scope openid

A detentora deverá validar o id_token de acordo com as tabelas referenciadas acima dos itens 9 e 10.

8. Resposta do Backchannel Authentication Endpoint

HTTP/1.1 200 OK

...

 Content-Type: application/json

...

 Cache-Control: no-store

 {

   "auth_req_id":

...

 "1c266114-a1be-4252-8ad1-04986c5b9ac1",

   "expires_in":

...

  120,

   "interval":    2

 }

• auth_req_id: identificador da requisição de autenticação;

• expires_in: tempo de expiração do auth_req_id em segundos, tempo máximo que a iniciadora poderá fazer o polling do /token;

• interval: intervalo mínimo do polling no /token que deve ser maior que 2 segundo;

Nesse momento poderá ocorrer os erros descritos no item 7 das diretrizes descritos acima. 

9. Ao receber a chamada do Backchannel Authentication Endpoint, a detentora deve informar o usuário sobre a solicitação de pagamento, utilizando o canal desacoplado (SMS, push notification, etc) de sua escolha para autenticar o cliente de acordo com suas políticas e autorizar o pagamento.

10. Com o pagamento reconhecido pelo usuário a detentora muda o status do consentimento para authorized.

11. Em posse do auth_req_id a iniciadora deve chamar o endpoint /token em um intervalo de tempo determinado pelo campo interval da resposta da chamada do Backchannel Authentication Endpoint para receber o access_token , id_token e o refresh_token do consentimento autorizado até um tempo limite determinado pelo campo expires_in da resposta. Esse é o modo poll da documentação CIBA listado acima. 

POST {TokenEndpoint} HTTP/1.1

Host: {AuthorizationServer}

Content-Type: application/x-www-form-urlencoded

grant_type=urn:openid:params:grant-type:ciba&      // Mandatory

auth_req_id=1c266114-a1be-4252-8ad1-04986c5b9ac1   // Mandatory

• Os campos devem ser codificado para url (URL Encoded). No exemplo foi deixado como plaintext para facilitar o entendimento.

• grant_type: deve ser urn:openid:params:grant-type:ciba

• auth_req_id: identificador da requisição de autenticação recebido na resposta da chamada do Backchannel Authentication Endpoint

12. Enquanto a solicitação de pagamento não for autorizada pelo cliente, ou automaticamente no caso de uma solicitação subsequente já consentida pelo cliente, a detentora deve retornar uma resposta de erro com statusCode 403, E uma vez autorizada a solicitação de pagamento a detentora deve retornar uma resposta de sucesso com statusCode 200.

 Exemplo de resposta de sucesso conforme CIBA.Core1 10.1.1:

HTTP/1.1 200 OK

Content-Type: application/json

Cache-Contro: no-store

{

  "access_token":  "9f312798-11e7-4e87-a143-b83bd1c2026f",

  "token_type":    "Bearer",

  "refresh_token": "c410670a-5cb9-4bef-aa0d-d5c30e3d33a3",

  "expires_in":    120,

  "id_token":      "eyJhbGciOiJSUzI1NiIsImtpZCI6IjE2Nzcy

    NiJ9.eyJpc3MiOiJodHRwczovL3NlcnZlci5leGFtcGxlLmNvbSI

    sInN1YiI6IjI0ODI4OTc2MTAwMSIsImF1ZCI6InM2QmhkUmtxdDM

    iLCJlbWFpbCI6ImphbmVkb2VAZXhhbXBsZS5jb20iLCJleHAiOjE

    1Mzc4MTk4MDMsImlhdCI6MTUzNzgxOTUwM30.aVq83mdy72ddIFV

    JLjlNBX-5JHbjmwK-Sn9Mir-blesfYMceIOw6u4GOrO_ZroDnnbJ

    XNKWAg_dxVynvMHnk3uJc46feaRIL4zfHf6Anbf5_TbgMaVO8icz

    D16A5gNjSD7yenT5fslrrW-NU_vtmi0s1puoM4EmSaPXCR19vRJy

    WuStJiRHK5yc3BtBlQ2xwxH1iNP49rGAQe_LHfW1G74NY5DaPv-V

    23JXDNEIUTY-jT-NbbtNHAxnhNPyn8kcO2WOoeIwANO9BfLF1EFW

    tjGPPMj6kDVrikec47yK86HArGvsIIwk1uExynJIv_tgZGE0eZI7

    MtVb2UlCwDQrVlg"

}

13. Exemplo de resposta de erro conforme CIBA.Core1 11:

HTTP/1.1 403 Forbidden

Content-Type: application/json

{

  "error": "authorization_pending",

  "error_description":

    "The user has not yet been authenticated, and the authorization request is still pending."

}

Possíveis erros:

14. Iniciação de pagamento pela iniciadora. Uma vez que a iniciadora recebeu o token e refresh_token do consentimento o fluxo segue igualmente feito no hybrid flow.

15. A detentora ao receber a iniciação de pagamento e responder com status code igual a 201 ou 422 o consentimento deve ser consumido.

16. A detentora responde a iniciação de pagamento como no Hybrid flow.

17. A iniciadora consulta o status do pagamento com polling na rota de consulta como no Hybrid flow.

18. A detentora responde com o status do pagamento atualizado como no Hybrid flow.

Diagrama de sequência com o id_token salvo:

<<<<Replicar o diagrama da etapa de salvar o token com as mudanças de chamadas descritas acima.>>>>