Identity Provider & SSO

OpenID Connect Single Sign-On Provider Agnostic

The CloudRader ecosystem is identity provider agnostic. Rather than locking deployments into a single proprietary authentication system, all CloudRader applications authenticate users and verify API tokens using standard OpenID Connect (OIDC) and OAuth 2.0.

You can integrate CloudRader with any OIDC-compliant identity provider, including Keycloak, Authentik, Authelia, Zitadel, or managed corporate IdPs (such as Okta or Microsoft Entra ID).

Why Central Identity?

Rather than maintaining separate user accounts and password databases in each service, CloudRader delegates identity to your central provider:

Standard OIDC Architecture & Roles

All CloudRader applications interact with identity providers through standardized protocols:

1. Web Interface Authentication: Single-page applications (SPAs) and web portals use the standard Authorization Code Flow with PKCE (Proof Key for Code Exchange) to obtain ID and access tokens securely in the browser.
2. API Request Verification: Backend services validate incoming Bearer <token> HTTP headers against the identity provider's JSON Web Key Set (JWKS) endpoint without transmitting credentials over internal networks.
3. Role-Based Access Control (RBAC): Applications inspect token claims (such as roles or realm access) to enforce permissions.

Common Application Roles

CloudRader services look for specific role claims in the validated access token:

Reference Implementation: Keycloak

While CloudRader works with any standard OIDC provider, Keycloak is included as the primary reference implementation in the Quickstart Stack. Below is the complete step-by-step setup guide.

Step 1. Log in to the Admin Console

1. Navigate to your Keycloak administrative URL (e.g., http://localhost:8443 or https://auth.example.com).
2. Log in using the admin credentials defined in your .env file (KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD).

Step 2. Create the CloudRader Realm

It is recommended practice to leave the default master realm dedicated solely to Keycloak system administration and create a dedicated realm for your applications:

1. In the top-left realm dropdown (which displays master), click Create realm.
2. Realm name: Enter cloudrader.
3. Toggle Enabled to ON.
4. Click Create.

Step 3. Create Application Clients

Each CloudRader service needs an OpenID Connect client registered in the cloudrader realm.

Configuring the Reservium Client

1. In the left navigation menu, click Clients -> Create client.
2. General Settings:
3. Client type: OpenID Connect
4. Client ID: reservium-app
5. Name: Reservium Booking System
6. Click Next.
7. Capability Config:
8. Client authentication: Toggle ON (confidential client).
9. Authentication flow: Check Standard flow and Direct access grants.
10. Click Next.
11. Login Settings:
12. Root URL: https://reservium.example.com (or http://localhost:3000 for local dev)
13. Home URL: /
14. Valid redirect URIs: https://reservium.example.com/* (or http://localhost:3000/*)
15. Valid post logout redirect URIs: https://reservium.example.com/*
16. Web origins: + (inherits valid redirect URIs for CORS)
17. Click Save.
18. Retrieve Client Secret:
19. Open the Credentials tab on the client page.
20. Copy the value under Client Secret and save it into your .env file as RESERVIUM_CLIENT_SECRET.

Step 4. Define Roles & Users

1. Create Realm Roles

Navigate to Realm roles -> Create role to define permissions recognized by CloudRader services:

• reservium-user
• reservium-manager
• reservium-admin

2. Create a User Account

1. In the left menu, navigate to Users -> Add user.
2. Fill in Username, Email, First name, and Last name.
3. Toggle Email verified to ON and click Create.
4. Switch to the Credentials tab, click Set password, enter a password, and toggle Temporary to OFF.
5. Switch to the Role mapping tab, click Assign role, and select the desired roles (e.g., reservium-user and reservium-manager).

Step 5. Connect CloudRader Services

In your deployment .env or container configuration, supply the matching connection parameters:

# OIDC / Keycloak Connection Parameters for Reservium
KEYCLOAK__SERVER_URL=https://auth.example.com
KEYCLOAK__REALM=cloudrader
KEYCLOAK__CLIENT_ID=reservium-app
KEYCLOAK__CLIENT_SECRET=your_copied_secret_here

Restart the application container to apply the settings:

docker compose up -d --force-recreate reservium-api

Other Identity Providers

Because CloudRader relies on standard OIDC, integrating another provider requires only registering an OIDC client and configuring the corresponding issuer endpoint:

Troubleshooting & Common Pitfalls