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. 1.
    Authentication Request: The user starts the login process. The client sends the authentication request to the server.
  2. 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. 3.
    Signature (and Authorization): The client receives the challenge, then requests signature and VP from the wallet with the challenge.
  4. 4.
    Authentication Response: The client receives the signature and VP from the wallet, and send the response message to the server.
  5. 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:
1
{
2
"ver": "1.0",
3
"type": "ClientHello",
4
"action": "1",
5
"ClientChanllege": {},
6
}
Copied!
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:
1
{
2
"ver": "1.0",
3
"type": "ServerHello",
4
"nonce": "128-uuid",
5
"server": {
6
"name": "",
7
"icon": "",
8
"url": "",
9
"did": "",
10
"verificationMethod": "",
11
},
12
"chain": ["ONT","BSC"],
13
"alg": ["ES256","Ed25519"],
14
"VCFilters": [
15
{"type": "DegreeCredential", "trustRoot":["did:ont:bob",""], "required": true},
16
{"type": "IdentityCredential", "trustRoot":["did:ont:bob",""], "express":["",""], "required": false},
17
],
18
"serverProof":{},
19
}
20
```
Copied!
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
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:
1
{
2
"type": "ClientResponse",
3
"server": {
4
"name":,
5
"url":,
6
"did":
7
},
8
"nonce": "128-uuid",
9
"did": "did:ont:alice",
10
"created":1630425600,
11
}
Copied!
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.
1
{
2
"ver": "1.0",
3
"type": "ClientResponse",
4
"nonce": "uuid-128",
5
"did": "did:ont:alice",
6
"proof": {
7
"type":"Ed25519",
8
"verificationMethod": "did:ont:alice#key-1",
9
"created":"2010-01-0119:23:24Z",
10
"value":"xx",
11
},
12
"VPs": ["",""],
13
}
Copied!
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. 1.
    Verify the validity of parameters
  2. 2.
    Verify if the nonce is the same as the one generated by the server
  3. 3.
    verify the signature
  4. 4.
    Verify the validity of VP and VC
  5. 5.
    Check if the provided VC meets the requirement