HridaOne Workspace Link (SSO)

Enterprise Only

This feature requires both Hrida AI Studio and HridaOne to be configured with the same Keycloak realm. It is not available in SaaS deployments or setups without Keycloak SSO.

The HridaOne workspace link lets users open HridaOne (your HRMS) directly from the Hrida AI Studio sidebar and land on the HridaOne dashboard already logged in — no second login prompt. Keycloak's existing browser session is reused silently via the Authorization Code flow with prompt=none.

How It Works

1. User clicks "HridaOne" in the AI Studio sidebar
         ↓
2. New tab → HridaOne: GET /sso/keycloak
         ↓
3. HridaOne redirects to Keycloak with prompt=none (silent — no login screen)
         ↓
4. Keycloak detects the active SSO session → issues an auth code
         ↓
5. HridaOne /sso/callback exchanges the code (server-to-server)
   → validates the KC token → resolves or provisions the employee
   → issues a HridaOne native JWT → injects it via localStorage
         ↓
6. User lands on the HridaOne dashboard — authenticated
   (If no active KC session → redirected to /login gracefully)

The auth code is single-use with a 60-second TTL; the KC access token never reaches the browser. CSRF is protected via a state nonce stored in a short-lived HttpOnly cookie.

---

Prerequisites

Requirement	Detail
Hrida AI Studio	Keycloak OIDC configured (OPENID_PROVIDER_URL set)
HridaOne	Running with KEYCLOAK_ISSUER_URI set to the same realm
Keycloak	Realm hrida (or your realm name) accessible from both services
Network	HridaOne backend must be able to reach the Keycloak token endpoint

---

Step 1 — Register HridaOne as a Keycloak Client

In the Keycloak Admin Console → your realm → Clients → Create client:

Setting	Value
Client ID	hridaone
Client protocol	openid-connect
Access type	confidential
Standard Flow (Auth Code)	Enabled
Direct Access Grants	Disabled
Valid Redirect URIs	https://one.hrida.ai/sso/callback (your HridaOne URL)
Web Origins	https://one.hrida.ai

After saving, go to the Credentials tab and copy the Client Secret. You will need it in Step 2.

Custom Claims

If you use the hrida_tenant_code claim to resolve multi-tenant employees in HridaOne, add the corresponding Protocol Mapper (type: User Attribute or Group Membership) to this client's scope. See the Keycloak group mapping guide.

---

Step 2 — Configure HridaOne Environment Variables

Add the following to your HridaOne deployment (.env or container env):

# Keycloak realm issuer URI — must match the 'iss' claim in KC tokens exactly
KEYCLOAK_ISSUER_URI=https://keycloak.example.com/realms/hrida

# OAuth2 client credentials for the browser SSO flow
KEYCLOAK_CLIENT_ID=hridaone
KEYCLOAK_CLIENT_SECRET=<secret-from-keycloak-credentials-tab>

# The callback URL Keycloak redirects to after the auth code is issued
# Must match the Redirect URI registered in Step 1 exactly
KEYCLOAK_SSO_CALLBACK_URL=https://one.hrida.ai/sso/callback

Restart HridaOne after adding these variables.

warning

KEYCLOAK_SSO_CALLBACK_URL must be reachable by the user's browser (it is a redirect destination, not a server-to-server call). The KC token exchange that follows is server-to-server — HridaOne must also be able to reach KEYCLOAK_ISSUER_URI from its container network.

---

Step 3 — Configure Hrida AI Studio

3a. Environment variable (optional bootstrap)

You can pre-seed both settings via environment variables. They can also be set and changed from the Admin Panel at any time:

# Full public URL of your HridaOne instance
HRIDAONE_URL=https://one.hrida.ai

# Set to true to show the link in the sidebar
ENABLE_HRIDAONE_SSO_LINK=true

3b. Admin Panel

