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.
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. |
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 | 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 requiredThe 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:
{
"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. |
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 | 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:
- 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
Last modified 1yr ago