Getting Started

Before starting you need to be authenticated, since the package is hosted within a private npm registry, the authentication steps are described before.

Authentication

First, you need to install the package using the following command:

npm i @tradinos/cms-backend-passport-uae-pass

🚦 Let’s Understand How This Package Works

⚙️ How It Works

We use a custom PassportStrategy that follows the standard OAuth2 flow, integrated seamlessly into our backend architecture.

---

🔁 1. Redirect to UAE PASS

Users are redirected to the official UAE PASS login page to authenticate using their national identity credentials.

🔐 2. Authorization Code Callback

After successful login, UAE PASS redirects the user back to your backend (via the configured callback URL) with an authorization code.

🔄 3. Token Exchange

Your backend uses this code to request an access token (and optionally a refresh token) from UAE PASS.

👤 4. Profile Retrieval

Once authenticated, the strategy fetches the user’s verified profile from UAE PASS — including full name, Emirates ID, mobile number, email, etc.

👥 5. User Sign-In

Based on the UAE PASS profile data, the user is either:

• Matched with an existing user in your system, or

• Automatically registered as a new user (if not found)

---

✅ This flow is built using PassportStrategy to ensure consistency with other auth mechanisms like JWT or Google OAuth in our TCB.

The options you can use with the package:

    const options: UAEPassOptions = {
      tokenURL: 'https://id.uaepass.ae/idshub/token',
      authorizationURL: 'https://id.uaepass.ae/idshub/authorize',
      clientID: 'sandbox_stage',
      clientSecret: 'sandbox_stage',
      callbackURL: 'https://cms.tradinos.com/auth/uaepass',
      userProfileURL: 'https://id.uaepass.ae/idshub/userinfo',
      scope:'',
      scopeseperator:' ',
      skipUserProfile:false
    }

Parameter	Description	Required/Optional	Type
tokenURL	This is the endpoint used to exchange the authorization code (received after login) for access and refresh tokens.	Optional	String and the default value is from Production documentation:https://docs.uaepass.ae/web-registration/endpoints
authorizationURL	The URL to which the user will be redirected to initiate the UAE PASS login. This is where they authenticate with their national digital identity.	Optional	String and the default value is from Production documentation:https://docs.uaepass.ae/web-registration/endpoints
clientID	The unique identifier for your application registered with UAE PASS. This tells UAE PASS which app is making the request.	Required	String
clientSecret	A secret key associated with your clientID, used to authenticate your app when exchanging the auth code for tokens. Keep this secure and don’t expose it in frontend code.	Required	String
callbackURL	The redirect URL where UAE PASS will send the user after successful login. This must match what you’ve configured in the UAE PASS developer console.	Required	String
userProfileURL	The endpoint used to fetch the authenticated user's profile information (e.g., full name, Emirates ID, phone, email). After getting the access token, your backend calls this to retrieve user data.	Optional	String and the default value is from Production documentation:https://docs.uaepass.ae/web-registration/endpoints
scope	A list of requested scopes (permissions) . Defaults are typically set, but can be customized to fetch specific data.	Optional	String
scopeseperator	Defines how multiple scopes are separated in the URL (e.g., ' ' (space) or ','). Default is a space (' ').	Optional	String
skipUserProfile	If set to true, skips fetching the user profile after login. This is useful if profile info is not needed or already available elsewhere. Default is false.	Optional	Bool default : false

We will see a full example in the next page =>