Índice |
---|
Introdução
O Fluxo CIBA (Client-Initiated Backchannel Authentication) é uma alternativa ao Hybrid Flow, que traz a possibilidade de autenticação do usuário pagador no ambiente da Detentora de Conta em um dispositivo desacoplado, sem a necessidade de um redirect para Browser ou App no mesmo dispositivo onde a transação foi iniciada.
O fluxo CIBA está descrito em três documentos técnicos que se complementam mutuamente, e fazem referências a outras especificações. Recomenda-se a consulta na seguinte ordem:
OpenID Connect Client-Initiated Backchannel Authentication Flow - Core 1.0 - https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html - Esta é a principal especificação do fluxo CIBA divulgada pela OpenID Foundation, contendo detalhes de implementação, requisitos e recomendações, e referências a outras especificações basais.
Financial-grade API: Client Initiated Backchannel Authentication Profile - https://openid.net/specs/openid-financial-api-ciba-ID1.html - Este é o perfil de regras e recomendações de autenticação e segurança proposto pela OpenID Foundation para implementações genéricas do fluxo CIBA.
Open Finance Brasil Financial-grade API CIBA Security Profile 1.0 - https://github.com/OpenBanking-Brasil/specs-seguranca/blob/main/open-banking-brasil-financial-api-CIBA-1_ID1.md - Este é o perfil de regras e recomendações de autenticação e segurança proposto pela Squad CIBA do Open Finance Brasil para implementação do fluxo CIBA para Iniciação de Pagamentos no cenário brasileiro.
As especificações acima permitem a implementação de três casos de uso, por sua vez descritos em mais detalhes no Manual de Experiência do Usuário, e explorados nas próximas seções deste manual de um ponto de vista de implementação técnica e integração.
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.
Fluxo - 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”.
O id_token deve ser utilizado na chamada de autorização através do parâmetro “id_token_hint” (conforme https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#rfc.section.7.1 )
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).
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
POST /bc-authorize
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]
Reposta esperada
HTTP/1.1 200 OK
Content-type: application/json
{
"auth_req_id": "1231243123123423",
"expires_in": "360",
"interval":"2"
}
...
Índice |
---|
Opção 1: Iniciação de pagamento usando um Token de Identificação (id_token) na Iniciadora
O serviço de Iniciação de Pagamentos do Open Finance Brasil implementa o fluxo de consentimento com redirecionamento para a autorização de pagamentos. Esse redirecionamento pode ser realizado via redirect entre aplicativos ou sites <> aplicativos. O CIBA fornece uma alternativa para esse fluxo onde ocorre um desacoplamento do processo e o canal para a autorização poderá ser um push-notification, SMS, email, WhatsApp etc.
Adesão
Após um redirecionamento comum, o usuário, em um detentor de conta com CIBA habilitado, poderá aderir a essa forma de autorização no aceite de um consentimento.
Liquidação
No ambiente do iniciador de pagamentos o usuário poderá selecionar a conta salva e receber o pedido de autorização via push-notification, SMS, email, WhatsApp etc. O usuário ainda deverá autorizar o consentimento para que o pagamento seja efetuado com sucesso.
Diretrizes para essa opção:
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;
O id_token deverá ter no mínimo 180 dias de expiração;
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);
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);
O id_token deve ser utilizado na chamada de autorização através do parâmetro “id_token_hint”;
Apenas o “poll mode” será utilizado para obter token para o envio do pagamento via endpoint Backchannel Authentication Endpoint do CIBA descrito no well-known da Detentora de Contas;
O cancelamento do id_token poderá ser realizado pela detentora de conta em casos de fraude ou por motivos de segurança;
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.
Informações e validações de um id_token
Informação contidas em uma id_token
Parâmetros | Validações |
---|---|
iss |
|
sub |
|
aud |
|
exp |
|
iat |
|
auth_time |
|
nonce |
|
acr |
|
amr |
|
azp |
|
Parâmetros para validação de um id_token
Todos os parâmetros devem estar presentes no cabeçalho (header) do JWT.
Parâmetros | Descrição | Valores recomendados |
---|---|---|
alg | O parâmetro "alg" (algoritmo) identifica o algoritmo criptográfico usado para proteger o JWS/JWE. O valor de Assinatura JWS não é válido se o valor "alg" não representar um algoritmo suportado ou se não houver uma chave compatível para uso do algoritmo associado à entidade que assinou digitalmente o conteúdo. | PS256 ou PS512 |
jku | O parâmetro "jku" (JWK Set URL) é um URI (RFC3986) que se refere a um recurso para um conjunto de chaves públicas codificadas em JSON, uma das quais corresponde à chave usada para assinar digitalmente o JWS. As chaves DEVEM ser codificadas como um JWK Set. O protocolo usado para adquirir o recurso DEVE fornecer proteção de integridade; uma solicitação HTTP GET para recuperar o JWK Set DEVE usar o Transport Layer Security (TLS); e a identidade do servidor DEVE ser validada, de acordo com a Seção 6 da RFC6125. (OPCIONAL) | |
jwk | O parâmetro "jwk" (JSON Web Key) é a chave pública que corresponde à chave usada para assinar digitalmente o JWS. Essa chave é representada como uma chave JWK. (OPCIONAL) | |
kid | O parâmetro "kid" (Key ID) é uma indica qual chave foi usada para proteger o JWS/JWE. Este parâmetro permite que os remetentes sinalizem explicitamente uma mudança de chave para os destinatários. O valor "kid" DEVE ser uma string com distinção entre maiúsculas e minúsculas. Quando usado com um JWK, o valor "kid" é usado para corresponder a um valor de parâmetro "kid" do JWK. (OPCIONAL) | |
x5u | O parâmetro "x5u" (X.509 URL) é um URI (RFC3986) referente a um recurso para o certificado de chave pública X.509 ou cadeia de certificados (RFC5280) correspondente à chave usada para assinar digitalmente o JWS. (OPCIONAL) | |
x5c | O parâmetro "x5c" (X.509 Certificate Chain) contém o certificado de chave pública X.509 ou cadeia de certificados (RFC5280) correspondente à chave usada para assinar digitalmente o JWS. (OPCIONAL) | |
x5t | O parâmetro "x5t" (X.509 Certificate SHA-1 Thumbprint) é uma impressão digital SHA-1 codificada em base64url (hash) da codificação DER do certificado X.509 (RFC5280) correspondente à chave usada para assinar digitalmente o JWS. (OPCIONAL) | |
x5t#S256 | O parâmetro "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) é uma impressão digital SHA-256 codificada em base64url (hash) da codificação DER do certificado X.509 (RFC5280) correspondente à chave usada para assinar digitalmente o JWS. Pode ser utilizado alternativamente ao "x5t". (OPCIONAL) | |
typ | O parâmetro "typ" (Type) é usado pelos aplicativos JWS para declarar o media type (IANA.MediaTypes) deste JWS completo. Destina-se ao uso pelo aplicativo quando mais de um tipo de objeto pode estar presente em uma estrutura de dados do aplicativo que pode conter um JWS; o aplicativo pode usar esse valor para eliminar a ambiguidade entre os diferentes tipos de objetos que podem estar presentes. (OPCIONAL) | JWT |
cty | O parâmetro "cty" (Content Type) é usado por aplicativos JWS para declarar o media type (IANA.MediaTypes) do conteúdo protegido (payload). Destina-se ao uso pelo aplicativo quando mais de um tipo de objeto pode estar presente no JWS Payload; o aplicativo pode usar esse valor para eliminar a ambiguidade entre os diferentes tipos de objetos que podem estar presentes. | ao invés de usar “application/example” usar “example” |
crit | O parâmetro "crit" (Critical) indica que extensões para esta especificação e/ou [JWA] estão sendo usadas e DEVEM ser compreendidas e processadas. Seu valor é um array com os nomes dos Parâmetros do Cabeçalho presentes no Cabeçalho do JOSE que usam essas extensões. |
Passo a passo para salvar um id_token
Informações |
---|
Lembre-se, o fluxo para a geração de um id_token é um fluxo de consentimento FAPI Hybrid-Flow comum! A Iniciadora de Pagamentos deverá salvar o id_token que vem no redirecionamento de volta da detentora via query parameters. |
Siga os passos do Diagrama de Sequência de uma Iniciação de Pagamento via Hybrid-Flow;
Na etapa de recebimento do code, state, id_token no redirectURL (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. Atentar-se ao item 4 do diagrama de sequência do link acima;
Realizar o pagamento normalmente, pois apenas no próximo pagamento será possível a utilização do canal CIBA para a comunicação com o cliente para autorizar um consentimento.
Passo a passo de uma Iniciação de Pagamento com o id_token salvo
Criar um consentimento fase 3 para Iniciação de Pagamentos padrão;
Receber resposta da criação do consentimento com status AWAITING_AUTHORISATION;
Requisitar Backchannel Authentication Endpoint do CIBA para autorização do consentimento, verificar payload abaixo:
Bloco de código |
---|
POST {BackchannelAuthenticationEndpoint} HTTP/1.1
Host: {AuthorizationServer}
Content-Type: application/x-www-form-urlencoded
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& |
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.
Tabela de erros “HTTP 400 Bad Request”:
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.
invalid_scope: The requested scope is invalid, unknown, or malformed.
expired_id_token_hint: The id_token hint provided in the authentication request is not valid because it has expired.
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).
unauthorized_client: The Client is not authorized to use this authentication flow.
invalid_id_token_hint: The id_token is invalid and can’t be used in the flow.
Resposta do Backchannel Authentication Endpoint:
Bloco de código |
---|
HTTP/1.1 200 OK
Content-Type: application/json
{
"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;
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.
Com o pagamento reconhecido pelo usuário a detentora muda o status do consentimento para AUTHORISED.
Em posse do auth_req_id a iniciadora deve chamar o endpoint
/token
em um intervalo de tempo determinado pelo campointerval
da resposta da chamada do Backchannel Authentication Endpoint para receber oaccess_token
,id_token
e orefresh_token
do consentimento autorizado até um tempo limite determinado pelo campoexpires_in
da resposta. Esse é o modo poll.
Bloco de código |
---|
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.
Realizar polling para obter o status da autorização da solicitação de consentimento, uma vez autorizada a solicitação de pagamento a detentora deve retornar uma resposta de sucesso com statusCode 200. Para os casos onde o consentimento ainda não foi aceito ou foi rejeitado a detentora deverá retornar 403 com os error codes listados abaixo.
Exemplo de resposta de sucesso conforme CIBA.Core1 10.1.1:
Bloco de código |
---|
HTTP/1.1 200 OK
Content-Type: application/json
{
"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"
} |
Exemplo de resposta de erro conforme CIBA.Core1 11:
Bloco de código |
---|
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
1. "error": "authorization_pending",
2. "error_description": "The user has not yet been authenticated, and the authorization request is still pending."
} |
Lista de possíveis erros:
Error Code | Error Description |
---|---|
authorization_pending | The user has not yet been authenticated, and the authorization request is still pending |
slow_down | The authorization request is still pending, and the client must increase the interval for polling requests by at least x seconds |
expired_token | The transaction (auth_req_id) has expired. The client must start over with a new Authentication Request |
access_denied | The user did not consent to the authorization request |
Seguir com o processo de uma iniciação de pagamento e realizar as chamadas na API de pagamento, caso o acesso for concedido com sucesso.
Diagrama de sequência fluxo CIBA