Protocol Specification

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.

1. Authentication Request: The user starts the login process. The client sends the authentication request to the server.

2. Authentication Challenge: Received the request, the server generates and sends a challenge to the client, which can specify the required VC if needed.

3. Signature (and Authorization): The client receives the challenge, then requests signature and VP from the wallet with the challenge.

4. Authentication Response: The client receives the signature and VP from the wallet, and send the response message to the server.

5. Verification: The server verifies if the response is correct. If yes, the server parses the VP to obtain the information authorized by the user.

Authentication Request

The client sends the authentication request to the server as the example below:

{
 "ver": "1.0",
 "type": "ClientHello",
 "action": "1",
 "ClientChanllege": {},
}

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.

Authentication Challenge

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:

{
"ver": "1.0",
 "type": "ServerHello",
 "nonce": "128-uuid",
 "server": {
   "name": "",
   "icon": "",
   "url": "",
   "did": "",
   "verificationMethod": "",
 },
 "chain": ["ONT","BSC"],
 "alg": ["ES256","Ed25519"],
 "VCFilters": [
   {"type": "DegreeCredential", "trustRoot":["did:ont:bob",""], "required": true},
   {"type": "IdentityCredential", "trustRoot":["did:ont:bob",""], "express":["",""], "required": false},
 ],
 "serverProof":{},
}
```

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	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.

Signature (and Authorization)

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:

{
  "type": "ClientResponse",
  "server": {
    "name":,
    "url":, 
    "did":
  },
  "nonce": "128-uuid",
  "did": "did:ont:alice",
  "created":1630425600,
}

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.

Authentication Response

After the signature and VP are received, the client sends the response to the challenge to the server.

{
 "ver": "1.0",
 "type": "ClientResponse",
 "nonce": "uuid-128",
 "did": "did:ont:alice",
 "proof": {
   "type":"Ed25519",
   "verificationMethod": "did:ont:alice#key-1",
   "created":"2010-01-0119:23:24Z",
   "value":"xx",
 },
 "VPs": ["",""],
}

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	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.

Verification

The server verifies data contained in the challenge response:

1. Verify the validity of parameters

2. Verify if the nonce is the same as the one generated by the server

3. verify the signature

4. Verify the validity of VP and VC

5. Check if the provided VC meets the requirement