UAE PASS integration guide: what wiring the national identity provider actually takes

Digital transformation

UAE PASS is not social login. It is a national identity provider with a registration and assessment process, and the teams that treat it as "add OAuth, done" end up stuck on two things: getting through onboarding, and mapping a UAE PASS subject onto the customer record they already own. This guide walks both, with the real endpoints, scopes and attribute behaviour, so you can scope the work before you promise a launch date.

Every digital transformation programme we look at in the UAE has the same identity bottleneck. A bank-adjacent fintech, a telco, a university, a hospital group and a contractor bidding on B2G portals all re-key the same customer data: Emirates ID copies in email, passports in WhatsApp, signatures on paper scanned back into the CRM. Then the AI programme stalls behind it, because no customer-facing AI service can legally act on an identity nobody verified.

UAE PASS fixes the verification step, but it does not fix itself. It is the UAE's national digital identity and signature platform, and integrating it is a project with an approval gate, a staging assessment and real mapping work on your side. This is a UAE PASS integration guide for product and digital leads: what the onboarding actually demands, what the OAuth2 flow looks like in practice, how to wire it into the IAM you already run, how to link a UAE PASS identity to your CRM without creating duplicate customers, and when to buy a verification aggregator instead of building direct.

What UAE PASS is, and what it is not

The official UAE PASS overview on u.ae describes it as the first national digital identity and signature solution, launched at Gitex 2018 as a collaboration between Digital Dubai, TDRA and the Department of Government Enablement. Face recognition registers a verified account in under 5 minutes, the app carries a digital document vault, and it signs documents digitally. Digital Dubai reported over 12 million registered users, and the TDRA service page lists 15,000+ services reachable through 363 service providers (figures compiled in the Didit guide).

The point that matters for your architecture: the identity that arrives at your back end is government-verified against the Emirates ID, mobile and email, and the login is confirmed in the app with a phishing-resistant number match between browser and phone. That is a different trust object from a Google or Apple login.

It is also tiered. UAE PASS accounts come in three assurance levels:

Sources: UAE PASS account types and attributes and the account-level summary in the Didit guide. The practical consequence: for anything resembling know-your-customer, SOP1 identifies nobody. You need SOP2 or SOP3, which is exactly what the Central Bank of the UAE's guidance on digital identification for customer due diligence (in force 31 October 2022) expects when it names the UAE PASS app as a route for verifying the Emirates ID.

The onboarding path is the first thing teams underestimate

You cannot self-serve production credentials. The UAE PASS initiation phase documentation sets out a seven-step process, and it is worth reading before you write a line of code:

1. Raise an integration request on the UAE PASS Developer Portal (uaepass.ae/developers), stating whether you are a government or private entity.
2. Private entities provide a valid UAE trade licence. Your emirate's onboarding team picks up the request.
3. You receive a welcome email with reference documentation and the required questionnaires.
4. You fill in a questionnaire per feature: Authentication, Digital Signature, e-Seal (plus an e-Seal certificate request form if you need e-Seal), Hash Signing, and Data Sharing Authorization.
5. You submit a workflow diagram of the UAE PASS user journey, referencing a numbered use case (UC X.X.X) from the use-case guidelines.
6. You submit UI mockups (wireframes) of the journeys where UAE PASS appears.
7. The onboarding team evaluates and approves the use case. Deviations from the standard use-case guidelines need management approval and, as the docs put it, can extend processing time.

Only after approval do you get staging credentials. You build and test against staging, then the onboarding team assesses your build on staging before go-live. The use-case flow diagram you submitted in step 5 is the reference for that assessment, so design it honestly rather than drawing something pretty.

Three details teams consistently miss:

• Staging and production are separate credential sets and separate hosts. Staging is stg-id.uaepass.ae; production is id.uaepass.ae. Testing also needs the staging UAE PASS mobile app and a test user with a valid Emirates ID (see the prerequisites in the SuperUaePass reference implementation).
• There is no published lead time. The FAQ states no charges for integration, but no fee schedule or timeline beyond use-case approval and staging assessment is published. Plan backwards from your launch date and start the portal request in the first week, not the last.
• Scope your questionnaire to what you will actually use. Authentication alone is a smaller review than Authentication plus Digital Signature plus Data Sharing Authorization. Each feature is a separate questionnaire and a separate approval surface.

The OAuth2 flow, concretely

Under the hood this is OAuth 2.0 authorization code flow, documented in the UAE PASS web application guide and the service provider authentication integration guide (OAuth, DP 2.0). The Oracle Cloud integration walkthrough summarises it in three phases: login (user confirms in the app), exchange (your back end swaps the code for a token), profile (your back end fetches verified attributes).

The authorization request against staging looks like this, straight from the docs:

https://stg-id.uaepass.ae/idshub/authorize?response_type=code&client_id=sandbox_stage&scope=urn:uae:digitalid:profile:general&state=HnlHOJTkTb66Y5H&redirect_uri=https://stg-selfcare.uaepass.ae&acr_values=urn:safelayer:tws:policies:authentication:level:low

