SSO Integration Guide for Satellite Applications
For: Software Engineers & Technical Leads developing applications in the OneXCC Network (digital portals, internal tools, partner platforms).
Quick Reference for Agents & Terminal
Machine-readable parameters and live curl test commands designed for automated coding agents and DevOps automation:
XCC IAM serves as a fully compliant OpenID Connect Provider. All relying party applications authenticate using Authorization Code Flow with mandatory PKCE (S256).
| Endpoint | Method | URL Path | Usage |
|---|---|---|---|
| Issuer URL | URI | https://iam.xcc.one/api/auth | Token Issuer Identifier (Issuer URI) |
| OIDC Discovery (Machine/SDK) | GET | https://iam.xcc.one/.well-known/openid-configuration | Automatic server metadata discovery for machine SDKs (RFC 8414) |
| JWKS Endpoint | GET | https://iam.xcc.one/jwks | Public keys for decoding & verifying JWT ID Tokens |
| Authorization | GET / POST | https://iam.xcc.one/oauth2/authorize | User sign-in & consent delegation interface |
| Token Endpoint | POST | https://iam.xcc.one/oauth2/token | Exchange Authorization Code for Access & ID Tokens |
| UserInfo Endpoint | GET / POST | https://iam.xcc.one/userinfo | Retrieve authenticated user claims via Bearer Token |
| Dynamic Client Registration (RFC 7591) | POST | https://iam.xcc.one/oauth2/register | Dynamic Client Registration for IDE Hosts / AI Agents via Initial Access Token (RFC 7591) |
| Token Revocation (RFC 7009) | POST | https://iam.xcc.one/oauth2/revoke | Instantly revoke Access or Refresh Tokens per RFC 7009 |
Endpoint Specification (API Reference)
Detailed parameter breakdown, HTTP headers, request formats, and response schemas for each endpoint:
Initiate user authorization session and request an Authorization Code via the browser (Browser-based flow).
| Param | Type | Status | Description |
|---|---|---|---|
| client_id | string | Required | OAuth Client ID obtained during client registration in the Console or via DCR. |
| redirect_uri | string | Required | Callback URL matching one of the whitelisted redirect URIs exactly. |
| response_type | string | Required | Must be set to fixed value: code |
| scope | string | Required | Requested scopes, must include openid (e.g. openid profile email mcp:access). |
| resource | string | Optional | Protected Resource Indicator per RFC 8707 (e.g. https://app.maerin.biz/api/mcp). Access Token JWT aud claim will be bound to this URI. |
| code_challenge | string | Required | PKCE hash: BASE64URL(SHA256(code_verifier)). |
| code_challenge_method | string | Required | Must be set to fixed value: S256 |
| state | string | Recommended | Opaque random string generated by client to mitigate CSRF attacks. |
| track | string | Optional | Specifies account track: personal or enterprise (supports aliases account_type, user_type). If passed, XCC IAM locks the UI to that track and hides the 2-tab switcher; if omitted, both tabs are displayed for user selection. |
Connect Single Sign-On in three simple steps:
Administrators navigate to OAuth Clients Console, click Create Client and provide:
- Name: Application name shown on consent screen (e.g. OneXCC Portal Production).
- Redirect URIs: Whitelisted callback URLs (e.g. https://app.example.com/api/auth/callback/xcc-iam, http://localhost:3101/api/auth/callback/xcc-iam for dev).
Declare OIDC parameters in .env.local or your satellite app's production configuration:
OIDC_ISSUER=https://iam.xcc.one/api/auth
OIDC_CLIENT_ID=your_assigned_client_id
OIDC_CLIENT_SECRET=your_assigned_client_secret
OIDC_REDIRECT_URI=https://app.example.com/api/auth/callback/xcc-iam
OIDC_SCOPES="openid profile email"Integrate your authentication client library using the code samples below:
import { betterAuth } from "better-auth";
import { genericOAuth } from "better-auth/plugins";
export const auth = betterAuth({
plugins: [
genericOAuth({
config: [
{
providerId: "xcc-iam",
clientId: process.env.OIDC_CLIENT_ID!,
clientSecret: process.env.OIDC_CLIENT_SECRET!,
discoveryUrl: "https://iam.xcc.one/api/auth/.well-known/openid-configuration",
scopes: ["openid", "profile", "email"],
pkce: true, // Bắt buộc bật PKCE S256 theo tiêu chuẩn XCC IAM
},
],
}),
],
});After successful authentication and consent approval, the client application receives an ID Token and UserInfo response containing standard claims:
{
"sub": "usr_xcc_123456789",
"email": "[email protected]",
"name": "Nguyễn Văn A",
"image": "https://avatar.xcc.one/avatar.png",
"email_verified": true
}Mandatory PKCE (RFC 7636 S256)
All client applications (including SPAs, Mobile Apps, and Server-rendered apps) must enforce PKCE S256 to eliminate Authorization Code interception attacks.
Exact Redirect URI Matching
All callback URLs must be pre-registered character-for-character. XCC IAM immediately rejects authorization if redirect_uri differs by port or scheme.
Never Expose Client Secret to Frontend
Client Secrets must only be stored and used within server-side runtimes. Never bundle secrets into client JavaScript or public code repositories.
When redirecting users to XCC IAM, your relying party application can proactively control the active account track via request parameters (track, account_type, user_type):
Append track=enterprise (or account_type=enterprise) to the authorization URL. XCC IAM completely hides the 2-tab switcher and locks the UI into Enterprise mode with company email fields.
https://iam.xcc.one/api/auth/oauth2/authorize?client_id=...&redirect_uri=...&response_type=code&scope=openid+profile&track=enterpriseAppend track=personal (or account_type=personal). XCC IAM hides the tab switcher and locks the UI into Personal ID mode. If no account type is specified, XCC IAM renders both tabs for the user to choose.
https://iam.xcc.one/sign-in?track=personal&callbackURL=https://app.example.com/dashboardXCC IAM provides native OAuth 2.1 authorization with Dynamic Client Registration (RFC 7591) and Resource Indicators (RFC 8707) tailored for modern AI IDE hosts (Cursor, Windsurf, VS Code).
IDE Hosts dynamically register client credentials via POST /oauth2/register using a pre-shared Initial Access Token (IAT) in the Authorization header:
# 1. Đăng ký IDE Host Client động qua Initial Access Token:
curl -X POST https://iam.xcc.one/oauth2/register \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <MCP_INITIAL_ACCESS_TOKEN>" \
-d '{
"client_name": "Cursor IDE - Workstation",
"redirect_uris": ["http://127.0.0.1:8080/callback"],
"application_type": "native",
"token_endpoint_auth_method": "none",
"grant_types": ["authorization_code"],
"response_types": ["code"]
}'The IDE initiates an authorization code request with scope mcp:access and the resource parameter targeting the MCP server:
https://iam.xcc.one/oauth2/authorize?
response_type=code&
client_id=mcp_clnt_YOUR_CLIENT_ID&
redirect_uri=http%3A%2F%2F127.0.0.1%3A8080%2Fcallback&
scope=openid+profile+email+mcp%3Aaccess&
resource=https%3A%2F%2Fapp.maerin.biz%2Fapi%2Fmcp&
code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&
code_challenge_method=S256The IDE exchanges the authorization code for an access token. The returned JWT contains an aud claim bound to the MCP server:
# 2. Đổi Authorization Code lấy Resource-Bound JWT Access Token:
curl -X POST https://iam.xcc.one/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "client_id=mcp_clnt_YOUR_CLIENT_ID" \
-d "redirect_uri=http://127.0.0.1:8080/callback" \
-d "code=AUTHORIZATION_CODE_RECEIVED" \
-d "code_verifier=YOUR_PKCE_CODE_VERIFIER" \
-d "resource=https://app.maerin.biz/api/mcp"All mcp:access delegations are logged to the audit system (oauth_consent.grant). Administrators can revoke access from the Admin Console, and clients can revoke tokens via POST /oauth2/revoke.