UAE PASS Authentication: A Production Architecture Guide

A UAE PASS login button is easy to demo. The production work sits behind it: binding the callback to the browser that started the request, exchanging a short-lived code without leaking a client secret, deciding which identity attributes to retain, and recovering when the identity provider or the user's phone is unavailable.

This guide turns the current UAE PASS web flow into an implementation plan for server-rendered applications and backend-for-frontend architectures. It focuses on authentication, not digital signatures or e-seals. Practical information only; it is not legal advice.

Start with the protocol you actually have

The UAE PASS web documentation describes an OAuth 2.0 authorization-code flow. A service provider redirects the browser to UAE PASS, receives a code at its registered callback, exchanges that code at the token endpoint, then calls the user-information endpoint with a bearer token.

UAE PASS publishes separate staging and production endpoints: authorization, token, user information and logout. Keep those environments in separate configuration records. Give each its own client ID, secret reference, callback allowlist and monitoring label. A production secret should never be usable by a staging deployment.

The documented token response has an access token with token_type set to Bearer and expires_in set to 3600. The documentation also says the authorization code must be used within 10 seconds. That is an operational constraint, not trivia. Your callback must complete the server-side exchange immediately; do not put the code on a queue or send it through a client-side analytics layer.

UAE PASS documentation says an ID token can be returned when the openid scope is requested. Do not assume every integration has the same scopes or token shape. Treat the approved onboarding configuration as the contract, then test the exact staging tenant you were issued.

Put an identity adapter between UAE PASS and your product

Do not scatter UAE PASS fields through the application. Put one adapter behind an internal interface:

interface NationalIdentityAdapter {
  beginLogin(input: { returnTo: string; locale: "en" | "ar" }): Promise<string>;
  finishLogin(input: { code: string; state: string }): Promise<VerifiedIdentity>;
  logout(input: { sessionId: string }): Promise<void>;
}

type VerifiedIdentity = {
  provider: "uae-pass";
  subject: string;
  assurance?: string;
  profileType?: "resident" | "visitor";
  attributes: Record<string, string>;
};

The adapter owns provider endpoints, token exchange, claim mapping and error translation. The rest of the product sees a stable internal subject and a small set of approved attributes. This makes a later SDK change, scope reduction or second national identity provider a contained migration rather than a rewrite.

Use the provider's durable subject as the external identity key. The user-information examples include sub, uuid, idn, Arabic and English names, nationality, mobile, email, acr and amr. Availability depends on scopes, account type and the attributes approved for the service provider. Never join accounts by mutable fields such as email, mobile number or display name.

Store an internal user ID and a mapping such as (provider, provider_subject). If an existing customer signs in with UAE PASS for the first time, link the identity only after an authenticated account-linking ceremony. Matching an email address is not enough.

Build the callback as a security boundary

Generate at least 256 bits of random data for state, store only a hash server-side, bind it to the initiating browser session and expire it quickly. The UAE PASS guide recommends state against CSRF. RFC 9700, the IETF's current OAuth security best practice, requires clients to prevent callback CSRF and recommends transaction-bound controls such as PKCE or a one-time state value.

Before exchanging the code, the callback should:

1. Require HTTPS and the exact registered callback path.
2. Look up the one-time transaction by a constant-time comparison of the state hash.
3. Reject missing, expired, reused or session-mismatched transactions.
4. Consume the transaction before making the token request.
5. Allow only a server-side returnTo value that was validated when login began.

Do not put an arbitrary post-login URL inside state and trust it later. That creates an open redirect. Store a short transaction identifier in the browser and keep the destination in server-side state, restricted to known local paths.

Use PKCE with S256 when the UAE PASS configuration assigned to your client supports it. RFC 9700 recommends PKCE even for confidential web clients because it protects the authorization code from interception and injection. If support is unclear, confirm it during onboarding rather than adding untested parameters to production requests. state remains useful for binding local application context even when PKCE is enabled.

