Get started with ONTPass

Overview

This article will guide Requester to access the Ontology network, and to use the authentication service provided by ONTPass. The participants involved in the whole process include:

  • Requester: Any institution or service provider that requires authentication for people, object or event. Requester is the demand side of authentication service in the Ontology Trust Eco-system.
  • ONTPass: Based on ONTID and Ontology Trust Ecosystem, it is an open, decentralized authentication platform that provides rich authentication services for people, asset, objects, and things. ONTPass synergizes users and requesters for data exchange and all the data is encrypted protect User's private data.
  • TrustAnchor: Trust Anchor refers to the partner that provides authentication verification services on the Ontology Trust Ecosystem. A trust anchor can be a government agency, university, bank, third-party certification service organization (such as CA institutions), biometric technology company, etc.

Interaction Process Description

  • A0:ONTPass provides a public authentication service marketplace. A Requester can browse and select their desired TrustAnchor and its authentication service they need on the ONTPass platform.
  • A1:After the Requester confirms the authentication service, the Requester needs to register certain basic information to the ONTPass platform. The information includes ONTID of the Requester, basic introduction of the Requester and a callback address.
  • A2:The Requester submits the user's data to the TrustAnchor Source based on the requirements of the specific TrustAnchor.
  • A3.1,A3.2:TrustAnchor authenticates user's data uploaded by Requester and completes the issuance of the verifiable claim, which will be stored on the blockchain. Transaction will then be made
  • A4:After the TrustAnchor issues the verifiable claim, the encrypted public key of the ONTID corresponding to the verifiable claim user, will be sent to the ONTPass.
  • A5:ONTPass pushes the verifiable claim to Requester according to the callback address.

Step 1: Find the Right Service

TrustAnchor registers to the ONTPass the authentication service and verifiable claim template information to the ONTPass. ONTPass provides the TrustAnchor authentication service marketplace. Requester can select the certification service from the marketplace.

The ONTPass authentication services that are currently open to the public include:

Global Identity Authentication Service

  • TrustAnchor Name : Ontology Global Identity TrustAnchor
  • TrustAnchor ONT ID : did:ont:ANNmeSiQJVwq3z6KvKo3SSKGnoBqvwYcwt
  • TrustAnchor Account Address : ATGJSGzm2poCB8N44BgrAccJcZ64MFf187
  • Service list
Claim_Templete_NameClaim_DescriptionDocLink
claim:sfp_passport_authenticationGlobal User Passport Authenticatioinhttp://pro-docs.ont.io/#/docs-cn/ontpass/ONTTA
claim:sfp_idcard_authenticationGlobal User ID Card Authenticationhttp://pro-docs.ont.io/#/docs-cn/ontpass/ONTTA
claim:sfp_dl_authenticationGlobal User Driver License Authenticationhttp://pro-docs.ont.io/#/docs-cn/ontpass/ONTTA

Step 2: Choose the Payment Model

There is a fee associated for using ONTPass. ONTPass supports two payment models. You need to choose the one that fits your need.

  • Mode 1: Pay as You Go

The instant payment mode is completely open and autonomous, that is, each authentication request will consume ONG fee, so the authentication requester needs to establish an ONG transfer transaction (The payment address and specific amount are specified by each TrustAnchor). After receiving the authentication request, TrustAnchor will first sends the transaction to the blockchain, and the subsequent identity authentication process will continue after the transaction is successfully sent.

  • Mode 2: Postpaid model

If you choose post-paid mode, you need to contact Ontology
Institutional cooperation
.

Step 3: ONTPass Platform Registion

After Requester selects the authentication service provided by the TrustAnchor, Requester needs to register the relevant information on the ONTPass platform, including the ONTID, basic introduction, authentication service, and a callback address. Only registered Requester on the platform will receive the subsequent verifiable claim callback.

Please refer to [Appendix] for the method to have your own ONT ID
AppendixDEMO

Requester Registers API

Host:https://api.ont.network/api/v1/ontpass/authrequesters
Method:POST /HTTP/1.1
Content-Type: application/json
RequestExample:
{
	"callback_addr": "https://xxx",
	"description": "coinwallet",
	"name": "coinwallet",
	"ontid": "did:ont:AXXxiWCuJXmuPGnsBji4cqWqV1VrKx8nkM",
	"ta_info": [
		{
			"claim_contexts": [
				"claim:cfca_authentication",
				"claim:sensetime_authentication"
			],
			"ontid": "did:ont:AXXxiWCuJXmuPGnsBji4cqWqV1VrKx8nkM"
		}
	],
	"signature":"AQp2ka0OJG5K7jlnaV8jwWneye7knHWTNN+D3yUly="
}

SuccessResponse:
{
	"version":"1.0",
	"action":"Register",
	"error":0,
	"desc":"SUCCESS",
	"result":true
}
RequestFieldTypeDescriptionNecessary
callback_addrStringverifiable claim callback addressY
descriptionStringRequester discriptionY
nameStringRequester's nameY
ontidStringRequestes's ONT IDY
ta_info.claim_contextslistSelect the list of verifiable claims templates for the TrustAnchor in needY
ta_info.ontidStringSelect the required TrustAnchor's ONT IDY
signatureStringThe Requester uses the ONT ID private key to sign the requested content according to Signature ruleY
ResponseFieldTypeDescription
resultBooleantrue:egister Success false:Register Failure

In order to ensure data transmission's security, the callback interface must be in the form of https+domain name, and Requester must ensure that the registered callback interface is highly available and accepts the https post request that meets the ONTPass standard.

