Solid OIDC Broker Service#

ESS’ Solid OIDC (OpenID Connect) Broker Service (also referred to as the Broker Service or Broker sfor short) is responsible for handling authentication.

The service provides a compatibility layer between the Solid ecosystem in which users are identified with a WebID and traditional OpenID Connect providers that identify users with strings. ESS’ Broker allows a Solid user to login with any existing OIDC-compliant identity provider.

Integration with the Identity Provider#

The ESS’ Broker Service integrates with your OpenID Connect (OIDC) compliant Identity Provider (IdP). During installation/setup, the Broker Service is set up as a client to your IdP.

Broker Service Endpoint#

By default, the Broker runs from the following root URL:

https://openid.<ESS DOMAIN>

Discovery#

ESS provides Broker metadata at the following /.well-known/openid-configuration URI:

https://openid.<ESS DOMAIN>/.well-known/openid-configuration

The endpoint returns the current deployment’s Broker metadata.

Application Registration#

The Broker provides an Application Registration interface where users can register their server-side scripts for use with a client credentials OAuth flow (i.e., client_id and client_secret).

With these client credentials, your scripts can perform the authentication flow without requiring an in-browser interaction with the Broker.

For more information, see Application Registration.

Tokens and Claims#

The Broker Service issues ID and signed access tokens:

ID tokens assert the identity of the user.
- They are represented as a JSON Web Token (JWT).
- They have a default lifespan of 5 minutes (see SMALLRYE_JWT_NEW_TOKEN_LIFESPAN).
Access tokens provide access to resources.
- They are represented as JWT-based structure.
- They have a default lifespan of 5 minutes (see SMALLRYE_JWT_NEW_TOKEN_LIFESPAN).

Broker Token Claims#

Using the response from the Identity Provider (IdP), the Broker issues ID Tokens and Access tokens (as JSON Web Tokens) that contain various claims, including:

`aud`	The intended audience/recipients for the token: In the ID Token, the `aud` is an array that includes the string literal `"solid"` as well as the registered client_id of the application. In the Access Token, the `aud` is a string literal `"solid"`.
`azp`	The Authorized party (i.e., the registered client_id) to whom the ID Token is issued.
`iss`	The issuer of the token; i.e., the ESS’ Broker’s URL. See `INRUPT_OPENID_ISSUER`.
`sub`	The subject of the token; i.e., the username from the IdP.
`webid`	The WebID for the user. ESS’ Broker generates the `webid` claim value to be consistent with the WebIDs created by ESS’ WebID service. Specifically, ESS’ Broker takes its `INRUPT_OPENID_WEBID_HOST` configuration and, by default, thes `sub` claim in the backing IdP’s ID token (see also `INRUPT_OPENID_USER_CLAIM_NAME`). To work with other WebID services, the ESS’ Broker also supports the following configuration values if set: `INRUPT_OPENID_WEBID_PATH` `INRUPT_OPENID_WEBID_FRAGMENT`. However, these configurations are incompatible with ESS’ WebID service.

Broker Service Configuration#

As part of the installation process, Inrupt provides base Kustomize overlays and associated files that require deployment-specific configuration inputs.

The following configuration options are available for the service and may be set as part of updating the inputs for your deployment. The Inrupt-provided base Kustomize overlays may be using updated configuration values that differ from the default values.

Required#

INRUPT_OPENID_ISSUER#

The URL of the Broker. The value is used to generate the iss claim.

Important

To work with ESS’ WebID service, ensure that:

the value matches that of the WebID service’s INRUPT_WEBID_ISSUER.
the value is included in the WebID service’s INRUPT_JWT_ISSUER_ALLOW_LIST.

INRUPT_OPENID_WEBID_FRAGMENT#

A URI fragment used to generate the webid claim value when using an external WebID service.

Starting in version 2.0, ESS’ WebID service creates WebIDs of the form https://id.{ESS DOMAIN}/{username}, and as such, INRUPT_OPENID_WEBID_FRAGMENT is incompatible with ESS’ WebID service.

Instead, this setting is provided to work with external WebID services that support WebIDs of the form https://{DOMAIN}/{username}/{path to profile}{fragment} (e.g., https://{DOMAIN}/{username}/profile/card#me).

INRUPT_OPENID_WEBID_HOST#

The WebID Service host. The value is used, along with the sub claim in the backing Identity Provider’s ID tokens, to generate the webid claim value.

See also INRUPT_OPENID_USER_CLAIM_NAME to use a different claim from the backing Identity Provider’s ID tokens.

INRUPT_OPENID_WEBID_PATH#

