Authentication

An authentication system determines the identity of a user or agent and the level of trust associated with this identity.

For authentication, ESS supports OpenID Connect (OIDC) standards, which build on the OAuth 2.0 authorization framework.

• OAuth 2.0 defines a framework for authorization, in which a client obtains an access token to obtain access to resources.

• OpenID Connect defines a standard mechanism by which a web application leads a user through a login flow. The login flow results in a signed ID token, which is a JSON Web Token (JWT) that asserts the identity of the user.

Identity Provider Integration

ESS integrates with your existing OIDC-compliant Identity Provider. There is no proprietary identity broker or intermediary required — ESS establishes a trust relationship directly with your IdP, allowing you to use the identity infrastructure you already have.

Supported Identity Providers include any OIDC-compliant provider, such as:

• Keycloak

• Amazon Cognito

• Microsoft Azure AD

• Okta

• Ping Identity

• ESS Solid OIDC Broker (see Advanced Configuration: Solid OIDC Broker)

Trust Relationship

To integrate an IdP with ESS, configure the IdP's issuer URL as a trusted issuer in the Platform Management Service. ESS validates tokens from trusted issuers using standard OIDC discovery — it fetches the IdP's .well-known/openid-configuration to obtain signing keys and verify token signatures.

Authentication Flow

Client → External IdP → Platform Management Service (token exchange) → ESS Access Token

1. The client authenticates with the external Identity Provider using standard OIDC flows.

2. The IdP issues an ID token to the client.

3. The client exchanges the ID token for an ESS Access Token via the Platform Management Service's token exchange endpoint.

4. The client uses the ESS Access Token for all subsequent requests to ESS services.

ESS Access Token

The ESS Access Token is a signed JSON Web Token (JWT) issued by the Platform Management Service. It is the credential used to access all ESS services.

• Format: JWT

• Default TTL: 5 minutes

• Usage: Include as a Bearer token in the Authorization header of requests to ESS services

ESS verifies the token signature and that the token has not expired. An invalid or expired token cannot be used to access resources.

For details on obtaining an ESS Access Token, see Token Exchange.

Client IDs in Allow Lists and Access Policies

ESS supports the use of Client IDs in client allow list configurations and access policies to restrict which clients can be used. These restrictions are enforced at the Platform Management Service level.

For details, see Authorization and Clients.

Advanced Configuration: Solid OIDC Broker

When ESS must interoperate with other Solid servers or issue Solid-OIDC-compliant tokens, ESS includes a Solid OIDC Broker Service. In this configuration, the Broker is the Identity Provider that ESS trusts, and it implements the Solid-OIDC specification.

The Solid OIDC Broker is an advanced configuration, needed only when ESS must interoperate with other Solid servers or issue Solid-OIDC-compliant tokens. Standard enterprise deployments use the Identity Provider integration described above.

WebID

In the Solid ecosystem, users are identified by a WebID. A WebID is a URL (e.g., https://id.<ESS Domain>/user1234) that can be dereferenced to an RDF profile document.

ESS includes a WebID Service. WebIDs issued by ESS have the form:

https://id.<ESS DOMAIN>/<username>

Client Identifier (Client ID)

In Solid-OIDC, an application identifies itself using a client identifier (Client ID).

A Client ID can be:

• a URL that dereferences to a Client ID Document.

• a value that has been registered using either OIDC dynamic or static registration.

Solid-OIDC Client ID Document

ESS supports Client Identifiers (Client IDs) that are of type URL and dereference to a JSON-LD document, the Client ID Document.

Client Registration

For applications that do not use identifiers that dereference to a Client ID Document, they can register with ESS' Solid OIDC Broker service (the Broker).

To register, a client provides various metadata about itself as part of its registration request (see RFC7591: 3.1 Client Registration Request).

Upon successful registration, the Broker responds with a unique client_id. The response may include additional fields. For details, see RFC7591: 3.2 Client Registration Responses.

Dynamic Registration

To dynamically register an application, an application POSTs to the Broker's client registration_endpoint with the client's metadata.

Tip To determine if the Broker supports dynamic client registration, check its /.well-known/openid-configuration for the registration_endpoint field.

Inrupt's JavaScript client libraries provide login APIs that handle dynamic registration of applications.

Static Registration

ESS supports static registration of client applications associated with a user (i.e., WebID). Static registration results in client credentials (i.e., client_id and client_secret). ESS' application registration returns client_id of type UUID.

Single-user scripts and bots can use these client credentials to authenticate (on behalf of the user) without requiring browser-based user interactions with the Identity Provider.

For details, see Application Registration.

Broker Tokens

As part of the Solid-OIDC login flow, ESS' Solid OIDC Broker Service issues ID tokens and access tokens. The Broker includes the WebID and the Client ID as claims in these tokens.

ID Tokens

An ID token asserts the identity of the user and is represented as a JSON Web Token (JWT).

The OpenID specification defines an extensible data structure for ID Tokens. This data structure is serialized as a JSON Web Token.

See also Broker Token Claims.

ESS ID tokens have a default lifespan of 5 minutes (see SMALLRYE_JWT_NEW_TOKEN_LIFESPAN).

Signed Access Tokens

The Broker issues signed access tokens that provide access to resources. Access tokens are represented as JSON Web Tokens (JWT).

ESS verifies the token signature and that the token has not expired. An invalid token cannot be used to gain access to resources.

See also Broker Token Claims.

ESS access tokens have a default lifespan of 5 minutes (see SMALLRYE_JWT_NEW_TOKEN_LIFESPAN).

Demonstration of Proof-of-Possession (DPoP) Token

As an additional layer of protection against token stealing and various replay attacks, Solid clients can send an additional HTTP header (specifically a DPoP proof).

A DPoP proof can be used to verify that a client is in legitimate possession of an access token while also scoping the request to a particular Pod resource. This helps prevent against token exfiltration attacks.

ESS uses version 00 of DPoP.