Step 4: Submit Certification to TrustAnchor

After Requester selects the TrustAnchor authentication service in the ONTPass certification market, Requester needs to submit the authentication data to TrustAnchor. TrustAnchor will then authenticates the identity, issues the verifiable claim, deposits basic information of the verifiable claim, and passes it to ONTPass through end-to-end encrypted transmission

Step 5: Get Authentication Results

After TrustAnchor completes the user's information authentication and issues a verifialbe claim, the verifiable claim will then be sent to ONTPass. ONTPass pushes the signed verifialbe claim to Requester based on the callback address previously registered by Requester.

When the information is called back, the ONTPass platform will bring the signature corresponding to its own ONT ID. Requester can verify the signature, as well as the credibility and the non-tamperable features of the callback request.

Host:callback address
Method:POST /HTTP/1.1
Content-Type: application/json
RequestExample:
{
	"auth_flag":true,
	"auth_id":"xxxxxxxxxxx",
	"claim_context":"claim:sfp_passport_authentication",
	"description":"shuftipro passport authentication ",
    "encrp_origdata":"header.payload.signature.blockchain_proof",
	"ontid":"did:ont:AEnB1v4zRzepHY344g2K1eiZqdskhwGuN3",
	"owner_ontid":"did:ont:A9Kn1v4zRzepHY344g2K1eiZqdskhnh2Jv",
	"ta_ontid":"did:ont:A7wB7v4zRzepHY344g2K1eiZqdskhwHu9J",
	"txnhash":"836764a693000d2ca89ea7187af6d40c0a10c31b202b0551f63c6bc1be53fc5b"
	"signature":"AQp2ka0OJWTNN+D3yUlydyjpLpS/GJp6cFt9+wWeT25dBdGYSaErxVDpM1hnbC6Pog="
}
RequestFieldTypeDescriptionNecessary
auth_flagBooleanTrustAnchor authentication results true:authentication passed false:authentication failedY
auth_idStringThe authentication number passed to TrustAnchor when Requester is authenticated.Y
claim_contextStringVerifiable claim template identifierY
descriptionStringThe reason for the failure if the authentication fails; The description of verifiable claim, if the authentication is successfulY
encrp_origdataStringencrypted verifiable claimY
ontidStringONTPass's ONT IDY
owner_ontidStringUser's ONT IDY
ta_ontidStringTrustAnchor's ONT IDY
txnhashStringHash of verifiable claim deposit transactionY
signatureStringONTPass uses ONT ID priviate key to sign the requested contentSignature RulesY

Appendix

Error Code Dictionary

FieldTypeDescription
0longSUCCESS. success
61001longFAIL, param error. parameter error
61002longFAIL, already exist. already exist
61003longFAIL, not found. not found
62003longFAIL, communication fail. Internal communication failure
62006longFAIL, FAIL, verify signature fail. signature verification failure
63001longFAIL, inner error. inner error

Get your own ONT ID

Registering an ONT ID on Ontology requires an ONG fee. First, you need to have a digital asset account, and there is at least 0.01 ONG in your account. Then use the account to pay the fee for registering ONT ID and complete the registration on the ONT ID blockchain.

Please refer to Appendix DEMO or SDK developer documentation centerfor method to create a digital asset account, to use the account to create an ONT ID, to obtain information about the ONT ID, and to do the signature

TestNet ONG can be applied from Ontology Developer Center:TestNet ONG Applicaiotn Gateway

Use ONT ID to sign and verify a signature

Signature Rules:

The JSON object in the HTTP Post request body needs to be sorted in ascending alphabetical order of the key, serialized into a standard JSON format string, then the request content string is signed and finally the signature is added to the request body with the signature as the key.

Take a registration request as an example:
After the JSON object of POST Request is sorted in ascending key order.

{
	"callback_addr": "https://xxx",
	"description": "coinwallet",
	"name": "coinwallet",
	"ontid": "did:ont:AXXxiWCuJXmuPGnsBji4cqWqV1VrKx8nkM",
	"ta_info": [
		{
			"claim_contexts": [
				"claim:sensetime_authentication"
			],
			"ontid": "did:ont:AXXxiWCuJXmuPGnsBji4cqWqV1VrKx8nkM"
		}
	]
}

Convert it to standard JSON format string:

{"callback_addr":"https://xxx","description":"coinwallet","name":"coinwallet","ontid":"did:ont:AXXxiWCuJXmuPGnsBji4cqWqV1VrKx8nkM","ta_info":[{"claim_contexts":["claim:sensetime_authentication"],"ontid":"did:ont:AXXxiWCuJXmuPGnsBji4cqWqV1VrKx8nkM"}]}

Then Sign the JSON format string(For Signer's Operation,please refer toAppendix DEMO or SDK deverloper documentation center),after getting sigvalue,add the signature as the key to the JSON object of the Post request body.

Finally Authentication Post Body Object is:

{
	"callback_addr": "https://xxx",
	"description": "coinwallet",
	"name": "coinwallet",
	"ontid": "did:ont:AXXxiWCuJXmuPGnsBji4cqWqV1VrKx8nkM",
	"ta_info": [
		{
			"claim_contexts": [
				"claim:sensetime_authentication"
			],
			"ontid": "did:ont:AXXxiWCuJXmuPGnsBji4cqWqV1VrKx8nkM"
		}
	],
	"signature":"sigvalue"
}

DEMO

JAVA DEMO](https://github.com/ontio/documentation/blob/master/pro-website-docs/assets/Demo.java)

TS DEMO


What’s Next