# 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](https://docs.inrupt.com/security/authentication). The service provides a compatibility layer between the Solid ecosystem in which users are identified with a [WebID](https://docs.inrupt.com/reference/glossary#webid) and traditional [OpenID Connect](https://openid.net/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](https://docs.inrupt.com/ess/installation#oidc-compliant-identity-provider), 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: ```none https://openid. ``` ### Discovery ESS provides Broker metadata at the following **`/.well-known/openid-configuration`** URI: ```none https://openid./.well-known/openid-configuration ``` The endpoint returns the current deployment’s Broker metadata. ### Application Registration The Broker provides an [Application Registration](https://docs.inrupt.com/ess/2.3/services/service-oidc/service-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](https://docs.inrupt.com/ess/2.3/services/service-oidc/service-application-registration) ## Tokens and Claims The Broker Service issues [ID and signed access tokens](https://docs.inrupt.com/security/authentication#tokens): * ID tokens assert the identity of the user. * They are represented as a [JSON Web Token](https://datatracker.ietf.org/doc/html/rfc7519) (JWT). * They have a default lifespan of 5 minutes (see [**`SMALLRYE_JWT_NEW_TOKEN_LIFESPAN`**](#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`**](#smallrye_jwt_new_token_lifespan) ). ### 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:
FieldDescription
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".
azpThe Authorized party (i.e., the registered client_id) to whom the ID Token is issued.
issThe issuer of the token; i.e., the ESS’ Broker’s URL. See INRUPT_OPENID_ISSUER.
subThe 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](https://openid.net/specs/openid-connect-core-1_0.html#IDToken). ## Broker Service Configuration As part of the [installation process](https://docs.inrupt.com/ess/2.3/installation), 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](https://docs.inrupt.com/ess/installation#step-1-initialize-the-installation-directory) . 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. {% hint style="warning" %} **Important**\ To work with ESS’ WebID service, ensure that: * the value matches that of the WebID Service’s [**`INRUPT_WEBID_ISSUER`**](https://docs.inrupt.com/ess/2.3/service-webid#inrupt_webid_issuer) . * the value is included in the WebID Service’s [**`INRUPT_JWT_ISSUER_ALLOW_LIST`**](https://docs.inrupt.com/ess/2.3/service-webid#inrupt_jwt_issuer_allow_list). {% endhint %} #### **INRUPT\_OPENID\_WEBID\_FRAGMENT** A URI fragment used to generate the **`webid`** claim value when using an external WebID service. ESS’ [WebID Service](https://docs.inrupt.com/ess/2.3/services/service-webid) 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](https://docs.inrupt.com/ess/2.3/services/service-webid) 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`**](#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](https://docs.inrupt.com/ess/2.3/services/service-webid) 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. {% hint style="warning" %} **Warning**\ The JWT Key is used to sign tokens issued by your ESS deployment’s Broker. Safeguard your JWT Key. {% endhint %} ### Kafka Configuration {% hint style="info" %} **Tip**\ See also [ESS’ Kafka Configuration](https://docs.inrupt.com/ess/2.3/services/appendix/appendix-kafka-configuration) {% endhint %} #### **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`**](#kafka_bootstrap_servers) configures ESS to use the same Kafka instance(s) for all its Kafka [message channels](https://quarkus.io/guides/kafka#kafka-configuration) (e.g., **`solidresource`** and **`auditv1out`** message channels). This service uses the **`auditv1out`** message channel. {% hint style="info" %} **Note**\ Inrupt-provided overlays default to using [**`KAFKA_BOOTSTRAP_SERVERS`**](#kafka_bootstrap_servers) . To use a different Kafka instance for the **`auditv1out`** channel, use [**`MP_MESSAGING_OUTGOING_AUDITV1OUT_BOOTSTRAP_SERVERS`**](#mp_messaging_outgoing_auditv1out_bootstrap_servers) instead. {% endhint %} See also [ESS’ Kafka Configuration](https://docs.inrupt.com/ess/2.3/services/appendix/appendix-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](https://quarkus.io/guides/kafka#kafka-configuration) . {% hint style="info" %} **Note**\ To configure ESS to use the same Kafka instances for all its Kafka message channels, use [**`KAFKA_BOOTSTRAP_SERVERS`**](#kafka_bootstrap_servers) option instead. Inrupt-provided overlays default to using [**`KAFKA_BOOTSTRAP_SERVERS`**](#kafka_bootstrap_servers). {% endhint %} ### Optional #### **Configuration Logging** ESS services log their startup configuration. {% hint style="info" %} **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 "`** . {% endhint %} #### **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: * If the list is empty, **NO** configuration property is logged. * If a configuration property starts with a listed prefix ( **case-sensitive** ), the configuration property and its value are logged **unless** the configuration also matches a prefix in [**`INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY`**](#inrupt_logging_configuration_prefix_deny) (which acts as a filter on [**`INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW`**](#inrupt_logging_configuration_prefix_allow) list).\ As such, if the configuration matches prefix in both [**`INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW`**](#inrupt_logging_configuration_prefix_allow) and [**`INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY`**](#inrupt_logging_configuration_prefix_deny) , the [**`INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY`**](#inrupt_logging_configuration_prefix_deny) takes precedence and the configuration is not logged. For example, if **`inrupt.`** is an allow prefix, but **`inrupt.kafka.`** is a deny prefix, all configurations that start with **`inrupt.kafka.`** are excluded from the logs. When specifying the prefixes, you can specify the prefixes using one of two formats: * using dot notation (e.g., **`inrupt.foobar.`** ), or * using the [MicroProfile Config environmental variables conversion value](https://quarkus.io/guides/config-reference#environment-variables) (e.g., **`INRUPT_FOOBAR_`** ). {% hint style="danger" %} **Warning**\ Use the same format for **both** [**`INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW`**](#inrupt_logging_configuration_prefix_allow) and [**`INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY`**](#inrupt_logging_configuration_prefix_deny) . For example, if you change the format of [**`INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW`**](#inrupt_logging_configuration_prefix_allow) , change the format of [**`INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY`**](#inrupt_logging_configuration_prefix_deny) as well. {% endhint %} {% hint style="info" %} **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....`**, 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_...`**, specify **`FOOBAR_`** (including the underscore **`_`**) instead of, for example, **`FOO`** or **`FOOBAR`**. {% endhint %} #### **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`**](#inrupt_logging_configuration_prefix_allow) ) are not logged. That is, [**`INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY`**](#inrupt_logging_configuration_prefix_deny) acts as a filter on [**`INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW`**](#inrupt_logging_configuration_prefix_allow) . For example: * If **`foobar.`** is an allowed prefix, to suppress **`foobar.private.`** , 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: * using dot notation (e.g., **`inrupt.foobar.`** ), or * using the [MicroProfile Config environmental variables conversion value](https://quarkus.io/guides/config-reference#environment-variables) (e.g., **`INRUPT_FOOBAR_`** ). {% hint style="danger" %} **Warning**\ Use the same format for **both** [**`INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW`**](#inrupt_logging_configuration_prefix_allow) and [**`INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY`**](#inrupt_logging_configuration_prefix_deny) . For example, if you change the format of [**`INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW`**](#inrupt_logging_configuration_prefix_allow) , change the format of [**`INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY`**](#inrupt_logging_configuration_prefix_deny) as well. {% endhint %} ### **Log Redaction** #### **INRUPT\_LOGGING\_REDACTION\_NAME\_ACTION** Default : **`REPLACE`** Type of the redaction to perform. Supported values are:
ActionDescription
REPLACEDefault. Replaces the matching text with a specified replacement.
PLAINLeaves the matching field unprocessed. Only available if the redaction target is a field (i.e., INRUPT_LOGGING_REDACTION_{NAME}_FIELD).
DROPSuppresses the matching field. Only available if the redaction target is a field (i.e., INRUPT_LOGGING_REDACTION_{NAME}_FIELD).
PRIORITIZEChanges the log level of the matching message.
SHA256Replaces 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](https://docs.inrupt.com/ess/2.3/administration/logging/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](https://docs.inrupt.com/ess/2.3/administration/logging/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](https://docs.inrupt.com/ess/2.3/administration/logging/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](https://docs.inrupt.com/ess/2.3/administration/logging/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](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/regex/Pattern.html#sum)) 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](https://docs.inrupt.com/ess/2.3/administration/logging/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](https://docs.inrupt.com/ess/2.3/administration/logging/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](https://docs.inrupt.com/security/auditing#audit-events) (unless specified in the corresponding [**`INRUPT_AUDIT_PRODUCER_REQUEST_METADATA_DENY`**](#inrupt_audit_producer_request_metadata_deny) ). This configuration is **case-sensitive** to the propagated properties in the baggage. {% hint style="info" %} **Tip**\ To include a propagated property that was added via the [**`INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW`**](#inrupt_request_metadata_propagator_header_allow) configuration, ensure that the cases of these properties match. {% endhint %} See: * [Manage Application-Defined Metadata Propagation](https://docs.inrupt.com/ess/2.3/installation/customize-configurations/customization-logging/manage-app-defined-metadata) to configure. * [Application-Defined Metadata](https://docs.inrupt.com/ess/2.3/administration/application-defined-metadata) for more information. #### **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`**](#inrupt_audit_producer_request_metadata_allow) . This configuration is **case-sensitive** to the propagated properties in the baggage. {% hint style="info" %} **Tip**\ To exclude a propagated property that was added via the [**`INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW`**](#inrupt_request_metadata_propagator_header_allow) configuration, ensure that the cases of these properties match. {% endhint %} See: * [Manage Application-Defined Metadata Propagation](https://docs.inrupt.com/ess/2.3/installation/customize-configurations/customization-logging/manage-app-defined-metadata) to configure. * [Application-Defined Metadata](https://docs.inrupt.com/ess/2.3/administration/application-defined-metadata) for more information. #### **INRUPT\_LOGGING\_REQUEST\_METADATA\_ALLOW** A comma-separated list of application-defined properties that can be included in the associated [log messages](https://docs.inrupt.com/ess/2.3/administration/logging) (unless specified in the corresponding [**`INRUPT_LOGGING_REQUEST_METADATA_DENY`**](#inrupt_logging_request_metadata_deny)). This configuration is **case-sensitive** to the propagated properties in the baggage. {% hint style="info" %} **Tip**\ To include a propagated property that was added via the [**`INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW`**](#inrupt_request_metadata_propagator_header_allow) configuration, ensure that the cases of these properties match. {% endhint %} See: * [Manage Application-Defined Metadata Propagation](https://docs.inrupt.com/ess/2.3/installation/customize-configurations/customization-logging/manage-app-defined-metadata) to configure. * [Application-Defined Metadata](https://docs.inrupt.com/ess/2.3/administration/application-defined-metadata) for more information. #### **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`**](#inrupt_logging_request_metadata_allow) . This configuration is **case-sensitive** to the propagated properties in the baggage. {% hint style="info" %} **Tip**\ To exclude a propagated property that was added via the [**`INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW`**](#inrupt_request_metadata_propagator_header_allow) configuration, ensure that the cases of these properties match. {% endhint %} See: * [Manage Application-Defined Metadata Propagation](https://docs.inrupt.com/ess/2.3/installation/customize-configurations/customization-logging/manage-app-defined-metadata) to configure. * [Application-Defined Metadata](https://docs.inrupt.com/ess/2.3/administration/application-defined-metadata) for more information. #### **INRUPT\_REQUEST\_METADATA\_PROPAGATOR\_HEADER\_ALLOW** A comma-separated list of non-baggage request headers to add to the [baggage](https://www.w3.org/TR/baggage/) (unless specified in the corresponding [**`INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_DENY`**](#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: * [Manage Application-Defined Metadata Propagation](https://docs.inrupt.com/ess/2.3/installation/customize-configurations/customization-logging/manage-app-defined-metadata) to configure. * [Application-Defined Metadata](https://docs.inrupt.com/ess/2.3/administration/application-defined-metadata) for more information. #### **INRUPT\_REQUEST\_METADATA\_PROPAGATOR\_HEADER\_DENY** A comma-separated list of non-baggage request headers to exclude from being added to the [baggage](https://www.w3.org/TR/baggage/) ; i.e., excludes these headers as application-defined properties. This setting takes precedence over [**`INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW`**](#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: * [Manage Application-Defined Metadata Propagation](https://docs.inrupt.com/ess/2.3/installation/customize-configurations/customization-logging/manage-app-defined-metadata) to configure. * [Application-Defined Metadata](https://docs.inrupt.com/ess/2.3/administration/application-defined-metadata) for more information. #### **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](https://docs.inrupt.com/ess/administration/application-defined-metadata#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`**](#inrupt_request_metadata_reflector_header_deny) ). This configuration is **case-sensitive** to the propagated properties in the baggage. {% hint style="info" %} **Tip** * To return a propagated property that was added via the [**`INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW`**](#inrupt_request_metadata_propagator_header_allow) configuration, ensure that the cases of these properties match. * You may need to update **`QUARKUS_HTTP_CORS_EXPOSED_HEADERS`** to extend the list of [CORS-safelisted response headers](https://developer.mozilla.org/en-US/docs/Glossary/CORS-safelisted_response_header) . {% endhint %} See: * [Manage Application-Defined Metadata Propagation](https://docs.inrupt.com/ess/2.3/installation/customize-configurations/customization-logging/manage-app-defined-metadata) to configure. * [Application-Defined Metadata](https://docs.inrupt.com/ess/2.3/administration/application-defined-metadata) for more information. #### **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`**](#inrupt_request_metadata_reflector_header_allow) . This configuration is **case-sensitive** to the propagated properties in the baggage. {% hint style="info" %} **Tip**\ To exclude a propagated property that was added via the [**`INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW`**](#inrupt_request_metadata_propagator_header_allow) configuration, ensure that the cases of these properties match. {% endhint %} See: * [Manage Application-Defined Metadata Propagation](https://docs.inrupt.com/ess/2.3/installation/customize-configurations/customization-logging/manage-app-defined-metadata) to configure. * [Application-Defined Metadata](https://docs.inrupt.com/ess/2.3/administration/application-defined-metadata) for more information. ### Purge Configuration The Broker service contains user data, and as such it can be purged upon user request. See the [Purger Application documentation](https://docs.inrupt.com/ess/2.3/services/purger-application) 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](https://docs.oracle.com/javase/8/docs/api/java/time/temporal/ChronoUnit.html) constants as strings; e.g., **`SECONDS`** , **`MINUTES`** , **`HOURS`** , etc. See also [**`COM_INRUPT_OPENID_CDI_DEFAULTCLIENTRESOLVERSERVICE_FETCHREMOTECLIENT_TIMEOUT_VALUE`**](#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`**](#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](https://github.com/inrupt/docs-gitbook/blob/main/ess/2.3/services/service-oidc/broken-reference/README.md). #### **INRUPT\_OPENID\_CATALOG\_DISABLED** A boolean flag for disabling the [Application Registration](https://docs.inrupt.com/ess/2.3/services/service-oidc/service-application-registration) where users can register client applications. [Application Registration](https://docs.inrupt.com/ess/2.3/services/service-oidc/service-application-registration) is available by default. Set [**`INRUPT_OPENID_CATALOG_DISABLED`**](#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`**](#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**](#inrupt_openid_client_domain_denylist) configuration. See also [**`INRUPT_OPENID_CLIENT_DOMAIN_DENYLIST`**](#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`**](#inrupt_openid_client_domain_allowlist) is set. #### **INRUPT\_OPENID\_CUSTOM\_CLAIMS** Comma-delimited mapping of custom claims to OAuth2 scopes having the form **`=,=,...`** (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. {% hint style="info" %} **Tip**\ Do not use this setting with [**`QUARKUS_OIDC_LOGOUT_PATH`**](#quarkus_oidc_logout_path) . {% endhint %} #### **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](https://openid.net/specs/openid-connect-basic-1_0.html) (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](#broker-token-claims). 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. {% hint style="warning" %} **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. {% endhint %} #### **INRUPT\_OPENID\_WEBHOOK\_POST\_CONSENT\_AUTH** {% hint style="danger" %} ***Deprecated since version 2.0***: This option will be removed in a future release. {% endhint %} 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** {% hint style="danger" %} ***Deprecated since version 2.0***: This option will be removed in a future release. {% endhint %} 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`**](#inrupt_openid_user_claim_name) setting). [**`INRUPT_OPENID_WEBID_SUBJECT_PREFIX`**](#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`**](#inrupt_openid_webid_subject_prefix) value of **`user_`** would result in WebID values taking the following form: **`https://id.server.example/user_123456`** . {% hint style="warning" %} **Important**\ Do not change this value after users have begun provisioning Pods with their WebID. {% endhint %} #### **INRUPT\_OPENID\_WEBID\_TRIM\_BASE64\_PADDING** Default : **`false`** {% hint style="danger" %} ***Deprecated since version 2.0.*** {% endhint %} 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`**](#quarkus_datasource_username) and [**`QUARKUS_DATASOURCE_PASSWORD`**](#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`**](#quarkus_datasource_jdbc_url) and [**`QUARKUS_DATASOURCE_USERNAME`**](#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`**](#quarkus_datasource_jdbc_url) and [**`QUARKUS_DATASOURCE_PASSWORD`**](#quarkus_datasource_password). #### **QUARKUS\_LOG\_LEVEL** Default : **`INFO`** Logging level. #### **QUARKUS\_OIDC\_AUTHENTICATION\_SCOPES** A comma-delimited list of OAuth2 [scopes](https://openid.net/specs/openid-connect-basic-1_0.html) (e.g., **`openid,offline_access`** ) available from the backend identity provider. #### **QUARKUS\_OIDC\_LOGOUT\_PATH** If the backing identity provider supports [user-initiated logout](https://openid.net/specs/openid-connect-session-1_0.html) , 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 . #### **QUARKUS\_OIDC\_LOGOUT\_POST\_LOGOUT\_PATH** If [**`QUARKUS_OIDC_LOGOUT_PATH`**](#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](https://quarkus.io/guides/all-config) #### **Configure the Broker Service** To update the configuration, you can use [Kustomize overlays](https://github.com/kubernetes-sigs/kustomize) . For examples, see * [Use a Custom Approval Template](https://docs.inrupt.com/ess/latest/installation/customize-configurations/customization-start-apps/customize-approval) * [Logging](https://docs.inrupt.com/ess/2.3/administration/logging) For additional information and examples on customizing ESS, see [Customize ESS](https://docs.inrupt.com/ess/2.3/installation/customize-configurations).