Dashboard authentication (GitHub)#

Introduction#

This documents an example of installing an OAuth2 proxy in front of the Aspen Mesh dashboard. This ensures that only authenticated users in your organization can access the dashboard.

The example uses GitHub as an OAuth2 identity provider. It uses the oauth2-proxy project which has integrations for other providers such as Google, Azure, GitLab, or custom. Please consult those documents if you want to adjust these instructions for a different provider.

Setup#

We will fulfill some prerequistes, create a GitHub application, configure the OAuth2 proxy, and then deploy it in front of the Aspen Mesh dashboard.

Prerequisites#

You will need admin permissions for a GitHub organization.

You must choose a domain name where the Aspen Mesh dashboard will be exposed. We will provide this to the GitHub Application as the redirect URI, so GitHub can send users back to the Aspen Mesh dashboard once they have completed the GitHub Authorization flow.

If this is a domain on the public internet, we recommend you protect this domain with HTTPS/TLS. If you have a certificate and keypair, you can provide it directly to the OAuth2 proxy later in this configuration.

We’ll refer to this domain as <DOMAIN> throughout this document. An example domain might be aspenmesh.admin.yourplatform.com.

Create GitHub Application#

The GitHub Application is the authentication endpoint we will redirect to for users to approve a “Sign In with GitHub”.

Go to https://github.com/organizations/<yourorganization>/settings/applications in your web browser (replace <yourorganization>).
Click New OAuth App.
Provide entries for these fields:
- Application Name: Aspen Mesh
- Homepage URL: https://<DOMAIN>/
- Application Description (optional): Aspen Mesh dashboard helps you observe, secure, and gain insights into your microservices.
- Authorization callback URL: https://<DOMAIN>/oauth2/callback
Click Register Application. You will be taken to the Application Page which provides the credentials we will need to provide to configure the proxy. Specifically, we will need the Client ID and Client Secret.

Deploy the OAuth2 proxy#

This section involves configuring some credentials for the OAuth2 proxy. If someone later got access to your shell’s scrollback buffer or history, they may be able to discover these secrets. You should close your shell once these steps are complete. This command will disable shell history for this session (you need to run it each time you make a new shell for handling the secrets): set +o history.

Make a Cookie Secret. This is used to encrypt the cookies that are stored in your users’ browsers. It can be any long base64 value as long as it is confidential and used only for this application. Here is one way to generate one:
```
export COOKIE_SECRET=`pwgen -s 150 1 | base64`
```

Create a secret containing the GitHub Application details and a Cookie Secret. Replace <CLIENT_ID> and <CLIENT_SECRET> with the Client ID and Client Secret from the GitHub Application.

kubectl create secret generic -n istio-system aspen-mesh-oauth2-proxy-secrets --from-literal=CLIENT_ID=<CLIENT_ID> --from-literal=CLIENT_SECRET=<CLIENT_SECRET> --from-literal=COOKIE_SECRET=$COOKIE_SECRET

Create a secret containing the TLS certificate and key for <DOMAIN>. Put the certificate chain and key in files called fullchain.pem and privkey.pem, or replace those in the command below with a path to the files. Your platform may also have platform-specific techniques for securely creating Kubernetes TLS secrets. If so, create a TLS secret named aspen-mesh-oauth2-proxy-cert in the istio-system namespace.
```
kubectl create secret tls -n istio-system aspen-mesh-oauth2-proxy-cert --key privkey.pem --cert fullchain.pem
```
At this point, we are finished handling credentials. You may want to remove local copies of the certificates and keys, and close your terminal session and open a new one so that any credentials that appeared on screen while working through this section are not visible.

Deploy the OAuth proxy#

Create a Kubernetes deployment and service like the following. You need to replace <github-org> and <github-team> below.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: aspen-mesh-oauth2-proxy
  namespace: istio-system
  labels:
    app: aspen-mesh-oauth2-proxy
spec:
  replicas: 1
  selector:
    matchLabels:
      app: aspen-mesh-oauth2-proxy
  template:
    metadata:
      labels:
        app: aspen-mesh-oauth2-proxy
      annotations:
        sidecar.istio.io/inject: "false"
    spec:
      containers:
        - name: oauth2-proxy
          image: quay.io/pusher/oauth2_proxy:v4.0.0
          imagePullPolicy: IfNotPresent
          args:
            - '--provider=github'
            - '--https-address=0.0.0.0:8443'
            - '--tls-cert-file=/etc/oauth2-https-certs/tls.crt'
            - '--tls-key-file=/etc/oauth2-https-certs/tls.key'
            - '--email-domain=*'
            - '--github-org=<github-org>'
            - '--github-team=<github-team>'
            - '--cookie-secret=$COOKIE_SECRET'
            - '--client-secret=$CLIENT_SECRET'
            - '--client-id=$CLIENT_ID'
            - '--upstream=http://aspen-mesh-controlplane.istio-system:19001'
          ports:
            - containerPort: 4180
              name: http
            - containerPort: 8443
              name: https
          env:
            - name: COOKIE_SECRET
              valueFrom:
                secretKeyRef:
                  name: aspen-mesh-oauth2-proxy-secrets
                  key: COOKIE_SECRET
            - name: CLIENT_SECRET
              valueFrom:
                secretKeyRef:
                  name: aspen-mesh-oauth2-proxy-secrets
                  key: CLIENT_SECRET
            - name: CLIENT_ID
              valueFrom:
                secretKeyRef:
                  name: aspen-mesh-oauth2-proxy-secrets
                  key: CLIENT_ID
          volumeMounts:
          - name: https-certs
            mountPath: /etc/oauth2-https-certs
            readOnly: true
      volumes:
        - name: https-certs
          secret:
            secretName: aspen-mesh-oauth2-proxy-cert
---
apiVersion: v1
kind: Service
metadata:
  name: aspen-mesh-oauth2-proxy
  namespace: istio-system
  labels:
    app: aspen-mesh-oauth2-proxy
spec:
  type: LoadBalancer
  selector:
    app: aspen-mesh-oauth2-proxy
  ports:
    - name: https
      port: 443
      protocol: TCP
      targetPort: 8443

The service aspen-mesh-oauth2-proxy in the namespace istio-system is type: LoadBalancer, so your cloud or platform should create an external load balancer for it. If not, you must follow platform-specific instructions for how to expose the service outside the cluster.
You should associate the service aspen-mesh-oauth2-proxy with the domain that you chose at the beginning (<DOMAIN>). This is platform-specific. In many environments, this means creating an A, AAAA, or CNAME DNS record that points at an automatically assigned load-balancer domain name. You can find the load-balancer domain name or IP address in the EXTERNAL-IP like this:
```
$ kubectl get svc -n istio-system aspen-mesh-oauth2-proxy
```
```
NAME                      TYPE           CLUSTER-IP       EXTERNAL-IP
aspen-mesh-oauth2-proxy   LoadBalancer   100.20.113.43    a123w----------------------5a3e-150000001.us-west-2.elb.amazonaws.com
```
In your DNS provider, configure <DOMAIN> to map to the EXTERNAL-IP above.
Visit https://<DOMAIN> in your browser and you should see a “Sign In with GitHub” button. Click it.
You will be taken to GitHub to authorize the app that you created earlier. If you are not logged in to GitHub, you will have to complete a login. You must be a member of the GitHub team specified when configuring the proxy.

Click the Authorize button.
You will be redirected back to the Aspen Mesh dashboard.
To log out, visit https://<DOMAIN>/oauth2/sign_out or delete the cookies from your browser for <DOMAIN>.