OAuth 2.0 and OIDC Basics

What Are OAuth 2.0 and OIDC?

When you use the Moneyhub API, you'll encounter two important standards: OAuth 2.0 and OpenID Connect (OIDC). Let's break down what they are and why they matter.

OAuth 2.0: Authorisation

OAuth 2.0 is a framework that lets users grant applications limited access to their resources without sharing passwords.

Think of it like a hotel key card:

• The hotel (bank) gives you a card (token)
• The card only opens specific doors (limited permissions)
• The card expires after your stay (time-limited access)
• The hotel can deactivate it anytime (revocable)
• You never give away the master key (password)

In Open Banking: OAuth 2.0 lets your users authorise Moneyhub to access their bank data or make payments without ever sharing their bank password with you or Moneyhub.

OpenID Connect (OIDC): Authentication

OIDC is built on top of OAuth 2.0 and adds identity information. It answers the question "who is the user?"

The key difference:

• OAuth 2.0: "Can this app access my bank account?" (authorisation)
• OIDC: "Who am I?" + "Can this app access my bank account?" (authentication + authorisation)

In Open Banking: OIDC is used to verify user identity and manage the authorisation process. Moneyhub uses OIDC to handle the complete authentication flow.

Authentication vs Authorisation

These terms are often confused, but they're different:

Authentication: "Who are you?"

Proving your identity.

Example: When you log into your bank with username and password, you're authenticating.

Authorisation: "What are you allowed to do?"

Granting permission to perform specific actions.

Example: After logging in, you authorise Moneyhub to read your transactions for 90 days.

In Open Banking

1. Authentication happens at the bank (user logs in)
2. Authorisation happens when user grants consent (what Moneyhub can do)

The OAuth 2.0 Authorisation Code Flow

Open Banking uses the "Authorisation Code Flow" - the most secure OAuth 2.0 flow. Here's how it works:

The Players

1. Resource Owner - The user (owns the bank account)
2. Client - Your application (wants to access data)
3. Authorisation Server - Moneyhub's identity service (manages authorisation)
4. Resource Server - Moneyhub's API and the bank (holds the data)

The Flow (Step by Step)

┌──────────┐                                    ┌───────────────┐
│          │                                    │               │
│   User   │                                    │  Your App     │
│          │                                    │               │
└────┬─────┘                                    └───────┬───────┘
     │                                                  │
     │ 1. Click "Connect Bank Account"                 │
     │◄─────────────────────────────────────────────────┤
     │                                                  │
     │                                          ┌───────▼───────┐
     │                                          │               │
     │ 2. Redirect to Authorization URL         │   Moneyhub   │
     │◄─────────────────────────────────────────┤   Identity   │
     │                                          │    Service   │
     │                                          │               │
     │                                          └───────┬───────┘
┌────▼─────┐                                           │
│          │                                           │
│   Bank   │ 3. User logs in and grants consent        │
│          │                                           │
└────┬─────┘                                           │
     │                                                  │
     │ 4. Redirect back with authorization code        │
     │──────────────────────────────────────────────────►
     │                                                  │
     │                                          ┌───────▼───────┐
     │                                          │               │
     │                                          │   Your App    │
     │ 5. Exchange code for tokens              │               │
     │◄─────────────────────────────────────────┤               │
     │                                          └───────────────┘
     │
     │ 6. Access data using token
     │──────────────────────────────►
     │

Detailed Steps

Step 1: User Initiates Action

User clicks "Connect Bank" or "Make Payment" in your application.

Step 2: Create Authorisation URL

Your application generates an authorisation URL through Moneyhub that includes:

• client_id - Your application's identifier
• scope - What permissions you're requesting
• redirect_uri - Where to send the user back
• state - Security token to prevent attacks
• nonce - Another security token

Step 3: User Redirected to Bank

The user is sent to Moneyhub's authorisation service, which redirects them to their bank where they:

• Log in with their bank credentials
• See exactly what you're requesting
• Grant or deny permission

Step 4: Authorisation Code Returned

If the user approves, the bank redirects them back to your redirect_uri with:

• An authorisation code (single-use, short-lived)
• The state value (verify it matches what you sent)