1. Log in to Hrida AI Studio as an admin.
2. Go to Admin → Settings → Integrations.
3. Scroll to the HridaOne section (tagged Enterprise).
4. Enter your HridaOne URL (e.g., https://one.hrida.ai).
5. Toggle Show HridaOne link in workspace sidebar on.
6. Click Save.

---

Step 4 — Pin the Link in the Sidebar

The HridaOne item is not pinned by default. Each user (or admin) enables it once:

1. In the sidebar, click the + or Manage sidebar items button.
2. Find HridaOne in the list and toggle it on.
3. The HridaOne icon (↗ external link) now appears in the sidebar.

Clicking the icon opens a new tab, silently authenticates via Keycloak, and lands on the HridaOne dashboard.

---

Troubleshooting

Redirected to /login instead of the dashboard

This is the expected graceful fallback when there is no active Keycloak session in the browser. It happens when:

• The user has not logged into AI Studio via Keycloak SSO (e.g., they used native login instead).
• The Keycloak SSO session has expired.
• The user is in a private/incognito window with no existing KC session.

Fix: Ensure the user's current AI Studio session was established through Keycloak. prompt=none requires an active browser-level KC session — it cannot create one.

"CSRF state mismatch" in HridaOne logs

SSO: state mismatch (possible CSRF) — cookie=... param=...

The browser did not send back the sso_state cookie that was set when the flow was initiated. Common causes:

• The browser is blocking third-party cookies for one.hrida.ai (uncommon for same-domain redirects).
• KEYCLOAK_SSO_CALLBACK_URL is on a different subdomain than where /sso/keycloak was served, causing cookie scope issues.
• More than 5 minutes elapsed between clicking the link and Keycloak redirecting back (the state cookie TTL is 300 seconds).

Fix: Ensure KEYCLOAK_SSO_CALLBACK_URL and the HridaOne URL share the same origin. Verify there are no cookie-blocking browser policies.

Token exchange fails (HridaOne cannot reach Keycloak)

SSO: KC token exchange failed: Connection refused

HridaOne's backend cannot reach the Keycloak token endpoint.

Fix: Confirm KEYCLOAK_ISSUER_URI is reachable from within the HridaOne container. In Docker Compose deployments, use the internal service hostname (e.g., http://keycloak:9090/realms/hrida), not the public URL.

Employee not found / provisioning failed

SSO: could not resolve/provision user for email=...

HridaOne could not create the employee record. Common causes:

• The tenant code in hrida_tenant_code KC claim does not match any company in HridaOne.
• Database write failed (check HridaOne application logs for the underlying error).

Fix: Verify the hrida_tenant_code value in the user's KC token matches a tenant_code in the HridaOne companies table.

HridaOne link not visible in the sidebar

Confirm both conditions are true in Admin → Settings → Integrations:

• HridaOne URL is non-empty.
• Show HridaOne link toggle is on.

Also verify the user has added HridaOne to their pinned sidebar items (see Step 4).

---

Security Notes

Concern	Mitigation
Token in URL	Auth code only (60 s TTL, single-use). Access token never reaches the browser.
CSRF	state nonce in HttpOnly; Secure; Path=/sso cookie, verified on callback and immediately expired.
Code replay	KC auth codes are single-use.
No KC session	prompt=none returns error=login_required → graceful redirect to /login.
JWT injection	The HridaOne native JWT is written to localStorage via an inline <script>. The page is served over HTTPS and is never cached or indexed.

Production Requirements

• Both HridaOne and Keycloak must be served over HTTPS in production. The sso_state cookie carries Secure=true and will not be sent over plain HTTP.
• KEYCLOAK_CLIENT_SECRET must be kept confidential. Rotate it in the Keycloak Admin Console if compromised.

---

Just-in-Time (JIT) Employee Provisioning

When a user logs in through the HridaOne SSO link for the first time and no matching employee record exists, HridaOne automatically creates one:

Field	Value
Email	From KC email claim
Full name	From KC name or preferred_username claim
Role	EMPLOYEE
Status	ACTIVE
Password	Unusable sentinel — KC users cannot log in natively
Company	Resolved from hrida_tenant_code KC claim (if present)

JIT-provisioned accounts appear immediately in HridaOne's employee list. An admin can update role, department, and other fields afterward. The KC account remains the authoritative identity — changes to the KC user's email or name are reflected on the next SSO login.