Install OIDC Broker Service

Inrupt’s 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 OIDC Broker Service allows a Solid user to login with any existing OIDC-compliant identity provider.

The 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: Configure Backend Identity Provider(s)

  1. Create an OIDC Application on the backend Identity provider or providers. Once created, note the following information for each provider:

    • Issuer URL,

    • Application Name,

    • Client ID, and

    • Client secret.

  2. Build the configuration string with the Identity provider’ or providers’ information:

    Note

    Remove all spaces and new lines from this string.

    id=<value>|clientName=<value>|clientId=<value>|clientSecret=<value>
    

    If using multiple providers, separate multiple Identity Providers with a semi-colon (;):

    id=<value>|clientName=<value>|clientId=<value>|clientSecret=<value>;id=<value>|clientName=<value>>|clientId=<value>|clientSecret=<value>
    

    The fields available for configuration are listed below:

    Key

    Default

    Description

    id

    (none)

    The issuer URL for the remote OIDC provider.

    clientId

    (none)

    The configured Client ID value.

    clientSecret

    (none)

    The configured Client Secret value.

    clientName

    (none)

    The display name for the provider.

    logoUri

    (none)

    The URI for displaying a logo for the provider on the OIDC Broker Service login page.

    tokenEndpointAuthMethod

    SECRET_BASIC

    The authentication method for the remote provider.

    scope

    openid, profile, webid

    A comma-delimited set of scopes.

Step 2: Download Configuration Files

Download the OIDC configuration files using the <TOKEN> and <VERSION> values provided by Inrupt:

cd ${ROOT_DIR}
curl -O 'https://download.software.inrupt.com/<TOKEN>/release/raw/names/Identity-Broker-AWS-Deployment/versions/<VERSION>/configuration-reference-oidc-aws.zip'
unzip configuration-reference-oidc-aws.zip -d oidc
cd oidc
export OIDC_RELEASE_DIR=$(pwd)

Step 3: Create Database for the OIDC Broker Service

Log into the PostgreSQL Database created during the install.

Note

For simplicity, the example creates a database in the same PostgreSQL instance that is used for the ESS LDP server. In a production deployment, it is highly recommended that you use a separate PostgreSQL instance for the OIDC Broker Service.

  1. Create a Kubernetes pod for PostgreSQL:

    cat <<EOF | kubectl apply -f -
    apiVersion: v1
    kind: Pod
    metadata:
      name: postgres-util
      namespace: default
    spec:
      containers:
      - name: postgres
        image: postgres:12
        env:
          - name: POSTGRES_DB
            value: "util"
          - name: POSTGRES_USER
            value: "util"
          - name: POSTGRES_PASSWORD
            value: "util"
    EOF
    
  2. Log into the Kuberntes pod:

    kubectl -n default exec -it postgres-util sh
    
  3. Using the POSTGRES_URL value from the install, connect to the database:

    psql -h <POSTGRES_URL> -d postgres -U ess
    

    When prompted for password, use the POSTGRES_PASSWORD from the install.

  4. Once in the psql terminal:

    • Create a Database called broker.

    • Create a user called broker, specifying the password for the user.

    • Grant privileges to the broker user to access the broker database:

    create database broker;
    create user broker with encrypted password '<somePassword>';
    grant all privileges on database broker to broker;
    
  5. Exit the psql terminal.

  6. Exit the postgres-util terminal.

  7. Delete the Kubernetes pod created for Postgres:

    kubectl -n default delete pod postgres-util
    

Manage Secrets

Add the following AWS SSM Parameter Store secrets:

Parameter Name

Description

/ess-<ENVIRONMENT>/oidc-postgres-db

Reference to the backend storage system. Use the value of POSTGRES_URL from the terraform apply output.

/ess-<ENVIRONMENT>/oidc-postgres-username

Username of the Postgres user user created in section…

/ess-<ENVIRONMENT>/oidc-postgres-password

Password of the Postgres user created in section…

/ess-<ENVIRONMENT>/oidc-admin-webid

A WebID for the Admin user.

While strictly not necessary, it is recommended that you use a dereferenceable WebID.

/ess-<ENVIRONMENT>/oidc-admin-email

An email for the Admin user.

While strictly not necessary, it is recommended that you use a valid email.

