...
shall distribute discovery metadata (such as the authorization endpoint) via the metadata document as specified in OIDD and [RFC8414]
shall support the claims parameter as defined in clause 5.5 OpenID Connect Core
shall support the oidc standard claim "cpf" as defined in clause 5.2.2.2 of [FAPI-BR]shall support the oidc standard claim "cnpj" as defined in clause 5.2.2.3 of [FAPI-BR] if providing access to resources where the resource owner is not a natural personshall support the acr "urn:brasil:openbanking:loa2" as defined in clause 5.2.2.4 of FAPI-BR
should support the acr "urn:brasil:openbanking:loa3" as defined in clause 5.2.2.4 of [FAPI-BR]]
shall implement the userinfo endpoint as defined in clause 5.3 OpenID Connect Core
shall support parameterized OAuth 2.0 resource scope consent as defined in clause 6.3.1 OIDF FAPI WG Lodging Intent Pattern
shall support refresh tokens
shall issue access tokens with an expiry no greater than 900 seconds and no less than 300 secondsshall always include an acr claim in the id_tokenshall require the Signed Authentication Request to contain nbf and exp claims that limit the lifetime of the request to no more than 10 minutesshall issue ciba auth request acknowledgements with a minimum expiry of 6 minutes;The acceptance time of consent on the Authorization request received via CIBA shall remain the same as defined for the flow via Hybrid Flow, of 5 minutes;
The id_token shall have a minimum expiration of 180 days;
The id_token shall be used in the authorization call through the "id_token_hint" parameter
The "poll mode" shall be the only mode used to obtain a token for the payment sending via the bc-authorize endpoint.
The cancellation of the id_token shall be carried out by the account holder institution in cases of fraud or for security reasons.
is going to be added – The routine rotation of signing keys of id tokens SHALL NOT BE a reason to reject a non-expired id token signed with the older key. The authorization server should be prepared to use signing keys with similar validity periods to the ones of the id token.
Error table “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
shall issue ciba auth request acknowledgements (response of the consultation of auth_req_id) with a maximum expiry of 5 minutes;
Payload validation
Parameters | Validation |
iss | - The Authorization Server must establish an identifier, or set of standard "iss" identifiers for use in CIBA transactions. - The Authorization Server should not accept "iss" different from its own identifier, or set of identifiers, standard. |
sub | - The Authorization Server should check if the "sub" identifier in question has already been issued to a client/account, and if it is valid within its requirements. |
aud | - The Authorization Server should not accept "aud" different from the client_id from where the authorization request for the CIBA flow originates. |
exp | - "exp" should be established according to the risk policies of the Account Holder institution. - The , provided that requirement 5.2.2.15 is respected (minimum of 180 days) - The Authorization Server should not accept authorization requests whose date/time is greater than "exp". |
iat | - No specific validations |
auth_time | - No specific validations |
nonce | - No specific AS validations |
acr | - If present, the AS should only accept values equal to or above the Holder's authentication requirements to authorize payment transactions. |
amr | - If present, the AS should only accept values equal to or better than the Holder's authentication requirements to authorize payment transactions. |
azp | - The Authorization Server should not accept "azp" different from the client_id from where the authorization request for the CIBA flow originates. |
...
All parameters must be present in the JWT header.
Parameters | Description | Recommended values | |||||||
alg | The "alg" (algorithm) parameter identifies the cryptographic algorithm used to protect the JWS/JWE. The JWS Signature value is invalid if the "alg" value does not represent a supported algorithm or if there is no compatible key for the use of the algorithm associated with the entity that digitally signed the content. | PS256 ou PS512 | |||||||
jkukid | The "jkukid" (JWK Set URL) parameter is a URI (RFC3986) that refers to a resource for a set of public keys encoded in JSON, one of which corresponds to the key used to digitally sign the JWS. The keys MUST be encoded as a JWK Set. The protocol used to acquire the resource MUST provide integrity protection; an HTTP GET request to retrieve the JWK Set MUST use Transport Layer Security (TLS); and the server's identity MUST be validated, according to Section 6 of RFC6125. (OPTIONAL) | jwk | The "jwk" (JSON Web Key) parameter is the public key that corresponds Key ID) parameter indicates which key was used to protect the JWS/JWE. This parameter allows senders to explicitly signal a key change to recipients. The "kid" value MUST be a case-sensitive string. When used with a JWK, the "kid" value is used to match a "kid" parameter value of the JWK. (OPTIONAL) | ||||||
x5t | The "x5t" (X.509 Certificate SHA-1 Thumbprint) parameter is a base64url encoded SHA-1 thumbprint (hash) of the DER encoding of the X.509 certificate (RFC5280) corresponding to the key used to digitally sign the JWS. This key is represented as a JWK. (OPTIONAL(OPTIONAL) | ||||||||
kidx5t#S256 | The "kidx5t#S256" (Key ID) parameter indicates which key was used to protect the JWS/JWE. This parameter allows senders to explicitly signal a key change to recipients. The "kid" value MUST be a case-sensitive string. When used with a JWK, the "kid" value is used to match a "kid" parameter value of the JWK. (OPTIONAL) | x5u | The "x5u" (X.509 URL) parameter is a URI (RFC3986) referring to a resource for the X.509 public key certificate or certificate chain (RFC5280) corresponding to the key used to digitally sign the JWS. (OPTIONAL) | x5c | The "x5c" (X.509 Certificate Chain) parameter contains the X.509 public key certificate or certificate chain (RFC5280) corresponding to the key used to digitally sign the JWS. (OPTIONAL) | x5t | The "x5t" (X.509 Certificate SHA-1 Thumbprint) parameter is a base64url encoded SHA-1 thumbprint (hash) of the DER encoding of the X.509 certificate (RFC5280) corresponding to the key used to digitally sign the JWS. (OPTIONAL) | x5t#S256 | The "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) parameter is a base64url encoded SHA-256 thumbprint (hash) of the DER encoding of the X.509 certificate (RFC5280) corresponding to the key used to digitally sign the JWS. It can be used as an alternative to "x5t" (OPTIONAL) |
typ | The "typ" (Type) parameter is used by JWS applications to declare the media type (IANA.MediaTypes) of this complete JWS. It is intended for use by the application when more than one type of object may be present in an application data structure that can contain a JWS; the application can use this value to eliminate ambiguity between the different types of objects that may be present. (OPTIONAL) | JWT | |||||||
cty | The "cty" (Content Type) parameter is used by JWS applications to declare the media type (IANA.MediaTypes) of the protected content (payload). It is intended for use by the application when more than one type of object may be present in the JWS Payload; the application can use this value to eliminate ambiguity between the different types of objects that may be present. | instead of using “application/example” use “example” | crit | The "crit" (Critical) parameter indicates that extensions to this specification and/or [JWA] are being used and MUST be understood and processed. Its value is an array with the names of the Header Parameters present in the JOSE Header that use these extensions. |
5.2.3. Confidential client
In addition, the confidential client
shall support parameterized OAuth 2.0 resource scope consent as defined in clause 6.3.1 OIDF FAPI WG Lodging Intent Pattern
shall support refresh tokens
5.2.4. Resource Owner identity hint mechanisms
5.2.4.1. Introduction
As described in FAPI-CIBA, there are many mechanisms that can be used to convey a Resource Owners identity from the Consumption Device to the Authorization Server however in call cases this identity attestation must be treated as a hint only. There are naturally limitations on the types of id hints that can be captured by the consumption device based on the input and output contraints of the device being used. In addition to input and output challenges, there are several key privacy and security conerns that must be evaluated when defining id conveyance processes. This profile defines several login hint types that must be supported by authorisation servers.
FAPI-CIBA requires requests to be signed, there is no requirement in Brazil to additionally sign these hints as they are all asserted by the Client.
5.2.4.1.1. Authorisation Server Generated - Login Hint Token
This login hint can be used where it is not possible for the Resource Owner to provide a Login Hint to the Consumption Device or where the Resource Owner wishes to claim the authentication request by independently reaching out to the Authorisation Server out of band to claim this authentication request.
urn:brasil:openbanking:ciba:login-hint-token-type:as-generated
The use of a binding message is mandatory if this token type is to be leveraged.
5.2.4.1.1.1. Authorisation Server Generated - Login Hint Presentation
Presentation of the Authorisation Server Generated Token must be in the format of a JWE displayed as a QR Code with the following properties in the following way.
JWS Creation
The payload of signed messages (requestJWT) shall include the following claims as defined atRFC7519:
audthe Authorization Servers advertised issuer as perOIDD;issthe receiver of the message shall validate if the value of theissfield matches the clientId of the sender;jtithe value of thejtifield shall be filled with the UUID defined by the institution according to [RFC4122] version 4;iattheiatfield shall be filled with the message generation time and according to the standard established inRFC7519to theNumericDateformat.*
exptheexpfield shall be filled with the message expiry time and according to the standard established inRFC7519to theNumericDateformat with an maximum value not greater than 5 minutes;auth_request_idthe authentication request id returned from the Authorisation Server CIBA requst.
The JOSE header must contain the following attributes:alg- shall be filled with the value PS256";kid- shall be filled with the key identifier value used for the signature listed on the software statement keystore on the Open Finance Brasil Directory of Participants;typ- shall be filled with the value cibabr+jwt.
...
X.509 Certificate SHA-256 Thumbprint) parameter is a base64url encoded SHA-256 thumbprint (hash) of the DER encoding of the X.509 certificate (RFC5280) corresponding to the key used to digitally sign the JWS. It can be used as an alternative to "x5t" (OPTIONAL) | ||
typ | The "typ" (Type) parameter is used by JWS applications to declare the media type (IANA.MediaTypes) of this complete JWS. It is intended for use by the application when more than one type of object may be present in an application data structure that can contain a JWS; the application can use this value to eliminate ambiguity between the different types of objects that may be present. (OPTIONAL) | JWT |
5.2.3. Confidential client
In addition, the confidential client
shall support parameterized OAuth 2.0 resource scope consent as defined in clause 6.3.1 OIDF FAPI WG Lodging Intent Pattern
shall support refresh tokens
5.2.3.1.1. Authorisation Server Generated - Login Hint Token
This login hint can be used where it is not possible for the Resource Owner to provide a Login Hint to the Consumption Device or where the Resource Owner wishes to claim the authentication request by independently reaching out to the Authorisation Server out of band to claim this authentication request.
urn:brasil:openbanking:ciba:login-hint-token-type:as-generated
The use of a binding message is mandatory if this token type is to be leveraged.
5.2.3.1.1.1. Authorisation Server Generated - Login Hint Presentation
Presentation of the Authorisation Server Generated Token must be in the format of a JWE displayed as a QR Code with the following properties in the following way.
JWS Creation
The payload of signed messages (requestJWT) shall include the following claims as defined atRFC7519:
audthe Authorization Servers advertised issuer as perOIDD;issthe receiver of the message shall validate if the value of theissfield matches the clientId of the sender;jtithe value of thejtifield shall be filled with the UUID defined by the institution according to [RFC4122] version 4;iattheiatfield shall be filled with the message generation time and according to the standard established inRFC7519to theNumericDateformat.*
exptheexpfield shall be filled with the message expiry time and according to the standard established inRFC7519to theNumericDateformat with an maximum value not greater than 5 minutes;auth_request_idthe authentication request id returned from the Authorisation Server CIBA requst.
The JOSE header must contain the following attributes:alg- shall be filled with the value
...
PS256";kid- shall be filled with the
...
key identifier
...
value used
...
cty - shall be filled with the value JWT.
5.2.4.1.2. Authentication Device Generated - Login Hint Token
This login hint token should be used when Client has requested a unique identifier be provided by the Resource Owner to the Consumption Device. It is recommended that this identifier be dynamic, time based, have sufficient entropy and short lived to prevent replay attacks.
{ "format": "urn:brasil:openbanking:ciba:login-hint-token-type:ad-generated", "id": "11112222333344445555" }
...
for the signature listed on the software statement keystore on the Open Finance Brasil Directory of Participants;typ- shall be filled with the value cibabr+jwt.
JWE Creation
The JOSE header must contain the following attributes:alg- shall be filled with the value RSA-OAEP";enc- shall be filled with the value A256GCM";kid- shall be filled with the encryption key identifier kid value used to encrypt the JWE with the encryption key advertised on the authorisation servers jwks endpoint;cty- shall be filled with the value JWT.
5.2.4
...
This login hint token should be used when Client has requested a unique identifier be provided by the Resource Owner to the Consumption Device. It is recommended that this identifier be dynamic, time based, have sufficient entropy and short lived to prevent replay attacks.
{ "format": "urn:brasil:openbanking:ciba:login-hint-token-type:ad-generated", "id": "11112222333344445555" }
The use of a binding message is mandatory if this token type is to be leveraged.
6. Security considerations
Participants shall support all security considerations specified in all clauses and sub clauses of [FAPI-BR] and FAPI-CIBA
7. Data Sharing Considerations
Participants shall support all data sharing considerations specified in [FAPI-BR]
8. Registration and Discovery Metadata
OpenID Provider Metadata
The following authorization server metadata parameters are introduced by this specification for OPs publishing their support of the Brazil CIBA flow and details thereof.
backchannel_endpoint_login_hint_token_types_supported: REQUIRED.
JSON array containing one or more of the following values:
.1.2. Authentication Device Generated - Login Hint Token
This login hint token should be used when Client has requested a unique identifier be provided by the Resource Owner to the Consumption Device. It is recommended that this identifier be dynamic, time based, have sufficient entropy and short lived to prevent replay attacks.
{ "format": "urn:brasil:openbanking:ciba:login-hint-token-type:ad-generated", "id": "11112222333344445555" }
The use of a binding message is mandatory if this token type is to be leveraged.
5.2.4.1.2. Authentication Device Generated - Login Hint Token
This login hint token should be used when Client has requested a unique identifier be provided by the Resource Owner to the Consumption Device. It is recommended that this identifier be dynamic, time based, have sufficient entropy and short lived to prevent replay attacks.
{ "format": "urn:brasil:openbanking:ciba:login-hint-token-type:
...
urn:brasil:openbanking:ciba:login-hint-token-type:ephemeral or urn:brasil:openbanking:ciba:login-hint-token-type:credit-proposition.
...
urn:brasil:openbanking:ciba:login-hint-token-type:id-token.
...
ad-generated", "id": "11112222333344445555" }
The use of a binding message is mandatory if this token type is to be leveraged.
6. Security considerations
Participants shall support all security considerations specified in all clauses and sub clauses of [FAPI-BR] and FAPI-CIBA
7. Data Sharing Considerations
Participants shall support all data sharing considerations specified in [FAPI-BR]
8. Acknowledgements
With thanks to all who have set the foundations for secure and safe data sharing through the formation of the OpenID Foundation FAPI Working Group, the Open Finance Brasil GT Security and to the pioneers who will stand on their shoulders.
...