Admin Portal Overview
A self-service surface your customers' IT admins use to configure their own SSO — separate from the vendor dashboard and the RealmSSO operator tooling.
What the Admin Portal is
The Admin Portal is the customer-facing UI at /portal in the realmsso-app frontend — not on this documentation site, which is marketing pages only (see Architecture Overview). It lets a single named person at one of your customers — typically their IT admin — configure SAML, OIDC, and SCIM for their own account without ever getting a RealmSSO login, a password, or access to your vendor dashboard. It is deliberately narrow: one account per session, no cross-account visibility, no billing or provisioning controls.
Three different surfaces, easy to conflate
Vendor dashboard (/dashboard) is for you, the SaaS vendor — it authenticates a VendorUser with a JWT and manages every one of your customer accounts.
Admin Portal (/portal) is for your customer's IT admin — it authenticates against a single AdminPortalSession row scoped to one account, using an opaque token rather than a JWT.
Neither is the Keycloak admin console — RealmSSO and the Admin Portal only ever talk to Keycloak through the server's own provisioning code.
How access is granted
There is no sign-up flow. From the vendor dashboard's Accounts page, you invite an IT admin by email ("Invite IT Admin"), which calls:
/api/v1/admin-portal/generate-linkThis requires vendor authentication and account access. It creates an AdminPortalSession row (account, email, optional display name, expiry) and emails the admin a single link shaped like {ADMIN_PORTAL_BASE_URL}/portal?token=...&org={slug}. See Magic Link Authentication for exactly how that token is issued, verified, and stored client-side.
What a customer admin can do
Once signed in, the portal layout shows the account's name, logo, and brand color (see Branding & Customization) and five tabs:
| Tab | Route | What it does |
|---|---|---|
| Overview | /portal/dashboard | Shows SAML/OIDC configured status and lists the account’s connections with health. |
| SAML Configuration | /portal/saml | Create a SAML connection by metadata URL or manual IdP entity ID / SSO URL / certificate; shows the resulting ACS URL and Entity ID to hand to the IdP. |
| OIDC Configuration | /portal/oidc | Create an OIDC connection with client ID, client secret, and discovery URL. |
| SCIM Directory Sync | /portal/scim | Toggle SCIM provisioning on and generate a bearer token for the customer’s IdP to call RealmSSO’s SCIM endpoint. |
| Settings | /portal/settings | Read-only account details, endpoint copy-paste helpers, and current session expiry. |
Every one of those pages authenticates by sending the admin's opaque session token as an X-Admin-Token header — the browser never holds a JWT for this session. For the underlying data model (single-use, time-boxed sessions) and the request/response shape, see Magic Link Authentication. For the account/realm model these connections attach to, see Accounts (Tenants).
The OIDC tab's save still doesn't accept the portal token
The OIDC tab sends its "Save Configuration" request to POST /api/v1/connections/oidc — a route in the connections module, which requires a vendor JWT or an API key on every request via an onRequest hook, not an admin-portal token. A real Admin Portal session carries neither, so that one save action 401s instead of creating a connection.
The SAML tab no longer has this problem: it posts to POST /api/v1/admin-portal/connections/saml, which does check the portal token. The SCIM tab (PUT /api/v1/admin-portal/connections/:id/scim) and the read-only GET /api/v1/admin-portal/connections have always used portal-token routes. The backend exposes a matching POST /api/v1/admin-portal/connections/oidc; pointing the OIDC tab at it is the fix, and it is the frontend that has to change, not the API.