/ess-<ENVIRONMENT>/oidc-admin-password

An admin password of your choice.

/ess-<ENVIRONMENT>/oidc-issuer-clients

The configuration string created from the Step 1: Configure Backend Identity Provider(s) step.

/ess-<ENVIRONMENT>/oidc-ssl-keystore-password

A password for the Keystore used for SSL certificate generation.

/ess-<ENVIRONMENT>/oidc-ssl-truststore-password

A password for the Trust Store used for holding trusted certificates.

Signed TLS Certificates

When the OIDC Broker Service is run behind the ESS proxy, the service is responsible for all the signed TLS certificates of the exposed services. When creating the signed certificates per Appendix E: Docker Image Repositories, the OIDC Broker Service URL will need to be added.

The OIDC Broker can also be deployed as an independent service and does not require to be deployed behind the ESS Proxy. It could have its very own Proxy and AWS Load Balancer. A similar process for adding signed certificates per Appendix E: Docker Image Repositories applies.

Most of these environment variables have been setup during installation.

Important

For the OIDC Broker, export the KEYSTORE_PASSWORD with the value from Manage Secrets.

  1. Set environment variables to your substitution values:

    export DOMAIN=[Domain you are hosting the ESS system on]
    export COUNTRY=[Your company's 2-letter country code for TLS certificate generation (e.g., US)]
    export STATE=[Your company's state for TLS certificate generation (e.g., Massachusetts)]
    export CITY=[Your company's city for TLS certificate generation (e.g., Boston)]
    export ORG_NAME=[Your company's organization name for TLS certificate generation (e.g., Acme, Inc)]
    export ORG_UNIT=[Your company's organizational unit for TLS certificate generation (e.g., Engineering)]
    export AWS_REGION=[The AWS region where this service will be deployed to]
    export ENVIRONMENT=[The name given to the environment (e.g., dev, stage, or prod)]
    export DOCKER_CREDENTIALS=[Docker credentials string]
    
  2. Use sed to make the substitution:

    Note

    The below sed operations use the ? character as the delimiter. If your environment variable includes the ? character in its value, you must escape the character in the value.

    find ./ -type f -name "*.yaml" -exec sed -i 's?_REPLACE_ME_DOMAIN_?'${DOMAIN}'?g' {} \;
    find ./ -type f -name "*.yaml" -exec sed -i 's?_REPLACE_ME_COMPANY_COUNTRY_?'${COUNTRY}'?g' {} \;
    find ./ -type f -name "*.yaml" -exec sed -i 's?_REPLACE_ME_COMPANY_STATE_?'${STATE}'?g' {} \;
    find ./ -type f -name "*.yaml" -exec sed -i 's?_REPLACE_ME_COMPANY_CITY_?'${CITY}'?g' {} \;
    find ./ -type f -name "*.yaml" -exec sed -i 's?_REPLACE_ME_COMPANY_ORG_NAME_?'${ORG_NAME}'?g' {} \;
    find ./ -type f -name "*.yaml" -exec sed -i 's?_REPLACE_ME_COMPANY_ORG_UNIT_?'${ORG_UNIT}'?g' {} \;
    find ./ -type f -name "*.yaml" -exec sed -i 's?_REPLACE_ME_AWS_REGION_?'${AWS_REGION}'?g' {} \;
    find ./ -type f -name "*.yaml" -exec sed -i 's?_REPLACE_ME_ENVIRONMENT_?'${ENVIRONMENT}'?g' {} \;
    find ./ -type f -name "*.yaml" -exec sed -i 's?_REPLACE_ME_DOCKER_CREDENTIALS_?'${DOCKER_CREDENTIALS}'?g' {} \;
    

    Note

    The below sed operations use the ? character as the delimiter. If your environment variable includes the ? character in its value, you may need to escape the character in the value.

    find ./ -type f -name "*.yaml" -exec sed -i '' -e 's?_REPLACE_ME_DOMAIN_?'${DOMAIN}'?g' {} \;
    find ./ -type f -name "*.yaml" -exec sed -i '' -e 's?_REPLACE_ME_COMPANY_COUNTRY_?'${COUNTRY}'?g' {} \;
    find ./ -type f -name "*.yaml" -exec sed -i '' -e 's?_REPLACE_ME_COMPANY_STATE_?'${STATE}'?g' {} \;
    find ./ -type f -name "*.yaml" -exec sed -i '' -e 's?_REPLACE_ME_COMPANY_CITY_?'${CITY}'?g' {} \;
    find ./ -type f -name "*.yaml" -exec sed -i '' -e 's?_REPLACE_ME_COMPANY_ORG_NAME_?'${ORG_NAME}'?g' {} \;
    find ./ -type f -name "*.yaml" -exec sed -i '' -e 's?_REPLACE_ME_COMPANY_ORG_UNIT_?'${ORG_UNIT}'?g' {} \;
    find ./ -type f -name "*.yaml" -exec sed -i '' -e 's?_REPLACE_ME_AWS_REGION_?'${AWS_REGION}'?g' {} \;
    find ./ -type f -name "*.yaml" -exec sed -i '' -e 's?_REPLACE_ME_ENVIRONMENT_?'${ENVIRONMENT}'?g' {} \;
    find ./ -type f -name "*.yaml" -exec sed -i '' -e 's?_REPLACE_ME_DOCKER_CREDENTIALS_?'${DOCKER_CREDENTIALS}'?g' {} \;
    

Step 4: Deploy

The launch order for the Kubernetes configuration files is important, so the directories contain numbered prefixes as follows:

  • 01_namespaces

  • 02_services

  • 03_config

  • 05_deployments

01_namespace

Create Namespace that will contain the OIDC Broker Service deployment:

cd ${OIDC_RELEASE_DIR}/deployment/kubernetes/aws
kubectl apply -f 01_namespace/

The operation returns the following output:

namespace/oidc created

02_services

Create the OIDC Broker Service:

kubectl apply -f 02_services/

The operation returns the following output:

service/inrupt-oidc-service created

03_config

Apply the OIDC Broker Service configurations into the cluster:

kubectl apply -f 03_config/

The operation returns the following output:

configmap/acquire-self-signed-cert created
secret/docker-repo created
configmap/oidc-broker-config created
secret/inrupt-oidc-secret created

05_deployments

Create the OIDC Broker Service deployment:

kubectl apply -f 05_deployments/

The operation returns the following output:

deployment.apps/inrupt-oidc-deployment created

Step 5: 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 OIDC Broker Service Deployment

  1. Open a web browser to https://broker.<DOMAIN>/, substituting your domain for <DOMAIN>.

  2. Click Log in. The list of configured identity providers will be displayed.

  3. Select one of the identity providers and follow their login flow.

  4. Once logged in, you will be brought back to the OIDC Broker Service page. Your login ID is displayed on the top right button of the screen.

Configure ESS to use OIDC Broker

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

  1. Open the file $RELEASE_DIR/deployment/kubernete/03_config/ess-config.yaml.

  2. Locate the MP_JWT_VERIFY_PUBLICKEY_LOCATION environment variable and update its 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.

  3. Apply the changes to Kubernetes, substituting your <ENVIRONMENT> value:

    cd ${RELEASE_DIR}/deployment/kubernetes/aws
    kubectl apply -f 03_config/
    

    The operation should return an output similar to the following:

    configmap/acquire-self-signed-cert unchanged
    secret/docker-repo unchanged
    configmap/oidc-broker-config configured
    secret/inrupt-oidc-secret unchanged
    
  4. Restart the LDP service deployment:

    kubectl rollout restart deployment.apps/ess-ldp -n ess
    
  5. 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 OIDC Broker Service

  1. Open a web browser to https://<DOMAIN>/verify.html, substituting your domain for <DOMAIN>.

  2. On the displayed Enterprise Solid Server Deployment Tests page, enter:

    1. Identity Provider: URL to the OIDC Broker Service (e.g., http://broker.<DOMAIN>).

    2. LDP Storage Server: URL of the LDP Storage service (e.g., http://<DOMAIN>).

  3. Click the Begin Tests button to run the first set of tests.

    When these tests complete, you should see the results.

  4. If all the initial tests pass, click on the Authenticate button. You should be redirected to a Provider selection page.

  5. Select a provider with whom you have an existing account and the specific account use for the login.

  6. Once logged in, you are redirected to a standard OIDC Authorization screen.

  7. 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 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 OIDC Broker Service, Deployment, and the configurations:

kubectl delete namespace oidc