Skip to content

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 response
  • reason describes the goal of the authentication
  • message represents the message to be signed by the user inside the proof generation
  • scope 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 request
  • circuit_id, describes the type of circuit that must be used to generate the proof
  • rules that must apply by the user when generating the proof such as:
  • query, that includes allowed_issuers, which is an array of IDs of allowed issuers, and a set of requirement req for that specific claim, for example that the value birthday inside user's Claim is less than ($lt) 2000/01/01.
  • schema includes the url of the claim JSON schema and type 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:

  1. Parse the authorization request and resolve the verifier identifier if required.
  2. Generate proof(s) using the handler specified in the request.
  3. 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