SSO-Keycloak¶

Overview¶

This document describes the Single Sign-On (SSO) integration using Keycloak as the identity provider, with user provisioning through our Auth and Client microservices. Our microservices do NOT validate Keycloak tokens - they only create users in Keycloak.

Key Components¶

Keycloak Server: Identity provider (realm: omvivoltaic_dev)
Auth Microservice: Creates admin users in Keycloak
Client Microservice: Creates distributor users in Keycloak
Applications: Use Keycloak tokens directly (no microservice validation)

Detailed User Provisioning Flow¶

Admin User Creation:
- Admin registers through Auth microservice UI/API
- Auth microservice makes REST call to Keycloak Admin API
- Creates user in Keycloak with:
  - Username/email
  - Temporary password
  - admin role assigned
- Password reset email sent (if configured)
Distributor User Creation:
- Admin creates distributor in Client microservice
- Client microservice calls Keycloak Admin API
- Creates user in Keycloak with:
  - Username/email
  - Temporary password
  - distributor role assigned
- Welcome email sent with login instructions

Authentication Flow (No Microservice Token Validation)¶

Diagram

Code

Download

Client MicroserviceAuth MicroserviceKeycloakApplicationUserClient MicroserviceAuth MicroserviceKeycloakApplicationUserUser Provisioning OnlyAuthentication FlowCreate admin user (Admin API)Create distributor user (Admin API)Access protected resourceRedirect to authEnter credentialsReturn tokens (no microservice validation)Present tokensVerify tokens directlyToken validation responseGrant access based on roles

Keycloak Configuration Details¶

Realm: omvivoltaic_dev
Clients:
- auth-service (for Auth microservice admin API access)
- client-service (for Client microservice admin API access)
- Various application clients (for end-user authentication)
Roles:
- admin - Full system access
- distributor - Limited distributor access
Admin API Access:
- Service accounts with manage-users permissions
- Client credentials grant flow for microservices

Keycloak Groups Integration with Grafana¶

Group Structure¶

Defined Groups¶

The system currently implements two primary user groups:

SUPER-ADMIN
- Highest level of access
- Full administrative privileges
- Complete system oversight capabilities
DISTRIBUTOR
- Standard user access level
- Distributor-specific permissions
- Limited administrative capabilities

Group Assignment¶

All users created in the backend system are automatically registered and assigned to appropriate groups
Group assignments are embedded within JWT tokens sent to Grafana
Users can belong to multiple groups simultaneously

Token Structure and Implementation¶

JWT Token Components¶

The authentication tokens contain the following relevant fields for group management:

Core Authentication Fields¶

exp: Token expiration timestamp
iat: Token issued at timestamp
iss: Token issuer (Keycloak realm URL)
aud: Token audience (grafana-localhost)
sub: Subject identifier (unique user ID)

User Information Fields¶

name: Full user name
email: User email address
preferred_username: Username for system identification
given_name: First name
family_name: Last name

Group Authorization Fields¶

groups: Array containing user's assigned groups
realm_access.roles: Realm-level roles assigned to user

Token Examples¶

SUPER-ADMIN User Token¶

{
  "exp": 1747727319,
  "iat": 1747727019,
  "iss": "https://dev-keycloak.omnivoltaic.com/realms/Omnivoltaic_dev",
  "aud": "grafana-localhost",
  "sub": "576aadfe-4cd5-409b-9b01-94338322a80d",
  "name": "Rodgers OVES",
  "groups": [
    "SUPER-ADMIN"
  ],
  "preferred_username": "rodgers",
  "email": "rodgers_muyira@omnivoltaic.com"
}

Key Characteristics:

Single group assignment: SUPER-ADMIN
Standard realm roles included
Clean group structure for administrative access

DISTRIBUTOR User Token¶

{
  "exp": 1747725051,
  "iat": 1747724751,
  "iss": "https://dev-keyclloak.omnivolltaic.com/realms/Omnivoltaic_dev",
  "aud": "account",
  "sub": "4269be28-8e77-4225-be3c-c571ac8f7bbc",
  "name": "testdistributor OVES",
  "groups": [
    "DISTRIBUTOR",
    "DISTRIBUTOR_ovestestdistributor3@outlook.com"
  ],
  "preferred_username": "ovestestdistributor3@outlook.com",
  "email": "ovestestdistributor3@outlook.com"
}

Key Characteristics:

Multiple group assignments including base DISTRIBUTOR group
User-specific distributor group: DISTRIBUTOR_ovestestdistributor3@outlook.com
Additional realm roles including DiSTRIBUTOR in realm_access

Implementation Details¶

Keycloak Configuration¶

Group Creation: Two primary groups created in Keycloak:
- SUPER-ADMIN
- DISTRIBUTOR
Token Mapping: Groups are automatically included in JWT tokens through Keycloak's group mapper configuration
User Registration: Backend system automatically assigns users to appropriate groups during user creation process

Grafana Integration¶

Grafana receives JWT tokens containing group information
Group membership determines user permissions and dashboard access
Token validation ensures secure authentication flow

Security Considerations¶

Token Security¶

Tokens include expiration timestamps to prevent unauthorized long-term access
Issuer validation ensures tokens originate from trusted Keycloak instance
Audience validation confirms tokens are intended for Grafana usage

Group-Based Access Control¶

Group membership provides fine-grained permission control
Multiple group assignments allow for flexible permission structures
User-specific groups enable individual access customization

Troubleshooting¶

Common Issues¶

Missing Groups in Token
- Verify group assignment in Keycloak
- Check group mapper configuration
- Confirm user is properly assigned to groups
Token Validation Errors
- Verify issuer URL matches Keycloak configuration
- Check audience parameter matches Grafana client ID
- Ensure token hasn't expired
Permission Denied in Grafana
- Confirm group-to-permission mapping in Grafana
- Verify user's groups match required permissions
- Check Grafana role mapping configuration