A path component used to generate the webid claim value when using an external WebID service.

Starting in version 2.0, ESS’ WebID service creates WebIDs of the form https://id.{ESS DOMAIN}/{username}, and as such, INRUPT_OPENID_WEBID_PATH is incompatible with ESS’ WebID service.

Instead, this setting is provided to work with external WebID services that support WebIDs of the form https://{DOMAIN}/{username}/{path to profile} (e.g., https://{DOMAIN}/{username}/profile/card#me).

QUARKUS_OIDC_AUTH_SERVER_URL#: The URL of your backing Identity Provider.

QUARKUS_OIDC_CLIENT_ID#: The client ID for connecting to the backing Identity Provider.

QUARKUS_OIDC_CREDENTIALS_SECRET#: The client secret for connecting to the backing Identity Provider.

SMALLRYE_JWT_SIGN_KEY_LOCATION#: Path to your JWT Key location.

Warning

The JWT Key is used to sign tokens issued by your ESS deployment’s Broker. Safeguard your JWT Key.

Kafka Configuration#

Tip

Optional#

COM_INRUPT_OPENID_CDI_DEFAULTCLIENTRESOLVERSERVICE_FETCHREMOTECLIENT_TIMEOUT_UNIT#

Default: SECONDS

Valid values are the ChronoUnit Enum Constants constants as strings; e.g., SECONDS, MINUTES, HOURS, etc.

COM_INRUPT_OPENID_CDI_DEFAULTCLIENTRESOLVERSERVICE_FETCHREMOTECLIENT_TIMEOUT_VALUE#

Default: 10

The maximum time to wait for the client resolver to fetch remote application identifiers.

INRUPT_OPENID_ACCESS_TOKEN_SUB#

Default: false

A boolean flag that specifies whether to include a subject sub claim in the user’s access token. Set to true to include.

INRUPT_OPENID_APPROVAL_TEMPLATE_LOCATION#: The location of a custom approval HTML page to be shown as part of the login flow. Leave unset to use the default approval page. For an example of setting a custom approval page, see Use a Custom Approval Template.

INRUPT_OPENID_CATALOG_DISABLED#

A boolean flag for disabling the Application Registration where users can register client applications. Application Registration is available by default.

Set INRUPT_OPENID_CATALOG_DISABLED to true to disable this feature.

New in version 2.0.

INRUPT_OPENID_CLIENT_DOMAIN_ALLOWLIST#

