A Root Trusted Accreditation Organisation (Root TAO) serves as the foundation of a Trust Model and has full control of the Trust Chain. It may:
- Accredit itself to govern or issue domain-specific Verifiable Credentials
- Accredit any legal entity to govern or issue domain-specific Verifiable Credentials
- Revoke an accreditation from a legal entity that is participating in the trust chain
0. Request to Onboard as a Root TAO
As a preliminary step towards building your solution, you need to submit a request to the EBSI Support Office to initiate the onboarding process of your Root TAO, which will form the anchor of your Trust Chain. This section will provide an overview and explanation of the steps needed to start the process that correspond to the diagram below.
Step 0.1 Submit onboarding request to EBSI Support Office
The EBSI Support Office is responsible for the onboarding process of a Legal Entity as a Root TAO. To initiate this process, you will need to contact the EBSI Support Office, fill out an EU Survey and submit the completed survey for review. Once approved, the EBSI Support Office will begin the technical onboarding process. Follow the steps below for detailed guidance on how to complete this process.
Step 0.1.1 Contact the EBSI Support Office
A Legal Entity wishing to be onboarded on EBSI as a Root TAO needs to contact the EBSI Support Office by opening a ticket request with the EBSI Help Desk.
Access the EBSI Help Desk to submit your request. You will be prompted to sign in using your EU Login account. Once signed in, you will be directed to a contact form with both required and optional fields.
- For the 'Subject' field, select 'Onboard to EBSI'.
When you have finished filling out the information, submit your request by selecting the 'Create' button.
Step 0.1.2 Fill out the EU Survey form
Once you have contacted the EBSI Support Office, you will be directed to fill in the Trust Policy Root TAO Request EU Survey form. You will be prompted to sign in using your EU Login account.
The Trust Policy Root TAO Request EU Survey guides the prospective Root TAO to define their Trust Chain in a concrete domain and for a concrete Use Case. The Root TAO is required to complete this survey as part of the onboarding process.
Step 0.1.3 Fill in EU Survey, download and e-sign the PDF
Fill in the survey with the requested information. After completing the survey, you will be able to download a PDF version of the survey containing your answers. Once you have downloaded the PDF, you will need to electronically sign it.
Step 0.1.4 Send the e-signed PDF to the EBSI Support Office
Attach the signed PDF to the previously created ticket and send it back to the EBSI Support Office.
Step 0.1.5 EBSI Support Office reviews the submission
Once the EBSI Support Office has received the signed PDF, they will review the document and decide whether you can become a Root TAO. This review process typically takes up to 24 hours.
Step 0.1.6 Green light to start with the technical onboarding
The EBSI Support Office will notify you of the result via the original ticket thread. Once approved, the EBSI Support Office will proceed with the Root TAO technical onboarding process.
Step 0.2 Set up your Organisation Wallet
An Organisation Wallet is a digital wallet controlled by your organisation and used to accredit and authorise other organisations. It is important to set up your wallet to gain access to EBSI's core services.
You can use the 'Find your wallet' tool to help you find an EBSI Conformant Wallet that best suits the needs of your organisation.
Remember to tick the Accredit and Authorise capability as this capability is required for Root TAOs. Other features are optional.
If an existing EBSI Conformant Wallet is chosen, the technical onboarding steps detailed below may differ depending on the specific Wallet.
1. Become a Root TAO
Step 1.1 Create DID and DID document
Decentralised identifiers (DIDs) are URL-based identifiers representing a specific entity. These identifiers are associated with a DID document containing information related to a specific DID, such as the associated repository and public-key information.
The DID and DID document of a Root TAO are self-generated and must follow the DID Method for Legal Entities. To create a DID, it is encouraged to use any JWS-supported cryptographic algorithm, with ES256 as the minimum mandatory requirement. The DID document must contain an ES256K cryptographic key pair.
For details on the full process of creating a DID, refer to the Register a did document - Create DID and DID document guidelines.
Need a quick refresher on DIDs and DID documents? Check out Chapter 3: Decentralised Identifiers (DID) Methods of our Verifiable Credentials Explained series and the DID method for legal entities specifications.
Step 1.2 Obtain Verifiable Authorisation to Onboard
The VerifiableAuthorisationToOnboard credential will allow you to request access to register your new DID into the DID registry as a Root TAO. You can obtain this credential by opening a request with the EBSI Support Office.
Before you can request the VerifiableAuthorisationToOnboard, you must accept and sign the legal package as an EBSI Application Service Provider via the Acceptance form as mentioned on the Get Started page.
Access the EBSI Help Desk to submit your request. You will be prompted to sign in using your EU Login account. Once signed in, you will be directed to a contact form with both required and optional fields.
- For the 'Subject' field, select 'Register a DID'.
When you have finished filling out the information, submit your request by selecting the 'Create' button.
After successfully submitting the request, the EBSI Support Office will issue you the VerifiableAuthorisationToOnboard credential.
Step 1.3 Register DID and DID document in the EBSI DID Registry
Now that you have received a VerifiableAuthorisationToOnboard, you can proceed to request the access tokens needed to register your DID document and DID keys to the EBSI DID Registry and add additional verification methods and verification relationships to your DID document.
For more details on this process, refer to our How to register a DID document guidelines.
Step 1.3.1 Get didr_invite access token to write to the DID Registry
To request a didr_invite access token, you need to present the Verifiable Authorisation to Onboard to the EBSI Authorisation API with the openid didr_invite scope.
Follow this sequence of API calls to request a didr_invite access token:
- GET Presentation definition: Begin by fetching the presentation definition for the
didr_invitescope. - POST Token Endpoint: Create and submit a presentation according to the fetched definition that contains the Verifiable Authorisation to Onboard.
For further details please consult our 'How to obtain an access token' guide
Upon successful submission, the EBSI Authorisation API will issue a short-lived, OAuth 2.0 compatible didr_invite access token.
Step 1.3.2 Insert a DID document into the DID registry
Insert the DID document and its ES256K key by making a call to the JSON-RPC API using the insertDidDocument method. This action creates a DID document containing default values and assigns the ES256K key with the capability to sign Verifiable Presentation Tokens and ID Tokens.
The following endpoint must be used to insert the DID document:
For further details, please consult our 'How to obtain an access token' guide.
When performed successfully, the Organisation Wallet will receive an Ethereum transaction to be signed. Once the transaction is signed, it is ready to be sent using the sendSignedTransaction method, which will update the ledger with the transaction.
The following endpoint must be used to send a signed transaction:
Step 1.3.3 Get a didr_write access token to register your Verification Method and Verification Relationships to the DID Registry
Now you are ready to request a didr_write access token with the openid didr_write scope. It is now not required to present your Verifiable Authorisation to Onboard now that your DID has been onboarded.
Follow this sequence of API calls to request a didr_write access token:
- GET Presentation definition: Begin by fetching the presentation definition for the
didr_writescope. - POST Token Endpoint: Create and submit a presentation according to the fetched definition.
For further details, please consult our 'How to obtain an access token' guide.
Upon successful submission, the EBSI Authorisation API will issue a short-lived, OAuth 2.0 compatible didr_invite access token.
Step 1.3.4 Add a verification method and verification relationships to your DID document
Since EBSI requires ES256 keys for signing Verifiable Credentials, you need to use the didr_write access token to add this key in the form of a new verification method with additional verification relationships to complete the DID document.
Note: It will be necessary to perform the process below three times. This means there will be three transactions in total, one for each of the following methods:
- addVerificationMethod - this method will add the ES256 key to the DID document
- addVerificationRelationship - this adds the "authentication" verification relationship for the ES256 key
- addVerificationRelationship - this adds the "assertionMethod" for the ES256 key
The following endpoints must be used to add the verification methods and verification relationships:
Upon successful submission, your wallet will receive an HTTP 200 transaction from the EBSI DID Registry Service to be signed. Once the transaction is signed, it is then ready to be returned using the sendSignedTransaction method, which will update the ledger with the transaction.
The following endpoint must be used to send a signed transaction:
After you have completed all three transactions, you can verify if the DID registration was successful by calling the Get DID document endpoint.
Step 1.4 Obtain Verifiable Authorisation for Trust Chain
Root TAOs represent the root or top-level trust point in the EBSI's Issuers Trust model and must be onboarded directly by EBSI. The Trusted Issuers Registry (TIR) is a registry containing a list of Legal Entities that are authorised to issue certain types of credentials.
To receive an invitation from the EBSI Credential Issuer, you must first request a VerifiableAuthorisationForTrustChain. The Credential Issuer will then invite you to join the Trust Chain, reserving a location and issuing the VerifiableAuthorisationForTrustChain for that specific location.
Step 1.5 Register your Verifiable Authorisation for Trust Chain
After you have received the Verifiable Authorisation for Trust Chain, you must complete the invitation by registering the credential into the TIR. The following steps will guide you through this process.
Step 1.5.1 Obtain tir_invite access token from the Authorisation API to write into the Trusted Issuers Registry
To request a tir_invite access token, you need to present proof of ownership of your Verifiable Authorisation for Trust Chain to the EBSI Authorisation API.
Follow this sequence of API calls to request a tir_invite access token:
GET Presentation definition: Begin by fetching the presentation definition for the tir_invite scope.
POST Token Endpoint: Create and submit a presentation according to the fetched definition that contains proof of ownership of your Verifiable Authorisation for Trust Chain
For further details, please consult our 'How to obtain an access token' guide.
Upon successful submission, the EBSI Authorisation API will issue a short-lived, OAuth 2.0 compatible tir_invite access token.
Step 1.5.2 Register Verifiable Authorisation for Trust Chain in TIR
The invitation is accepted by registering your Verifiable Authorisation for Trust Chain into the Trusted Issuers Registry.
The Verifiable Authorisation has a reservedAttributeId that defines the location where the authorisation must be registered into. You should build a setAttributeData transaction with attributeId from reservedAttributeId.
The following endpoint must be used to register your Verifiable Authorisation for Trust Chain into the TIR:
- TIR JSON RPC - setAttributeData: Begin by fetching the presentation definition for the tir_invite scope.
Upon successful submission, your wallet will receive an HTTP 200 transaction from the EBSI TIR Service to be signed. Once the transaction is signed, it is then ready to be returned using the sendSignedTransaction method, which will update the ledger with the transaction.
The following endpoint must be used to send a signed transaction:
After the transaction has been completed, you are officially onboarded as a Root TAO. Congratulations! 👏
2. Accredit TAOs and TIs
Now you are almost ready to start issuing Verifiable Credentials. Just a few more steps to go!
Verifiable Credential and Presentation
Check out our VC and VP library to create and verify EBSI-compliant W3C Verifiable Credentials and Verifiable Presentations in JWT format
Step 2.1 Authorise TAO to onboard by issuing a V. Authorisation to Onboard
Step 2.1.1 Provide Authorisation Server to authenticate TAO
Now that you have set up your Root Trusted Accreditation Organisation, you can onboard Trusted Accreditation Organisations.
Your Root TAO needs to provide an OIDC Authorisation Server for TAO. Authentication can be performed by using a code flow or by pre-authorisation.
Step 2.1.2 Authentication code flow
For authentication and authorisation, the Root TAO needs to provide an Authorisation Server. The TAO can start authentication by calling the Authorisation Server's authorise endpoint with response_type code. In response, the Authorisation Server should proceed to authenticate the TAO/TI, for example by requesting an ID Token. After succesful authentication, the Authorisation Server should respond with a code. Using this code, the TAO/TI can request an access token (by calling the Authorisation Server's token endpoint).
Step 2.1.3 Authentication with pre-authorization
In addition to the code flow above, authentication can also be done using a pre-authorised code. This code is delivered to the TAO via a Credential Offering or out of band method. Using this code, the TAO/TI can invoke the Authorisation Server's token endpoint directly to get an access token.
Step 2.1.4 Provide Credential Issuer service for issuing TAO Authorisation to Onboard
The Root TAO needs to provide a Credential Issuer service for a TAO. It should contain a credential endpoint which is protected by requiring an access token issued in the previous phase.
The TAO should use this endpoint to request a Verifiable Authorisation to Onboard credential. Using this credential the TAO can onboard to EBSI by inserting their DID document into EBSI DID Registry.
Step 2.2 Authorise TAO to register in the TIR
To be able to issue VCs the TAO needs to add themselves to the EBSI Trusted Issuer Registry. The Root TAO authorises this by issuing a Verifiable Accreditation to Attest.
Step 2.2.1 Enable TAO Request a V. Accreditation to Attest
Using the Authorisation Server and Credential Issuer service provided by the Root TAO, the TAO is able to request a Verifiable Accreditation to Attest VC. Using this VC, the TAO can add themselves to the EBSI Trusted Issuers Registry.
Step 2.2.2 Authorise TAO to accredit other TAO/TIs
To be able to accredit other TAO/TIs, a TAO needs register in the Trusted Issuers Registry. The Root TAO authorises this by issuing a Verifiable Accreditation to Accredit VC. Using this VC the TAO can register themselves in the Trusted Issuers Registry.
3. Revoke a Verifiable Accreditation
The following steps will allow you to revoke a Verifiable Accreditation if you need to.
Step 3.1 Obtain tir_write access token in Auth API to write to the TIR
To request a tir_write access token, you need to present proof of ownership of your Verifiable Authorisation for Trust Chain to the EBSI Authorisation API with the openid tir_write scope.
Follow this sequence of API calls to request a tir_write access token:
- GET Presentation definition: Begin by fetching the presentation definition for the
tir_writescope. - POST Token Endpoint: Create and submit a presentation according to the fetched definition.
For further details, please consult our 'How to obtain an access token' guide.
Step 3.2 Register the revocation in the Trusted Issuers Registry
Revocation of a Verifiable Accreditation will be done through the Trusted Issuer Registry by the Root TAO who originally invited the Legal Entity.
The Root TAO must set the issuerType to revoked to revoke an existing Verifiable Accreditation or the invitation. Verifiable Accreditations must contain credentialStatus with type EbsiAccreditation, where validity is determined by the smart contract.
Use the following endpoint to modify the attribute metadata using the setAttributedata method: