UAE PASS Integration with Next.js and Node.js SaaS Apps

UAE PASS integration can give a Next.js or Node.js application a trusted sign-in flow for customers across Dubai, Abu Dhabi, Sharjah and the wider UAE. It is more than another social-login button. UAE PASS is the national digital identity platform, and its developer documentation covers authentication, verified identity data, digital signatures and other government-backed services.

For a SaaS team, the difficult part is not drawing the button. The real work is secure OAuth handling, matching an identity to the correct local account, protecting tenant boundaries, supporting corporate users and passing the UAE PASS assessment before production.

I have built authentication, role permissions and multi-tenant workflows in production SaaS products. I have not presented UAE PASS as a past client implementation. Instead, this guide applies those real engineering lessons to the official UAE PASS requirements and shows how I would structure a production integration.

This article covers the web authentication flow, a practical Next.js and Node.js architecture, safe account linking, testing, deployment and optional digital signing. Endpoint details and approval requirements can change, so confirm them in the current official UAE PASS documentation before shipping.

What UAE PASS integration means for a UAE SaaS application

UAE PASS lets an approved service provider redirect a user to UAE PASS for authentication and receive identity information after consent. The web flow follows OAuth 2.0 concepts: the application requests authorization, receives a short-lived authorization code at a registered callback URL, exchanges that code for an access token and then calls the user-information endpoint.

UAE PASS should not replace your authorization model

A successful UAE PASS callback should never automatically make someone a company administrator. Your database remains responsible for organisations, memberships, roles and permissions. The identity returned by UAE PASS should be mapped to a local user, while access to a tenant should come from an invitation, an approved corporate relationship or another explicit business rule.

Keep UAE PASS and local login independent

The official standard implementation guidance says UAE PASS login and the service provider's existing login should work independently. That supports a gradual rollout and gives approved users another route when a particular business process still needs local credentials.

Do not silently merge accounts because two profile names look similar. Link an existing verified local account only through a unique, trusted attribute and store the UAE PASS UUID as the stable external identifier. If there is no safe match, ask the user to authenticate the existing account or complete an approved linking process.

Official UAE PASS onboarding, staging and production

A production integration starts with organisational onboarding, not an API key copied from a public dashboard. The service provider submits its use case, receives approval and staging credentials, builds the integration, tests it and goes through an assessment before production access. UAE PASS publishes developer toolkits, demonstrations and onboarding material on its developer portal.

Prepare a short, exact use-case description before development. Explain who signs in, what the application does with the identity, which attributes are required, whether accounts are linked, and whether the flow includes personal or corporate services. A vague request creates questions later because reviewers need to understand the complete user journey.

Register callback URLs carefully

The callback, also called the redirect URI, is where UAE PASS returns the browser after the user approves or rejects authentication. Staging and production use different URLs and credentials. Treat every registered URI as an exact allow-listed value.

For example, staging might return to https://staging.example.ae/api/auth/uaepass/callback, while production returns to https://example.ae/api/auth/uaepass/callback. Do not accept a redirect destination supplied freely by the browser. An open redirect can turn a trusted login flow into a phishing route.

Credentials are tied to the approved channel and use case. The UAE PASS guidance warns against reusing credentials between web and mobile implementations. Keep each environment's client ID and secret in a managed secret store, never in browser JavaScript, source control or a public environment file.

Design for English and Arabic

The authorization request supports locale selection, including English and Arabic. The login button, consent explanation, error messages and return journey should stay understandable in the selected language. For UAE users, Arabic support is part of a complete product experience rather than an SEO phrase added to a page.

Secure UAE PASS OAuth 2.0 flow in Next.js and Node.js

I would keep the OAuth exchange on the server. Next.js can render the login interface and expose server-side route handlers, while a dedicated Node.js API can own the integration in a larger system. In both cases, the browser should only carry the authorization request, a temporary code and secure session cookies. It should never receive the client secret.

1. Start login and protect the request with state

When the user chooses UAE PASS, generate a cryptographically random state value. Store it in an encrypted, HTTP-only, secure, same-site cookie or in a short-lived server session. Add the same value to the authorization request.

The official guide recommends state to protect against cross-site request forgery. On the callback, compare the returned value with the stored value using a safe equality check and reject missing, expired or mismatched requests. Delete the state after one use.

import crypto from 'node:crypto'

export async function startUaePassLogin(request, response) {
  const state = crypto.randomBytes(32).toString('base64url')
  await saveTemporaryState(response, state, { maxAgeSeconds: 300 })

  const authorizeUrl = new URL(process.env.UAEPASS_AUTHORIZE_URL)
  authorizeUrl.searchParams.set('response_type', 'code')
  authorizeUrl.searchParams.set('client_id', process.env.UAEPASS_CLIENT_ID)
  authorizeUrl.searchParams.set('redirect_uri', process.env.UAEPASS_REDIRECT_URI)
  authorizeUrl.searchParams.set('scope', 'urn:uae:digitalid:profile:general')
  authorizeUrl.searchParams.set('state', state)
  authorizeUrl.searchParams.set('ui_locales', 'en')

  response.redirect(authorizeUrl.toString())
}

This is an architectural example, not a copy-paste substitute for the latest UAE PASS contract. Use the scope, URLs, authentication method and parameters assigned to the approved application.