Step 5: Exchange Code for Tokens

Your application sends the code to Moneyhub's token endpoint and receives:

• access_token - Use this to make API calls
• id_token - Contains user identity and consent information
• refresh_token - (Optional) Use to get new access tokens

Step 6: Access Resources

Your application uses the access_token to call Moneyhub's API and access the authorized data or complete the payment.

Understanding Tokens

Tokens are central to OAuth 2.0. Let's understand each type:

Access Token

Purpose: Grants access to protected resources (APIs).

Characteristics:

• Short-lived (typically 1 hour)
• Sent with every API request
• Contains permissions (scopes)
• Doesn't contain personal information

How to use:

GET /accounts HTTP/1.1
Host: api.moneyhub.co.uk
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

ID Token

Purpose: Contains information about the authenticated user.

Characteristics:

• JWT format (can be decoded)
• Contains claims about user and consent
• Includes payment IDs or connection IDs
• Signed by Moneyhub (verifiable)

Example claims:

{
  "sub": "user-id-12345",
  "mh:con_id": "connection-id",
  "mh:payment": "payment-id",
  "aud": "your-client-id",
  "exp": 1234567890
}

Refresh Token

Purpose: Get new access tokens without user interaction.

Characteristics:

• Long-lived (days, weeks, or months)
• Only used for ongoing access scenarios
• Can be revoked by user
• Must be stored securely

When to use: If you need to periodically fetch new data (e.g., daily transaction updates for a budgeting app).

Scopes and Claims

These determine what your application can access.

Scopes

What they are: Permissions you request from the user.

Examples:

• openid - Required; indicates you're using OIDC
• accounts:read - Read account information
• transactions:read:all - Read all transactions
• payment - Initiate a payment
• offline_access - Request a refresh token

How they work:

• You specify scopes in the authorisation request
• User sees what you're requesting
• Access token is limited to granted scopes

Example request:

scope=openid accounts:read transactions:read:all offline_access

Claims

What they are: Specific pieces of information you request.

Why they exist: Scopes are broad; claims are specific. Claims let you request exact data points or specify payment details.

Example payment claim:

{
  "id_token": {
    "mh:payment": {
      "essential": true,
      "value": {
        "amount": 1000,
        "payeeId": "payee-123",
        "payerRef": "Invoice 456"
      }
    }
  }
}

What this means: "I need to make a payment of £10.00 to payee-123 with reference 'Invoice 456', and I need the payment ID in the ID token."

Grant Types

OAuth 2.0 supports different grant types for different scenarios. Open Banking primarily uses one:

Authorisation Code Grant (With PKCE)

Used for: Web applications, mobile apps, server-side apps.

Why it's secure:

• User credentials never shared with your app
• Authorisation code is single-use
• Tokens only issued after code exchange
• PKCE prevents code interception attacks

When to use: Always, for Open Banking. This is the standard flow.

Client Credentials Grant

Used for: Server-to-server communication without a user.

In Moneyhub: Used for creating payees, managing users, and other administrative tasks.

Example:

# Create a payee without user interaction
POST /payees
Authorization: Bearer {client_credentials_token}

Security Parameters Explained

You'll see these security parameters throughout the OAuth flow:

State

Purpose: Prevent Cross-Site Request Forgery (CSRF) attacks.

How it works:

1. Generate a random value (e.g., abc123xyz)
2. Send it in the authorisation URL
3. Store it in your session
4. When user returns, verify the state matches
5. Reject the request if it doesn't match

Why it matters: Ensures the authorisation response is for a request YOU initiated.

Nonce

Purpose: Prevent replay attacks on ID tokens.

How it works:

1. Generate a random value
2. Include in authorisation request
3. Verify it appears in the ID token
4. Reject if it doesn't match

Why it matters: Ensures the ID token was created for YOUR request, not reused from another session.

PKCE (Proof Key for Code Exchange)

Purpose: Prevent authorisation code interception attacks.

How it works:

1. Generate a random code_verifier
2. Create a code_challenge (hash of verifier)
3. Send code_challenge in authorisation request
4. Send code_verifier when exchanging code
5. Server verifies they match

Why it matters: Even if an attacker intercepts the code, they can't use it without the verifier.

