Banco do Brasil Authentication: OAuth 2.0 & Open Banking

Authentication overview

Banco do Brasil's API authentication framework is built to align with the Open Banking Brasil Security Profile, which mandates specific security protocols for financial data exchange. The core mechanism for accessing Banco do Brasil APIs is the OAuth 2.0 authorization framework. This standard provides secure delegated access from client applications to server resources, without sharing user credentials directly with the client. Implementing OAuth 2.0 involves several steps, including client registration, obtaining authorization from the resource owner (the user), and exchanging an authorization grant for an access token.

The Open Banking Brasil ecosystem, regulated by the Central Bank of Brazil, requires a robust security posture to protect sensitive financial information. This includes requirements for mutual TLS (mTLS) for server-to-server communication, ensuring that both the client and the server authenticate each other using X.509 certificates. The use of signed and encrypted JSON Web Tokens (JWTs) is also part of the security profile for identity and access tokens, providing integrity and confidentiality of the transmitted claims. Developers integrating with Banco do Brasil's APIs must adhere to these specifications to ensure secure and compliant operations, as detailed in the Banco do Brasil developer documentation.

Supported authentication methods

Banco do Brasil primarily supports OAuth 2.0 for API authentication, with specific flows tailored for different integration scenarios and security requirements. The choice of flow depends on the type of client application and the nature of the data being accessed.

OAuth 2.0 Client Credentials Grant: This flow is suitable for server-to-server interactions where the client application needs to access its own resources, or resources where it has been granted permission, without the involvement of an end-user. It's often used for backend services or batch processes. The client authenticates itself directly to the authorization server using its client ID and client secret, and receives an access token in return. This method is documented within the Banco do Brasil API reference.

OAuth 2.0 Authorization Code Grant with PKCE (Proof Key for Code Exchange): This is the recommended flow for public clients (e.g., mobile apps, single-page applications) and confidential clients that interact with end-users. PKCE adds an additional layer of security by mitigating authorization code interception attacks. In this flow, the user authenticates with Banco do Brasil, grants consent to the client application, and an authorization code is issued. The client then exchanges this code for an access token and refresh token, proving possession of a dynamically generated code verifier. The OAuth 2.0 PKCE specification provides further details on this security enhancement.

Mutual TLS (mTLS): Beyond OAuth 2.0, mTLS is a foundational security requirement for all communications with Banco do Brasil's Open Banking APIs. It ensures that both the client application and the API server verify each other's identity using digital certificates. This prevents man-in-the-middle attacks and ensures that only trusted parties can establish connections. Client certificates must be issued by a trusted Certificate Authority (CA) recognized within the Open Banking Brasil ecosystem. The Banco do Brasil integration guide outlines the specific requirements for mTLS certificate configuration.

Getting your credentials

To integrate with Banco do Brasil's APIs and obtain the necessary authentication credentials, developers must follow a structured registration process on the Banco do Brasil Developer Portal. This process typically involves several key steps:

1. Developer Account Registration: Create an account on the Banco do Brasil Developer Portal. This initial step requires basic company and contact information.
2. Application Registration: Once logged in, register your application. During this step, you will provide details such as your application's name, description, redirect URIs (for OAuth 2.0 Authorization Code flow), and specify the APIs you intend to consume.
3. Client ID and Client Secret: Upon successful application registration, Banco do Brasil will issue a unique client_id and client_secret. These credentials are vital for the OAuth 2.0 Client Credentials Flow and for initiating the Authorization Code Flow. The client_secret must be treated as highly confidential and never exposed in client-side code or public repositories.
4. mTLS Certificate Generation and Registration: For Open Banking APIs, you will need to generate a private key and a Certificate Signing Request (CSR) for your client application. This CSR must then be submitted to a Certificate Authority (CA) accredited by Open Banking Brasil to obtain a valid X.509 client certificate. This certificate, along with its corresponding private key, is essential for establishing mutual TLS connections. The specific process for certificate registration and validation is detailed in the Banco do Brasil Open Banking documentation.
5. Sandbox Access: Banco do Brasil provides a sandbox environment for testing integrations without affecting live production data. After registration, you generally gain access to this sandbox, allowing you to validate your authentication flows and API calls using test credentials.

