ZK Login Workflow
Platforms can leverage iden3 to login and authenticate users with Zero Knowledge.
Login Workflow
- A Web application designs an authentication request to users that want to access the website. This is generated by the server and embedded in a QR code (or via deep-linking, it is up to the implementer).
- The user scans the QR code using their mobile wallet and parse the request
- The user generates a ZK proof on mobile according to the request of the website
- The user packs the response into a JWZ (JSON Web Zero Knowledge) and sends it to the callback server
- The server verifies the ZK proof and, if verified, grants user access to the platform (or sets up any customized logic)
Auth request
The web application, via its server, presents a request to the user for authentication purpose. The auth request describes the conditions that must be satisfied to authenticate the user.
{
"id":"7f38a193-0918-4a48-9fac-36adfdb8b542",
"typ":"application/iden3comm-plain-json",
"type":"https://iden3-communication.io/authorization/1.0/request",
"thid":"7f38a193-0918-4a48-9fac-36adfdb8b542",
"body":{
"callbackUrl":"http://localhost:8080/api/callback?sessionId=1",
"reason":"test flow",
"message":"message to sign",
"scope":[
{"id":1,
"circuit_id":"credentialAtomicQuerySig",
"rules":{
"query":{"allowedIssuers":["*"],"req":{"birthDay":{"$lt":20000101}},
"schema":{"url":"https://schema.polygonid.com/jsonld/kyc.json-ld","type":"AgeCredential"}}}}
]
},
"from":"1125GJqgw6YEsKFwj63GY87MMxPL9kwDKxPUiwMLNZ"
}
The body of the Auth Request includes:
callbackUrl
of the server where to send the responsereason
describes the goal of the authenticationmessage
represents the message to be signed by the user inside the proof generationscope
describes the type of proof that the web application requests to the user in order to authenticate
Focusing of the scope, it contains:
id
, uniquely identitfies the requestcircuit_id
, describes the type of circuit that must be used to generate the proofrules
that must apply by the user when generating the proof such as:query
, that includesallowed_issuers
, which is an array of IDs of allowed issuers, and a set of requirementreq
for that specific claim, for example that the valuebirthday
inside user's Claim is less than ($lt
) 2000/01/01.schema
includes theurl
of the claim JSON schema andtype
of the claim requested
In this case, the verifier is setting the rules for the login. The user must have been born before 2000/01/01. This is information must exist inside a claim of type AgeCredential that satisfies a specific schema format. The verifier is not setting specific requirement for the allowedIssuers
that issued the AgeCredential claim. Lastly, the proof must be generated using credentialAtomicQuerySig circuit.
from
identifies the subject that is making the request, in this case the web application.
The auth request message can be delivered to the user's identity wallet through different communication channels: QR code, email, deep-linking, etc.
To design more specific queries
Auth response
When receiveing the auth request, the identity wallet will:
- Parse the authorization request and resolve the verifier identifier if required.
- Generate proof(s) using the handler specified in the request.
- Pack the proof inside a JWZ (JSON Web Zero Knowledge) and send it to the callback url.
JWZ
eyJhbGciOiJncm90aDE2IiwiY2lyY3VpdElkIjoiYXV0aCIsImNyaXQiOlsiY2lyY3VpdElkIl0sInR5cCI6ImFwcGxpY2F0aW9uL2lkZW4zLXprcC1qc29uIn0.eyJpZCI6IjZhOWU4MDlhLTAwNzktNDI2OS1hMzA5LTdlYmIyZDE2YTIzYyIsInR5cCI6ImFwcGxpY2F0aW9uL2lkZW4zY29tbS1wbGFpbi1qc29uIiwidHlwZSI6Imh0dHBzOi8vaWRlbjMtY29tbXVuaWNhdGlvbi5pby9hdXRob3JpemF0aW9uLzEuMC9yZXNwb25zZSIsInRoaWQiOiI3ZjM4YTE5My0wOTE4LTRhNDgtOWZhYy0zNmFkZmRiOGI1NDIiLCJmcm9tIjoiMTFCckE5cmhiWEJwWEMyS0tUOTlzNTEyc1htYnlWa3V1MjFuWWU0NHFiIiwidG8iOiIxMTI1R0pxZ3c2WUVzS0Z3ajYzR1k4N01NeFBMOWt3REt4UFVpd01MTloiLCJib2R5Ijp7Im1lc3NhZ2UiOiJtZXNzYWdlIHRvIHNpZ24iLCJzY29wZSI6W3siaWQiOjEsImNpcmN1aXRfaWQiOiJjcmVkZW50aWFsQXRvbWljUXVlcnlTaWciLCJwcm9vZiI6eyJwaV9hIjpbIjIzNDkzNTkyMTg4NjIyMTAxOTk4NTgzMTc3MTE2OTMwMDAyNTg2MzIwMjQxMzk4MjE2NTQ0MTk1Nzg4MTg3MTc0MDk5MTExMDMzNDUiLCI5NzgzNjU5NTQyNzgxOTM1OTQ3NTk0MjcxMTk1ODA5OTk3MzcyOTM4NDk5NzQ1MDM3NzI1MjMxNDgwNjE3NzgyODk1MTA4Nzk4NjM4IiwiMSJdLCJwaV9iIjpbWyIyNzIyNTc0ODgxMjgxNTQ1MDgyOTAzNjAyMjIyMDYwOTQ3MjA3OTA0NzcwMjYyMzMwOTM2NTQ3MTQ5NjAzNzAxNzE5MTE1Njc2OTY2IiwiOTEyNTA4MDA3ODY0MzM4OTU0ODIzNzExMjk1NDU2MzAyOTE4NTU1NjI4NjMwMTg5MDM5ODc2MzUxNDUyMzExOTQ4MDAzNjU3MDMxMSJdLFsiMTM2NDAzMDk4MDA3ODQwNTUyMDI2OTYwOTk3ODI5MTk3OTg1NjE5ODU0OTA3MDI2NjM1MzgxNjgyMTkxMTUxNzU4NDk5OTk5MTkzNzMiLCIxMDM2MzMyMDQ2MjI5NjAwMTc5ODU2MDUwNTc4MTM5NzM3MzAzMjk0MzI5NzU3MTU4OTY3NzA3NjQyMDU1MDg3Nzg2MzYzNDQ3NzY1MiJdLFsiMSIsIjAiXV0sInBpX2MiOlsiMTk0NjgyODk1MDc0Mjg1MTUyOTcwNTU0MjM1MjEzNjkwNTg1MTQ4NTgyMjgxMTE0MDA2MTkzOTcwODkxODQ3OTg3OTU1MDIwMzA0MzQiLCI2MTg0NTc0NjY3ODYyNjg5OTQ2Mjk0MzgwMDAxMDk5NjgzOTI3NTYwMzk0ODE4MjM2Mzc5MzEzNTgxMTI2NjIwMjYyMDUxMzI1OTkwIiwiMSJdLCJjdXJ2ZSI6bnVsbCwicHJvdG9jb2wiOiJncm90aDE2In0sInB1Yl9zaWduYWxzIjpbIjE2NTE2MTkxMjIyMjc2NDg0NzQzMDE5NDIyMDM5ODIxMTA4ODcwNjI3MjcxNTgwNzIwMzI5NTk5MzQwNzg5MjQxMjcwMDE1Mjg2Mjg4IiwiMzc4MTg4ODY2MjM0Njc5Nzk0MTcxNjY1Njk4NTU0NjQ4OTEyMjYyNTUwMTQzODY2NTUyMzY5MTQ3NDY4MTY2OTAyMzc4NzkwOTEyIiwiMTI5NzU3NjYzNTEzNTMyMjM1ODA4MDk5MDYxNzAwMDY0NjYwNzAzOTQ3NDE3ODM5MjUzOTI2OTE1MTU5NDc2NTI2NDc1MTY3NDYxODIiLCIxIiwiNTMxMDMwMjA4MzM5MTc0NDM5OTUxMDAxNTExODU5MjI4OTU5MTYyMTkzNDcwNzY5NTM2MDMwMzIxODI4MTIyMjI2MDczOTI3NjgiLCIxNTU4NjUxOTcwMDcwNTkxMjc3OTE3MzU3MzgzMDEyMTYyMzU2NTg4OTcyODE3MjAzOTE5NTk2ODQyNTU3MTA5MTAxMzc0NTY5ODg2NiIsIjE2NTUzMDQwNDkiLCIyMTA0NTk1Nzk4NTkwNTgxMzU0MDQ3NzAwNDM3ODgwMjgyOTIzOTgiLCIyIiwiMiIsIjIwMDAwMTAxIiwiMCIsIjAiLCIwIiwiMCIsIjAiLCIwIiwiMCIsIjAiLCIwIiwiMCIsIjAiLCIwIiwiMCIsIjAiLCIwIiwiMCIsIjAiLCIwIiwiMCIsIjAiLCIwIiwiMCIsIjAiLCIwIiwiMCIsIjAiLCIwIiwiMCIsIjAiLCIwIiwiMCIsIjAiLCIwIiwiMCIsIjAiLCIwIiwiMCIsIjAiLCIwIiwiMCIsIjAiLCIwIiwiMCIsIjAiLCIwIiwiMCIsIjAiLCIwIiwiMCIsIjAiLCIwIiwiMCIsIjAiLCIwIiwiMCIsIjAiLCIwIiwiMCIsIjAiLCIwIiwiMCIsIjAiLCIwIl19XX19.eyJwcm9vZiI6eyJwaV9hIjpbIjIxNzkwODAzMjI2NDE1NDQzNTg3NTAzMjk4NzY5MjQwODA5MDYzMTE5MTgzMjY4MzMzODU1NzM4MTI4NDU4MDA2NjI1MTM4NzM4MTIwIiwiMTY2OTg2MjAyMzY2MjE3Mjk1MjM4NjUzNzc5MTkzODMyNjM2MDc3MzQ4OTU0NjQ5MDEwNDY2ODI3Mjc0NDE4NDczODcwNTM0NTIyMjMiLCIxIl0sInBpX2IiOltbIjQ1MzU3NDg4NDc0NTE2MjA3MjcwMzA4NTA5NjgzNDgyODM1MzMyMjE4OTIxNTY0Nzk3ODQ0Nzg1NTA1NzYyOTE5Njc4NzAxNDYzNjkiLCI5NzM4MjczODE4NDA0ODMyNzYzNzk3NzU1NzI5MzY0NDY5MzU5MDMyNTg5Mzc0MjU3MDc3OTg3MzE0ODQwMDc0MjkxNzAwMDQ2NjYzIl0sWyI4MDQyMTUzMDUwOTA0ODE0NzUzNTI0Mjk5OTM2OTczNjg4MDMzNDg0NzU5MDk5MDAwNjE2OTUyNTk3MjQwOTI0MDIwMTYxNTIyOTAzIiwiMTIxODAwMzE1NDk1NzkwMzU5OTI1MTU5NDI5MzQ1MDk3MjgwNzQ0NDYwMzU5MDU2MDkxNzA2MDAxMTE3NDM4MDgxMDM2MzE1MzAxNiJdLFsiMSIsIjAiXV0sInBpX2MiOlsiMTA3OTQ0MzMyNTU0NTc0MDU0NTcxNTA5NjUxMDgyNDI0MTg2NzkyNzEyNjQyOTExNDIwNzkzNTgzODc3OTUwNTA4NzE4MTg0MDU4NjIiLCIyMDk0MjA1NTIxMTA2NDMyNTg2NjU4NjUxMDAwNzU2NjgwMjcyNjg3NjgxNjIzNzEyMTgyODM2MDQ4Mzk0ODc0MTIyMzk5MTkzNTE5OCIsIjEiXSwicHJvdG9jb2wiOiJncm90aDE2In0sInB1Yl9zaWduYWxzIjpbIjE4MDE2NDYyOTI3NzgzNjAwNDgyODIyNjgxNTQ4OTg1MDYxMDk5MzY5MTQ0MjczMzE1OTA1MDU1Mzc4NDUxMjg5NzM1MjY0MTI3NTMyIiwiMTI5NzU3NjYzNTEzNTMyMjM1ODA4MDk5MDYxNzAwMDY0NjYwNzAzOTQ3NDE3ODM5MjUzOTI2OTE1MTU5NDc2NTI2NDc1MTY3NDYxODIiLCIzNzgxODg4NjYyMzQ2Nzk3OTQxNzE2NjU2OTg1NTQ2NDg5MTIyNjI1NTAxNDM4NjY1NTIzNjkxNDc0NjgxNjY5MDIzNzg3OTA5MTIiXX0
The JWZ, similarly similarly to JWT, contains a header
, a payload
and a signature
.
The payload
contains the ZK proof based on the query presented inside the Auth Request.
The signature
is a special Zero Knowledge signature. It contains a proof of identity ownership generated using the authorization circuit
To understand how a JWZ looks like
Verification
The server, after receiveing the JWZ from the identity wallet, performs the verification process. It involves:
- Zero-knowledge Proof Verification
- Extraction of Metadata from the JWZ, like the public inputs of the circuit and elements included inside the
scope
- Verification of identity states stored on-chain
- Verification that the public inputs used to generate the proof matches the rules included inside the auth request. For example the
query
established by the verifier inside the auth request must match the query used as public input to generate the proof
At the end of the workflow:
- The web-client is able to authenticate the user using its identifier
ID
after establishing that the user controls that identity and satisfies the query presented in the auth request. - The user is able to log-in to the platform without disclosing any personal information to the client exept for its identifier