2. Exchange the authorization code on the server

The callback receives a temporary code. Before exchanging it, validate state, reject unexpected query parameters and handle the user's denial cleanly. Send the code to the official token endpoint from the backend using the registered redirect URI and assigned client credentials.

3. Retrieve identity data and create a local session

Use the access token with the official user-information endpoint. Validate the response before touching the database. Required fields should be present, types should be correct and the account's verification level must satisfy the approved use case.

Look up the stored UAE PASS UUID. If it already maps to a user, create a local application session. If it does not, follow the approved registration or account-linking flow. Do not use the access token as your application's long-lived session. Issue your own short-lived, secure session cookie and apply the same session rotation and logout rules used by the rest of the product.

The official endpoint reference separates authorization, token, user-information and logout operations. Keeping those responsibilities separate in code makes security reviews and testing easier.

Account linking for individuals, companies and multiple tenants

Account linking is where many identity integrations become risky. Email addresses can change, names can be transliterated differently and phone numbers may have formatting differences. The UAE PASS UUID is the external identity key intended for a durable mapping.

A simple data model could include users, external_identities, organisations and memberships. The external identity record stores the provider name and UUID. Memberships connect the local user to a tenant and role. Add a unique database constraint on the provider and UUID so two local users cannot claim the same UAE PASS identity.

Never trust tenant information from the browser

If a login starts from a company-specific page, the browser may send a tenant slug. Treat it only as a requested context. After authentication, confirm on the server that the mapped user has an active membership for that tenant. Otherwise show a safe selection screen or deny access.

Corporate UAE PASS accounts need explicit rules

Corporate profiles introduce another layer because a person can act in relation to an organisation. The official corporate-account guidance describes verification and mapping considerations. Your product should decide whether it trusts only verified corporate relationships, what happens when a relationship changes and how often the status must be refreshed.

Do not link a verified local company account to an unverified external profile. Store enough information to explain why access was granted, but avoid copying identity attributes that the application does not need. Access should be reviewable and revocable by authorised company administrators.

Production security, testing and UAE PASS assessment

A good login demo is not evidence that the integration is production-ready. Test the full journey: new registration, existing-account linking, returning login, denial, expired state, reused callback, invalid code, token timeout, missing profile fields, disabled local membership, Arabic locale, logout and account recovery.

Add rate limits to login-start and callback routes. Use HTTPS everywhere, secure HTTP-only cookies, strict redirect validation and a content security policy. Monitor unusual callback failures and repeated state mismatches. Avoid putting personal identity data into analytics events, error trackers or URLs.

Build an auditable identity trail

For sensitive changes, record who performed the action, which tenant was active, when it happened and the result. Do not store tokens in audit logs. If support staff can change identity links, require stronger permissions and record the old and new mapping.

Review data retention with the organisation's legal and privacy advisers. Collect only attributes required for the approved use case. UAE PASS verification does not remove the application's responsibility to protect personal data.

Prepare evidence for go-live

The assessment phase checks the implemented use case before production. Keep an environment checklist, screenshots or recordings of the approved journey, test cases, callback URLs, error handling and security controls. Resolve staging shortcuts before review: shared test credentials, verbose token logs and bypassed permission checks have no place in production.

Use feature flags to enable UAE PASS per tenant or customer group. Start with a controlled audience, watch login success and failure categories, then expand. Keep the existing login path available where the approved product design requires it.

Optional UAE PASS digital signatures

Authentication can be the first phase, with digital signatures added only when the business process needs signed documents. UAE PASS documents different signing assurance levels and provides flows for signing documents after authentication.

Its hash-signing option lets an organisation send a document hash rather than the complete PDF outside its premises. UAE PASS signs the hash, and the organisation embeds the result back into the document. The official hash-signing guide explains the high-level process.

Signing should remain separate from login in the application architecture. Authentication establishes the user session; a signing request has its own document ID, consent journey, status, expiry and audit evidence. Never assume that a logged-in user automatically approves a document.

UAE PASS integration checklist for a SaaS team

• Define the exact personal or corporate use case.
• Apply for onboarding and obtain staging credentials.
• Register exact staging and production callback URLs.
• Keep web, mobile and production credentials separate.
• Run the OAuth code exchange only on the server.
• Generate, store and validate a one-time state value.
• Store the UAE PASS UUID as the external identity key.
• Keep local tenant memberships and permissions separate.
• Support English and Arabic authentication journeys.
• Test denials, expired requests, retries and disabled users.
• Protect logs, tokens and returned personal information.
• Complete the UAE PASS assessment before production launch.

Practical takeaway

A secure UAE PASS integration is an identity and authorization project, not a login-button task. The strongest design keeps secrets on the server, validates every OAuth request, maps the UAE PASS UUID safely, enforces tenant permissions locally and gives corporate access its own explicit rules.

For a Next.js or Node.js SaaS product serving Dubai, Abu Dhabi, Sharjah or customers throughout the UAE, the result can be a simpler and more trusted onboarding journey. The implementation still needs disciplined security, privacy review, staging evidence and official production approval.

If you are planning a UAE SaaS platform, customer portal or secure Node.js integration, contact me to discuss the architecture.