Keep the client secret in a managed secret store and exchange the code only from a backend. Never ship it to a browser bundle, mobile app or edge log. Redact code, Authorization, access_token, mobile, email and Emirates ID values from logs. Record a request correlation ID, provider, stage, result category and latency instead.

Request fewer attributes

The UAE PASS attributes list separates citizen/resident and visitor profiles. It also shows that verified Emirates ID (idn) is not returned for visitors, while profileType and unifiedId support the visitor flow. Build explicit branches for those account types. A missing Emirates ID is not automatically an authentication failure.

Start the data design from the business decision. If the product only needs verified sign-in, a stable subject and assurance result may be enough. If a regulated onboarding process requires a legal name or identifier, document why each attribute is required, who can read it, how long it remains stored and how corrections are handled.

The UAE's Personal Data Protection Law applies controls to electronic processing and gives data subjects rights including correction of inaccurate personal data and restriction or cessation of processing in defined circumstances. Identity payloads should therefore pass through a field allowlist before persistence. Do not archive the full user-information response "in case it is useful later."

A useful mapping table belongs in code and in the privacy design:

Do not interpret the presence of a field as permission to use it for unrelated marketing, profiling or account discovery.

Sources: UAE PASS web integration documentation and IETF RFC 9700. Reporting period: documentation checked 13 August 2026. Visual by SultanByte.

Separate authentication from your session

The UAE PASS access token is for calling UAE PASS resources. It is not your product session. After validating the response and mapping the subject, issue a fresh application session with its own identifier, expiry, revocation controls and cookie policy.

Use Secure, HttpOnly and an appropriate SameSite setting on the session cookie. Rotate the session ID after login. Keep provider tokens out of the browser and discard them when the user-information call is complete unless a documented feature requires further provider access.

OpenID Connect Core requires clients that consume ID tokens to validate the issuer, audience, signature and expiry; a nonce must also match when one was sent. OAuth access tokens and ID tokens have different jobs. Do not treat a bearer access token as proof of identity merely because it is a string returned by the token endpoint.

Assurance is also separate from authorization. A verified UAE PASS identity does not tell your product whether the person may approve a company payment, view a medical record or administer a tenant. Resolve those permissions from product-owned roles and current business data.

Make failure a designed path

National identity login depends on the user's browser, phone, network, the UAE PASS service and your own callback. Design for each part to fail without creating an account takeover route.

Use a short, bounded retry for token and user-information calls only when the failure is clearly transient. Never replay an authorization code after an ambiguous token-exchange result; start a new authorization transaction. Give users a clean restart button and preserve non-sensitive form progress.

Keep a break-glass login method for support staff and operational administrators, protected by phishing-resistant authentication and strong audit controls. Do not quietly give every customer a weak password fallback, because attackers will choose the weakest route. NIST SP 800-63B recommends phishing-resistant options at higher assurance levels and defines reauthentication timeouts according to risk.

Your runbook should cover provider timeout, mobile approval timeout, invalid state, code expiry, denied consent, missing required attributes, account-link conflict and local session failure. Support agents need safe result codes, not raw identity payloads.

Test more than the happy path

The UAE PASS prerequisites call for a staging user and staging mobile app. Use them to test a matrix that includes Arabic and English UI, citizen/resident and visitor profiles where approved, browser refresh on the callback, duplicate callbacks, two parallel login tabs, expired state, an expired code, a changed callback URI, provider denial and application-session failure after successful provider authentication.

Add automated tests around your adapter. Mock the provider boundary, but keep a scheduled staging smoke test for the real redirect and token flow. Alert separately on authorization abandonment, callback rejection, token failures, user-information failures and local session creation. A single "login failed" metric hides the part that needs fixing.

Before launch, verify the exact callback allowlist, approved scopes, production endpoints, secret rotation process, privacy notice, retention schedule, support playbook and rollback switch. The UAE PASS documentation version history shows continued changes through June 2026, so assign an owner to review release notes and rerun staging tests after provider updates.

A sound integration is deliberately boring: the browser carries a one-time code, the backend performs the sensitive exchange, the product stores only what it needs, and failures return the user to a safe starting point. That structure matters more than the login button.