Carerix Marketplace Framework - Authentication & SSO Flow

This article explains how authentication and authorization work when integrating an iframe application via the Carerix Marketplace.

Make sure you have also read Carerix Marketplace Framework
and UI.

The flow has three phases:

Feature installation — done by an admin
Feature activation — done by an admin
Recruiter access via Single Sign-On (SSO)

The authenticate model works as follows:

Admins install and activate the integration through the Marketplace
Recruiters access the integration inside the Carerix UI
The partner iframe authenticates using OAuth2 / OpenID Connect
Single Sign-On happens automatically via the Carerix Identity Server

Phase 1 — Feature Installation

Step 1 — Admin installs the feature

A tenant administrator installs the partner integration from the Carerix Marketplace.

Step 2 — OAuth clients are provisioned

Carerix reads the partner manifest and creates two OAuth clients per tenant:

Backend client (confidential) — used by the partner backend to call Carerix APIs. Credentials: clientId + clientSecret
Frontend client (public) — used by the partner iframe UI. Configuration: clientId, redirect URIs, allowed web origins

Step 3 — Carerix calls the partner management endpoint

Carerix sends a lifecycle event to the partner system:

POST /features/management Event: FeatureCreateCommand

The payload contains the OAuth credentials:

json

{   "clientCredentials": {     "backend": {       "clientId": "...",       "clientSecret": "..."     }   },   "publicClients": {     "frontend": {       "clientId": "..."     }   } }

Step 4 — Partner provisions tenant resources

The partner system stores:

Tenant identifier
OAuth client credentials
Carerix Identity Server URL (iss)
Feature status

Step 5 — Installation complete

✅ Feature status: Deactivated — OAuth clients exist, partner environment is ready.

Phase 2 — Feature Activation

Step 6 — Admin activates the feature

The tenant administrator clicks Activate. Carerix sends a FeatureActivateCommand to the partner management endpoint.

Step 7 — Partner enables the tenant

The partner system marks the tenant as active.

✅ Feature status: Activated — the integration is now available inside the Carerix application.

Phase 3 — Recruiter Access & Single Sign-On

Step 8 — Recruiter logs into Carerix

The recruiter logs in via the Carerix Identity Server using OpenID Connect. After login, a valid Carerix session exists.

Step 9 — Recruiter opens the partner integration

Inside Carerix, the recruiter navigates to the partner feature (via a menu, tab, or embedded component). Carerix loads the partner application in an iframe.

Step 10 — Partner app initiates OAuth login

The iframe uses the frontend OAuth client and starts an Authorization Code Flow:

https://idX.carerix.io/auth/realms/{tenant}/protocol/openid-connect/auth   ?client_id={frontend clientId}   &redirect_uri={partner redirect URI}   &response_type=code   &scope=openid profile email

Step 11 — Single Sign-On occurs

Because the recruiter already has an active Carerix session, the Identity Server:

Does not prompt for login
Immediately issues an authorization code

💡 This is the SSO moment. The recruiter is authenticated in the partner app without entering any credentials.

Step 12 — Token exchange

The partner app exchanges the authorization code at the token endpoint. The Identity Server returns:

access_token (JWT)
id_token
refresh_token (optional)

Step 13 — Partner identifies the recruiter

The partner backend validates the token:

Signature
Expiration
Issuer (iss)
Audience (aud)

The tokens contain: recruiter identifier, tenant identifier, scopes, and issuer.

Step 14 — Partner session is active

After successful validation, the partner app creates its own session and the iframe loads normally. ✅

Optional — Partner calls Carerix APIs

If the partner backend needs to call Carerix APIs, it uses the confidential backend OAuth client via a Client Credentials Flow:

Partner backend requests a token via Client Credentials Flow
Carerix IAM issues an access token
Partner backend calls Carerix APIs using that token