Common Integration Issues

The purpose of this is to explain the integration process and issues faced by SP’s during their integration.

Authentication Flow

  1. Entity has to hit UAEPASS authentication url for getting the access code.

Authentication URL sample: https://stg-id.uaepass.ae/idshub/authorize?redirect_uri=your redirect url&client_id=your client id&state=ShNP22hyl1jUU2RGjTRkpg==&response_type=code&scope=urn:uae:digitalid:profile:general&acr_values=urn:safelayer:tws:policies:authentication:level:low&ui_locales=en

2. Above url redirects user to login with UAEPASS, here user gives his mobile number. He will receive push notification in his mobile. Once user confirms the push notification in his mobile, Entity gets the access code.

3. By using that access code , entity has to generate the token by calling the token API (below link)

https://qa-id.uaepass.ae/idshub/token?grant_type=authorization_code&redirect_uri= your redirect url&code=paste the access code here. Authentication here is basic auth with client credentials(Already shared staging client credentials).

4. From above url, entity receives bearer token. By using that bearer token, entity has to call https://qa-id.uaepass.ae/idshub/userinfo API to get the user details. If the user is SOP3, below are the 18 attributes which you get from this API call.

  • uuid (user unique id)

  • userType

  • fullnameEN

  • fullnameAR

  • firstnameEN

  • firstnameAR

  • lastnameEN

  • lastnameAR

  • nationalityEN

  • nationalityAR

  • gender

  • mobile (2)

  • email

  • idType (1)

  • idn(emirates ID)

  • spuuid1 (smart pass uuid)

  • titleEN (1)

  • titleAR (1)

Note:

  1. Available only for applicable users

  2. Available for all users unless verified via OTP in another profile

Authentication Issues

1. Consumer Key not found:

Resolution: This error appears when client is not registered in node6 server. Provide the client id, secret and redirect URI to respective onboarding team and get it configured in node6 server, incase of existing integration with UAEPASS or get a new client id, and secret from onboarding team by proving your redirect URI.

2. Callback URL does not match:

Resolution: Validate the redirect uri configured in UAE PASS and the URL used in the authorization and token request.

3. Invalid Scope:

Resolution: Make sure that SP is passing correct scope in authentication URL.

4. Authentication URL Format

Web:

Staging:

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

Production:

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

Mobile:

Staging:

https://stg-id.uaepass.ae/idshub/authorize?response_type=code&client_id={client_id}&scope=urn:uae:digitalid:profile:general&state=HnlHOJTkTb66Y5H&redirect_uri={redirect_uri}&acr_values=urn:digitalid:authentication:flow:mobileondevice .

Production:

https://id.uaepass.ae/idshub/authorize?response_type=code&client_id={client_id}&scope=urn:uae:digitalid:profile:general&state=HnlHOJTkTb66Y5H&redirect_uri={redirect_uri}&acr_values=urn:digitalid:authentication:flow:mobileondevice

5. Invalid grant or expired code:

Resolution: This error appears when passing the expired code to token generation call. The authentication code received from authorization url should be utilized by SP within 10 seconds.

6. Invalid basic header authentication

Resolution: This error appears when SP is not passing the client id or secret properly as configured in server.

7. Callback url mismatch while calling the token generation url:

Resolution: Please make sure that SP passes the same redirect url in authentication and token generation calls.

8. Internal Server Error

Resolution: Please make sure that SP is passing the header Content-Type as multipart/form-data in token generation call.

9. Access token validation failed:

Resolution: Please make sure that SP is passing the token to user profile API using header Authorization as Bearer {token}.

10. If SP is facing any issues in mobile app-to-app integration, please make sure that you configure proper xml file in node 6.

11. HTTP errors:

HTTP Status CodeDescription

200

Success and response is recieved

204

No Content

400

Not all required parameters provided

405

Method not allowed. Invalid method sent for calling the API

401

Unauthorized, Invalid or no credentials provided

403

Forbidden. Invalid credentials i.e. Wrong username or passwrod

404

Not Found

500

Server Error

503

Service Under Maintenance

12. Steps for Mobile App-App Integration:

  • Authorization call:

https://stg-id.uaepass.ae/idshub/authorize?response_type=code&client_id={client_id}&scope=urn:uae:digitalid:profile:general&state=HnlHOJTkTb66Y5H&redirect_uri={redirect_uri}&acr_values=urn:digitalid:authentication:flow:mobileondevice

  • Deep link url received from uaepass

uaepass://digitalid-users-ids/signatures/capTPqaTB648aqBdXHkL?successurl=https%3A%2F%2Fqa-ids.uaepass.ae%2Fauthenticationendpoint%2FmobileWaiting.jsp%3Fstatus%3Dsuccess%26sessionDataKey%3D5c406d59-40af-4328-841b-25cfaf41c7ee%26relyingParty%3Duaedds_mob_stage&failureurl=https%3A%2F%2Fqa-ids.uaepass.ae%2Fauthenticationendpoint%2FmobileWaiting.jsp%3Fstatus%3Dfailure%26sessionDataKey%3D5c406d59-40af-4328-841b-25cfaf41c7ee%26relyingParty%3Duaedds_mob_stage

  • Save the success and failure urls in different variables

Successvar1: https%3A%2F%2Fqa-ids.uaepass.ae%2Fauthenticationendpoint%2FmobileWaiting.jsp%3Fstatus%3Dsuccess%26sessionDataKey%3D5c406d59-40af-4328-841b-25cfaf41c7ee%26relyingParty%3Duaedds_mob_stage

