> For the complete documentation index, see [llms.txt](https://docs.inrupt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.inrupt.com/security/authentication.md). # 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](https://openid.net/connect/) (OIDC) standards, which build on the [OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749) authorization framework. * [OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749) defines a framework for authorization, in which a client obtains an access token to obtain access to resources. * [OpenID Connect](https://openid.net/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](https://datatracker.ietf.org/doc/html/rfc7519) (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](#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](https://docs.inrupt.com/ess/latest/services/service-platform-management/token-exchange). 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](https://docs.inrupt.com/ess/latest/services/service-platform-management/token-exchange). 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](https://datatracker.ietf.org/doc/html/rfc7519) (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](https://docs.inrupt.com/ess/latest/services/service-platform-management/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](/security/authorization.md#authorization-and-clients). ## Advanced Configuration: Solid OIDC Broker When ESS must interoperate with other [Solid](https://solidproject.org/) servers or issue Solid-OIDC-compliant tokens, ESS includes a [Solid OIDC Broker Service](https://docs.inrupt.com/ess/latest/services/service-oidc/). In this configuration, the Broker is the Identity Provider that ESS trusts, and it implements the [Solid-OIDC](https://solid.github.io/solid-oidc/) specification. {% hint style="info" %} 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](#identity-provider-integration) described above. {% endhint %} ### WebID In the Solid ecosystem, users are identified by a [WebID](/reference/glossary.md#webid). A WebID is a URL (e.g., **`https://id./user1234`**) that can be dereferenced to an RDF profile document. ESS includes a [WebID Service](https://docs.inrupt.com/ess/latest/services/service-webid/). WebIDs issued by ESS have the form: ```none https://id./ ``` ### Client Identifier (Client ID) In [Solid-OIDC](https://solid.github.io/solid-oidc/), an application identifies itself using a [client identifier (Client ID)](/reference/glossary.md#client-id). A Client ID can be: * a URL that dereferences to a [Client ID Document](https://solid.github.io/solid-oidc/#clientids-document). * a value that has been registered using either [OIDC dynamic or static registration](https://solid.github.io/solid-oidc/#clientids-oidc). #### **Solid-OIDC Client ID Document** ESS supports [Client Identifiers (Client IDs)](https://solid.github.io/solid-oidc/#clientids) that are of type URL and dereference to a JSON-LD document, the [Client ID Document](https://solid.github.io/solid-oidc/#clientids-document). #### **Client Registration** For applications that do not use identifiers that dereference to a Client ID Document, they can [register](https://datatracker.ietf.org/doc/html/rfc7591.html) with ESS' [Solid OIDC Broker service (the Broker)](https://docs.inrupt.com/ess/latest/services/service-oidc/). To register, a client provides various [metadata about itself](https://datatracker.ietf.org/doc/html/rfc7591#section-2) as part of its registration request (see [RFC7591: 3.1 Client Registration Request](https://www.rfc-editor.org/rfc/rfc7591#section-3.1)). 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](https://www.rfc-editor.org/rfc/rfc7591#section-3.2). #### **Dynamic Registration** To dynamically register an application, an application POSTs to [the Broker's](https://docs.inrupt.com/ess/latest/services/service-oidc/) client **`registration_endpoint`** with the client's metadata. {% hint style="info" %} Tip\ To determine if the Broker supports dynamic client registration, check its **`/.well-known/openid-configuration`** for the **`registration_endpoint`** field. {% endhint %} Inrupt's JavaScript client libraries provide **`login`** APIs that handle dynamic registration of applications. #### **Static Registration** ESS supports [static registration of client applications](https://docs.inrupt.com/ess/latest/services/service-oidc/service-application-registration) 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](https://docs.inrupt.com/ess/latest/services/service-oidc/service-application-registration). ### Broker Tokens As part of the Solid-OIDC login flow, ESS' [Solid OIDC Broker Service](https://docs.inrupt.com/ess/latest/services/service-oidc/) 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](https://datatracker.ietf.org/doc/html/rfc7519) (JWT). The [OpenID specification](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) defines an extensible data structure for ID Tokens. This data structure is serialized as a [JSON Web Token](https://datatracker.ietf.org/doc/html/rfc7519). See also [Broker Token Claims](https://docs.inrupt.com/ess/latest/services/service-oidc/#openidp-claims). ESS ID tokens have a default lifespan of 5 minutes (see [**`SMALLRYE_JWT_NEW_TOKEN_LIFESPAN`**](https://docs.inrupt.com/ess/latest/services/service-oidc#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](https://datatracker.ietf.org/doc/html/rfc7519) (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](https://docs.inrupt.com/ess/latest/services/service-oidc/#openidp-claims). ESS access tokens have a default lifespan of 5 minutes (see [**`SMALLRYE_JWT_NEW_TOKEN_LIFESPAN`**](https://docs.inrupt.com/ess/latest/services/service-oidc#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](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop-00)). A [DPoP proof](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop-00) 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.