March 27, 2025 by Appler LABS

Identity Service: Using Keycloak across your multiple applications with multi-tenacy

blog-feature-image

Identity Service: Using Keycloak across your multiple applications with multi-tenacy

To architect a multi-tenant strategy using Keycloak for registration, authentication, authorization, and managing users, roles, and role assignments across multiple applications with a single Keycloak instance, we need to carefully design the structure of realms, clients, users, groups, and roles. Below is a step-by-step approach based on the provided hierarchy and requirements:

1. Understanding the Requirements

From the image and description, the following key points are identified:

  • Multi-Tenancy: The system supports multiple tenants (e.g., AMA and IO).
  • Isolation: Each tenant has isolated users, groups, and roles.
  • Hierarchical Structure:
    • Each tenant has an admin (AMAAdmin, InkOrbitAdmin).
    • Each tenant can have multiple organizations (AMAOrg1, AMAOrg2, etc.).
    • Each organization has its own set of users and administrators.
  • Applications: Multiple applications need to be integrated with Keycloak for authentication and authorization.
  • Management Screens: There are screens for adding users, roles, and assigning roles to users within each tenant.

2. Architecture Design

a. Realms

Keycloak uses realms as the top-level container for all authentication and authorization configurations. For a multi-tenant setup, you can use one of the following approaches:

  1. Single Realm with Tenant Isolation:
    • Use a single realm (e.g., Default) and isolate tenants using groups or custom attributes.
    • This approach simplifies management but requires careful design to ensure isolation.
  2. Multiple Realms:
    • Create separate realms for each tenant (e.g., AMA, IO).
    • This approach provides strict isolation but may require more maintenance if there are many tenants.

Given the requirement for strict isolation and the hierarchical structure in the diagram, the Multiple Realms approach is recommended.

b. Clients

Each application that integrates with Keycloak should be represented as a client within the relevant realm. For example:

  • In the AMA realm, create clients for each application associated with the AMA tenant.
  • Similarly, in the IO realm, create clients for applications associated with the IO tenant.

Clients define the OAuth2/OpenID Connect configuration for each application, including scopes, redirect URIs, and other settings.

c. Users, Groups, and Roles

Users, groups, and roles are defined within each realm to ensure tenant isolation. Here’s how they can be structured:

  1. Users:

    • Each tenant has its own set of users.
    • Users are created within the respective tenant’s realm.

  2. Groups:

    • Use groups to organize users hierarchically.
    • For example:
      • In the AMA realm:
        • Group: AMAOrg1
          • Subgroup: AMAOrg1Admin
          • Subgroup: AMAOrg1User
        • Group: AMAOrg2
          • Subgroup: AMAOrg2Admin
          • Subgroup: AMAOrg2User
      • In the IO realm:
        • Group: IoOrg1
          • Subgroup: IoOrg1Admin

  3. Roles:

    • Define roles at the realm level or assign them to specific groups.
    • For example:
      • Realm-level roles: TenantAdmin, OrganizationAdmin, User.
      • Group-specific roles: Assign roles like Admin or User to the appropriate groups.

d. Role Assignments

  • Roles can be assigned to users directly or via group membership.
  • For example:
    • Users in the AMAOrg1Admin group automatically inherit the Admin role.
    • Users in the AMAOrg1User group inherit the User role.

e. Registration and Authentication

  • Registration:
    • Use Keycloak’s built-in user federation mechanisms or custom registration flows.
    • Ensure that users are registered in the correct realm based on their tenant.
  • Authentication:
    • Applications authenticate users by redirecting them to the appropriate Keycloak realm/client login page.
    • Use OAuth2/OpenID Connect protocols for secure authentication.

f. Authorization

  • Use Keycloak’s fine-grained authorization services (Authorization Services) to control access to resources.
  • Define policies based on roles, groups, or custom attributes.
  • Integrate the authorization server into your applications using the Keycloak adapter or API.

g. Management Screens

  • Develop custom screens or use Keycloak’s Admin Console for managing users, groups, and roles.
  • If custom screens are required:
    • Use Keycloak’s REST API to programmatically manage users, groups, and roles.
    • Implement UI components to add users, assign roles, and manage organizations.

3. Implementation Steps

Step 1: Set Up Realms

  • Create realms for each tenant (e.g., AMA, IO).
  • Configure each realm with the necessary settings (e.g., themes, email templates).

Step 2: Define Clients

  • For each application, create a client in the appropriate realm.
  • Configure client settings such as redirect URIs, scopes, and access types.

Step 3: Create Users, Groups, and Roles

  • Within each realm, create users and organize them into groups based on the hierarchical structure.
  • Define roles at the realm level or assign them to groups.

Step 4: Implement Registration and Authentication

  • Configure registration flows in Keycloak or implement custom registration logic.
  • Integrate applications with Keycloak using OAuth2/OpenID Connect.

Step 5: Set Up Authorization

  • Use Keycloak’s Authorization Services to define policies and permissions.
  • Integrate the authorization server into your applications.

Step 6: Develop Management Screens

  • Use Keycloak’s Admin Console for basic management or develop custom screens using the Keycloak REST API.
  • Implement UI components for adding users, assigning roles, and managing organizations.

4. Example Structure

Realms

  • AMA

    • Clients: Application1, Application2
    • Groups:
      • AMAOrg1
        • Subgroups: AMAOrg1Admin, AMAOrg1User
      • AMAOrg2
        • Subgroups: AMAOrg2Admin, AMAOrg2User
    • Roles: TenantAdmin, OrganizationAdmin, User

  • IO

    • Clients: Application3, Application4
    • Groups:
      • IoOrg1
        • Subgroups: IoOrg1Admin
    • Roles: TenantAdmin, OrganizationAdmin, User

Authentication Flow

  1. User accesses an application.
  2. Application redirects the user to the appropriate Keycloak realm/client login page.
  3. User authenticates, and Keycloak issues an access token.
  4. Application uses the access token to make requests to protected resources.

Authorization Flow

  1. Keycloak evaluates the user’s roles and group memberships.
  2. Based on predefined policies, Keycloak determines whether the user has access to the requested resource.
  3. Access is granted or denied accordingly.

5. Keycloak REST API Usage

For custom management screens, you can use Keycloak’s REST API to perform operations such as:

  • Creating/Managing users: /auth/admin/realms/{realm}/users
  • Managing groups: /auth/admin/realms/{realm}/groups
  • Assigning roles: /auth/admin/realms/{realm}/users/{userId}/role-mappings

6. Security Considerations

  • Ensure proper access controls for the Keycloak Admin Console and REST API.
  • Use HTTPS for all communication.
  • Implement rate limiting and IP whitelisting for sensitive APIs.

Conclusion

By using multiple realms for tenant isolation and leveraging Keycloak’s features for users, groups, roles, and authorization, you can effectively architect a multi-tenant system. The provided structure ensures clear separation between tenants while providing flexibility for managing users, roles, and applications. Custom management screens can be built using Keycloak’s REST API to meet specific requirements.

LET’S WORK TOGETHER