Carbyne Stack Thymus Authentication and Authorization

DISCLAIMER: Carbyne Stack Thymus is in proof-of-concept stage. The software is not ready for production use. It has neither been developed nor tested for a specific use case.

Thymus is the authentication and authorization subsystem of Carbyne Stack.

Namesake

The thymus is an organ that is critically important to the immune system which serves as the body’s defense mechanism providing surveillance and protection against diverse pathogens, tumors, antigens and mediators of tissue damage. (Source)

Within Carbyne Stack Thymus implements measures and mechanisms to defend against unauthorized access.

Development

Isolated Deployment

The Thymus subsystem can be run in isolation, i.e., without a full-fledged Carbyne Stack system. In order to follow the steps below, we assume that you have a kind Kubernetes cluster at your disposal that comes along with Istio, MetalLB, and the Zalando PostgreSQL operator. This can be achieved by following the Platform Setup Guide available on the Carbyne Stack website.

[!TIP] You can skip the Knative installation as it is not required for running Thymus.

To deploy Thymus follow the steps below:

1. Clone the Thymus repository:

   git clone https://github.com/carbynestack/thymus.git

2. Create the PostgreSQL instance required by both Kratos and Hydra:

   kubectl apply -f thymus/hack/postgres.yaml

3. Change into the Thymus chart directory:

   cd thymus/charts/thymus

4. Fetch the dependencies of the chart:

   helm dependency update

5. Install the chart:

   helm install thymus . --set thymus.gateway.enabled=true --set thymus.users.enabled=true

   [!NOTE] thymus.gateway.enabled=true and thymus.users.enabled=true are optional flags that enable the creation of an Istio gateway and a set of demo users respectively.

Thymus is now available and exposes the following APIs at the given endpoints:

API	Endpoint
Kratos	http://172.18.1.128.sslip.io/iam
Kratos UI	http://172.18.1.128.sslip.io/iam/ui
Hydra	http://172.18.1.128.sslip.io/iam/oauth

Authentication Flow

[!NOTE] The following assumes that you have deployed Thymus as described above.

The following steps demonstrate the OpenID Connect authentication flow using Thymus:

1. Get the OAuth2 client ID:

   CLIENT_ID=$(kubectl get secrets thymus-client-secret -o jsonpath='{.data.CLIENT_ID}' | base64 -d)

2. Request an authorization code by opening the following URL in a browser and authenticate yourself via the credentials of one of the users listed in charts/thymus/values.yaml:

   open "http://172.18.1.128.sslip.io/iam/oauth/oauth2/auth?client_id=${CLIENT_ID}&redirect_uri=http%3A%2F%2F127.0.0.1%3A5555%2Fcallback&response_type=code&state=1102398157&scope=offline%20openid"

   After being redirected to address http://127.0.0.1/callback copy the value of the code query parameter and store it in the $AUTH_CODE variable.

   AUTH_CODE="<token>"

3. Exchange the authentication code for an authentication token:

   curl --request POST \
   --url http://172.18.1.128.sslip.io/iam/oauth/oauth2/token \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data client_id=${CLIENT_ID} \
   --data code=${AUTH_CODE} \
   --data grant_type=authorization_code \
   --data redirect_uri=http://127.0.0.1:5555/callback

You can use the returned access and refresh tokens to authenticate yourself to an Istio with properly configured End User Authentication.

License

The Carbyne Stack Thymus Authentication and Authorization subsystem repository is open-sourced under the Apache License 2.0. See the LICENSE file for details.

3rd Party Licenses

For information on how license obligations for 3rd party OSS dependencies are fulfilled see the README file of the Carbyne Stack repository.

Contributing

Please see the Carbyne Stack Contributor's Guide