A comma-delimited list of allowed domains for application identifiers (e.g., https://registry.example/,https://apps.example/registry/).

If set, only the listed domains are allowed for application identifiers unless the domain is also denied in the INRUPT_OPENID_CLIENT_DOMAIN_DENYLIST. If unset, all domains are allowed for appliction identifiers with the exception of any domains listed in the INRUPT_OPENID_CLIENT_DOMAIN_DENYLIST configuration.

INRUPT_OPENID_CLIENT_DOMAIN_DENYLIST#

A comma-delimited list of domains that are not acceptable for application identifiers (e.g., https://registry.example/,https://apps.example/registry/).

If set, application identifiers from the listed domains are not allowed. If unset, all domains are allowed unless INRUPT_OPENID_CLIENT_DOMAIN_ALLOWLIST is set.

INRUPT_OPENID_CUSTOM_CLAIMS#: Comma-delimited mapping of custom claims to OAuth2 scopes having the form <claim1>=<scope1>,<claim2>=<scope2>,... (e.g., appid=myapp,avatar=myapp,pet=myapp).

INRUPT_OPENID_JWT_ALTERNATIVE_PUBLIC_KEY_LOCATIONS#: A comma-delimited list of paths to alternative keys to include in the service’s public JSON Web Key Set. The property may be useful when rotating signing keys while continuing to support the verification of older signatures.

INRUPT_OPENID_LOGOUT_URL#: If the backing authorization server does not support OpenID-based logout but does have a custom logout endpoint, that value can be defined with this configuration.

Tip

Do not use this setting with QUARKUS_OIDC_LOGOUT_PATH.

INRUPT_OPENID_SCHEDULED_TASKS#

Default: 300s (every 300 seconds)

The interval at which to run scheduled jobs in the background. The value is a string that specifies the number of seconds followed by the letter s.

This configuration is only relevant for PostgreSQL-based deployments.

INRUPT_OPENID_SCOPES#: A comma-delimited list of OAuth2 scopes (e.g., openid,webid,offline_access) available for client applications.

INRUPT_OPENID_USER_CLAIM_NAME#

The claim in the ID tokens (issued by the backing Identity Provider) that ESS’ Solid OIDC Broker Service should use to construct the WebID value in Solid OIDC Broker Service's tokens.

By default, ESS’ Solid OIDC Broker Service uses the sub claim in the ID tokens produced by the backing identity provider. To use a different claim, specify the name of the claim in this configuration. For example, if the backing identity provider produces tokens with a user_id claim, set this configuration to user_id to have ESS’ Solid OIDC Broker Service use the user_id claim instead of the sub claim.

Important

If using this setting, ensure that values in the specified claim are unique across the corresponding user pool.
The value of the claim must be URL-safe (e.g., no spaces or characters that are problematic for URLs).
The value of the claim must be consistent over time for a user.

INRUPT_OPENID_WEBHOOK_POST_CONSENT_AUTH#: Deprecated since version 2.0: This option will be removed in a future release.

When the INRUPT_OPENID_WEBHOOK_POST_CONSENT_URL configuration is used with endpoints that require authentication, this setting can be used to populate an Authorization header in those requests.

INRUPT_OPENID_WEBHOOK_POST_CONSENT_URL#

Deprecated since version 2.0: This option will be removed in a future release.

The URL to which the post_consent Webhook sends data. The data sent includes:

OIDC issuer claim
OIDC subject claim
Solid WebID claim
Authentication stage (e.g., post_consent)

This can be used with an external auditing system that keeps track of all OpenId-based user consent agreements.

INRUPT_OPENID_WEBID_REENCODE_BASE64#

Default: false

A boolean flag that indicates whether the Broker should re-encode a Base64-encoded subject claim in Base64URL encoding without padding, suitable for generating WebID URLs.

Only enable (i.e., set to True) if your backing identity provider produces claims encoded in Base64.

INRUPT_OPENID_WEBID_SUBJECT_PREFIX#

A prefix to include as part of the WebID.

A user’s WebID value is formed from either the sub claim from the backing identity provider or from another claim (via the INRUPT_OPENID_USER_CLAIM_NAME setting). INRUPT_OPENID_WEBID_SUBJECT_PREFIX makes it possible to prefix these incoming values with a supplied string.

For example, if the identity provider generates ID tokens with a sub claim of 123456, a WebID URL might otherwise be formed as https://id.server.example/123456. A INRUPT_OPENID_WEBID_SUBJECT_PREFIX value of user_ would result in WebID values taking the following form: https://id.server.example/user_123456.

Important

Do not change this value after users have begun provisioning Pods with their WebID.

INRUPT_OPENID_WEBID_TRIM_BASE64_PADDING#

Default: false

Deprecated since version 2.0.

A boolean flag that indicates whether the Broker should remove padding from the base64 encoding on the end of a subject claim.

Only enable (i.e., set to True) if your backing identity provider produces claims with base64 padding.

Beginning with version 2.0.5, this claim is deprecated. Deployments should use the INRUPT_OPENID_WEBID_REENCODE_BASE64 configuration instead.

QUARKUS_DATASOURCE_JDBC_URL#

Required if using a PostgreSQL database for persistence

The JDBC connection string for the PostgreSQL database.

QUARKUS_DATASOURCE_PASSWORD#

Required if using a PostgreSQL database for persistence

The password for the JDBC connector

QUARKUS_DATASOURCE_USERNAME#

Required if using a PostgreSQL database for persistence

The username for the JDBC connector

QUARKUS_LOG_LEVEL#

Default: INFO

Logging level.

QUARKUS_OIDC_AUTHENTICATION_SCOPES#: A comma-delimited list of OAuth2 scopes (e.g., openid,offline_access) available from the backend identity provider.

QUARKUS_OIDC_LOGOUT_PATH#

If the backing identity provider supports user-initiated logout, as defined by the OpenID specification, this property can be used to define the path where logout is initiated. For example, if this service is running at https://id.example, a logout path of /logout would set the url https://id.example/logout as the logout path for the application.

This configuration should not be used if the backing identity provider does not support OpenID-based logout.

For more information, see https://quarkus.io/guides/security-openid-connect#quarkus-oidc_quarkus.oidc.logout.path.

QUARKUS_OIDC_LOGOUT_POST_LOGOUT_PATH#: If QUARKUS_OIDC_LOGOUT_PATH is used, this value must be set as /endsession.

SMALLRYE_JWT_NEW_TOKEN_LIFESPAN#

Default: 300

The number of seconds before access tokens and ID tokens expire.

Additional Information#

Configure the Broker Service#

To update the configuration, you can use Kustomize overlays. For examples, see

For additional information and examples on customizing ESS, see Customize ESS.