Common Integration Issues
The purpose of this is to explain the integration process and issues faced by SP’s during their integration.
Authentication Flow
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:
Available only for applicable users
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:
Production:
Mobile:
Staging:
Production:
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 Code | Description |
|---|---|
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:
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
