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+clientSecretFrontend 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 emailStep 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_tokenrefresh_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