OpenID Provider#

ESS’ OpenID Provider 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’ OpenID Provider allows a Solid user to login with any existing OIDC-compliant identity provider.

OpenID Provider Endpoint#

By default, the ESS OpenID Provider runs from the following root URL:

https://openid.<ESS DOMAIN>

Discovery#

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

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

The endpoint returns the current deployment’s OpenID Provider metadata.

Application Registration#

ESS’ OpenID Provider 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 ESS OpenId Provider.

For more information, see Application Registration.

OpenID Provider 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 OpenID Provider.

INRUPT_OPENID_WEBID_HOST#

The WebID Service host.

INRUPT_OPENID_WEBID_PATH#

A path component added to a user’s WebID URL.

INRUPT_OPENID_WEBID_FRAGMENT#

A URI fragment added to a user’s WebID URL.

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 deployment’s OpenID Provider. Safeguard your JWT Key.

Kafka Configuration#

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.

INRUPT_KAFKA_AUDITV1EVENTSENCRYPTED_CIPHER_PASSWORD#

The strong cipher key to use when running auditing with encrypted messages.

Optional#

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.

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.

QUARKUS_LOG_LEVEL#

Default: INFO

Logging level.

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 Customize Approval Page.

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#

By default, WebID values are derived from the sub claim in the ID tokens produced by the backing identity provider. If a different claim is to be used, that should be set with this configuration.

For example, if the identity provider produces tokens with a user_id claim, this setting will use that claim instead of the sub claim when generating WebID values.

Important

When using this setting, ensure that values in this claim are unique across the corresponding user pool.

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_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_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_REENCODE_BASE64#

Default: false

A boolean flag that indicates whether the OpenID Provider 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_TRIM_BASE64_PADDING#

Default: false

Deprecated since version 2.0.

A boolean flag that indicates whether the OpenID Provider 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_OIDC_AUTHENTICATION_SCOPES#

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

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

Configure Solid OpenID Provider#

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

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