Parameters you must get right: client_id and redirect_uri must match your registration exactly; state is your CSRF defence and must be validated on return; acr_values sets the authentication level; ui_locales (en or ar) controls the login page language. If you are onboarding visitors as well as residents, the docs require extra scopes on the first call: urn:uae:digitalid:profile:general urn:uae:digitalid:profile:general:profileType urn:uae:digitalid:profile:general:unifiedId.

The endpoints, from the reference implementation and docs:

After the user confirms the push notification in the app (the browser shows a numeric code and the app asks them to tap the matching number), UAE PASS redirects back to your redirect_uri with code and state. Your server exchanges the code at /idshub/token, then calls /idshub/userinfo with the access token. The token response carries access_token, token_type: Bearer, scope and expires_in (the FAQ gives the production token lifetime as 3,600 seconds). A minimal server-side configuration, from the SuperUaePass repository:

{
  "UaePass": {
    "BaseUrl": "https://stg-id.uaepass.ae",
    "ClientId": "your-client-id",
    "ClientSecret": "your-client-secret",
    "RedirectUri": "https://your-app.com/callback",
    "Scope": "urn:uae:digitalid:profile:general",
    "Environment": "Staging",
    "ResponseType": "code"
  }
}

Three protocol habits worth enforcing in code review: generate and store state in server-side session and reject mismatches; keep tokens on the server and never ship them to the browser; and call UAE PASS logout, not just your own session clear, so the mobile session ends too. One more tip from the Oracle write-up that we would repeat: validate the whole three-step flow in Postman against staging before you touch any IAM configuration. The staging environment faithfully mirrors production.

Put it behind your enterprise IAM, do not hand-roll auth

Most organisations we meet already run an identity layer: Oracle OCI IAM for Oracle Fusion estates, Keycloak, Microsoft Entra ID, or a CIAM platform. UAE PASS should be wired in there as a federated identity provider, not coded into each application.

The Oracle walkthrough is the clearest public example. OCI IAM ships social connectors for Google, Facebook, Microsoft and LinkedIn, but UAE PASS's custom authorization parameters and UAE-specific attribute names do not fit the generic OIDC connector. The engineer registered a custom social IdP through the /admin/v1/SocialIdentityProviderMetadata REST API with a UAEPASS_2 provider template, defined in JSON how OCI IAM should behave at each phase of the OAuth flow, and enabled just-in-time provisioning so first-time logins create the account automatically. The attribute mapping was table-driven:

The same shape works in Keycloak (identity provider plus mapper rules) or Entra ID (external identity provider with claims mapping). The point is architectural: your applications keep their existing sessions, roles and audit logs; UAE PASS becomes one upstream source of verified identity; and you configure the quirk handling in one place instead of five codebases.

How the three routes compare:

The second thing you underestimate: mapping identity to your CRM

Authentication is a fortnight. Identity resolution is where the programme actually spends its time. The UAE PASS attributes list gives you sub (of the form UAEPASS/<uuid>), uuid, userType (the assurance level), verified mobile and email, English and Arabic names, and, only at SOP2 and SOP3, idn (the verified Emirates ID number), full names, nationality and gender. Two gaps to design around: the published list contains no date of birth, address or portrait, and visitors registered with a passport or GCC national ID never return idn, even at SOP3. Visitor profiles instead carry profileType (1 for citizens and residents, 2 for visitors) and unifiedId.

Worked example: a Dubai healthcare group adds "Continue with UAE PASS" to patient onboarding, serving a CRM that already holds 250,000 patient records built over a decade of scanned forms.

1. The patient signs in and returns at SOP3 with idn, fullnameEN, fullnameAR, nationalityEN, mobile, email, uuid.
2. Your identity service matches on idn first: the Emirates ID number is the only attribute that can be matched to the legacy record with confidence. If the legacy record has a properly stored Emirates ID field, you link, you do not create.
3. If idn is absent (the patient is at SOP1, or is a visitor), you cannot treat this as a verified identity. You downgrade to a lead record, or route to the document fallback. Never write an unverified idn into the CRM field your compliance reports count on.
4. If idn is present but unmatched, check for an existing record by UAE PASS uuid, then by verified mobile and email as a last resort with human review, because a shared family mobile number will otherwise merge two patients.
5. On link or create, store uuid as an external identity key on the customer record, store userType as the assurance level at the time of capture, and timestamp the attributes you took from UAE PASS. One customer, one primary identity key, one provenance trail.
6. Re-authentication later refreshes attributes and can raise assurance (a patient who first appeared at SOP2 and returns at SOP3 after face verification). Write the higher assurance, keep the history.

The matching logic, sketched as pseudocode so it can go into a service rather than a stored procedure:

