Skip to content

Identity Service

Overview

The Identity Service is responsible for managing identity synchronization between VitalBridge and Keycloak.

While Keycloak serves as the platform's Identity Provider (IdP), the Identity Service maintains VitalBridge-specific identity information and coordinates user provisioning across the platform.

The service acts as the boundary between external identity management and internal business domains.

Responsibilities

The Identity Service is responsible for:

  • User provisioning
  • Identity synchronization
  • User lifecycle management
  • Role assignment
  • Tenant assignment
  • User profile normalization
  • Identity-related event publication

The service is not responsible for authentication.

Authentication is delegated entirely to Keycloak.

Service Architecture

flowchart TB

    USERS["Users"]

    KC["Keycloak"]

    ID["Identity Service"]

    ID_DB[("Identity DB")]

    USERS --> KC

    KC <--> ID

    ID --> ID_DB
Hold "Alt" / "Option" to enable pan & zoom

Identity Ownership

The platform separates authentication from identity management.

Keycloak Owns

  • Credentials
  • Passwords
  • Access Tokens
  • Refresh Tokens
  • Login Sessions
  • Authentication Flows

Identity Service Owns

  • User metadata
  • Tenant mappings
  • Platform roles
  • User lifecycle state
  • Business identity information

User Lifecycle

A user typically enters the platform through a business workflow.

For example:

  • Tenant Administrator created
  • Provider created
  • Patient created

These actions trigger identity provisioning.

sequenceDiagram

    participant Service

    participant Identity

    participant Keycloak

    Service->>Identity: Create User

    Identity->>Keycloak: Provision Account

    Keycloak-->>Identity: User Created

    Identity-->>Service: Identity Created
Hold "Alt" / "Option" to enable pan & zoom

Identity Provisioning

When a user is created, the Identity Service provisions the corresponding Keycloak account.

flowchart LR

    USER["New User"]

    ID["Identity Service"]

    KC["Keycloak"]

    DB[("Identity DB")]

    USER --> ID

    ID --> KC

    ID --> DB
Hold "Alt" / "Option" to enable pan & zoom

Provisioning typically includes:

  • User creation
  • Role assignment
  • Tenant assignment
  • Initial activation

User Types

The Identity Service manages identities for all platform users.

flowchart TB

    USER["User"]

    SUPER["Super Administrator"]

    TENANT["Tenant Administrator"]

    PROVIDER["Provider"]

    PATIENT["Patient"]

    USER --> SUPER

    USER --> TENANT

    USER --> PROVIDER

    USER --> PATIENT
Hold "Alt" / "Option" to enable pan & zoom

Each user is assigned platform roles and tenant ownership.

Role Assignment

Roles determine platform access.

flowchart LR

    USER["User"]

    ROLE["Role Assignment"]

    KC["Keycloak"]

    USER --> ROLE

    ROLE --> KC
Hold "Alt" / "Option" to enable pan & zoom

Supported roles include:

  • ROLE_SUPER_ADMIN
  • ROLE_TENANT_ADMIN
  • ROLE_PROVIDER
  • ROLE_PATIENT

Tenant Assignment

Every non-platform user belongs to a tenant.

flowchart LR

    USER["User"]

    TENANT["Tenant"]

    USER --> TENANT
Hold "Alt" / "Option" to enable pan & zoom

Tenant context is propagated through authentication tokens and validated by downstream services.

User Activation Flow

sequenceDiagram

    participant Admin

    participant Identity

    participant Keycloak

    Admin->>Identity: Create User

    Identity->>Keycloak: Provision Account

    Keycloak-->>Identity: Account Created

    Identity-->>Admin: User Provisioned
Hold "Alt" / "Option" to enable pan & zoom

At this point the user can authenticate through Keycloak.

Identity Events

The Identity Service publishes domain events when identity state changes.

flowchart LR

    ID["Identity Service"]

    KAFKA["Apache Kafka"]

    ID --> KAFKA
Hold "Alt" / "Option" to enable pan & zoom

Examples include:

  • user.created
  • user.activated
  • user.deactivated
  • role.assigned
  • tenant.assigned

These events enable downstream services to react to identity changes.

Database Model

The Identity Service maintains its own database.

flowchart TB

    ID["Identity Service"]

    DB[("Identity DB")]

    ID --> DB
Hold "Alt" / "Option" to enable pan & zoom

Typical information includes:

  • Internal user identifiers
  • Keycloak user identifiers
  • Tenant mappings
  • Role mappings
  • Status information

Credentials are never stored.

Relationship with Keycloak

The Identity Service and Keycloak work together.

flowchart LR

    KC["Keycloak"]

    ID["Identity Service"]

    SERVICES["Domain Services"]

    KC --> ID

    ID --> SERVICES
Hold "Alt" / "Option" to enable pan & zoom

Keycloak

Provides:

  • Authentication
  • Access Tokens
  • Session Management

Identity Service

Provides:

  • User Provisioning
  • Identity Metadata
  • Business Identity Management

Security Considerations

The Identity Service never:

  • Stores passwords
  • Performs authentication
  • Issues access tokens
  • Manages login sessions

These responsibilities belong exclusively to Keycloak.

This separation reduces complexity and improves security.

Design Principles

The Identity Service follows several principles.

Separation of Concerns

Authentication belongs to Keycloak.

Identity management belongs to the Identity Service.

Single Source of Truth

Keycloak remains the source of truth for authentication.

The Identity Service remains the source of truth for platform identity metadata.

Event-Driven Integration

Identity changes are propagated through domain events.

Tenant Awareness

Every identity is associated with the appropriate tenant context.