failurevar2: https%3A%2F%2Fqa-ids.uaepass.ae%2Fauthenticationendpoint%2FmobileWaiting.jsp%3Fstatus%3Dfailure%26sessionDataKey%3D5c406d59-40af-4328-841b-25cfaf41c7ee%26relyingParty%3Duaedds_mob_stage

  • Change uaepass to uaepassstg

uaepassqa://digitalid-users-ids/signatures/capTPqaTB648aqBdXHkL?successurl=https%3A%2F%2Fqa-ids.uaepass.ae%2Fauthenticationendpoint%2FmobileWaiting.jsp%3Fstatus%3Dsuccess%26sessionDataKey%3D5c406d59-40af-4328-841b-25cfaf41c7ee%26relyingParty%3Duaedds_mob_stage&failureurl=https%3A%2F%2Fqa-ids.uaepass.ae%2Fauthenticationendpoint%2FmobileWaiting.jsp%3Fstatus%3Dfailure%26sessionDataKey%3D5c406d59-40af-4328-841b-25cfaf41c7ee%26relyingParty%3Duaedds_mob_stage

  • Change the success and failureurl as below.

uaepassstg://digitalid-users-ids/signatures/capTPqaTB648aqBdXHkL?successurl=dds%3A%2F%2Fuaedds.com%3Furl%3Dhttps%3A%2F%2Fqa-ids.uaepass.ae%2Fauthenticationendpoint%2FmobileWaiting.jsp%3Fstatus%3Dsuccess%26sessionDataKey%3D5c406d59-40af-4328-841b-25cfaf41c7ee%26relyingParty%3Duaedds_mob_stage&failureurl=dds%3A%2F%2Fuaedds.com%3Furl%3Dhttps%3A%2F%2Fqa-ids.uaepass.ae%2Fauthenticationendpoint%2FmobileWaiting.jsp%3Fstatus%3Dfailure%26sessionDataKey%3D5c406d59-40af-4328-841b-25cfaf41c7ee%26relyingParty%3Duaedds_mob_stage

  • SP will receive call back from uaepass.

dds%3A%2F%2Fuaedds.com%3Furl%3Dhttps%3A%2F%2Fqa-ids.uaepass.ae%2Fauthenticationendpoint%2FmobileWaiting.jsp%3Fstatus%3Dsuccess%26sessionDataKey%3D5c406d59-40af-4328-841b-25cfaf41c7ee%26relyingParty%3Duaedds_mob_stage

  • Once you recieve the callback from uaepass, fire the success url which is saved in below variable within the same webview.

Successvar1

13. Mobile integration with UAE PASS SDK

  • Update this section in Integration document as it is copied from migration guide.

14. Logout from UAE PASS

a. URL given in the Integration document is below

https://stg-id.uaepass.ae/idshub/logout?redirect_uri=http://localhost:8080/logout

b. Update above with below (communicated over email).

  • UAEPASS new system accepts only state parameter. To pass an additional parameter in the logout url, encode the value into state parameter and pass it to logout url as below.

https://stg-id.uaepass.ae/idshub/logout?redirect_uri= http://localhost:8080/logout?state={base 64 encoded value of query string}

  • Please make sure that once SP receive the state parameter thereafter SP have to decode the same to use it.

c. Above logout URL is applicable in web and mobile both or in case of mobile only destroying cache is enough. If applicable for mobile, mention it in mobile integration section.

Digital Signature Flow:

1. Get the access token to start the signature process:

2. Create sign process: use the token from step 4 to create sign process

3. Get the signature status:

4. Fetch the signed document:

5. Delete the signature process:

Digital Signature Issues:

1. Asking for authenticate again while signing:

If UAEPASS is asking for authentication again while initiating the signature process, please make sure that you add WSO2 SAML flow in trustedx for that SP client config. Below are the steps to add:

  • Login to trusted

  • Find the SP in the client applications list.

  • Go to User Authentication tab ( select Yes)

  • Authentication requirements ( Select Specific Flows)

  • Click on add and then select WSO2 IDS SAML2 Flow and save

2. Remote server returned error:

Resolution: Please make sure that SP is using token generation call for signature only. Kindly note that node6 urls are to be used only authentication but not for signarture. Digital signature API’s remains same.

3. Invalid scope:

Resolution: Please make sure that SP passes correct scope as below:

urn%3Asafelayer%3Aeidas%3Asign%3Aprocess%3Adocument

4. Unauthorized client:

Resolution: Please make sure that all the signing scopes are assigned to that SP in trustedx and enable client_credentials in grant types tab. Below are the signing scopes to be assigned to SP if they have signing use case.

Signing Scopes

UAEPASS General Profile

Use Server Signing Identity

Sign Documents

Get Signing Identity Attributes

Use Advanced Server Signing Identity

Get Profile Information

5. If signing the same document twice, please make sure that SP passes the unique value for name parameter in process type of request body as below:

"name": "Sign1" for first signature

"name": "Sign2" for second signature.

6. If digital signature call is failing due to special character in full name parameter.

Follow below steps in order to resolve the issue.

1. Trim the first name and last name returned from UAE PASS.

2. Append last name to first name and pass it in full name parameter.

7. If the grant type is not passed correctly.

Resolution: Please make sure that SP passes correct grant_type value as client_credentials.

8. If client credentials are not passed correctly.

Resolution: Please make sure that SP passes the client id and secret value correctly.

Last updated