Solid OIDC Broker Service

ESS’ Solid OIDC Broker Service (also referred to as the Broker Service or Broker for 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 (OIDC) 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 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:

Broker Token Claims

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

Field
Description

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, the 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:

However, these configurations are incompatible with ESS’ WebID Service.

See also ID Token section in the OpenID Connect specification.

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.

INRUPT_OPENID_WEBID_FRAGMENT

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

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.

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.

Kafka Configuration

Tip See also ESS’ Kafka Configuration

INRUPT_KAFKA_AUDITV1EVENTSENCRYPTED_CIPHER_PASSWORD

The strong cipher key to use when running auditing with encrypted messages over the auditv1eventsencrypted topic.

INRUPT_KAFKA_AUDITV1EVENTSPRODUCERENCRYPTED_CIPHER_PASSWORD

The strong cipher key to use when running auditing with encrypted messages over the auditv1eventsproducerencrypted topic.

KAFKA_BOOTSTRAP_SERVERS

Default : localhost:9092

Comma-delimited list of Kafka broker servers for use by ESS services, including this service.

Setting KAFKA_BOOTSTRAP_SERVERS configures ESS to use the same Kafka instance(s) for all its Kafka message channels (e.g., solidresource and auditv1out message channels). This service uses the auditv1out message channel.

Note Inrupt-provided overlays default to using KAFKA_BOOTSTRAP_SERVERS .

To use a different Kafka instance for the auditv1out channel, use MP_MESSAGING_OUTGOING_AUDITV1OUT_BOOTSTRAP_SERVERS instead.

See also ESS’ Kafka Configuration

MP_MESSAGING_OUTGOING_AUDITV1OUT_BOOTSTRAP_SERVERS

Default : localhost:9092

Comma-delimited list of Kafka broker servers used for the outgoing audit v1 messages.

These messages are sent over the auditv1out message channel .

Note To configure ESS to use the same Kafka instances for all its Kafka message channels, use KAFKA_BOOTSTRAP_SERVERS option instead. Inrupt-provided overlays default to using KAFKA_BOOTSTRAP_SERVERS.

Optional

Configuration Logging

ESS services log their startup configuration.

Note Whitespaces are preserved when parsing comma-delimited lists (i.e., the parsed string values are not trimmed). For example, when parsed, "value1, value2,value3 " results in "value1" , " value2" , "value3 " .

INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW

Default: inrupt,smallrye.jwt.sign.key.location,smallrye.jwt.token.schemes,quarkus.oidc.logout.path,quarkus.oidc.auth-server-url

A comma-separated list of configuration property prefixes (case-sensitive) that determine which configurations are logged:

When specifying the prefixes, you can specify the prefixes using one of two formats:

Tip

To avoid allowing more than desired configurations, specify as much of the prefix as possible. If the prefix specifies the complete prefix term, include the term delineator. For example:

  • If using dot-notation, if you want to match configuration properties of the form foobar.<xxxx>..., specify foobar. (including the dot .) instead of, for example, foo or foobar.

  • If using converted form, if you want to match configuration properties of the form FOOBAR_<XXXX>..., specify FOOBAR_ (including the underscore _) instead of, for example, FOO or FOOBAR.

INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY

Default : inrupt.kafka

A comma-separated list of configuration name prefixes (case-sensitive) that determines which configurations (that would otherwise match the INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW ) are not logged. That is, INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY acts as a filter on INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW . For example:

  • If foobar. is an allowed prefix, to suppress foobar.private.<anything> , you can specify foobar.private. to the deny list.

  • If foobar. is not an allowed prefix, no property starting with foobar. is logged. As such, you do not need to specify foobar.private to the deny list.

When specifying the prefixes, you can specify the prefixes using one of two formats:

Log Redaction

INRUPT_LOGGING_REDACTION_NAME_ACTION

Default : REPLACE

Type of the redaction to perform. Supported values are:

Action
Description

REPLACE

Default. Replaces the matching text with a specified replacement.

PLAIN

Leaves the matching field unprocessed. Only available if the redaction target is a field (i.e., INRUPT_LOGGING_REDACTION_{NAME}_FIELD).

DROP

Suppresses the matching field. Only available if the redaction target is a field (i.e., INRUPT_LOGGING_REDACTION_{NAME}_FIELD).

PRIORITIZE

Changes the log level of the matching message.

SHA256

Replaces the matching text with its hash.

  • If the action is REPLACE ( default ), see also INRUPT_LOGGING_REDACTION_{NAME}_REPLACEMENT .

  • If the action is to PRIORITIZE , see also INRUPT_LOGGING_REDACTION_{NAME}_LEVEL .

For more information on log redaction, see Logging Redaction.

INRUPT_LOGGING_REDACTION_NAME_ENABLED

Default : true

A boolean that determines whether the redaction configurations with the specified INRUPT_LOGGING_REDACTION_{NAME}_ prefix is enabled.

For more information on log redaction, see Logging Redaction.

INRUPT_LOGGING_REDACTION_NAME_EXCEPTION

Fully qualified name of the exception class to match in the log messages (includes inner exception). Configure to target an exception message class.

For more information on log redaction, see Logging Redaction.

INRUPT_LOGGING_REDACTION_NAME_FIELD

Exact name of the field to match in the log messages. Configure to target a specific log message field for redaction.

For more information on log redaction, see Logging Redaction.

INRUPT_LOGGING_REDACTION_NAME_LEVEL

A new log level to use for the log message if the INRUPT_LOGGING_REDACTION_{NAME}_ACTION is PRIORITIZE .

INRUPT_LOGGING_REDACTION_NAME_PATTERN

A regex (see Java regex pattern) to match in the log messages. Configure to target log message text that matches a specified pattern.

For more information on log redaction, see Logging Redaction.

INRUPT_LOGGING_REDACTION_NAME_REPLACEMENT

Replacement text to use if the INRUPT_LOGGING_REDACTION_{NAME}_ACTION is REPLACE .

If unspecified, defaults to [REDACTED] .

For more information on log redaction, see Logging Redaction.

Application-Defined Metadata Propagation

INRUPT_AUDIT_PRODUCER_REQUEST_METADATA_ALLOW

A comma-separated list of application-defined properties that can be included in the associated audit events (unless specified in the corresponding INRUPT_AUDIT_PRODUCER_REQUEST_METADATA_DENY ).

This configuration is case-sensitive to the propagated properties in the baggage.

Tip To include a propagated property that was added via the INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW configuration, ensure that the cases of these properties match.

See:

INRUPT_AUDIT_PRODUCER_REQUEST_METADATA_DENY

A comma-separated list of application-defined properties to exclude from the associated audit messages. This setting takes precedence over INRUPT_AUDIT_PRODUCER_REQUEST_METADATA_ALLOW .

This configuration is case-sensitive to the propagated properties in the baggage.

Tip To exclude a propagated property that was added via the INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW configuration, ensure that the cases of these properties match.

See:

INRUPT_LOGGING_REQUEST_METADATA_ALLOW

A comma-separated list of application-defined properties that can be included in the associated log messages (unless specified in the corresponding INRUPT_LOGGING_REQUEST_METADATA_DENY).

This configuration is case-sensitive to the propagated properties in the baggage.

Tip To include a propagated property that was added via the INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW configuration, ensure that the cases of these properties match.

See:

INRUPT_LOGGING_REQUEST_METADATA_DENY

A comma-separated list of application-defined properties to exclude from the associated log messages. This setting takes precedence over INRUPT_LOGGING_REQUEST_METADATA_ALLOW .

This configuration is case-sensitive to the propagated properties in the baggage.

Tip To exclude a propagated property that was added via the INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW configuration, ensure that the cases of these properties match.

See:

INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW

A comma-separated list of non-baggage request headers to add to the baggage (unless specified in the corresponding INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_DENY ); i.e., include these non-baggage request headers as application-defined properties.

The configuration is case-insensitive; i.e., the listed headers do not need to match the case of the client request headers. For example, a list that includes x-correlation-id can match x-correlation-id header, X-CoRrElAtIoN-Id header, etc.

See:

INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_DENY

A comma-separated list of non-baggage request headers to exclude from being added to the baggage ; i.e., excludes these headers as application-defined properties. This setting takes precedence over INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW .

The configuration is case-insensitive; i.e., the listed headers do not need to match the case of the client request headers. For example, a list that includes x-correlation-id can match (and exclude) x-correlation-id header, X-CoRrElAtIoN-Id header, etc.

See:

INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_OVERRIDES

A flag that determines ESS behavior when metadata property is defined both as a header and as a baggage entry:

  • If true , ESS updates/overrides the baggage entry with the header value.

  • If false (the default), ESS keeps the baggage entry.

For details, Duplicate Property Definition .

INRUPT_REQUEST_METADATA_REFLECTOR_HEADER_ALLOW

A comma-separated list of application-defined properties that can return as response headers (unless specified in the corresponding INRUPT_REQUEST_METADATA_REFLECTOR_HEADER_DENY ).

This configuration is case-sensitive to the propagated properties in the baggage.

Tip

See:

INRUPT_REQUEST_METADATA_REFLECTOR_HEADER_DENY

A comma-separated list of application-defined properties to exclude from returning as response headers. This setting takes precedence over INRUPT_REQUEST_METADATA_REFLECTOR_HEADER_ALLOW .

This configuration is case-sensitive to the propagated properties in the baggage.

Tip To exclude a propagated property that was added via the INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW configuration, ensure that the cases of these properties match.

See:

Purge Configuration

The Broker service contains user data, and as such it can be purged upon user request. See the Purger Application documentation for more information about the data being purged.

INRUPT_PURGE_CLEANUP_TASK_EVERY

Default : PT5H

Frequency at which a task goes through stored purge statuses to clear any which are beyond their retention window.

INRUPT_PURGE_IN_PROGRESS_TIMEOUT_SECONDS

Default : 120

Timeout after which an ongoing purge task is considered stale. Stale tasks are picked up by an ESS background process to be taken to completion. By keeping track of a purge task’s state (active or stale) the service can ensure that a purge which was started will eventually reach completion, even if the system is disrupted whilst the asynchronous purge process is ongoing.

INRUPT_PURGE_PROCESS_TASK_EVERY

Default : PT5M

Frequency at which an ESS background process goes through ongoing purges to pick up the incomplete stale ones. See INRUPT_PURGE_IN_PROGRESS_TIMEOUT_SECONDS for additional details.

INRUPT_PURGE_STATUS_RETENTION_WINDOW

Default : P2D

Duration after which a purge task status will be cleared from storage. The purge task contains some Personally Identifying Data (such as the WebID), so ensuring it is cleared after a purge is required for compliance.

General

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.

See also COM_INRUPT_OPENID_CDI_DEFAULTCLIENTRESOLVERSERVICE_FETCHREMOTECLIENT_TIMEOUT_VALUE for the amount of time.

COM_INRUPT_OPENID_CDI_DEFAULTCLIENTRESOLVERSERVICE_FETCHREMOTECLIENT_TIMEOUT_VALUE

Default : 10

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

See also COM_INRUPT_OPENID_CDI_DEFAULTCLIENTRESOLVERSERVICE_FETCHREMOTECLIENT_TIMEOUT_UNIT for the time unit.

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.

INRUPT_OPENID_CATALOG_MAX_APP_COUNT

Default : 10

Maximum number of Client Credentials that can be registered for a user.

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 application identifiers with the exception of any domains listed in the INRUPT_OPENID_CLIENT_DOMAIN_DENYLIST configuration.

See also INRUPT_OPENID_CLIENT_DOMAIN_DENYLIST

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_TRUSTED_CLIENTS

A comma-delimited list of trusted application identifiers that will bypass the OpenID approval page.

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.

INRUPT_OPENID_WEBHOOK_POST_CONSENT_AUTH

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

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 .

INRUPT_OPENID_WEBID_TRIM_BASE64_PADDING

Default : false

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.

See also: QUARKUS_DATASOURCE_USERNAME and QUARKUS_DATASOURCE_PASSWORD.

QUARKUS_DATASOURCE_PASSWORD

Required if using a PostgreSQL database for persistence

The password for the JDBC connector

See also: QUARKUS_DATASOURCE_JDBC_URL and QUARKUS_DATASOURCE_USERNAME.

QUARKUS_DATASOURCE_USERNAME

Required if using a PostgreSQL database for persistence

The username for the JDBC connector

See also: QUARKUS_DATASOURCE_JDBC_URL and QUARKUS_DATASOURCE_PASSWORD.

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

See also Quarkus Configuration Options

Configure the Broker Service

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

  • Use a Custom Approval Template

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

Last updated