NorthStar Bank IAM Architecture (Keycloak)

A Keycloak-based IAM lab focused on scalable authentication, RBAC, and access control across multiple services.

Summary

Project Overview

This project focuses on building a centralised IAM setup using Keycloak for a multi-service banking-style environment.

The aim was to create something that is secure, scalable, and easy to manage — not just something that works, but something that can grow without becoming difficult to maintain.

I structured the environment around multiple applications and APIs, each with their own roles and access requirements, and built a clear RBAC model to keep things consistent.

A big part of the design was making sure the access model stayed understandable as more users, services and roles were added, rather than becoming harder to maintain over time.

• Keycloak used as a central identity provider
• Realms, clients, roles and groups structured for multiple services
• RBAC using composite roles
• Group-based access to reduce manual user management
• User attributes mapped into tokens for scoped access
• OIDC authentication flows tested using Postman

Although the bank itself is fictional, the setup mirrors the kind of IAM structure you would expect in a real environment with multiple internal services and separate access boundaries.

While this was built as a lab, the structure was designed the same way I would approach a real Keycloak environment: keep the access model clear, keep service boundaries explicit, and avoid anything that becomes difficult to support as the platform grows.

Architecture

User (Postman / Application)
        ↓
Keycloak (Identity Provider)
        ↓
JWT Access Token (roles + claims)
        ↓
Applications / APIs

Keycloak acts as the central identity provider. It handles authentication, issues JWTs, and gives one place to manage clients, roles, groups and token claims, which helps keep access control consistent across services as the environment grows.

Keycloak Configuration

Realm: northstar-bank

Realm Setup

A dedicated realm was created to isolate the IAM environment and manage authentication independently.

• branch-staff-portal
• customer-portal
• loan-portal
• payments-api
• accounts-api
• reporting-api

The client structure was designed to reflect a microservice-style environment, where different applications and APIs have distinct trust boundaries and access requirements.

Client Configuration

Each application and API was configured as a separate client to reflect real-world service boundaries.

RBAC Model

• teller
• branch_manager
• customer
• loan_officer
• auditor
• support_engineer
• platform_admin

teller →
  - view_branch_customers
  - initiate_cash_operation
  - read_account_data
  - create_payment

Role Structure

Composite roles were used to group permissions, making access easier to manage and scale.

This approach keeps the model easier to support over time, because changes can be made at role level without reworking access on a per-user basis.

Group-Based Access

branches
 ├── London
 │    └── tellers
 └── Tokyo
      └── managers

Group Hierarchy

Groups represent organisational structure, allowing users to inherit access automatically.

Group Role Assignment

Roles were assigned at group level so access is consistent and not manually managed per user.

Using groups in this way reduces manual administration and makes access changes easier to manage when teams, branches or internal structures change.

Scoped Access with Token Claims

david.teller → branch_id = London

Attribute Mapping

Custom attributes were mapped into tokens to support context-based access decisions.

User Attribute Example

User-specific attributes such as branch_id are included in tokens for downstream services.

OIDC Token Flow Testing

/realms/northstar-bank/protocol/openid-connect/token

Postman Configuration

Postman was configured to interact with Keycloak’s OIDC endpoints.

Token Response

A successful 200 OK response confirmed authentication and token generation were working.

Testing the token flow directly made it easier to confirm that authentication, client setup and token issuance were all working as expected before relying on the setup from an application layer.

JWT Claims Validation

After the token was issued, I checked it to make sure the expected roles and claims were present.

"realm_access": { "roles": ["teller"] }
"branch_id": "London"

This was mainly to confirm that the RBAC model and custom claim mapping were both working as expected.

Decoded Token Claims

The decoded JWT confirms that roles and custom attributes are correctly included in the token.

This was important because downstream services need a reliable token structure if they are going to make consistent authorisation decisions at runtime.

At this point I was checking that downstream services would receive the role and context they needed to make access decisions reliably.

Operational Considerations

Beyond the initial setup, the project was designed with day-to-day maintainability in mind. That meant keeping the Keycloak configuration clear, making role assignments predictable, and structuring clients and groups in a way that would still make sense as more services and users were added.

• Access is easier to review because roles are tied to business function
• Group-based assignment reduces manual changes and repeated admin work
• Client separation keeps service boundaries clear
• The token structure is predictable enough for downstream services to depend on
• The setup leaves room for future improvements such as HA, PostgreSQL and larger-scale deployment

That matters because IAM systems tend to become harder to reason about over time unless the structure is kept simple and consistent from the start.

Key Takeaways

• Centralised IAM improves consistency across products and internal services
• RBAC plus token claims creates a clearer and more maintainable access model
• Separating clients, groups and roles makes the system easier to support as it grows
• OIDC-based token flows give services a reliable basis for authentication and authorisation
• Clear IAM design helps reduce risk and avoid access control becoming difficult to manage over time

Conclusion

This project gave me a practical way to design and test a Keycloak-based IAM setup across multiple services, with a strong focus on keeping authentication reliable, access control clear, and the overall model maintainable as the environment grows.