Protocol Specification
Last updated
Last updated
The following parties are involved in the authentication process:
Server: The service relying party that provides services to the user.
Client: A website or app with which the user sends authentication request to the server.
Decentralized Identity Management Wallet ("Wallet"): A tool for the user to manage their decentralized identities and verifiable credentials.
ONT Login requires end users to have an ONT ID. Please refer to this doc on how to generate ONT IDs for your users.
The whole process can be divided in the following 5 steps. We will go through each step in detail in later sections.
Authentication Request: The user starts the login process. The client sends the authentication request to the server.
Authentication Challenge: Received the request, the server generates and sends a challenge to the client, which can specify the required VC if needed.
Signature (and Authorization): The client receives the challenge, then requests signature and VP from the wallet with the challenge.
Authentication Response: The client receives the signature and VP from the wallet, and send the response message to the server.
Verification: The server verifies if the response is correct. If yes, the server parses the VP to obtain the information authorized by the user.
The client sends the authentication request to the server as the example below:
Property
Type
Description
ver
1.0
Protocol version, current version is 1.0.
type
ClinetHello
Message type, the type of an authentication request is ClinetHello.
action
integer
"0" = authentication; "1" = authentication and authorization. You can define other actions based on the business logic.
ClientChanllege
ClientChanllege
Optional, challenge sent from the the client, required for mutual authentication.
Upon receiving the request from the client, the server generates and a nonce and stores it.
The server returns the following message to the client:
Property
Type
Description
ver
1.0
Protocol version, current version is 1.0.
type
ServerHello
Message type, the type of an authentication challenge is ServerHello.
nonce
string
A one-time random number or 128-digit UUID generated by the server used as a challenge. It's necessary to ensure it's randomly and recently generated.
server
A message from the server including strings:
- name: string, name of the server, required.
- icon: string, image URL of the server's icon or the serialized icon, optional.
- url: string, server URL, required.
- did: string, server DID, required for mutual authentication.
- verificationMethod: string, serial number of the verification method in the server DID Document, required for mutual authentication.
VCFilters
VCFilter[]
Types of VC required from the server, including at least 3 fields below:
- type: string, type of VC
- trustRoot: VC issuer
- required: boolean, if the VC is required
The express string is used to specify requirements in a zero knowledge proof, e.g. age 18 and above.
chain
string[]
Denoting chains supported by the server with native token symbols, e.g. “ONT” represents Ontology chain.
alg
string[]
Signature schemes supported by the server.
serverProof
object
Optional, server's response to the challenge sent from the client for mutual authentication.
When the client receives the authentication challenge , a message is generated accordingly for the wallet to sign. The wallet signs the message containing the challenge, and generates the VP for VC required by the server.
An example of message to be signed:
Property
Type
Description
type
ClientResponse
Message type, the type of a message to be signed is ClientResponse.
server
object
Server details including 3 strings:
- name: string, server name
- url: string, server URL
- did: string, server DID, optional
nonce
string
The nonce included in the challenge.
did
string
User DID.
created
number
UNIX timestamp in seconds of signature creation time.
After the signature and VP are received, the client sends the response to the challenge to the server.
Property
Type
Description
ver
1.0
Protocol version, current version is 1.0.
type
ClientResponse
Message type, the type of the challenge response is ClientResponse.
nonce
string
Nonce included in the challenge.
did
string
User DID.
proof
Signed challenge including the following 4 fields:
- type: signature scheme used for the signature
- verificationMethod: serial number of the verification method in the user DID Document
- created: UNIX timestamp in seconds of signature creation time
- value: signature
VPs
string[]
Encoded VC.
The server verifies data contained in the challenge response:
Verify the validity of parameters
Verify if the nonce is the same as the one generated by the server
verify the signature
Verify the validity of VP and VC
Check if the provided VC meets the requirement