Note: PKCE is essential for mobile and single-page applications.

Why These Standards?

You might wonder: "Why so complicated?"

Security

OAuth 2.0 and OIDC are proven, battle-tested standards used by Google, Microsoft, Facebook, and now banking.

Key security benefits:

• No password sharing
• Limited scope (principle of least privilege)
• Time-limited access
• Revocable permissions
• Encrypted communication

Standardization

Banks across Europe and the UK all use the same standards.

This means:

• Your code works with hundreds of banks
• Consistent behaviour and APIs
• Interoperability
• Regulatory compliance

Separation of Concerns

The flow separates different responsibilities:

• Banks authenticate users and manage accounts
• Moneyhub manages authorisation and API access
• Your app focuses on user experience and business logic

Common Patterns in Open Banking

Pattern 1: One-Time Payment

1. User wants to pay
2. Generate authorization URL with payment claim
3. User consents at bank
4. Exchange code for tokens
5. Payment ID in ID token
6. Check payment status
7. Done

Tokens: No refresh token needed (one-time action).

Pattern 2: Ongoing Data Access

1. User connects bank account
2. Generate authorization URL with offline_access scope
3. User consents at bank
4. Exchange code for tokens (includes refresh token)
5. Access data immediately
6. Later: Use refresh token for new access token
7. Fetch updated data

Tokens: Refresh token enables ongoing access.

Pattern 3: Re-consent / Re-authentication

1. Access token expired and no refresh token
2. Generate new authorization URL with reauth scope
3. User authenticates (may not need to re-consent)
4. Get new tokens
5. Continue accessing data

Tokens: New access token issued.

OAuth 2.0 vs Open Banking

While Open Banking uses OAuth 2.0, there are specific requirements:

What this means: Moneyhub handles the Open Banking-specific requirements. You use our API, which abstracts these complexities.

Key Takeaways

1. OAuth 2.0 = Authorisation framework (who can do what)
2. OIDC = Authentication layer on OAuth (who is the user)
3. Authorisation Code Flow = The secure flow used in Open Banking
4. Tokens = Access (use APIs), ID (user info), Refresh (renew access)
5. Scopes = Broad permissions (what data types)
6. Claims = Specific requests (exact payment details)
7. Security parameters = State, nonce, PKCE protect the flow
8. No passwords shared = User always authenticates at their bank

Visualizing the Complete Flow

Your App                 Moneyhub              User's Bank            User
   │                        │                      │                    │
   │  Create Auth URL       │                      │                    │
   │───────────────────────►│                      │                    │
   │                        │                      │                    │
   │  Return Auth URL       │                      │                    │
   │◄───────────────────────│                      │                    │
   │                        │                      │                    │
   │  Redirect user to Auth URL                    │                    │
   │───────────────────────────────────────────────┼───────────────────►│
   │                        │                      │                    │
   │                        │  Forward to bank     │   Login & Consent  │
   │                        │─────────────────────►│◄───────────────────│
   │                        │                      │                    │
   │                        │  Authorization code  │                    │
   │                        │◄─────────────────────│                    │
   │                        │                      │                    │
   │  Redirect with code    │                      │                    │
   │◄───────────────────────┼──────────────────────┼────────────────────│
   │                        │                      │                    │
   │  Exchange code         │                      │                    │
   │───────────────────────►│                      │                    │
   │                        │                      │                    │
   │  Return tokens         │                      │                    │
   │◄───────────────────────│                      │                    │
   │                        │                      │                    │
   │  Use access_token to call API                 │                    │
   │───────────────────────►│                      │                    │
   │                        │  Fetch data from bank                     │
   │                        │─────────────────────►│                    │
   │                        │◄─────────────────────│                    │
   │  Return data           │                      │                    │
   │◄───────────────────────│                      │                    │

Next Steps

Now that you understand how OAuth 2.0 and OIDC work, you're ready to see how this applies to a real payment:

→ Continue to The Payment Journey to see the complete flow in action

Further Reading

• Security Concepts - Deep dive into Open Banking security
• Key Terminology - Look up specific terms
• [Your First Payment](../getting started/your-first-payment) - Build your first integration