Install on a Shared Server

This document describes how to set up the Inrupt Enterprise Solid Server (ESS) on a single machine that is accessible externally by multiple users.

Operating System

The recommended deployment environment is Ubuntu Server 20.04 LTS with 4 CPUs, 8 GB RAM, and at least 100GB of free disk space.

Prerequisites

Repository Account

The ESS Docker images and install configuration files are hosted on Inrupt’s CloudSmith Repository. To download, you need to obtain the following details from Inrupt:

  • An entitlement token, and

  • The version number of the software that you can download with the token.

To obtain the token and associated version number, you can either:

apt

Update the list of available packages and their versions, and upgrade the installed packages:

sudo apt update && sudo apt upgrade

Archive Extraction Tool

An archive extraction (i.e., unzip) tool is required to extract downloaded .zip files.

To install unzip, run:

sudo apt install unzip

Java

Java 8 is required by openssl and keytool to generate security certificates and importing them into a Keystore file:

To install the necessary open-source OpenJDK (JDK 8), run:

sudo apt install openjdk-8-jre-headless

Minikube

Minikube is a tool that makes it easy to run Kubernetes locally. And to manage Minikube, the guide uses kubectl.

To install Minikube, follow the instructions at https://kubernetes.io/docs/tasks/tools/install-minikube/#install-minikube-via-direct-download.

To install kubectl, follow the installation instructions at https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl-on-linux.

Optional. You can also install kubectl autocompletion. To install, follow the kubectl autocompletion installation instructions at https://kubernetes.io/docs/tasks/tools/install-kubectl/#optional-kubectl-configurations.

Installation Part 1: ESS

Step 1: Download ESS Configuration Files

To install ESS, you need to download a .zip file containing the ESS Kubernetes configuration files from Inrupt’s CloudSmith repository.

  1. Open a Terminal window.

  2. Create the ESS directory and change to the directory. For example, to create the directory under your home directory:

    cd ~
    mkdir ESS && cd ESS
    
  3. Download the zip file using curl. Replace <TOKEN> and <VERSION> with the values as provided to you by Inrupt:

    curl -O 'https://download.software.inrupt.com/<TOKEN>/release/raw/names/ESS-Minikube-Deployment/versions/<VERSION>/configuration-reference-minikube.zip'
    
  4. Unzip the file:

    unzip configuration-reference-minikube.zip
    
  5. Set the ESS_RELEASE_DIR environment variable to the ESS directory:

    export ESS_RELEASE_DIR=$(pwd)
    

Step 2: Start Kubernetes Cluster

  1. Start Minikube:

    minikube start --driver=none
    

    If you run the minikube start command without sudo, you might get a permission denied error similar to Error getting cluster config: read:. To fix, change the ownership of the ~/.minikube and ~/.kube directories as follows:

    sudo chown -R $(whoami):$(whoami) ~/.minikube/
    sudo chown -R $(whoami):$(whoami) ~/.kube
    

    If you see the error Sorry, Kubernetes v1.18.0 requires conntrack to be installed in root's path when trying to start Minikube, this is a known issue, and you will need to install conntrack and Docker:

    sudo apt install conntrack
    sudo apt install docker.io
    
  2. Verify the status of the Kubernetes cluster:

    minikube status
    

    The operation should return output that resembles the following:

    host: Running
    kubelet: Running
    apiserver: Running
    kubeconfig: Configured
    
  3. To view resources in the default namespace:

    kubectl get all
    

    The operation should return output that resembles the following:

    NAME                 TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
    service/kubernetes   ClusterIP   10.96.0.1    <none>        443/TCP   48m
    

Step 3: Enable Kubernetes Ingress

For service routing, enable Kubernetes Ingress Controller to manage external access to the services in the cluster:

minikube addons enable ingress

Step 4: Get Docker Credentials

To retrieve Docker images from Inrupt’s repository, Kubernetes generally needs credentials for that repository. Kubernetes currently requires the credentials to be in a Kubernetes secret.

  1. Create a Kubernetes secret named registrykey. Replace <TOKEN> with your token used to download the configuration files and <EMAIL> with your email.

    kubectl create secret docker-registry registrykey --docker-server=docker.software.inrupt.com --docker-username=inrupt/release --docker-password='<TOKEN>' --docker-email=<EMAIL>
    
  2. Retrieve the docker credentials:

    kubectl get secret registrykey --output=yaml
    

    The command returns the credential information similar to the following:

    apiVersion: v1
    data:
      .dockerconfigjson: eyJhdXRocyI6eyJkb2NrZXIuc29mdHdhcmUuaW5ydXB0LmNvbSI6eyJ1c2VybmFtZSI6Im....
    kind: Secret
    metadata:
    
    ...
    

    Note the .dockerconfigjson value (i.e., eyJhdXRocyI6... value in the example). The value is used to replace _REPLACE_ME_DOCKER_CREDENTIALS_ in a later step.

  3. Delete the secret registrykey.

    kubectl delete secret registrykey
    

