Configure with Centralized OIDC Broker

Inrupt’s Solid OIDC Broker Service can integrate with various OIDC Identity Providers, such as Auth0, Google, Okta, Keycloak, etc., or your company’s internal OIDC Authentication Server. The following page provides instructions on integrating Inrupt’s Solid OIDC Broker Service with your ESS deployment.

Note

In these instructions, replace <DOMAIN> with your ESS deployment.

Register an OIDC Client

An OIDC Client may be registered against the Solid OIDC Broker for the ESS deployment:

  1. Go to https://broker.<DOMAIN>/ and login.

  2. In the left-side menu, click on Self-service client registration.

  3. Click the + New Client button.

  4. Fill out the client registration form. The only values that need to be included are “Client Name” and “Redirect URI(s)”. The remaining items may be left unchanged:

    • Main tab → Client Name: Enter the name for the OIDC Client.

    • Main tab → Redirect URI(s): The Redirect URIs should point to the client redirect endpoint. If this configuration is being used for ESS login integration, then this value would be: <DOMAIN>/callback (e.g., https://ess.mycompany.com/callback).

    • Other tab → Post-Logout Redirect: Optional If you would like the user sent to a particular location after they log out, enter that URL to this field.

    • The remaining items may be left unchanged.

  5. Submit the form. Once created, record the clientId, clientSecret and the location of the identity provider.

    Note

    If you are not an admin user, this information only appears once. Be sure to record the information in a safe place.

Configure ESS OIDC Client Integration

To enable the OIDC login flow in ESS, set the following environment variables on the LDP server:

INRUPT_OIDC_RP_CLIENT_SITE: https://broker.<DOMAIN>
INRUPT_OIDC_RP_CLIENT_ID: <clientId>
INRUPT_OIDC_RP_CLIENT_SECRET: <clientSecret>
INRUPT_OIDC_RP_LOGOUT_REDIRECT: https://broker.<DOMAIN>/endsession

Note

The INRUPT_OIDC_RP_LOGOUT_REDIRECT config needs to be as shown above even if you configure the OIDC Client “Post-Logout Redirect” item on the Solid OIDC Broker.

Considerations

Logging in

By default, ESS uses bearer tokens in HTTP headers for authentication. However, to allow browsers to navigate to protected resources directly, ESS provides an alternative cookie-based mechanism.

To opt in to use cookie-based authentication instead of token-based authentication, clients must fetch the resource at /login?redirect=<path/to/resource>. The login flow sends the users to the redirect destination once logged in.

If a browser attempts to fetch a protected resource directly, the server responds with an error page and a login link (e.g., /login?redirect=/mypod/private/). The login link leads the user through a standard OIDC login flow at the end of which the user will be directed to the resource (e.g., /mypod/private).

Logging out

With ESS OIDC client integration, the logout process is initiated with a request to the /logout endpoint on the ESS server.

The /logout ESS endpoint expires any application-specific cookies and then redirects the client to the logout endpoint of the IdP. If using the Solid OIDC Broker, that URL will be https://broker.<DOMAIN>/endsession.

The IdP endpoint prompts the user for confirmation. Once confirmed, the endpoint expires any cookies associated with the user’s session on the IdP. If the Post-Logout Redirect configuration was not set, this ends the logout process. Otherwise, the user is redirected to the specified location.