Break-glass¶

For day-to-day usage, Welkin recommends Platform Administrators and Application Developers to authenticate to all Welkin endpoints using single sign-on via an Identity Provider (IdP). However, certain information security standards require a break glass procedure, in case the IdP is down.

In this section we recommend two break glass procedures, to ensure Platform Administrators and/or Application Developers can gain access to a Welkin environment:

The first procedure targets a malfunctioning IdP.
The second procedure targets a malfunctioning or misconfiguration of the Welkin component integrating with the IdP.

Dex Static User¶

Important

Make sure to only use the Dex static user for break glass. Welkin recommends against daily usage.

When the IdP provider is malfunctioning, you can use the Dex static user to access the Welkin environment.

The Dex static user is disabled by default. To configure a Dex static user proceed as follows:

Set dex.enableStaticLogin to true.
Set dex.staticPassword to the bcrypt-ed password. To compute the bcrypt-ed password, we suggest using the htpasswd tool: htpasswd -nB admin@example.com.

Tip

The Dex static user can either be used by the Platform Administrators or the Application Developers. See access control for details.

Single Sign-on Bypass¶

When Dex is malfunctioning, the Platform Administrator needs some kind of access which does not rely on Dex for troubleshooting. The following steps will give you temporary access sufficient for troubleshooting and recovery:

SSH to one of the control-plane Nodes.

Use /etc/kubernetes/admin.conf and run kubectl commands to check the problem

export KUBECONFIG=/etc/kubernetes/admin.conf
#run kubectl command
sudo kubectl get po -A

Kubernetes User Access¶

Note

This is a temporary solution and access should be disabled once the issue with Dex is resolved.

If Dex is broken, you can manually create a kubeconfig file for a user. While there are different ways to create kubeconfig files, we will use the X.509 client certificates with OpenSSL. Follow the steps below to create a user kubeconfig file.

Create a private key:
```
openssl genrsa -out user1.key 2048
```

Create a certificate signing request (CSR). CN is the username and O the group.

openssl req -new -key user1.key \
-out user1.csr \
-subj "/CN=user1/O=companyname"

Get the Base64 encoding for the generated CSR file.
```
cat user1.csr | base64 | tr -d '\n'
```

Create a Certificate Signing Request with Kubernetes

cat <<EOF | kubectl  apply -f -
apiVersion: certificates.k8s.io/v1
kind: CertificateSigningRequest
metadata:
    name: user1
spec:
    groups:
    - system:authenticated
    request: # put here the Base64 encoded text for the CRS that you get in step 3
    signerName: kubernetes.io/kube-apiserver-client
    usages:
    - client auth
EOF

Approve the CSR
```
kubectl certificate approve user1
```

Get the certificate. Retrieve the certificate from the CSR:

kubectl get csr/user1 -o yaml

The certificate value is in Base64-encoded format under status.certificate. Put the content under client-certificate-data:. And also get the Base64 encoded content for the private key and put it under client-key-data:. To get the Base64 encoded content cat user1.key | base64 | tr -d '\n'.

The kubeconfig file for user1 user looks like:

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: <CA>
    server: https://control-node-ip:6443 # ip address of one of the control nodes
  name: <cluster-name>
contexts:
- context:
    cluster: <cluster-name>
    user: user1 # <USER>
  name: <USER>@<CLUSTER-NAME>
kind: Config
users:
- name: user1
  user:
    client-certificate-data: <CLIENT-CRT-DATA>
    client-key-data: <CLIENT-KEY-DATA>

Add the user and namespaces that s/he has access to in wc-config.yaml file.

user:
  # This only controls if the namespaces should be created, user RBAC is always created.
  createNamespaces: true
  namespaces:
    - namespace1 # namespaces that the user is allowed to access
  adminUsers:
    - user1 # the user