Introduction
The Authorisation API is a core EBSI service responsible for managing access to protected EBSI services. To receive a short-lived access token with a two-hour lifespan, a legal entity must present a valid Verifiable Authorisation or Verifiable Accreditation in the form of a Verifiable Presentation (VP). The access token's scope is limited and corresponds to the specific authorisations of the legal entity.
Users obtain access tokens by presenting a valid EBSI Verifiable Credential and proving ownership over their DID. During the onboarding process, when a user does not yet have ownership of a DID, presenting a VerifiableAuthorisationToOnboard is sufficient.
The Authorisation API utilises the following capabilities:
- Authorisation Server discovery via the /.well-known/openid-configuration
- OpenID for Verifiable Presentation capabilities (v 0.14)
- OIDC capabilities (v1.0)
EBSI Platform differentiates between identified and anonymous users, each with a unique set of intents.
Identified users are legal entities that utilise the trusted registries - the DID registry and Trusted Issuer Registry.
Anonymous users only have access to read public information, allowing them to call all the REST endpoints, but not the JSON-RPC endpoints.
For more information, refer to:
- CLI Tool page: Test the capabilities using the EBSI CLI tool.
Mechanism
Within EBSI, DIDs serve as identity identifiers. Proof of DID ownership is established via the exchange of Verifiable Presentations.
Access management is divided into two components:
Endpoint protection - Filters intents to manage access.
Entity protection - Applies business logic-based rules.
Please note, access is always intent-based, which is manifested as an OAuth 2.0 scope.
Scopes must conform to the pattern of <domain>_<intent>[_<nominator>].
Presentation Definition
Each identified scope has unique Verifiable Presentation definition requirements. A GET HTTP endpoint is exposed, as defined in openid-configuration under the presentation_definition_endpoint claim, where the client can obtain the presentation definition for the requested scope. The following scopes are supported:
- SCOPES
| Intent | Scope | Type | Description | Authorisation |
|---|---|---|---|---|
| Add DID document | didr_write | Fallback | Grants write access to DID Registry | Granted When VP contains only a valid VerifiableAuthorisationToOnboard, issued by Root TAO or TAO. |
| Add Trusted Issuer Registry content | tir_write | Privileged | Grants write access to TIR. | Granted when VP contains a valid VerifiableAuthorisationForTrustChain from EBSI TO, or a Verifiable Accreditation (VerifiableAccreditationToAttest, or VerifiableAccreditationToAccredit), issued by Root TAO or TAO. |
Unrecognised scopes will return an error.
- ACTORS
| Abbreviation | Term | Description |
|---|---|---|
| EBSI TO | EBSI Technical Office | Technical support team within EBSI |
| RTAO | Root Trusted Accreditation Organisation | Entity that issues Verifiable Accreditations for Trusted Accreditation Organisations |
| TAO | Trusted Accreditation Organisation | Entity that issues Verifiable Accreditations (Accreditations, Attestations and Authorisations) to legal entities |
| TI | Trusted Issuer | Legal Entity with one or more accreditations. Accredited to accredit, attest or authorise |
- REGISTRIES
| Name | Role |
|---|---|
| DID Registry (DIDR) | Stores registered DIDs |
| Trusted Issuers Registry (TIR) | Stores registered accreditations from TIs |
- POLICIES
| API | Scope | Required Verifiable Credential | Granted Access | Methods to be used |
|---|---|---|---|---|
| DIDR | didr_write | No credentials are required, but the requestor must be a Trusted Issuer. | Full control over the DID Registry and Trusted Issuers Registry | insertDidDocument / updateBaseDocument / addController / revokeController / addVerificationMethod / addVerificationRelationship / revokeVerificationMethod / expireVerificationMethod / rollVerificationMethod |
| DIDR | didr_invite | VerifiableAuthorisationToOnboard | Registration of DID into the DID Registry | insertDidDocument: didr_invite + AT.sub == req.params.did (the DID to be inserted) |
| TIR | tir_write | No credentials are required, but the requestor must be a Trusted Issuer. | Full control over the DID Registry and Trusted Issuers Registry | insertIssuer / updateIssuer / setAttributeMetadata / setAttributeData / insertPolicy / updatePolicy / addIssuerProxy / updateIssuerProxy |
| TIR | tir_invite | VerifiableAuthorisationForTrustChain or VerifiableAccreditationToAttest or VerifiableAccreditationToAccredit | Registration of VC into the Trusted Issuers Registry | setAttributeData: tir_invite + AT.sub == req.params.did (the DID to be inserted) |
Obtaining Access
The authorisation service generates a short-lived, OAuth 2.0 compatible access token derived from the Verifiable Presentation. Please note, due to brief session lifetimes, which are currently defined on a case-by-case basis, refresh tokens are not supported.
Follow this sequence of API calls to request an access token:
GET Presentation definition: Begin by fetching the presentation definition for the required scope.
POST Token Endpoint: Once you have the definition, create and submit a presentation matching the fetched definition.
Note: didr_write scope is an exception and must be requested alone due to the validation requirements it implies.
The diagram below captures an interaction between a client and the EBSI Authorisation Service.
API Endpoints
OpenID Provider Metadata
Exposes the configuration of the OpenID Provider. For a detailed description of this endpoint, please refer to the documentation here:
OpenID Provider's public keys
Exposes the public keys used by the authorisation server. For a detailed description of this endpoint, please refer to the documentation here:
Get presentation definition requirements
Fetches presentation definition requirements. For a detailed description of this endpoint, please refer to the documentation here:
Get access token
Users receive access tokens by presenting a valid EBSI Verifiable Credential and proving ownership over their DID. For a detailed description of this endpoint, please refer to the documentation here: