Skip to content

Commit d9a348f

Browse files
muraeemuraee
committed
add docs for rosa external auth feature
1 parent 9b18c91 commit d9a348f

File tree

3 files changed

+116
-1
lines changed

3 files changed

+116
-1
lines changed

‎docs/book/src/SUMMARY_PREFIX.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@
2626
- [Creating a cluster](./topics/rosa/creating-a-cluster.md)
2727
- [Creating MachinePools](./topics/rosa/creating-rosa-machinepools.md)
2828
- [Upgrades](./topics/rosa/upgrades.md)
29+
- [External Auth Providers](./topics/rosa/external-auth.md)
2930
- [Bring Your Own AWS Infrastructure](./topics/bring-your-own-aws-infrastructure.md)
3031
- [Specifying the IAM Role to use for Management Components](./topics/specify-management-iam-role.md)
3132
- [Using external cloud provider with EBS CSI driver](./topics/external-cloud-provider-with-ebs-csi-driver.md)

‎docs/book/src/topics/rosa/external-auth.md

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# External Auth Providers (BYOI)
2+
3+
ROSA allows you to Bring Your Own Identity (BYOI) to manage and authenticate cluster users.
4+
5+
## Enabling
6+
7+
To enable this feature, `enableExternalAuthProviders` field should be set to `true` on cluster creation. Changing this field afterwards will have no effect:
8+
```yaml
9+
---
10+
apiVersion: controlplane.cluster.x-k8s.io/v1beta2
11+
kind: ROSAControlPlane
12+
metadata:
13+
name: "capi-rosa-quickstart-control-plane"
14+
spec:
15+
enableExternalAuthProviders: true
16+
....
17+
```
18+
19+
Note: This feauture requires OpenShift version `4.15.5` or newer.
20+
21+
## Usage
22+
23+
After creating and configuring your OIDC provider of choice, the next step is to configure ROSAControlPlane `externalAuthProviders` as follows:
24+
```yaml
25+
---
26+
apiVersion: controlplane.cluster.x-k8s.io/v1beta2
27+
kind: ROSAControlPlane
28+
metadata:
29+
name: "capi-rosa-quickstart-control-plane"
30+
spec:
31+
enableExternalAuthProviders: true
32+
externalAuthProviders:
33+
- name: my-oidc-provider
34+
issuer:
35+
issuerURL: https://login.microsoftonline.com/<tenant-id>/v2.0 # e.g. if using Micorsoft Entra ID
36+
audiences: # audiences that will be trusted by the kube-apiserver
37+
- "audience1" # usaully the client ID
38+
claimMappings:
39+
username:
40+
claim: email
41+
prefixPolicy: ""
42+
groups:
43+
claim: groups
44+
....
45+
```
46+
47+
Note: `oidcProviders` only accepts one entry at the moment.
48+
49+
## Accessing the cluster
50+
51+
### Setting up RBAC
52+
53+
When `enableExternalAuthProviders` is set to `true`, ROSA provider will generate a temporarily admin kubeconfig secert in the same namespace named `<cluster-name>-bootstrap-kubeconfig`. This kubeonconfig can be used to access the cluster to setup RBAC for oidc users/groups.
54+
55+
For example, bind the `cluster-admin` to an oidc group, to give admin permissions to all users part of that group:
56+
```shell
57+
kubectl get secret <cluster-name>-bootstrap-kubeconfig -o jsonpath='{.data.value}' | base64 -d > /tmp/capi-admin-kubeconfig
58+
export KUBECONFIG=/tmp/capi-admin-kubeconfig
59+
60+
kubectl create clusterrolebinding oidc-cluster-admins --clusterrole cluster-admin --group <group-id>
61+
```
62+
63+
Note: The generated bootstrap kubeconfig is only valid for 24h, and will not be usable afterwards. However, users can opt to manually delete the secret object to trigger the generation of a new one which will be valid for another 24h.
64+
65+
### Login using the cli
66+
67+
The [kubelogin kubectl plugin](https://github.com/int128/kubelogin/tree/master) can be used to login with OIDC credentials using the cli.
68+
69+
### Configuring OpenShift Console
70+
71+
The OpenShift Console needs to be configured before it can be used to authenticate and login to the cluster.
72+
1. Setup a new client in your OIDC provider with the following Redirect URL `<console-url>/auth/callback`. You can find the console URL in the status field of the `ROSAControlPlane` once the cluster is ready:
73+
```shell
74+
kubectl get rosacontrolplane <control-plane-name> -o jsonpath='{.status.consoleURL}'
75+
```
76+
77+
2. Create a new client secret in your OIDC provider and store the value in a kubernetes secret in the same namespace as your cluster:
78+
```shell
79+
kubectl create secret generic console-client-secret --from-literal=clientSecret='<client-secret-value>'
80+
```
81+
82+
3. Configure `ROSAControlPlane` external auth provider with the created client:
83+
```yaml
84+
---
85+
apiVersion: controlplane.cluster.x-k8s.io/v1beta2
86+
kind: ROSAControlPlane
87+
metadata:
88+
name: "capi-rosa-quickstart-control-plane"
89+
spec:
90+
enableExternalAuthProviders: true
91+
externalAuthProviders:
92+
- name: my-oidc-provider
93+
issuer:
94+
issuerURL: https://login.microsoftonline.com/<tenant-id>/v2.0 # e.g. if using Micorsoft Entra ID
95+
audiences: # audiences that will be trusted by the kube-apiserver
96+
- "audience1"
97+
- <console-client-id> # <----New
98+
claimMappings:
99+
username:
100+
claim: email
101+
prefixPolicy: ""
102+
groups:
103+
claim: groups
104+
oidcClients: # <----New
105+
- componentName: console
106+
componentNamespace: openshift-console
107+
clientID: <console-client-id>
108+
clientSecret:
109+
name: console-client-secret # secret name created in step 2
110+
....
111+
```
112+
113+
see [ROSAControlPlane CRD Reference](https://cluster-api-aws.sigs.k8s.io/crd/#controlplane.cluster.x-k8s.io/v1beta2.ExternalAuthProvider) for all possible configurations.

‎docs/book/src/topics/rosa/index.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,4 +21,5 @@ A new template is available in the templates folder for creating a managed ROSA
2121
* [Enabling ROSA Support](enabling.md)
2222
* [Creating a cluster](creating-a-cluster.md)
2323
* [Creating MachinePools](creating-rosa-machinepools.md)
24-
* [Upgrades](upgrades.md)
24+
* [Upgrades](upgrades.md)
25+
* [External Auth Providers](external-auth.md)

0 commit comments

Comments
 (0)