def resolve_customer(profile):
    if profile.user_type == "SOP1":
        return Lead.from_contact(profile)  # not a verified identity

    if profile.idn:
        hit = crm.find_by_emirates_id(profile.idn)
        if hit:
            return crm.link_external_id(hit, provider="UAEPASS",
                                        external_id=profile.uuid,
                                        assurance=profile.user_type)
        hit = crm.find_by_external_id(provider="UAEPASS", external_id=profile.uuid)
        return hit or crm.create_from(profile, verified_fields=["idn", "fullnameEN",
                                          "fullnameAR", "nationalityEN", "mobile", "email"])

    return route_to_document_check(profile)  # visitors, missing idn

Do this once, in an identity service or in the IAM layer's JIT provisioning hooks, not in each application's login controller. The same resolved customer object then feeds onboarding, e-invoicing, the B2G portal profile and, later, the personalisation layer of any customer-facing AI service.

eKYC data, eSignature, consent and data residency

Four compliance surfaces sit on top of the login, and the questionnaires you filled in during onboarding are the map of which ones you touched.

eKYC. At SOP2 and SOP3 you receive a verified Emirates ID number and names, which is what the CBUAE guidance means when it tells licensed financial institutions they may use the UAE PASS application or the ICP validation gateway to verify the Emirates card and should keep the digital verification record. What you do not receive is a date of birth or a portrait. Any age-gated journey needs a document fallback, and this matters increasingly: Federal Decree-Law No. 26 of 2025 on Child Digital Safety introduces age verification obligations with effect from January 2026 and a one-year compliance window (summary in the Didit guide, referencing Baker McKenzie).

eSignature. Signing is a separate feature with its own questionnaire. SOP2 gives an advanced signature, SOP3 a qualified one, covering PAdES, CAdES and XAdES formats. Your job on the receiving side is the audit trail: retain the signed artefact, the verification record and the timestamped consent, in a form you can reproduce in a dispute. Hash signing and e-Seal are additional features with their own questionnaires, and e-Seal additionally needs a certificate request form.

High-risk confirmation. UAE PASS offers facial biometric confirmation for high-risk transactions, but that capability requires special approval in onboarding. If your journey depends on it, state that explicitly in the use-case diagram.

Consent, session and residency. Generate state per attempt, validate it on return, end sessions at both ends, and store tokens server-side. Under Federal Decree-Law No. 45 of 2021 on personal data protection, the attributes you receive are personal data with a purpose limitation; the CBUAE guidance goes further for financial institutions, restricting transfer and storage of personal data including Emirates ID copies outside the UAE except as Articles 22 and 23 of that law permit. If your CRM or data warehouse is hosted outside the UAE, resolve that before go-live, not after.

When a verification aggregator is the right answer

A verification aggregator (identity verification vendors that bundle document checks, liveness and screening behind one API) is worth considering in three situations: you operate in several countries and want one integration contract; a meaningful share of your users are visitors, minors or elderly customers whom UAE PASS cannot serve alone; or your timeline cannot absorb the use-case approval cycle. An aggregator gives you an eID-first flow with a document fallback (NFC chip reading, liveness, face match) already assembled, and typically bundles AML screening.

Read the fine print, though. The UAE PASS documentation describes no intermediary programme: if you integrate UAE PASS through a provider, the provider's own agreement must cover your use case, and prices are set by the provider. For scale, one vendor's published pricing was $0.33 per full KYC check and $0.20 per AML screening, and that vendor does not operate UAE PASS today (it is on their roadmap, with document checks covering UAE users). So an aggregator for UAE residents usually means a document verification fallback, not UAE PASS without the onboarding. Direct UAE PASS remains the strongest resident path, and the UAE PASS FAQ indicates no integration charges.

The combined design most UAE programmes converge on: UAE PASS first for residents at SOP2 and SOP3, document verification as the visible second option, and other channels (service centre, authorised representative) for minors and the elderly, as the FAQ advises.

What to do next

If you are scoping this week, work through this order:

1. Decide the features you need now (authentication only is fastest; signature and data sharing each add questionnaires) and name your use case against the UC X.X.X catalogue.
2. Raise the Developer Portal request with your trade licence, and book the questionnaire and mockup work into the plan as real tasks, not admin.
3. Stand up a staging client and run the full flow in Postman before any framework work: authorize, token, userinfo, logout.
4. Choose the integration route from the table above: brokered through your existing IAM unless you have a single small app and no IAM.
5. Build the identity resolution rules (match on idn, one external key per customer, assurance level stored) in one service, then reuse it everywhere.
6. Decide the fallback: document verification vendor, service centre, or both, and check where every attribute lands for data residency.

Azrty is a UAE company based in Dubai. Our own team in the UAE does the consulting, the deployment and the support for our clients. If identity plumbing is the bottleneck blocking your wider programme, that is central to our digital transformation work. If the reason you are doing this now is that customer-facing AI is queued up behind it, start with an AI strategy engagement so the identity foundation gets built for the services you actually plan to launch.

https://www.azrty.com/blog/uae-pass-integration-guide-what-wiring-the-national-identity-provider-actually-t

<a href="https://www.azrty.com/blog/uae-pass-integration-guide-what-wiring-the-national-identity-provider-actually-t">UAE PASS integration guide: what wiring the national identity provider actually takes</a> (Azrty)