Now you will learn how to become operational as a Trusted Issuer (TI). A Trusted Issuer represents the Issuer in a trust chain. It may issue domain-specific Verifiable Credential types defined by the received accreditation. Issuers may issue Verifiable Credentials outside the trust chain, but these are not associated with a Root TAO and contain no reference to an accreditation.
1 - Create your DID and obtain Verifiable Authorisation to Onboard
To be able to insert transactions into EBSI's underlying ledger, the Legal Entity must possess a valid Verifiable Credential for the given purpose.
In the case of a TI, a Verifiable Authorisation to Onboard is required to be able to register a new DID into the DID Registry. Follow the steps below to obtain a Verifiable Authorisation to Onboard.
Step 1. Get authorised to request Verifiable Authorisation to Onboard
Before you can submit a request for a Verifiable Authorisation to Onboard, you must meet some preliminary requirements first.
These requirements include setting up your Organisation Wallet and creating a DID and DID document. Let's take a closer look at each of these steps below.
Step 1.1. Set up your Organisation Wallet with required capabilities
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 TIs. Other features are optional.
If an existing EBSI Conformant Wallet is chosen, the technical onboarding steps detailed below may be different, depending on the user experience provided by the Wallet.
Step 1.2. 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 TI are self-generated and must follow the DID Method for Legal Entities. EBSI defines the following DID schema: did:ebsi. Be aware that the DID document must contain an ES256K cryptographic key pair.
Need a quick refresher on DIDs and DID documents? Check out Chapter 3: Decentralised Identifiers (DID) Methods of our Verifiable Credentials Explained series and also feel free to consult as well the DID method for legal entities specifications.
Step 2. Request a Verifiable Authorisation to Onboard
To receive a Verifiable Authorisation to Onboard, Legal Entities must submit a request to their TAO or Root TAO, as it must be issued by the existing Trust Chain members.
The business requirement must be agreed upon by all parties involved to ensure the security and integrity of the onboarding process.
2 - Register your DID document (and DID keys) in the EBSI DID Registry
How to generate a DID document Not sure about what a DID document looks like or how can you generate one? Consult our Legal Entity DID Resolver library.
Now that you have received a Verifiable Authorisation to Onboard, you can proceed to request the access tokens needed to register your DID document and DID keys to the EBSI DID Registry and add a verification method for verification relationships.
Step 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 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 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. Note that it is no longer 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 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:
Please note that this verification method will only appear in the DID document after adding a verification relationship.
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.
3 - Obtain and register the Verifiable Accreditation to Attest in the Trusted Issuers Registry
The Trusted Issuers Registry (TIR) is a registry containing a list of Legal Entities that are authorised to issue certain types of credentials.
After you have received the Verifiable Accreditation to Attest, you must complete the invitation by registering the credential into the Trusted Issuers Registry. The following steps will guide you through this process.
Step 1. Request Verifiable Accreditation To Attest
To receive an invitation from the EBSI Credential Issuer, you must first request a VerifiableAccreditationToAttest Verifiable Credential.
The Credential Issuer will then invite you to join the Trust Chain, reserving a location and issuing the VerifiableAccreditationToAttest for that specific location.
Step 2. 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 Accreditation to Attest 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 Accreditation to Attest
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 3. Register your Verifiable Accreditation to Attest
The invitation is accepted by registering your Verifiable Accreditation to Attest 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 Accreditation to Attest 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 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 TI. Congratulations! 👏
4 - Start issuing Verifiable Authorisations to Onboard TAO and TI
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 1. Get information about the requested VC(s)
Step 2. Create a VC issuance offer
You can initiate a Credential Offering using the openid-credential-offer endpoint implemented by the wallet. The Credential Offering can be structured in two ways:
- The data required can be directly included within the credential_offer field; or
- a URI reference can be provided via the credential_offer_uri field, which will resolve to the identical data structure with a content type of application/json.
Credential Offering - Non normative example
Credential Offering as URI reference - Non normative example
For security and consistency, it is recommended to host the Credential Offering under the same domain as the Credential Issuer.
The process initiated by the issuer can follow one of two different interaction models:
- Same-Device Model: In this model, the user's Holder wallet is installed on the same device used to access the credential issuer's website. The interaction is initiated by the issuer through an HTTP redirect.
- Cross-Device Model: In this case, the user's Holder wallet is installed on a device different from the one they are using to visit the credential issuer's website. The interaction is initiated by the issuer by presenting a QR code. The user must then scan this QR code using the device where their Holder Wallet is installed.
For a detailed overview of the Credential Offering process, required parameters and their descriptions, refer to the Credential Offering section of the VC Issuance Guidelines.
Step 3. Authenticate the user
Step 3.1. Request username/password or other authentication
In addition to requesting a username or password, several methods are available for user authentication. These include:
- Utilising the issuer's existing authentication service
- Requiring the user to prove control over a DID, as long as the Issuer already possesses a pre-established relationship with the DID
- Requiring the user to present a VC recognised by the Issuer
- Employing a blend of all these methods
Currently, Functional Flows employ a forced ID Token Request and Response for user authentication. This method is employed for some authentication coverage and might be eliminated if user authentication is not needed, or alternative means of authentication are applied.
The End-User DID for the Verifiable Credential is disclosed during the Credential Request flow, within the JWT proof.
Step 3.2. Request additional information in a VC/VP format
Note: Requesting additional information to the user before issuing VCs is dependent on the specific Use Case
Step 3.3. Create a VP request
A VP Token Request is a process initiated by the Authorisation Service to request a VP token.
The process begins when the user's wallet sends an Authorise Request to the Verifier. In response, the Authorisation Service sends the VP Token Request to the Wallet through a redirect Location URI. This VP token is a JWT (JSON Web Token), signed using the Holder's private key. This key corresponds to the authentication key mentioned in the Holder's DID document. By signing with the private key, it provides proof that the Holder has control over this key. The redirection schema involved is registered through the client_metadata.authorization_endpoint in the Authorisation Request. The request is then forwarded as a signed object, containing specific fields.
Step 3.4. Verify the shared VPs/VCs
To verify VPs and VCs, you need to first identify the type of signature used. To do this, you can check the header of the JWT. If it contains JAdES-specific header properties like 'x5c', it indicates that a JAdES signature has been used. If no such properties are found, it is a JWS signature.
Once the signature type is determined, the next step is to validate it.
For a JWS signature:
- First, identify the DID EBSI version used. If the JWT header contains properties 'kid' and 'jwk', it signifies the use of EBSI DID Method for Natural Persons. In the absence of these properties, the EBSI DID Method for Legal Entities is used.
- In the case of the EBSI DID Method for Legal Entities, resolve the DID Document and the public key. For the EBSI DID Method for Natural Persons, construct the DID Document from the JWK public key and the DID identifier.
- Finally, Verify the JWS signature (Compact Serialisation) using any library that supports JWS signatures.
For a JAdES signature, you must verify it using the DSS Demonstration WebApp. The signed file is the JWT, and the original file is the decoded payload, which is initially base64 encoded.
Step 3.5. Request a proof of DID control
This optional step is used to verify the user’s control of their DID and is use-case dependent. Trusted issuers can request the following for this purpose:
- ID Token for DID proof
- VP Token for VCs
- external authentication
- a combination of the previous ones
The TI requires the Holder to authenticate themselves or provide attestations before completing the initial authorisation request.
For a deeper dive into this topic, please see User Authentication
Step 3.6. Notify the user that the issuance is pending approval
- Return an acceptance token to the user
- Notify the back office about the pending VC issuance request
Step 4. Issue a VC
Step 4.1. Create a VC
Verifiable Credentials and Verifiable Attestations in EBSI with external proofs are generally encoded as JSON Web Tokens (JWT).
This encoding uses mature standards-based methods for signing content and builds on JWS with compact serialisation.
JWS compact serialised is the basis for JWT. JWT contains the header, payload, and signature. The header contains information about the used signing algorithm, while the payload contains JWT claims and VC/VP.
Currently, the ES256 cryptographic algorithm MUST be supported by all actors. Support for other cryptographic algorithms is encouraged and the current design of VC and VP should work with all well known cryptographic algorithms that JWS supports.
For detailed information on the properties of the core Verifiable Credential data model that must be transformed to JWT claims, refer to the JWS section in the E-signing and e-sealing VCs and VPs guidelines.
Step 4.2. E-seal/E-sign the VC
Once you have created a VC in JSON format using one of the EBSI VC Data models, you are ready to sign it. EBSI supports two signature formats: JSON Web Signatures (JWS) and JSON advanced electronic signatures (JAdES).
As per the eIDAS Regulation, Trusted Issuers operating in the European Single Market (ESM) must use JAdES, an enhanced form of JWS.
These signatures use cryptographic keys and certificates via a public-key infrastructure (PKI). JAdES also adds extra properties to the JWS header, aligning with other standards by the European Telecommunications Standards Institute (ETSI). This ensures the secure signing of Verifiable Credentials.
For a JWS signature, any library that supports JWS signatures (e.g., Authlib) can be used to sign the VC. As for JAdES, signing can be done using the DSS Demonstration WebApp.
For detailed examples of each type of signature, refer to How to sign VC and VP.
As an optional step you can notify the user via a communication channel (email, sms, ...) that the VC has been issued
5 - Revoke a Verifiable Attestation
Trusted issuers must maintain their own infrastructure, or use a trusted third-party service, to serve credential status lists and register the server as a proxy in the TIR. Once the proxy is configured, Trusted Issuers can issue revocable credentials by adding a credentialStatus object to the credential. The credentialStatus object will reference a specific bit position in a specific credential status list available through the proxy. A bit value of 0 indicates that the credential is valid, while a bit value of 1 indicates that the credential is revoked (or suspended, depending on the statuslist purpose)
For more in-depth technical information, please consult W3C VC bit String Status List.
If you need to revoke a Verifiable Attestation or Verifiable Credential, follow the steps below.
Step 1. Setup of Status API
The Issuer must register the Credential Status API endpoints on the EBSI Trusted Issuers Registry. When a request is submitted, a Credential Status VC is returned in a JWT-VC format, signed by the Issuer of the referenced VC. The Credential Status VC schemas of the supported revocation/suspension formats are defined in the JSON schema repository.
The following OpenAPI specification defines interfaces issuers must expose so that the Trusted Issuers Registry can fetch the information.
The timestamp query parameter is only supported by the Dynamic SL Bloom Filter 2023 and should be ignored for all others.
Step 2. Configure VC Status Proxy
The Issuer must configure a minimum of one proxy before a Status VC request is processed to protect the privacy of the Verifier's activities. The proxy is created using the Trusted Issuers Registry JSON-RPC method addIssuerProxy, and AttributeData must contain the proxy configuration. The configured proxy must provide a valid Status VC signed by the Issuer requesting the proxy for the registration to be accepted. A validation combining "prefix" with "testSuffix" is executed before the registration is accepted. The validation will fail if the credential status proxy does not exist.
The proxies operate by replacing the original URL prefix with a configured prefix and inserting a header into the call. The configuration must be uploaded into issuer attributes.
To learn more about configurable parameters for the proxy, please see Credential Status Framework - VC Status Proxy.