Single Sign-On (SSO) Configuration

AIIA integrates with standard enterprise identity providers (IdPs) through Keycloak, supporting OpenID Connect (OIDC) and SAML 2.0 authentication protocols.

This guide details how to configure OIDC identity providers, set up client applications in Keycloak, and map identity assertions to AIIA user profiles and roles.

---

Architecture Overview

AIIA uses NextAuth.js on the frontend to negotiate OIDC authentication sessions with Keycloak. The backend services validate incoming JSON Web Tokens (JWTs) issued by Keycloak to authorize API requests.

---

OIDC Configuration Parameters

To link AIIA to your Keycloak server, configure the following environment variables in your server's deployment environment:

Variable	Description	Example
KEYCLOAK_ISSUER	The canonical base URL of the Keycloak realm.	https://sso.aiia.sa/realms/aiia
KEYCLOAK_ID	The OIDC Client ID registered in Keycloak.	aiia-app
KEYCLOAK_SECRET	The client authentication secret key.	sec_abc123...
NEXTAUTH_URL	The public base URL of the AIIA frontend.	https://app.aiia.sa
NEXTAUTH_SECRET	A random key used to encrypt session cookies.	use-a-strong-random-hash

---

Keycloak Client Registration (Step-by-Step)

Follow these steps to configure a client in your Keycloak console:

1. Create Client:
   • Go to Clients → Create Client.
   • Client Type: OpenID Connect.
   • Client ID: aiia-app.
2. Capability Config:
   • Client Authentication: Enabled (Confidential Client).
   • Authorization: Disabled.
   • Authentication Flow: Check Standard Flow (Authorization Code) and Direct Access Grants.
3. Access Settings:
   • Valid Redirect URIs: https://app.aiia.sa/api/auth/callback/keycloak
   • Web Origins: https://app.aiia.sa
   • Admin URL: https://app.aiia.sa
4. Retrieve Secret:
   • Save the client.
   • Go to the Credentials tab and copy the generated Client Secret value.

---

Role & Claims Mapping

To map user roles defined in your Active Directory / identity provider to AIIA roles:

1. Define Realm Roles: Create corresponding roles in Keycloak (CAE, Auditor, Manager, Admin, Leadership, QA).
2. Configure Scope Mapper:
   • In the Keycloak client scope configuration, ensure the roles protocol mapper is configured.
   • This mapper must output roles as an array in the access token under realm_access.roles.
3. JWT Decoding: AIIA automatically parses the incoming JWT and extracts claims to establish user context:

   {
     "sub": "usr_99f2e8...",
     "name": "Khalid Al-Mansoori",
     "email": "khalid.cae@aiia.sa",
     "realm_access": {
       "roles": ["CAE", "default-roles-aiia"]
     }
   }

   If the token contains CAE, the frontend and backend dynamically grant administrative and sign-off privileges matching that role profile.