It is crucial to meticulously follow the instructions provided on the Banco do Brasil Developer Portal for credential generation and management, as any deviation can lead to authentication failures or security vulnerabilities. Regular review of the documentation is recommended to stay updated with any changes in security policies or credential requirements.

Authenticated request example

The following example demonstrates how to obtain an OAuth 2.0 access token using the Client Credentials Flow and then use this token to make an authenticated API request to a hypothetical Banco do Brasil API endpoint. This example uses a command-line tool (curl) for illustration.

Step 1: Obtain an Access Token (Client Credentials Flow)

First, you exchange your client_id and client_secret for an access token. This request typically targets an authorization server's token endpoint.

curl -X POST \
  https://auth.bb.com.br/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET'

A successful response will include an access_token, its token_type (usually Bearer), and an expires_in value:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImFwXzEtMmQ1ZDNlZTQifQ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "accounts payments"
}

Step 2: Make an Authenticated API Request

Once you have the access_token, you include it in the Authorization header of your API requests. The token type is typically Bearer.

curl -X GET \
  https://api.bb.com.br/open-banking/v1/accounts \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-fapi-interaction-id: [UNIQUE_REQUEST_ID]' \
  --cert CLIENT_CERTIFICATE.pem \
  --key CLIENT_KEY.pem

Note the inclusion of --cert and --key for mutual TLS, and the x-fapi-interaction-id header, which is a requirement for Open Banking APIs to track requests. Replace YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, YOUR_ACCESS_TOKEN, CLIENT_CERTIFICATE.pem, and CLIENT_KEY.pem with your actual credentials and certificate paths. The specific endpoints and required headers for each API are detailed in the Banco do Brasil API documentation.

Security best practices

Adhering to security best practices is paramount when integrating with financial APIs like Banco do Brasil's. The Open Banking Brasil framework, combined with general API security principles, provides a robust set of guidelines.

• Protect Client Credentials: Your client_id and especially your client_secret are critical. Never hardcode them directly into your application's source code, especially for public-facing clients. Instead, use environment variables, secure configuration files, or a secrets management service. For client-side applications (like SPAs or mobile apps), avoid storing any client secrets at all, and rely on the Authorization Code with PKCE flow.
• Secure Redirect URIs: When using the Authorization Code Flow, register only specific, controlled redirect URIs. Unauthorized URIs can lead to authorization code interception. Always use HTTPS for redirect URIs.
• Implement PKCE Correctly: For public clients, always use the Proof Key for Code Exchange (PKCE) extension with the Authorization Code Flow. This adds a cryptographic binding between the authorization request and the token exchange, protecting against code interception attacks. The RFC 7636 specifies PKCE for OAuth Public Clients.
• Mutual TLS (mTLS) Configuration: Ensure your application correctly implements mTLS for all API communications. This involves using valid, trusted client certificates and verifying the server's certificate. Securely store your private keys and client certificates, restricting access to authorized processes only.
• Token Management:
• Short-lived Access Tokens: Access tokens should have a limited lifespan. Refresh tokens should be used to obtain new access tokens when the current one expires.
• Secure Refresh Tokens: Refresh tokens are long-lived and highly sensitive. Store them securely, ideally encrypted, and revoke them immediately if compromise is suspected. They should only be used confidentially by your server-side application.
• Token Validation: Always validate access tokens received from Banco do Brasil. This includes checking the token's signature, expiry, issuer, and audience to ensure it's legitimate and intended for your application.
• Error Handling and Logging: Implement robust error handling for authentication failures without revealing sensitive information in error messages. Log authentication attempts and failures for audit purposes, but ensure logs do not contain sensitive data like client secrets or full access tokens.
• Regular Security Audits: Periodically review your application's security posture, including how it handles credentials, tokens, and mTLS certificates. Stay informed about updates to Open Banking Brasil security guidelines and Banco do Brasil's API documentation.
• Least Privilege Principle: Request only the necessary scopes (permissions) for your application. Do not request broader access than what is strictly required for your application's functionality.

By diligently applying these practices, developers can build secure and compliant integrations with Banco do Brasil's Open Banking APIs, protecting both customer data and application integrity.