Portal Initiated Credential Exchange Journey
This page explains Portal initiated credential exchange journey
Credential intent flow enables verifier portal to request VC from the aadhaar app.
1.1 Implementation Details
For cross-device transmission through QR codes:
Create a JWT payload with the payload and header parameters
Sign the JWT using the private key using RS256 algorithm
Convert JWT to Byte Format: Encode using ISO-8859-1 encoding
Append Delimiter: Add a delimiter byte (255) at the end of the byte array
Compress Data: Use gzip compression to reduce data size
Convert to Big Integer: Transform the compressed byte array into a large integer
Convert to Base-10 String: Represent the integer as a base-10 string
Generate QR Code: Embed the Base-10 encoded string into a QR code
1.2 Sample Request(JWT)
{
"txn": "94f63917-708a-4e58-9001-fce56d839948",
"i": "credential",
"lang": "<langauge code>",
"sc": "1110001110001110000001110001110001110001111",
"pop" : 1,
"m" : 1,
"ac": "1a2f",
"sa": "00b1", << to be compared against client_id attribute>>
"cb": "https://myaadhaarstage.uidai.gov.in/v1/submit-credential",
"aud": "https://myaadhaarstage.uidai.gov.in",
"iss": "https://myaadhaarstage.uidai.gov.in/v1/esignet",
"exp": exp,
"iat": iat,
"ht": "Name of the person",
"jti": "8a9d7c2b-b932-4131-9e36-43f22a019be5"
}JWT Header Structure
1.3 Request Params
Element
M/O
Type
Description
txn
M
String
A unique transaction ID that serves as a nonce to prevent replay attacks. It ensures that each request is unique, and the same request cannot be processed multiple times.
i
M
String
Indicates the action to be performed by the aadhaar app. For the CREDENTIAL request, the value would be CREDENTIAL
lang
O
String
This filed provides hint to the aadhaar app to change app language as per input (en:English, hi:Hindi, bn:Bengali, mr:marathi, kn:Kannada, ml:Malayalam, or:Oriya, ta:Tamil, te:Telugu)
sc
O
String
Scope enables verifier app to only request claim that it needs. It is 64bit bitmap, where in each bit indicates a potential claim.
m
O
Integer
0 : For Offline 1 : For Online Face Authentication
pop
O
Integer
0 : Not Required 1 : Required
ac
M
String
A unique code for the AUA which is assigned by UIDAI. This is an alpha-numeric string having maximum length 10
sa
O
String
A unique code for the subAUA which is assigned by UIDAI. This is an alpha-numeric string having maximum length 10
cb
M
String
The callback URL where the pid response will be sent after the transaction is processed.
aud
M
String
The audience claim indicates the intended recipient of the pid request or the Authorization Server.
iss
M
String
The issuer claim identifies the Authorization Server or the entity issuing the request. In this case, it specifies the e-signature service endpoint of UIDAI.
exp
M
String
The expiration time of the request, specified as a Unix timestamp (in seconds). This ensures that the request is valid only for a certain period of time. After the expiration time, the request is no longer valid.
iat
M
String
The issued at claim indicates the time at which the request was created, also in Unix timestamp format.
ht
O
String
Hint to trigger the selction of the profile from the aadhaar app. This has to be name of the person.
jti
M
String
The JWT ID (jti) is a unique identifier for the token. It helps to uniquely identify the request and prevent replay attacks (i.e., the same request being submitted multiple times).
1.4 Intent Response << Header to be looked into >>
Alternatively, << Need to be discussed >> << Callback header to be structure >>
<< Response from Callback URL to be looked into>>
1.5 Response Params
Attribute
M/O
Type
Description
txn
M
String
txn id from the request.
response
M
String
SD-JWT encoded as base64 string
dateTime
M
String
Date and time of the local match in YYYYMMDD’T’hhmmss format.
errCode
M
Integer
For more details see below Error Codes.
errInfo
M
String
For more details see below Error Codes.
1.6 Supported Credential Claims
The following table shows the mapping between bit positions in the "sc" field and the corresponding credential claims:
1
1
"credentialIssuingDate"
N
2
2
"enrolmentDate"
N
3
3
"enrolmentNumber"
N
4
4
"isNRI"
N
5
5
"residentImage"
Y
6
6
"residentName"
Y
7
7
"localResidentName"
N
Included along with Resident name
8
8
"ageAbove18"
Y
9
9
"ageAbove50"
Y
10
10
"ageAbove60"
Y
11
11
"ageAbove75"
Y
12
12
"dob"
Y
13
13
"gender"
Y
14
14
"careOf"
N
15
15
"localCareOf"
N
16
16
"building"
N
17
17
"localBuilding"
N
18
18
"locality"
N
19
19
"localLocality"
N
20
20
"street"
N
21
21
"localStreet"
N
22
22
"landmark"
N
23
23
"localLandmark"
N
24
24
"vtc"
N
25
25
"localVtc"
N
26
26
"subDistrict"
N
27
27
"localSubDistrict"
N
28
28
"district"
N
29
29
"localDistrict"
N
30
30
"state"
N
31
31
"localState"
N
32
32
"poName"
N
33
33
"LocalpoName"
N
34
34
"pincode"
N
35
35
"address"
Y
Y
36
36
"localAddress"
N
Included along with Address
37
37
"mobile"
N
38
38
"maskedMobile"
N
39
39
"email"
N
40
40
"maskedEmail"
N
41-63
Padding
N
1.7 Language Support
The API supports 23 languages specified in the lang field (English, Hindi, Tamil, etc.)
1.7.1 Supported Languages
The API supports multiple languages as specified in the "lang" field of the payload. Language must be passed as a numeric code.
1.7.2 Language Mapping
1
Assamese
Asm
as_in
2
Bengali
Ben
bn_in
3
Bodo
--
brx_in
4
Dogri
Doi
doi_in
5
Gujarati
Guj
gu_in
6
Hindi
Hin
hi_in
7
Kannada
Kan
kn_in
8
Kashmiri
Kas
ks_in
9
Konkani
Kok
kok_in
10
Maithili
Mai
mai_in
11
Malayalam
Mal
ml_in
12
Manipuri
Mni
mni_in
13
Marathi
Mar
mr_in
14
Nepali
Nep
ne_in
15
Oriya
Ori
or_in
16
Punjabi
Pan
pa_in
17
Sanskrit
San
sa_in
18
Santhali
--
sat_in
19
Sindhi
Snd
sd_in
20
Tamil
Tnd
ta_in
21
Telegu
Tel
te_in
22
Urdu
Urd
ur_in
23
Other language (English)
Eng
en_in
1.8 Sample Request
1.8.1 Sample Base10
The above sample mentioned JWT has been converted into Base-10 string:
1666947177694254269309103596996334580901989690959759198936103588643938573631979061018753077946111617797169116194122867596324818597982884730933604732378994794602618911120706214970681835845435701669503549149062158647058749331976362245344892081693319971586033702259751028310979837477030947168140542947792763434807782498444194065369957038988150709139446321927901929730846692286324245711137706926016352035819125445666459259943317622005984831662635506817628072191203347372421071323523812373381734739406770702586622777568695318376015238612621082228265559185089839599731512655147324223741016220660052640887674900634135862948639559387895681954927172399908263268414055098194767022942464403335372785177523158813476386522504647191734634767075728975611561998809718092099244824188604317615387470222181043696959718817136353879854224629587961684874057295216103388871994176201959548073391037531013184032927012084734592428040806894226847163547711198970122253547384855809913168141527679109893439274959725716297305705346768752646377288201657569672324989998403836257463195137087340682613061761698064582703410220276369903698710459551688446027449064287862818807765667394847882362733931910155429493062024390940170279369797875228118235491291553547767790577454968178597255373199082701202848310823120940936777912616956749839977733703048879438383712689997943436884493705895481466173875419378657058490645896568959866492963001075282025434199449816091818791933885395718060264551270105222851224539642514129981766823551033923482098060941755000387563910972858368465372565896875936399262679040
1.8.2 Sample QR CODE
The above base10 string is converted to a QR and is sent to the portal/web application or custom device in png/jpeg format for rendering. This is a non-normative flow and verifiers are free to choose their implementation.
1.9. Response Processing
1.9.1 SD-JWT Verification and Decoding
On receipt of the SD-JWT through the callback by the aadhaar app, the verifier app must perform following steps to consume the SD-JWT.
Verifier portal or the backend validates the SD-JWT signature using the UIDAI public key. The UIDAI public key is available at www.uidai.gov.in. Optionally, verifiers may verify the device signature.
Verifier app or backend validates the disclosure hashes against the `_sd` field in the JWT.
Optionally, the verifier app or backend may verify the shared data by matching hashes present at the end of SD-JWT.
The verified shared data is displayed and stored securely by the Verifier App.
1.9.2 Sample SD-JWT document of the UIDAI is as shown below:-
eyJhbGciOiJSUzI1NiIsInR5cCI6InNkLUpXVCJ9.eyJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvdjEiXSwiaXNzdWVyIjoiVUlEQUkiLCJpZCI6ImQzNmIyMWMwLThhYzgtNDZhMy05YzkyLTFjZmU3NjdjNjE4NiIsIl9zZF9hbGciOiJTSEEyNTYiLCJfc2QiOlsiaDV5S01oZkstSHg5RUtnVTBvRWVUeG1SY3A4RHJ6NF9iYnVQSGtxZDFxVSIsInlvOThiUjdsM1ZZMmxZU093aU1wOUI3eUVMU25STnJZbEhzOXBZcmdXZHciLCIzRmV4bXpVUTdJT3dhM1JWTmxfdTBYdzRfRVZsaVhKYVA3alFndFQxdnNrIiwiUjZoMEVoeHE5bC1BbFFnLWpYUkhJcDc3R0hZLWFFaXFIOGZ0WnJhbVFaMCIsIlVQY01URDcwYTBITUdPRnZKLTJfdEpOY0tNZEtsQU9hT2t4RmxSdjk3eVEiLCJJc2lvYUY4bjdZOEllenBuOWREek52YVRtZnVORzl2TWtpYW9lQ0tyOW5BIiwiMnJCU19yS1d5SkVEMVo4TDNpM0FhYmtNYVhsX0tKMk9ydWM1anhfclFYayIsInZKTEZpM2RzT09CeUN5Ty1pWTlHWldDdlhJUFFBeDZBRjNoTFdWLU1KejQiLCJBTXd3LWpuNTBBLVpOWTI1OVAzTXVJYXN0eTFiZldhX0RNOFpMSG1TZ3lVIiwiVk1FUENmNXpnX0p5cEhmakg2Y1ZUNVNkWHZpOURmWl84eTVNYVRZRGFURSIsImU5NERrbm1SUkdKbzlZRlZMcGIxdk1fLWxaTVc1aUNnNGJtLXF5SGUwbkUiLCJIcjRaUHI5X3Qzak9LTzVLM09yejZnR003Vy1VbUxIY2lWcF80YTlRWUJ3Iiwic253YXIzOGdTUmY5ZWN2b0sxcHF6TkFUaGdsTUVLaGtGWnZyY2FnWGptSSIsIll1UFE2SnBNc01BMWhtbjBWbE5INWJzblRuMkY2UFJGN1Z6U1pvbm4yQU0iLCI5czNQMnNfblY5dV9SaXRFZExnVEFnOVdkVVBHUFRySlFtT2hrUnBSTWNvIiwiWWpNV3ZLa2lsOWJ6T3BTUS1zZmJNVGRKb1hRYTBXNVFNZkRYWlFtMGp0USIsInBDZFZhdmw1VWRYNnJwamFWN240M0FNUzFLTWY2RWZZUTF0d2s5QlJXMGsiLCJpbHRoaHR3U1JSVTc0VVAtMXVwaVZLdWlNLXVxaVZvaXh5SVY5UmY4a1FRIiwiQXB4OEw4SC1aWGdFVm1YU2tQVFUxQ3FTQ09nUy0xU3JUSXFvWmJtSUt2YyIsIm1OZGZJRFlsdEtSM05CMXdhY092ZXU5MGNfOXpiQ3hra192ZEpNRjZOOXMiLCJzMTc3WXVrLXUxYkI1QWVMTVBfeVdoTjZpeTNRblpuTVlTcm1VZ0N6dFRVIiwia1FfbUU1dGR2YlFtaVhqSFlzV3FsYWZwZFM1QmdadDhiZkwtRVY5cGE1USIsIklQODZua3Viak05dGtlaGx2Z01ERE9UQjE0UzRBYzJEbENEMDJVTXlWZlkiLCJrUTM1bmFwU2VZWTROeF9fRWo2YTB0bFRiWk9PR0s1djBTdWdQaU1qbGJ3IiwiVmY3NDY0N05rT0MxWVFJS0tGc1kyMFdKdG45U1pWQ2lZTlo3MGYwYm1HZyIsInA4VkV6bDA2YmMza0ZlN1pkMzA1UG9xLVR2N1NxZkZtOUgzd19DNUFRbEUiLCJkTTcxZWhOdndfUnNJa1YtTzFOd0x3RHVHTWY4YlRoXzVlZHBlRDd5ZlJnIiwiWXBLSG9HWmJobzIwRDlaOGZmMFZoeS16c2dtTVNRN2JuVThldERNM0xXYyIsIjRUd2lJRW9sVzdJSVJIa05sTG10MUZNeXMzd0QxYmFLeXhCX1l2X1FhZ3ciLCJYT1hCeUU4TU9mTFVQVF9WUkZEUU16VmlYTVJEc0dfcXJralF2am1OTzBnIiwiOWlkNFRXVHpLbVktSXJWM2lKMkFWSkdaazlPT3hDMWh1elA0VzN4a2RtZyIsIkZvSXV3dzNzMFZOWEhTZ1VuYWRDSzVQMXVFZTlYWTJQNmZwQmlnMGREWFkiLCJVY0JxTTdIM3JjVXA0ZWpVdnh2UVpZV1lEUEdYMTR5dkNOWVE1eVV5VW1vIiwiQmRaZTlNemJwaWwtakRtd2hQZWpXaWgwRzdnd242U1Y2RktzX1ZTem5RUSIsIlNJRUQyQ2UzLV9aVWtQSnhWNDNQMkVpVGpPb25KNW9FaGFqbm01OGdIVDgiLCJ1dnk2WFRJVzFmM19LbS1BcFNjakNoZTlDcFhLZU1xZURCNUs4RE1BTVM0IiwiaGZuVlNvQXNKbDFvUTVYNTBGaWlVWWtCYTNQSk5DanZMdC0tenlPLWVVayIsIlFpTFl5YjFtWHVjeUlTc3VPckhZVUYwYmFrTWNkMklXUl9PS3JNUktiU3ciLCJyWk8yUEJOdlV5R0VYMEpCcEJqM3RrVFNWbThnTzZrcmhtc2w1NzA1MXljIiwiVlVnRUlYa2hNY0lDaXRhTXFKZ2NpMm03dnotZjMwSTNkMmZpX1M0SHpkVSIsImppZ2hIX1NSM3RiM2xObnhYbU5jZjdYUDZtQjNOQkJqejlETm5QbmIzc2ciXX0.HU2zr5nrSJ68bxrl7SPte3wQb4ZyrlWQLvcNFTNPLzYJjKbh4le0N6zxgRKi-MmptX4SjudiPu5ggScgy6NAfnYKCRPNg0clWRl_6nn7SNcLQGZMeSWR_Uk60kFBHqCbs24caJ-1w_0FhPy6UFCuVjJ1MqwpHeBvWb6OiwIG-nufD7YBCIQwXS7ys8XYuUf4yc6m3SZNZda_BEWROXGdXzsFEooeJj1ktaqoXHwUUMT3tI7Ly3Pf6VxtsuK6dvkS-wCXaalyAVva7ceH84TuYg5iGDgUcuSJfdDAGqV1tH_d60T1xcJt__VlqTlDvqenrwrHpRDGraGUqZSe0FyY9g~WyI4YmJiM2YzNS01ODY3LTQxNGUtOTM3MC1lNGNjMDIwMjgzZjciLCJDcmVkZW50aWFsSXNzdWluZ0RhdGUiLCIyMDI1LTAzLTE5VDE5OjAzOjMxIl0
1.10. Security Considerations
1.10.1 Best Practices
The following are some of the security best practices recommended for implementation by the Verifier.
Protection of the Personally Identifiable Information (PII) data to be handled as per the provisions of the Aadhaar Act.
The private key used by the Verifier for signing the JWT must be securely stored. Recommended to use any CloudHSM/Local HSM or USB Device to store the Private Key.
Only a valid Private Key is to be used to sign the JWT request.
Private keys are to be rotated as per the provisions of the CCA.
The JWT token must be set with a reasonable expiry time (exp). Typically, a duration of 5 minutes is recommended.
Verifier must validate JTI claim to prevent replay attacks.
For cross-device flow, verifiers must always validate the audience claim (aud) and Issuer (iss) claim.
Last updated