feat: update getting-started guide supporting authentication

Signed-off-by: Sebastian Becker <[email protected]>
carbynestack · May 29, 2024 · 5e00844 · 5e00844
1 parent 96eec82
commit 5e00844
Show file tree

Hide file tree

Showing 3 changed files with 93 additions and 8 deletions.
diff --git a/docs/documentation/getting-started/cli.md b/docs/documentation/getting-started/cli.md
@@ -3,6 +3,12 @@
 In this guide, you will learn how to download and configure the Carbyne Stack
 CLI that can be used to interact with a virtual cloud from the command line.
 
+!!! info
+    This guide expects Carbyne Stack to be deployed in a _local_ two player 
+    setting using kind clusters as described in the 
+    [manual deploymend guide](../deployment/manual). Cluster names as used for
+    connecting to the clusters may be different for individual deployments.
+
 1. Install the CLI using:
 
     ```shell
@@ -18,6 +24,21 @@ CLI that can be used to interact with a virtual cloud from the command line.
     export STARBUCK_FQDN="172.18.2.128.sslip.io"
     ```
 
+1. Export the Thymus OAuth2 client IDs for both VCPs.
+
+    !!! info
+        Thymus automatically registers an OAuth2 client for authentication with
+        the Carbyne Stack VCP and stores its ID as a k8s secret called 
+        `thymus-client-secret`. For more information about OAuth2 clients see the
+        [Ory Hydry documentation](https://www.ory.sh/docs/hydra/guides/oauth2-clients).
+
+    ```shell
+    kubectl config use-context kind-apollo
+    export APOLLO_OAUTH2_CLIENT_ID=$(kubectl get secret thymus-client-secret --template {{.data.CLIENT_ID}} | base64 -d)
+    kubectl config use-context kind-starbuck
+    export STARBUCK_OAUTH2_CLIENT_ID=$(kubectl get secret thymus-client-secret --template {{.data.CLIENT_ID}} | base64 -d)
+    ```
+
 1. Next, configure the CLI to talk to the virtual cloud you just deployed by
    creating a matching CLI configuration file in `~/.cs` using:
 
@@ -33,12 +54,20 @@ CLI that can be used to interact with a virtual cloud from the command line.
         "amphoraServiceUrl" : "http://$APOLLO_FQDN/amphora",
         "castorServiceUrl" : "http://$APOLLO_FQDN/castor",
         "ephemeralServiceUrl" : "http://$APOLLO_FQDN/",
+        "oauth2ClientId": "$APOLLO_OAUTH2_CLIENT_ID",
+        "oauth2AuthEndpointUri": "http://$APOLLO_FQDN/iam/oauth/oauth2/auth",
+        "oauth2TokenEndpointUri": "http://$APOLLO_FQDN/iam/oauth/oauth2/token",
+        "oauth2CallbackUrl": "http://127.0.0.1:32768/callback",
         "id" : 1,
         "baseUrl" : "http://$APOLLO_FQDN/"
       }, {
         "amphoraServiceUrl" : "http://$STARBUCK_FQDN/amphora",
         "castorServiceUrl" : "http://$STARBUCK_FQDN/castor",
         "ephemeralServiceUrl" : "http://$STARBUCK_FQDN/",
+        "oauth2ClientId": "$STARBUCK_OAUTH2_CLIENT_ID",
+        "oauth2AuthEndpointUri": "http://$STARBUCK_FQDN/iam/oauth/oauth2/auth",
+        "oauth2TokenEndpointUri": "http://$STARBUCK_FQDN/iam/oauth/oauth2/token",
+        "oauth2CallbackUrl": "http://127.0.0.1:32768/callback",
         "id" : 2,
         "baseUrl" : "http://$STARBUCK_FQDN/"
       } ],
@@ -55,6 +84,36 @@ CLI that can be used to interact with a virtual cloud from the command line.
     java -jar cs.jar configure
     ```
 
+1. Log in to the VCPs
+
+    With the user-facing endpoints being secured using _OAuth2.0_ and _OpenID 
+    Connect_, it is required to authenticate to the VCPs. This can be done 
+    using:
+
+    ```shell
+    java -jar cs.jar login
+    ```
+
+    !!! info
+        The command above will open a browser window for each VCPs and prompt for 
+        authentication.
+        
+        The development setup as described in the 
+        [deployment tutorial](../deployment) will automatically register two 
+        demo users as follows:
+        
+        | E-Mail | Password |
+        | ------ | -------- |
+        | [email protected] | 2#Tv91*d-Z,M |
+        | [email protected] | 86KIo6<]!/V= |
+
+    !!! warning
+        If you register individual users, you must ensure that the users are 
+        registered in all VCPs with the same e-mail address. Passwords can be
+        set individually.
+
+1. [_Optional_] Verify the configuration
+
     You can verify that the configuration works by fetching telemetry data from
     castor using:
 

diff --git a/docs/documentation/getting-started/deployment/manual/stack.md b/docs/documentation/getting-started/deployment/manual/stack.md
@@ -58,10 +58,10 @@ clusters using the kind tool as described in the
         cd carbynestack/deployments
         ```
 
-1. Checkout Carbyne Stack SDK version 0.5.0 using:
+1. Checkout Carbyne Stack SDK version 0.6.0 using:
 
     ```shell
-    git checkout sdk-v0.5.0
+    git checkout sdk-v0.6.0
     ```
 
 1. Before deploying the virtual cloud providers make some common configuration
@@ -119,7 +119,7 @@ clusters using the kind tool as described in the
     export IS_MASTER=false
     export AMPHORA_VC_PARTNER_URI=http://$APOLLO_FQDN/amphora
     kubectl config use-context kind-starbuck
-    helmfile apply
+    helmfile sync --set thymus.users.enabled=true
     ```
 
 1. Launch the `apollo` VCP using:
@@ -130,7 +130,7 @@ clusters using the kind tool as described in the
     export AMPHORA_VC_PARTNER_URI=http://$STARBUCK_FQDN/amphora
     export CASTOR_SLAVE_URI=http://$STARBUCK_FQDN/castor
     kubectl config use-context kind-apollo
-    helmfile apply
+    helmfile sync --set thymus.users.enabled=true
     ```
 
 1. Wait until all pods in both clusters are in the `ready` state.

diff --git a/docs/documentation/getting-started/millionaires.md b/docs/documentation/getting-started/millionaires.md
@@ -12,7 +12,7 @@ these.
 
 In addition, this guide assumes that you have the following tools installed:
 
-- Java 8 (newer versions will not work)
+- Java 11 (newer versions will not work)
 
 ## The Billionaires Problem
 
@@ -31,14 +31,37 @@ see how things work, let's put ourselves in Elon's shoes.
 First, we upload the inputs into the Carbyne Stack
 [Amphora Secret Store](https://github.com/carbynestack/amphora). The inputs are
 the billionaires' net worth in billions. Note that this obviously has to be done
-in a private way by Jeff and Elon in a real-world setting.
+in a private way by Jeff and Elon in a real-world setting, simplified here by 
+logging in as individual users.
+
+The first secret will be uploaded with the identity of Jeff. To do so please 
+perform the following commands and login as Jeff using the E-Mail
+`[email protected]` and password `86KIo6<]!/V=`.
+
 
 ```shell
+java -jar cs.jar login
 # Create a secret representing Jeff's net worth (note that we work with 
 # billion USD here)
 export JEFFS_NET_WORTH_ID=$(java -jar cs.jar amphora create-secret 177 -t billionaire=Jeff)
+```
+
+!!! info
+    If you have authenticated yourself to the VCPs recently, your previous 
+    session might still be cached using a browser cookie.
 
-# And another one for Elon
+    If you are not prompted for your credentials and not logged in as the 
+    desired user, please make sure to clear recent browser cache or cookies,
+    or re-open the tabs in private mode.
+
+Next we will log in as Elon to perform the remaining steps of the tutorial. The
+credentials for the development user Elon are as follows: <br>
+&ensp;&ensp;&ensp;&ensp;E-Mail: `[email protected]`Password: `2#Tv91*d-Z,M`. <br>
+(Please read the info box above if you are having trubles logging in as a different user.)
+
+```shell
+java -jar cs.jar login
+# And a secret for Elon
 export ELONS_NET_WORTH_ID=$(java -jar cs.jar amphora create-secret 151 -t billionaire=Elon)
 ```
 
@@ -51,7 +74,10 @@ java -jar cs.jar amphora get-secrets
 The output should resemble the following:
 
 !!! note
-    The output you see will differ wrt. identifiers and the `creation-date` tag.
+    The output you see will differ wrt. identifiers and the `creation-date` tag. <br>
+    Nevertheless, it will output both secrets, uploaded by Elon and Jeff even though
+    we are authenticated as Elon. This is to the fact of authentication, but not 
+    authorization being integrated into Carbyne Stack for the time beeing.
 
 ```shell
 ab160f93-3b7e-468f-b687-f9c46fb535f3