Install Solid OIDC Broker Service#

Inrupt’s Solid OpenID Connect (OIDC) Broker Service provides a compatibility layer between Solid that identifies users with a WebID and traditional OpenID Connect (OIDC) applications that identify users with strings. The Solid OIDC Broker Service allows a Solid user to login with any existing OIDC-compliant identity provider.

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

Note

The following instructions assume the infrastructure, command-line tools and environment variables have already been configured and setup per Install on AWS.

Procedure#

Step 1: Go to ESS deployment directory#

Go to the deployment directory under your installation directory. For example, for the reference AWS deployment:

cd  /tmp/installation-guide/deployment

Step 2: Initialize Environmental Variables#

If you have not initialized the environmental variables for the OIDC Broker installation, initialize your environment variables. If you have already initialized the values, you can skip this step.

./scripts/installer.sh -p aws -c init

When prompted, enter the appropriate values needed to build your deployment configuration files.

When prompted for the OIDC Broker (Do you want to install the OIDC Broker), enter y or Y to enter the OIDC Broker values at this time.

Step 3: Download and Build OIDC Broker Configuration Files#

Run the installer.sh file to download and build your OIDC Broker configuration files.
```
./scripts/installer.sh -e <environment> -p aws -s oidc -c build
```

Step 4: Create Database for the OIDC Broker Service#

Run the 07_setup-oidc-broker-db.sh, replacing <environment> with your environment value (e.g., dev, prod).
```
./scripts/aws/infrastructure/07_setup-oidc-broker-db.sh <environment>
```
Once the script finishes, log into the Kuberntes pod:
```
kubectl -n default exec -it postgres-util sh
```
Connect to the database, substituting your <POSTGRES_URL> value:
```
psql -h <POSTGRES_URL> -d postgres -U ess
```
Once in the psql terminal:
1. Create a Database called broker.
```
create database broker;
```
2. Create a user called broker, specifying the password for the user, substituting ‘<somePassword>’ with a password.
```
create user broker with encrypted password '<somePassword>';
```
3. Grant privileges to the broker user to access the broker database:
```
grant all privileges on database broker to broker;
```
Exit the psql terminal.
Exit the postgres-util terminal.

Delete the Kubernetes pod created for Postgres:

kubectl -n default delete pod postgres-util

Step 5: Deploy Solid OIDC Broker#

Run the installer.sh file to deploy the Solid OIDC Broker:

./scripts/installer.sh -e <environment> -p aws -s oidc -c install

The installer.sh prints the following line upon success:

OIDC Broker deployment installed successfully!

You can view the Solid OIDC Broker components and services that are running:
```
kubectl -n oidc get all
```

Step 6: Verify Component Status#

Verify that all the components have starte and are runing:

kubectl get all --namespace=oidc

The operation should return an output similar to the following:

NAME                                         READY   STATUS    RESTARTS   AGE
pod/inrupt-oidc-deployment-597c6859f-5qbvj   1/1     Running   0          33s

NAME                          TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
service/inrupt-oidc-service   ClusterIP   162.22.106.39   <none>        8443/TCP   34s

NAME                                     READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/inrupt-oidc-deployment   1/1     1            1           33s

NAME                                               DESIRED   CURRENT   READY   AGE
replicaset.apps/inrupt-oidc-deployment-597c6859f   1         1         1       33s

Validate Deployment#

Verify Solid OIDC Broker Service Deployment#

Open a web browser to https://broker.<DOMAIN>/, substituting your domain for <DOMAIN>.
Click Log in. The list of configured identity providers will be displayed.
Select one of the identity providers and follow their login flow.
Once logged in, you will be brought back to the Solid OIDC Broker Service page. Your login ID is displayed on the top right button of the screen.

Configure ESS to Use Solid OIDC Broker#

After the Solid OIDC Broker Service has been successfully deployed, configure the ESS LDP service to use the Solid OIDC Broker Service for authentication.

Go to your downloaded ESS configuration files directory. For example, for the reference AWS deployment, substituting your <environment> value:
```
cd /tmp/installation-guide/deployment/<environment>/release/ess/deployment/kubernetes/aws/
```
Open the 05_deployments/ldp-deployment.yaml file and update the MP_JWT_VERIFY_PUBLICKEY_LOCATION environment variable value to https://broker.<DOMAIN>/jwk, substituting your domain for <DOMAIN>. This value is the link to the public JSON Web Key of the OIDC Broker.
Apply the changes to Kubernetes,
```
kubectl apply -f 05_deployments/
```

Restart the LDP service deployment:

kubectl rollout restart deployment.apps/ess-ldp -n ess

Check the status:

kubectl rollout status deployment.apps/ess-ldp -n ess

The operation should return an output similar to the following:

deployment "ess-ldp" successfully rolled out

Verify ESS Deployment with Solid OIDC Broker Service#

Open a web browser to https://<DOMAIN>/verify.html, substituting your domain for <DOMAIN>.
On the displayed Enterprise Solid Server Deployment Tests page, enter:
1. Identity Provider: URL to the Solid OIDC Broker Service (e.g., https://broker.<DOMAIN>).
2. LDP Storage Server: URL of the LDP Storage service (e.g., https://<DOMAIN>).
Click the Begin Tests button to run the first set of tests.

When these tests complete, you should see the results.
If all the initial tests pass, click on the Authenticate button. You should be redirected to a Provider selection page.
Select a provider with whom you have an existing account and the specific account use for the login.
Once logged in, you are redirected to a standard OIDC Authorization screen.
Click the Authorize button. You should be redirected back to the ESS Server Verification webpage, and the second-phase set of tests should all run automatically.

If all of these checks are green, then the deployment was successful. If there are errors, it will indicate which part of functionality is not working to aid with debugging deployment issues.

Tear Down#

Since the Solid OIDC Broker Service is deployed in its own separate namespace, if you want to delete the service, you can do so by deleting the oidc namespace. The following command will delete the Solid OIDC Broker Service, Deployment, and the configurations:

kubectl delete namespace oidc