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:

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:

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

See also:

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:

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#

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.

New in version 2.2.0.

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#

Starting in 2.2, ESS services log their startup configuration.

INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW#

Default: inrupt,smallrye.jwt.sign.key.location,smallrye.jwt.token.schemes,smallrye.jwt.new-token.lifespan,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:

Warning

Use the same format for both INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW and INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY.

For example, if you change the format of INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW, change the format of INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY as well.

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.

New in version 2.2.0.

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:

Warning

Use the same format for both INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW and INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY.

For example, if you change the format of INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW, change the format of INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY as well.

New in version 2.2.0.

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.

New in version 2.2.0.

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.

New in version 2.2.0.

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.

New in version 2.2.0.

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.

New in version 2.2.0.

INRUPT_LOGGING_REDACTION_NAME_LEVEL#

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

New in version 2.2.0.

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.

New in version 2.2.0.

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.

New in version 2.2.0.

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:

New in version 2.2.0.

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:

New in version 2.2.0.

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:

New in version 2.2.0.

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:

New in version 2.2.0.

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:

New in version 2.2.0.

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:

New in version 2.2.0.

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.

New in version 2.2.0.

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:

New in version 2.2.0.

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:

New in version 2.2.0.

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.

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.

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_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.

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 https://quarkus.io/guides/all-config.

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.