Uaepass

UAE PASS Integration

UAE PASS is the UAE's national digital identity platform. Authentication is OAuth 2.0 / OpenID Connect (the IdP is Eviden/ForgeRock TrustedX, exposed under the idshub path). A Service Provider (SP) delegates login to UAE PASS; the user approves via a push notification in the UAE PASS mobile app.

This skill is organised so an agent loads only what the current task needs: pick your platform (§1), pull in the platform-agnostic references as needed (§2), and read a feature file (§3) only when the task is about that feature.

1. Pick your platform → read only that file

Platform	Read
Web / browser portal (default)	references/web-authentication.md + the quick start below
iOS native (app-to-app + SDK)	references/ios-integration.md
Android native (app-to-app + helper lib)	references/android-integration.md
Flutter	references/flutter-integration.md
React Native	references/react-native-integration.md

Loading rule (progressive disclosure): read the file for the platform you're working on and not the others — they're large and irrelevant across platforms. Same for the feature files in §3.

2. Platform-agnostic references (apply to every platform)

Need	Read
URLs — staging vs production, sandbox/POC creds	references/endpoints-and-environments.md
Get a client_id/client_secret, go live	references/onboarding-and-credentials.md
Scopes + what /userinfo returns (SOP1/2/3, visitors)	references/scopes-and-user-attributes.md
Errors — which code means what	references/troubleshooting-and-faq.md
Official UAE PASS button (brand rules)	references/login-button-and-design.md
SP use-case rules / assessment checklist	references/use-cases-and-guidelines.md

Web-specific extras: references/web-registration.md (let users create a UAE PASS account from your portal) · references/token-validation.md (verify a token on your backend) · references/user-linking.md (link a UAE PASS identity to an existing account).

3. Features (cross-platform) — load ONLY when the task is about them

Feature	Read
Digital signature / PDF signing	references/digital-signature.md
eSeal (organization seal)	references/eseal.md
Data sharing (consent-based)	references/data-sharing.md
Facial biometric transaction confirmation	references/facial-biometric.md

Web login — quick start (OAuth2 authorization-code flow)

The common case. Four steps; see references/web-authentication.md for annotated detail and references/endpoints-and-environments.md for the full URL table.

1. Authorize — redirect the browser to the authorization endpoint:

   GET https://stg-id.uaepass.ae/idshub/authorize
       ?response_type=code
       &client_id=<your client_id>
       &redirect_uri=<your callback, must match exactly>
       &scope=urn:uae:digitalid:profile:general
       &state=<random anti-CSRF value>
       &acr_values=urn:safelayer:tws:policies:authentication:level:low
       &ui_locales=en            # en | ar
   

2. Callback — UAE PASS redirects to redirect_uri?code=<code>&state=<state>. Verify state.
3. Token — exchange the code immediately (see gotchas):

   POST https://stg-id.uaepass.ae/idshub/token?grant_type=authorization_code&redirect_uri=<same>&code=<code>
   Authorization: Basic base64(client_id:client_secret)
   

   → { "access_token", "token_type": "Bearer", "expires_in", "scope" }
4. User info — GET https://stg-id.uaepass.ae/idshub/userinfo with Authorization: Bearer <token> → the user's profile JSON. End the session: GET .../idshub/logout?redirect_uri=<url>.

Production uses the same paths on https://id.uaepass.ae/idshub/....

Staging POC credentials (staging only): client_id=sandbox_stage, client_secret=sandbox_stage, callback = any URL. Real per-entity credentials are issued during onboarding.

Critical gotchas (read before coding)

• Use idshub endpoints, not trustedx-*. Current docs use stg-id.uaepass.ae/idshub/... / id.uaepass.ae/idshub/.... Older 2020 SDG PDFs show qa-id.uaepass.ae/trustedx-authserver/... — legacy; do not use them.
• The authorization code is single-use and very short-lived. Exchange it the instant the callback fires — no user interaction in between (else invalid_grant / expiredCode). Live docs conflict on the exact TTL (token page ~10s, POC guide 10min); assume the stricter bound.
• redirect_uri must be byte-identical in /authorize and /token (and registered with UAE PASS) — otherwise invalid_grant / redirectUriMismatch.
• Token params go in the POST query string, not a form body, with HTTP Basic client auth (base64(client_id:client_secret)) — not a textbook OAuth body. A default OAuth client will fail.
• Credentials are issued, not self-served. No developer signup: submit the "Authentication Integration Questionnaire" and UAE PASS provisions client_id/client_secret, scopes, and your registered redirect_uri. Use sandbox_stage only for staging POCs.
• Mobile is app-to-app. Native apps detect the UAE PASS app (Android pkg ae.uaepass.mainapp[.stg], iOS scheme uaepass[stg]://), hand off, and fall back to a WebView when it isn't installed. A mobile app can't hold a secret — see the platform file.
• Handle user types (SOP1/2/3) and visitors. SOP1 returns no Emirates ID number; visitors need extra scopes. See references/scopes-and-user-attributes.md.

Runnable sample (web)

assets/node-web-login-sample/ — a minimal Node.js + Express app implementing all four steps against the staging sandbox (two deps, ~200 lines):

cd assets/node-web-login-sample
cp .env.example .env        # defaults to staging + sandbox_stage creds
npm install && npm start    # → http://localhost:3000

Completing a real login needs a staging UAE PASS account + the staging UAE PASS app (see references/onboarding-and-credentials.md). Copy this app as a starting point, or port its server.js logic into your framework (Next.js route handlers, etc.). Requires Node ≥ 18 (global fetch).

Source & maintenance

References were consolidated from the live official docs at docs.uaepass.ae (current, GitBook; the idshub endpoints are authoritative), cross-checked against the 2020 SDG integration PDFs (legacy trustedx-* endpoints but useful extra detail) and the official iOS/Android sample apps. Flutter and React Native document community (unofficial) plugins plus the raw flow. When sources conflict, the live idshub docs win. To refresh from the latest docs, see MAINTAINING.md at the repo root.