Step 5: Process Kubernetes YAML Files

Update Kubernetes configuration .yaml files, replacing the following variables with the appropriate values for your deployment:

String to Replace

Description

_REPLACE_ME_DOMAIN_

Domain you are hosting the ESS system on.

_REPLACE_ME_COMPANY_COUNTRY_

Your company’s 2-letter country code for SSL certificate generation (e.g., US).

_REPLACE_ME_COMPANY_STATE_

Your company’s state for SSL certificate generation (e.g., Massachusetts).

_REPLACE_ME_COMPANY_CITY_

Your company’s city for SSL certificate generation (e.g., Boston).

_REPLACE_ME_COMPANY_ORG_NAME_

Your company’s organization name for SSL certificate generation (e.g., Acme, Inc).

_REPLACE_ME_COMPANY_ORG_UNIT_

Your company’s organizational unit for SSL certificate generation (e.g., Engineering).

_REPLACE_ME_DOCKER_CREDENTIALS_

Docker credentials string from the Step 4: Get Docker Credentials step.

The configuration files are in folders under the ${ESS_RELEASE_DIR}/deployment/kubernetes/minikube/ directory.

  1. Before modifying, make a backup of the minikube directory:

    cd ${ESS_RELEASE_DIR}/deployment/kubernetes
    cp -rf minikube minikube-bak
    
  2. Find all files with variables that need to be replaced by doing a string search for _REPLACE_ME_:

    cd ${ESS_RELEASE_DIR}/deployment/kubernetes/minikube
    grep -r "_REPLACE_ME_" *
    

    The operation returns a list of files:

    02_services/core-dns.yaml:   rewrite name identity._REPLACE_ME_DOMAIN_ proxy.ess.svc.cluster.local
    02_services/core-dns.yaml:   rewrite name _REPLACE_ME_DOMAIN_ proxy.ess.svc.cluster.local
    02_services/core-dns.yaml:   rewrite name broker._REPLACE_ME_DOMAIN_ proxy.ess.svc.cluster.local
    
    ...
    
    03_config/ess-config.yaml:    SUBJECT_ORG_NAME=_REPLACE_ME_COMPANY_ORG_NAME_
    03_config/ess-config.yaml:    SUBJECT_ORG_UNIT=_REPLACE_ME_COMPANY_ORG_UNIT_
    
    ...
    
  3. To make the string replacements in the files, you can use a text editor, such as vi or nano. Alternatively, you can use a stream editor, such as sed, to make these replacements:

    1. Set environment variables to your substitution values:

      export DOMAIN=[Domain you are hosting the ESS system on (e.g., ess.mycompany.com)]
      export COUNTRY=[Your company's 2-letter country code for SSL certificate generation (e.g., US)]
      export STATE=[Your company's state for SSL certificate generation (e.g., Massachusetts)]
      export CITY=[Your company's city for SSL certificate generation (e.g., Boston)]
      export ORG_NAME=[Your company's organization name for SSL certificate generation (e.g., Acme, Inc)]
      export ORG_UNIT=[Your company's organizational unit for SSL certificate generation (e.g., Engineering)]
      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 -exec sed -i 's?_REPLACE_ME_DOMAIN_?'${DOMAIN}'?g' {} \;
      find . -type f -exec sed -i 's?_REPLACE_ME_COMPANY_COUNTRY_?'${COUNTRY}'?g' {} \;
      find . -type f -exec sed -i 's?_REPLACE_ME_COMPANY_STATE_?'${STATE}'?g' {} \;
      find . -type f -exec sed -i 's?_REPLACE_ME_COMPANY_CITY_?'${CITY}'?g' {} \;
      find . -type f -exec sed -i 's?_REPLACE_ME_COMPANY_ORG_NAME_?'${ORG_NAME}'?g' {} \;
      find . -type f -exec sed -i 's?_REPLACE_ME_COMPANY_ORG_UNIT_?'${ORG_UNIT}'?g' {} \;
      find . -type f -exec sed -i 's?_REPLACE_ME_DOCKER_CREDENTIALS_?'${DOCKER_CREDENTIALS}'?g' {} \;
      
  1. Before modifying, make a backup of the minikube directory:

    cd ${ESS_RELEASE_DIR}/deployment/kubernetes
    cp -rf minikube minikube-bak
    
  2. Find all files with variables that need to be replaced by doing a string search for _REPLACE_ME_:

    cd ${ESS_RELEASE_DIR}/deployment/kubernetes/minikube
    grep -r "_REPLACE_ME_" *
    

    The operation returns a list of files:

    02_services/core-dns.yaml:   rewrite name identity._REPLACE_ME_DOMAIN_ proxy.ess.svc.cluster.local
    02_services/core-dns.yaml:   rewrite name _REPLACE_ME_DOMAIN_ proxy.ess.svc.cluster.local
    02_services/core-dns.yaml:   rewrite name broker._REPLACE_ME_DOMAIN_ proxy.ess.svc.cluster.local
    
    ...
    
    03_config/ess-config.yaml:    SUBJECT_ORG_NAME=_REPLACE_ME_COMPANY_ORG_NAME_
    03_config/ess-config.yaml:    SUBJECT_ORG_UNIT=_REPLACE_ME_COMPANY_ORG_UNIT_
    
    ...
    
  3. To make the string replacements in the files, you can use a text editor, such as vi or nano. Alternatively, you can use a stream editor, such as sed, to make these replacements:

    1. Set environment variables to your substitution values:

      export DOMAIN=[Domain you are hosting the ESS system on (e.g., ess.mycompany.com)]
      export COUNTRY=[Your company's 2-letter country code for SSL certificate generation (e.g., US)]
      export STATE=[Your company's state for SSL certificate generation (e.g., Massachusetts)]
      export CITY=[Your company's city for SSL certificate generation (e.g., Boston)]
      export ORG_NAME=[Your company's organization name for SSL certificate generation (e.g., Acme, Inc)]
      export ORG_UNIT=[Your company's organizational unit for SSL certificate generation (e.g., Engineering)]
      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 may need to escape the character in the value.

      find . -type f -exec sed -i '' -e 's?_REPLACE_ME_DOMAIN_?'${DOMAIN}'?g' {} \;
      find . -type f -exec sed -i '' -e 's?_REPLACE_ME_COMPANY_COUNTRY_?'${COUNTRY}'?g' {} \;
      find . -type f -exec sed -i '' -e 's?_REPLACE_ME_COMPANY_STATE_?'${STATE}'?g' {} \;
      find . -type f -exec sed -i '' -e 's?_REPLACE_ME_COMPANY_CITY_?'${CITY}'?g' {} \;
      find . -type f -exec sed -i '' -e 's?_REPLACE_ME_COMPANY_ORG_NAME_?'${ORG_NAME}'?g' {} \;
      find . -type f -exec sed -i '' -e 's?_REPLACE_ME_COMPANY_ORG_UNIT_?'${ORG_UNIT}'?g' {} \;
      find . -type f -exec sed -i '' -e 's?_REPLACE_ME_DOCKER_CREDENTIALS_?'${DOCKER_CREDENTIALS}'?g' {} \;
      
  1. Find all files with variables that need to be replaced by doing a string search for _REPLACE_ME_. From the Command Prompt (cmd.exe), issue the following:

    cd %ESS_RELEASE_DIR%\deployment\kubernetes
    findstr /S  "_REPLACE_ME_" "minikube/*"
    cd minikube
    
  2. To make the string replacements in the files, you can use a text editor, such as textedit.

    1. Before modifying, make a backup copy of the minikube directory. You can use the File Explorer to make a copy of the folder. Alternatively, you can use Xcopy from the command prompt.

    2. For each of the files with the _REPLACE_ME_ string, replace the _REPLACE_ME_* strings as described in the table above.

Step 6: Create ESS Namespace

  1. Create the ess namespace:

    kubectl apply -f 01_namespace/
    
  2. Set the namespace for the current context to ess:

    kubectl config set-context --current --namespace=ess
    

Step 7: Deploy Kafka

Deploy Apache Kafka in a Kubernetes cluster.

  1. Install Strimzi:

    kubectl apply -f 'https://strimzi.io/install/latest?namespace=ess'
    
  2. Deploy Kafka cluster:

    kubectl apply -f kafka/
    
  3. Wait for Kafka to be fully deployed and ready:

    kubectl wait kafka/ess-event --for=condition=Ready --timeout=300s
    

    Note

    Kafka needs to be fully started before continuing with the install as ESS services will throw errors trying to connect. The kubectl wait ... command waits until Kafka is fully deployed and ready.

  4. Verify that the Kafka namespace has spun up correctly:

    kubectl get all -n ess
    

    The output should resemble the following:

    NAME                                             READY   STATUS    RESTARTS   AGE
    pod/ess-event-entity-operator-75f7864d9d-cncll   3/3     Running   0          6m26s
    pod/ess-event-kafka-0                            2/2     Running   0          6m48s
    pod/ess-event-zookeeper-0                        2/2     Running   0          7m15s
    pod/strimzi-cluster-operator-6c8d574d49-876q4    1/1     Running   0          7m34s
    
    NAME                                 TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)                      AGE
    service/ess-event-kafka-bootstrap    ClusterIP   10.108.210.55   <none>        9091/TCP,9092/TCP,9093/TCP   6m49s
    service/ess-event-kafka-brokers      ClusterIP   None            <none>        9091/TCP,9092/TCP,9093/TCP   6m49s
    service/ess-event-zookeeper-client   ClusterIP   10.102.214.96   <none>        2181/TCP                     7m16s
    service/ess-event-zookeeper-nodes    ClusterIP   None            <none>        2181/TCP,2888/TCP,3888/TCP   7m16s
    
    NAME                                        READY   UP-TO-DATE   AVAILABLE   AGE
    deployment.apps/ess-event-entity-operator   1/1     1            1           6m26s
    deployment.apps/strimzi-cluster-operator    1/1     1            1           7m34s
    
    NAME                                                   DESIRED   CURRENT   READY   AGE
    replicaset.apps/ess-event-entity-operator-75f7864d9d   1         1         1       6m26s
    replicaset.apps/strimzi-cluster-operator-6c8d574d49    1         1         1       7m34s
    
    NAME                                   READY   AGE
    statefulset.apps/ess-event-kafka       1/1     6m48s
    statefulset.apps/ess-event-zookeeper   1/1     7m15s
    

Step 8: Create and Apply TLS Secrets to Kubernetes

The ESS services need to run with Transport Layer Security (TLS) certificates.

Warning

Self-signed certificates are for development purposes only. In production, ESS should be run with certificates from an official Certificate Authority (CA).

  1. Obtain tls.crt and tls.key files:

    • If you already have a valid TLS private key and certificate and want to apply them to ESS, copy them into the minikube/tls directory. They must be named tls.key and tls.crt respectively.

    • If you do not have a valid key and certificate for development purposes, you can create a self-signed certificate:

      1. Go to the minikube/tls directory:

        cd ${ESS_RELEASE_DIR}/deployment/kubernetes/minikube/tls
        
      2. Run the create-tls-certs.sh script to create the tls.crt and tls.key files in the current directory. The script will delete existing tls.crt and tls.key files in the directory before creating the new files:

        ./create-tls-certs.sh
        
  2. Import the TLS certificate into a keystore and create Kubernetes secrets ess-cluster-tls and ess-cluster-ca-certs:

    1. Go to the minikube/tls directory:

      cd ${ESS_RELEASE_DIR}/deployment/kubernetes/minikube/tls
      

      Note

      It is recommended that you edit the apply-tls-certs.sh file to change the default password for the keystore (i.e. change the argument of the -storepass option). This new password will also need to be set on the LDP Service using the javax.net.ssl.keyStorePassword system variable.

    2. Run the script to create two Kubernetes secrets, ess-cluster-tls and ess-cluster-ca-certs:

      ./apply-tls-certs.sh
      

      When asked to trust this certificate, type yes.

      The script deletes existing Kubernetes secrets ess-cluster-tls and ess-cluster-ca-certs before creating the new secrets. If they do not exist, the delete operations return secrets "..." not found messages that can be ignored.

Step 9: Deploy ESS to Kubernetes Cluster

  1. Go to your minikube directory:

    cd ${ESS_RELEASE_DIR}/deployment/kubernetes/minikube/
    
  2. Deploy ESS into your Kubernetes cluster:

    Note

    The 07_monitoring and 08_logging services are optional.

    kubectl apply -f 02_services/
    kubectl apply -f 03_config/
    kubectl apply -f 04_storage/
    kubectl apply -f 05_backend-deployments/
    kubectl apply -f 06_ess-deployments/
    kubectl apply -f 07_monitoring/
    kubectl apply -f 08_logging/
    
  3. View all ESS components and their status:

    kubectl get all -n ess
    

    You may need to run this command a few times to see all the components running, as some can take a little while to start up (especially the first time it’s run, as some of the images are externally downloaded).

Step 10: Add ESS Domains

By default, ESS exposes the following services for external access, where <DOMAIN> is domain name you configured earlier:

To access the service, create the DNS entries appropriate to the access level.

Globally

To allow global access to your ESS deployment from anywhere on the Internet, configure your organization’s globally registered DNS entries.

Within Organisation

To allow access to your ESS deployment within your organization only, configure your organization’s internal DNS server.

Local Machine

To allow access to your ESS deployment only from your local machine:

  1. Find the IP address. To determine the ESS server’s IP address, refer to your OS-specific documentation:

  2. Edit the /etc/hosts file on the local machine to add the following line, substitute in the <ESS Server IP>:

    <ESS Server IP> identity.<DOMAIN> <DOMAIN>
    

AWS Deployments

If ESS is being deployed to Amazon Web Services, to allow external access to the EC2 instance running ESS, add a new Incoming Rule:

  1. Select the EC2 instance, under Security groups (from the Description tab).

  2. Select launch-wizard-XXXX.

  3. Click the Edit inbound rules button in the Inbound Rules tab.

  4. Click Add Rule button.

  5. Configure the new rule for HTTPS and add the IP address of your local machine (and any other machines you wish to have access to this ESS deployment).

Step 11: Accept Self-Signed Certificates

Warning

The self-signed certificates are for development purposes only. In production, ESS should be run with certificates from an official Certificate Authority (CA).

If you are using self-signed certificates, you must accept them for the primary services. Replace <DOMAIN> with your domain name:

Service

Procedure

LDP

  1. Open https://<DOMAIN>/ in a browser.

  2. Accept the certificate.

Note

A 401 error is displayed. This is expected and indicates the certificate was accepted.

Installation Part 2: OIDC Broker

Step 1: Download Configuration Files

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

Note

The OIDC Broker <VERSION> is independent from the ESS <VERSION>.

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

Step 2: Configure Docker Credentials

Replace _REPLACE_ME_DOCKER_CREDENTIALS_ in the configuration files with the Docker credentials string.

  1. Find all files that contain _REPLACE_ME_DOCKER_CREDENTIALS_:

    cd ${OIDC_RELEASE_DIR}/deployment/kubernetes/
    grep -r "_REPLACE_ME_DOCKER_CREDENTIALS_" *
    
  2. Before modifying the files, make a backup of the minikube directory:

    cp -rf minikube minikube-bak
    
  3. Replace the _REPLACE_ME_DOCKER_CREDENTIALS_ strings with your Docker credentials created earlier and exported into the DOCKER_CREDENTIALS variable. You can modify the files using a text editor.

    Alternatively, you can use sed:

    1. Go to the minikube directory:

      cd minikube
      
    2. Use sed to make the replacments:

      find ./ -type f -name "*.yaml" -exec sed -i 's?_REPLACE_ME_DOCKER_CREDENTIALS_?'${DOCKER_CREDENTIALS}'?g' {} \;
      
      find ./ -type f -name "*.yaml" -exec sed -i '' -e 's?_REPLACE_ME_DOCKER_CREDENTIALS_?'${DOCKER_CREDENTIALS}'?g' {} \;
      

Step 3: Set up OIDC Application on Your 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.

  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.

    • The string is used in the Manage Secrets section for the oidc.clients.

    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 4: Create a Namespace for the OIDC Broker

kubectl create namespace oidc

Step 5: Create Self-Signed SSL Certificate

A self-signed SSL certificate needs to be created and imported into a Keystore that will be used by the OIDC Broker to secure all its endpoints on HTTPS:

  1. Make a tls directory:

    cd ${OIDC_RELEASE_DIR}/deployment/kubernetes/minikube
    mkdir tls
    
  2. Use openssl to create a private key and certificate, substituting your domain for <DOMAIN> in the subject:

    openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:4096 -keyout tls/oidc.key -out tls/oidc.crt -subj /CN=broker.<DOMAIN>
    
  3. Create a pkcs12 file from the created key and certificate:

    Important

    Use a different password than changeit. This password will be stored as oidc.http.ssl.certificate.truststore-store-password in later configuration.

    openssl pkcs12 -export -in tls/oidc.crt -inkey tls/oidc.key -passout pass:changeit -out tls/oidc-broker.p12
    

    To verify, you can ls the contents of the tls directory:

    ls tls
    

    You should see output similar to the following:

    oidc-broker.p12  oidc.crt  oidc.key
    
  4. Copy the certificate created for ESS:

    cp ${ESS_RELEASE_DIR}/deployment/kubernetes/minikube/tls/tls.crt tls/ess.crt
    
  5. Create a Truststore:

    Important

    • The operation uses the cacerts from your local machine. Ensure that this cacerts is valid and can be used inside your K8 cluster.

    • Use a different password than changeit for the new trust store.

    keytool -importkeystore -srckeystore /etc/ssl/certs/java/cacerts \
      -destkeystore tls/oidc-truststore.p12 -srcstoretype JKS -deststoretype PKCS12 \
      -srcstorepass changeit -deststorepass changeit -noprompt
    
  6. Import the ESS certificate into the Truststore:

    Important

    Use a different password than changeit.

    keytool -import -alias ess-tls-cert -file tls/ess.crt -storetype jks \
      -keystore tls/oidc-truststore.p12 -storepass changeit
    

    When asked to trust this certificate, type yes.

  7. Create a K8 Secret that contains the Keystore and Truststore that will apply it to the K8 cluster:

    kubectl create secret generic oidc-cluster-keystore \
      --from-file=oidc-broker.p12=tls/oidc-broker.p12 \
      --from-file=oidc-truststore.p12=tls/oidc-truststore.p12 -n oidc
    
  8. Import the OIDC Broker certificates into the ESS tls/cacerts Keystore:

    Important

    Use a different password than changeit.

    cd ${ESS_RELEASE_DIR}/deployment/kubernetes/minikube
    cp ${OIDC_RELEASE_DIR}/deployment/kubernetes/minikube/tls/oidc.crt tls/oidc.crt
    keytool -import -alias oidc-tls-cert -file tls/oidc.crt -storetype jks \
      -keystore tls/cacerts -storepass changeit
    

    When asked to trust this certificate, type yes.

  9. Delete and recreate the ESS ess-cluster-ca-cert secret:

    kubectl delete secrets ess-cluster-ca-cert -n ess
    kubectl create secret generic ess-cluster-ca-cert --from-file=cacerts=tls/cacerts -n ess
    
  10. Apply the config changes to the K8 cluster:

    kubectl apply -f ${ESS_RELEASE_DIR}/deployment/kubernetes/minikube/03_config
    

    The operation returns the following output:

    secret/docker-repo unchanged
    configmap/ldp-service-config unchanged
    configmap/websocket-service-config unchanged
    configmap/proxy-config configured
    configmap/ess-config unchanged
    configmap/jwks-service-config unchanged
    configmap/fluentd-es-config unchanged
    configmap/proxy-conf unchanged
    secret/inrupt-ess-secret unchanged
    
  11. Restart the ESS LDP Service:

    kubectl rollout restart deployment.apps/ess-ldp  \
      deployment.apps/ess-jwks deployment.apps/proxy-deployment -n ess
    

    Once restarted, you can verify the status:

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

Step 6: Manage Secrets

The OIDC Broker can use Kubernetes Secrets to configure sensitive information. The secret will need the following keys and values:

Secret

Description

oidc.issuer

The URL root of where the broker will be deployed (e.g., https://broker.local-ess.inrupt.com/).

oidc.jdbc.url

JDBC URL to a database. This deployment includes a Postgres DB. To connect, set the secret to: jdbc:postgresql://postgres/<DB_NAME> (e.g. jdbc:postgresql://postgres/oic). You can also update the value to use an external database.

The <DB_NAME> must be the same as the oidc.jdbc.db value.

oidc.jdbc.db

This configuration is used by the Postgres DB (e.g. oic). This needs to be the same as the <DB_NAME> used as part of oidc.jdbc.url.

oidc.jdbc.username

A DB username of your choice that will be used by the OIDC Broker (e.g. broker).

oidc.jdbc.password

A DB password of your choice that will be used by the OIDC Broker.

oidc.admin.webid

A WebID for the Admin user (e.g., https://identity.example.com/admin#i).

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

oidc.admin.email

An email for the Admin user.

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

oidc.admin.password

An admin password of your choice.

oidc.clients

List of backend identity providers. For example; Google, AuthO, Okta, Keycloak.

Specify the configuration string for the OIDC client application(s):

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

If using multiple providers, separate multiple Identity Providers with a semi-colon (;). Remove all spaces and new lines from this string.

oidc.servers

Used to configure back-end issuer identity servers. Set to none as it is not needed for most standard OIDC Providers.

oidc.http.ssl.certificate.truststore-store-password

A password for the Keystore used for SSL certificate generation. Make sure this is set the same as the password used to create the Keystore (e.g. changeit in the section above).

oidc.http.ssl.certificate.key-store-password

A password for the pkcs12 file. Make sure this is set the same as the password used to create the pkcs12 file.

oidc.resource.server.uri

The root URI of the LDP service that will host the Pods created for logged in users (e.g., https://<DOMAIN>/).

oidc.resource.server.admin

The WebID of an admin user that is entitled to create Pods on the LDP Service (e.g., https://identity.<DOMAIN>/registrar-agent.ttl).

If using the default value, a WebID needs to be set up as an Admin in the LDP service. See LDP Service.

  1. Create the Kubernetes Secret, updating the values for your <DOMAIN>, ``oidc.clients, and any other values as needed:

    kubectl create secret generic inrupt-oidc-secret -n oidc \
    --from-literal=oidc.issuer='https://broker.<DOMAIN>/' \
    --from-literal=oidc.jdbc.url='jdbc:postgresql://postgres/oic' \
    --from-literal=oidc.jdbc.db='oic' \
    --from-literal=oidc.jdbc.username='broker' \
    --from-literal=oidc.jdbc.password='pwdOIDCBrokerDB$123' \
    --from-literal=oidc.admin.webid='https://<DOMAIN>/admin/profile/card#me' \
    --from-literal=oidc.admin.email='admin@example.com' \
    --from-literal=oidc.admin.password='pwdOIDCAdmin$123' \
    --from-literal=oidc.clients='<Enter your Identity Provider(s) configuration here>' \
    --from-literal=oidc.servers='none' \
    --from-literal=oidc.http.ssl.certificate.key-store-password='changeit' \
    --from-literal=oidc.http.ssl.certificate.truststore-store-password='changeit' \
    --from-literal=oidc.resource.server.uri='https://<DOMAIN>/' \
    --from-literal=oidc.resource.server.admin='https://identity.<DOMAIN>/registrar-agent.ttl'
    
  2. Verify the secret:

    kubectl get secret inrupt-oidc-secret -n oidc -o yaml
    

    The command returns an output similar to the following:

    apiVersion: v1
    data:
      oidc.admin.email: xxx
      oidc.admin.password: xxx
      oidc.admin.webid: xxx
      oidc.clients: xxx
      oidc.http.ssl.certificate.key-store-password: xxx
      oidc.http.ssl.certificate.truststore-store-password: xxx
      oidc.issuer: xxx
      oidc.jdbc.db: xxx
      oidc.jdbc.password: xxx
      oidc.jdbc.url: xxx
      oidc.jdbc.username: xxx
      oidc.resource.server.admin: xxx
      oidc.resource.server.uri: xxx
      oidc.servers: xxx
    kind: Secret
    metadata:
      creationTimestamp: "2020-11-03T16:04:26Z"
      ...
      name: inrupt-oidc-secret2
      namespace: oidc
      resourceVersion: "2346529"
      selfLink: /api/v1/namespaces/oidc/secrets/inrupt-oidc-secret2
      uid: ab0d0fb1-b6de-44a4-bf45-3eb46255a513
    type: Opaque
    

Step 7: 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

  • 04_storage

  • 05_deployments

01_namespace

Create Namespace that will contain the OIDC Broker Service deployment:

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

The operation returns the following output:

namespace/oidc created

02_services

Create the OIDC Broker Service:

cd ${OIDC_RELEASE_DIR}/deployment/kubernetes/minikube
kubectl apply -f 02_services/

The operation returns the following output:

service/inrupt-oidc-service created
service/postgres created

03_config

Apply the OIDC Broker Service configurations into the cluster:

cd ${OIDC_RELEASE_DIR}/deployment/kubernetes/minikube
kubectl apply -f 03_config/

The operation returns the following output:

secret/docker-repo created

04_config

The OIDC service uses Postgres to store information:

cd ${OIDC_RELEASE_DIR}/deployment/kubernetes/minikube
kubectl apply -f 04_storage/

The operation returns the following output:

persistentvolumeclaim/postgres-pv-claim created

05_deployments

Create the OIDC Broker Service and Postgres deployments:

cd ${OIDC_RELEASE_DIR}/deployment/kubernetes/minikube
kubectl apply -f 05_deployments/

The operation returns the following output:

deployment.apps/inrupt-oidc-deployment created
deployment.apps/postgres-deployment created

Step 8: Verify Component Status

Verify that all the components have started and are running:

kubectl get all --namespace=oidc

The operation should return an output similar to the following:

NAME                                         READY   STATUS    RESTARTS   AGE
pod/inrupt-oidc-deployment-7c5f5cd77-lsvpq   1/1     Running   0          3m43s
pod/postgres-deployment-7d8b75484-crzpd      1/1     Running   0          3m43s

NAME                          TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
service/inrupt-oidc-service   ClusterIP   10.111.27.247   <none>        8443/TCP   100m
service/postgres              ClusterIP   10.100.91.7     <none>        5432/TCP   100m

NAME                                     READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/inrupt-oidc-deployment   1/1     1            1           3m43s
deployment.apps/postgres-deployment      1/1     1            1           3m43s

NAME                                               DESIRED   CURRENT   READY   AGE
replicaset.apps/inrupt-oidc-deployment-7c5f5cd77   1         1         1       3m43s
replicaset.apps/postgres-deployment-7d8b75484      1         1         1       3m43s

Step 9: Add OIDC Broker Domain

To allow the OIDC Broker to be accessed externally, the Broker’s URL (broker.<DOMAIN>) must be added to the hosts file on your local machine. Refer to the ESS Local Installation Guide or the ESS Shared Server Installation Guide (as appropriate) for instructions on how to modify your hosts file.

Once added, the hosts file should contain a line similar to the following:

<Minikube IP> <DOMAIN> broker.<DOMAIN>

Step 10: 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.

Step 11: 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. Go to the minikube directory:

    cd ${ESS_RELEASE_DIR}/deployment/kubernetes/minikube
    
  2. In the 03_config/ess-config.yaml, 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 ${ESS_RELEASE_DIR}/deployment/kubernetes/minikube
    kubectl apply -f 03_config/
    

    The operation should return an output similar to the following:

    secret/docker-repo unchanged
    configmap/ldp-service-config configured
    configmap/websocket-service-config configured
    configmap/proxy-config configured
    configmap/ess-config unchanged
    configmap/jwks-service-config unchanged
    configmap/fluentd-es-config unchanged
    configmap/proxy-conf unchanged
    secret/inrupt-ess-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 Installation

Note

Replace <DOMAIN> with the domain name for your deployment (e.g., ess.mycompany.com).

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., https://broker.<DOMAIN>).

    2. LDP Storage Server: URL of the LDP Storage service (e.g., https://<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.

    You may encounter an Authorization page. If so, click Authorize to continue withe the test.

  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.

Access via Application

You can validate the installation process by accessing the deployed ESS from an application:

  1. Open a web browser to https://podbrowser.inrupt.com.

  2. In the login dialog that appears, enter https://broker.<DOMAIN>.

  3. Click the Log In button.

Spin Down/Up ESS

Spin Down/Shut Down ESS

You can shut down ESS by removing them from Kubernetes.

  1. Go to the deployment/kubernetes/minikube directory.

    cd ${ESS_RELEASE_DIR}/deployment/kubernetes/minikube/
    
  2. To remove all ESS components from Kubernetes, run the following command:

    Note

    The 07_monitoring and 08_logging services are optional.

    kubectl delete -f 02_services/
    kubectl delete -f 03_config/
    kubectl delete -f 05_backend-deployments/
    kubectl delete -f 06_ess-deployments/
    kubectl delete -f 07_monitoring/
    kubectl delete -f 08_logging/
    
  3. To verify that all ESS components and services are gone, run:

    kubectl -n ess get all
    

    Only the service/kubernetes service should be running.

Spin Up/Restart ESS

You can restart all the ESS services after they have been shut down or restart an individual ESS service if it is down.

Restart All ESS Microservices

  1. Go to the deployment/kubernetes/minikube directory.

    cd ${ESS_RELEASE_DIR}/deployment/kubernetes/minikube/
    
  2. To restart all the ESS services after they have been shut down, run the following command:

    Note

    The 07_monitoring and 08_logging services are optional.

    kubectl apply -f 02_services/
    kubectl apply -f 03_config/
    kubectl apply -f 05_backend-deployments/
    kubectl apply -f 06_ess-deployments/
    kubectl apply -f 07_monitoring/
    kubectl apply -f 08_logging/
    
  3. To verify that all ESS components and services are running, run the following command:

    kubectl -n ess get all
    

    All components and services should be running.

Restart an ESS Microservice

  1. To restart a specific ESS Microservice if it is not running, run the following command, specifying the deployment to restart:

    kubectl rollout restart <service app deployment>
    
  2. To check the status of the rollout, run the following command, specifying the deployment:

    kubectl rollout status <service app deployment>
    

Stop/Start/Delete Minikube

Stop Minikube

When you’re finished with the environment, to save local resources it can be stopped with the following command:

minikube stop

This command shuts down the Kubernetes cluster and Minikube.

Start Minikube

To restart Minikube, run:

minikube start

kubectl config set-context --current --namespace=ess

The operation returns a message stating Context "minikube" modified.

Minikube and all related services are booted back up as before.

Delete Minikube

To fully delete the Kubernetes cluster and Minikube, run the following command:

minikube delete

This command removes everything, and it will require a full rebuild to spin the environment back up again.

Tear Down OIDC Broker Service

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