Integrating UAE PASS as the federated authentication in WSO2 Identity Server 5.11.0

UAE PASS as the federated authentication in WSO2 Identity Server

In this blog our goal is to understand how we can leverage UAE PASS for authentication.

Before we dive in, let’s understand what is a UAE PASS. UAE PASS is a foundational platform to accelerate the transformation towards a digital based economy and digital society. This platform enables UAE PASS users to register and authenticate themselves in a system integrated with SPs (Service Providers) across the UAE.

UAE PASS Mobile App is a digital idSP for secure online identification. It is an easy and safe service that gives the user access to various authentication and signature services within the UAE.

Prerequisites

1. UAE PASS account
2. WSO2 Identity Server
3. Sample application (for testing)

Steps to integrate

1. Start the WSO2 Identity Server
2. Configure UAE PASS as the OIDC/OAuth federated authenticator and Claim Mapping in federated authenticator.
3. Configure Service Provider and Claim Mapping in service provider
4. Testing.

Before you begin

Some insights about the UAE PASS integration.

1. Testing Credentials

The below credentials can be used to test authentication and signing services offered by UAE PASS on Staging environment.

client: sandbox_stage

secret: sandbox_stage

The credentials will only work on staging environment and should not be used on production environment. For production environment you need to contact the UAE PASS and obtain the productions credentials.

2. Endpoints

Staging

┌───────────────┬────────────────────────────────────────────┐
│   Endpoint    │                    URL                     │
├───────────────┼────────────────────────────────────────────┤
│ Authorization │ https://stg-id.uaepass.ae/idshub/authorize │
│ Token         │ https://stg-id.uaepass.ae/idshub/token     │
│ User Info     │ https://stg-id.uaepass.ae/idshub/userinfo  │
│ Logout        │ https://stg-id.uaepass.ae/idshub/logout    │
└───────────────┴────────────────────────────────────────────┘

Production

┌───────────────┬────────────────────────────────────────┐
│   Endpoint    │                  URL                   │
├───────────────┼────────────────────────────────────────┤
│ Authorization │ https://id.uaepass.ae/idshub/authorize │
│ Token         │ https://id.uaepass.ae/idshub/token     │
│ User Info     │ https://id.uaepass.ae/idshub/userinfo  │
│ Logout        │ https://id.uaepass.ae/idshub/logout    │
└───────────────┴────────────────────────────────────────┘

Step 1:

Add the following configuration to the deployment.toml in the <IS_HOME>/repository/components/conf directory.

[authentication.endpoint]
enable_custom_claim_mappings = true

Start the WSO2 Identity Server.

Note: Before you begin make sure that the necessary Cross Origin Resource Sharing (CORS) is configured.

Step 2:

• Login to the admin console.
• Navigate to Identity ▸ Identity Providers and click Add.
• Enter the Identity Provider Name (e.g., UAE PASS)
• Click on Federated Authenticators and then again click on the OAuth2/OpenID Connect Configuration.
• Enter the UAE PASS configuration details.

+===================+============================================+
| Field             | Value                                      |
+===================+============================================+
| Enable            |                                            |
| OAuth2/           |                                            |
| OpenIDConnect     | true                                       |
+-------------------+--------------------------------------------+
| Default           | true                                       |
+-------------------+--------------------------------------------+
| Client Id         | sandbox_stage                              |
+-------------------+--------------------------------------------+
| Client Secret:    | sandbox_stage                              |
+-------------------+--------------------------------------------+
| Authorization     |                                            |
| Endpoint          |                                            |
| URL               | https://stg-id.uaepass.ae/idshub/authorize |
+-------------------+--------------------------------------------+
| Token             |                                            |
| Endpoint          |                                            |
| URL               | https://stg-id.uaepass.ae/idshub/token     |
+-------------------+--------------------------------------------+
| Callback Url      | https://localhost:9443/commonauth          |
+-------------------+--------------------------------------------+
| Userinfo          |                                            |
| Endpoint          |                                            |
| URL               | https://stg-id.uaepass.ae/idshub/userinfo  |
+-------------------+--------------------------------------------+
| Logout            |                                            |
| Endpoint URL      | https://stg-id.uaepass.ae/idshub/logout    |
+-------------------+--------------------------------------------+
| OpenID Connect    |                                            |
| User ID Location: |  User ID found in 'sub' attribute          |
+-------------------+--------------------------------------------+
| Additional        |                                            |
| Query Parameters: | scope=openid urn:uae:digitalid:            |
|                   | profile:general                            |
|                   | &acr_values=urn:safelayer:                 |
|                   | tws:policies:authentication:level:low      |
+-------------------+--------------------------------------------+

UAE PASS configuration

• Click on the Claim Configuration.
• Expand the Basic Claim Configuration
• Map the necessary user claim with the WSO2 Identity Servers Claim as UAE PASS has it’s own claims.
• Sample UAE PASS response as follows.

{
  "sub": "800F475AC0E7A9ED01B2D5D2C25A59B3",
  "userType": "SOP3",
  "fullnameAR": "سميث جون",
  "fullnameEN": "John Smith",
  "gender": "Male",
  "lastnameEN": "Smith",
  "nationalityAR": "الهند",
  "firstnameEN": "John",
  "idn": "784000000000000",
  "idType": "ID",
  "email": "john.smith@organization.com",
  "spuuid": "b1320896-fb2e-5140-baf0-fa915eb9be5d",
  "nationalityEN": "IND",
  "firstnameAR": "جون",
  "lastnameAR": "سميث",
  "acr": "urn:safelayer:tws:policies:authentication:level:high",
  "mobile": "9715555555555",
  "titleEN": "Dr.",
  "titleAR": ".د",
  "amr": [
    "urn:safelayer:tws:policies:authentication:adaptive:methods:mobileid",
    "urn:uae:authentication:method:verified"
  ]
}

IdP Claim mapping

• Click Register.

Step 3:

• Navigate to Identity ▸ Service Providers and click Add.
• Enter the Service Provider Name and click Register
• Configure the Inbound Authentication Configuration based on your application.
• Configure the Local & Outbound Authentication Configuration (e.g., select the UAE PASS as the federated authenticator or configure the authentication flow under the advanced configuration).
• Add the necessary claim under Claim Configuration.

SP Claim Mapping

• Select email as the Subject Claim URI.
• Click Update.

Step 4:

• Navigate to your application and click sign in with UAE PASS (only when multi option configured).
• You will be redirected to the UAE PASS Authentication page.
• Enter your UAE PASS ID and click Login.
• Now your mobile application for the UAE PASS will prompt for the authorization.

UAE PASS Authorization

• By providing the authorization via the mobile application you will be successfully signed into the service provider.

References

[1] https://docs.uaepass.ae/guides/authentication/web-application/introduction