|
| 1 | +# Dex Config Guidance |
| 2 | + |
| 3 | +The scope of this document is to describe the steps to Install, Configure(Setup Login with OpenShift) and Uninstall the Dex with OpenShift GitOps Operator. |
| 4 | + |
| 5 | +## Table of Contents |
| 6 | + |
| 7 | +1. [Install](#install) |
| 8 | +2. [Login with OpenShift](#login-with-openshift) |
| 9 | +3. [Restrict login to only a set of Groups](#restrict-login-to-only-a-set-of-groups) |
| 10 | +4. [Argo CD RBAC Policies for Dex](#argo-cd-rbac-policies-for-dex) |
| 11 | +5. [Dex Resource requests/limits](#dex-resource-requestslimits) |
| 12 | +6. [Uninstall](#uninstall) |
| 13 | + |
| 14 | +## Install |
| 15 | + |
| 16 | +> **Note** |
| 17 | +`DISABLE_DEX` environment variable & `.spec.dex` fields are no longer supported in OpenShift GitOps v1.10 onwards. Dex can be enabled/disabled by setting `.spec.sso.provider: dex` in ArgoCD CR. |
| 18 | + |
| 19 | +To enable dex, set `.spec.sso.provider` to `dex` & add dex configs under `.spec.sso.dex` fields in ArgoCD CR. |
| 20 | + |
| 21 | +```yaml |
| 22 | +apiVersion: argoproj.io/v1alpha1 |
| 23 | +kind: ArgoCD |
| 24 | +metadata: |
| 25 | + name: <argocd-instance-name> |
| 26 | +spec: |
| 27 | + sso: |
| 28 | + provider: dex |
| 29 | + dex: |
| 30 | + openShiftOAuth: true |
| 31 | +``` |
| 32 | +or |
| 33 | +```bash |
| 34 | +oc -n <namespace> patch argocd <argocd-instance-name> --type='merge' --patch='{ "spec": { "sso": { "provider": "dex", "dex": {"openShiftOAuth": true}}}} |
| 35 | +``` |
| 36 | +
|
| 37 | +Operator has built-in support for OpenShift Dex connector and can be enabled by setting `.spec.sso.dex.openShiftOAuth` to `true`. This will automatically configure the dex to use OpenShift users to log in into Argo CD. Any additional connector configurations can be made using `.spec.sso.dex.config` field. |
| 38 | + |
| 39 | +> **Note** |
| 40 | +There is known issue due to which default OpenShift connector configurations are overridden when `.spec.sso.dex.config` is set. Fix is tracked [here](https://issues.redhat.com/browse/GITOPS-3600). |
| 41 | + |
| 42 | +> **Important** |
| 43 | +Dex resource creation will not be triggered, unless there is valid Dex configuration expressed through `.spec.sso.dex`. This could either be using the default OpenShift configuration via `.spec.sso.dex.openShiftOAuth` or it could be custom Dex configuration provided by the user via `.spec.sso.dex.config`. Absence of either will result in an error due to failing health checks on Dex. |
| 44 | + |
| 45 | +Addition configurations such as a different dex image, version, resource limits, etc can be provided. Refer [dex-options](https://argocd-operator.readthedocs.io/en/latest/reference/argocd/#dex-options) section in argocd-operator documentation for more details. |
| 46 | + |
| 47 | +## Login with OpenShift |
| 48 | + |
| 49 | +- Go to the `OpenShift Console -> Networking -> Routes`. |
| 50 | + |
| 51 | +- Select your Argo CD instance namespace under `Project` dropdown. |
| 52 | + |
| 53 | +- Click on the `<argocd-instance>-server` route url to access the Argo CD UI. |
| 54 | + |
| 55 | +- You will be redirected to Argo CD Login Page. |
| 56 | + |
| 57 | +- You can see an option to **LOG IN VIA OPENSHIFT** apart from the usual Argo CD login. Click on the button. (Please clear the site cache or use incognito window if facing issues). |
| 58 | + |
| 59 | +- You will be redirected to the OpenShift Login Page. |
| 60 | + |
| 61 | +- Provide the OpenShift login credentials to get redirected to Argo CD. |
| 62 | + |
| 63 | +- Upon successful login in Argo CD, you can look at the user details by clicking on the User Info Tab in Argo CD UI. |
| 64 | + |
| 65 | +## Restrict login to only a set of Groups |
| 66 | + |
| 67 | +Dex allows the admin to restrict login to optional list of groups. Which means, only the users who are part of any of the these groups will be able to login into Argo CD. |
| 68 | + |
| 69 | +To enable it, use `.spec.sso.dex.groups` field in ArgoCD CR. |
| 70 | + |
| 71 | +For example, below will give allow only users of `foo` & `bar` group to login into Argo CD via Dex. |
| 72 | + |
| 73 | +```yaml |
| 74 | +apiVersion: argoproj.io/v1alpha1 |
| 75 | +kind: ArgoCD |
| 76 | +metadata: |
| 77 | + name: <argocd-instance-name> |
| 78 | +spec: |
| 79 | + sso: |
| 80 | + provider: dex |
| 81 | + dex: |
| 82 | + openShiftOAuth: true |
| 83 | + groups: |
| 84 | + - foo |
| 85 | + - bar |
| 86 | +``` |
| 87 | + |
| 88 | +## Argo CD RBAC Policies for Dex |
| 89 | + |
| 90 | +#### Default access |
| 91 | + |
| 92 | +For versions upto and not including v1.10, |
| 93 | + |
| 94 | +- any user (except `kube:admin`) logged into Argo CD using Dex will be a **read-only** user by default. |
| 95 | + |
| 96 | + `policy.default: role:readonly` |
| 97 | + |
| 98 | +For versions starting v1.10 and above, |
| 99 | + |
| 100 | +- any user (except `kube:admin`) logged into the default Argo CD instance `openshift-gitops` in namespace `openshift-gitops` will have **no access** by default. |
| 101 | + |
| 102 | + `policy.default: ''` |
| 103 | +
|
| 104 | +- any user logged into user managed custom Argo CD instance will have **read-only** access by default. |
| 105 | +
|
| 106 | + `policy.default: 'role:readonly'` |
| 107 | + |
| 108 | +This default behavior can be modified by updating the `.spec.rbac.defaultyPolicy` in ArgoCD CR. |
| 109 | + |
| 110 | +```yaml |
| 111 | +apiVersion: argoproj.io/v1alpha1 |
| 112 | +kind: ArgoCD |
| 113 | +metadata: |
| 114 | + name: <argocd-instance-name> |
| 115 | +spec: |
| 116 | + rbac: |
| 117 | + defaultyPolicy: 'role:readonly' |
| 118 | +``` |
| 119 | + |
| 120 | +A detailed information on basic role policies can be found [here](https://argo-cd.readthedocs.io/en/stable/operator-manual/rbac/#basic-built-in-roles). |
| 121 | + |
| 122 | +#### Group Level Access |
| 123 | + |
| 124 | +Dex reads the group information of OpenShift users. This allows admin to configure rbac at group level using group name. `.spec.rbac.policy` in ArgoCD CR can be used to add group level rbac policies. |
| 125 | + |
| 126 | +For example, below will give admin level access to all the users from `foo-admins` OpenShift group. |
| 127 | + |
| 128 | +```yaml |
| 129 | +apiVersion: argoproj.io/v1alpha1 |
| 130 | +kind: ArgoCD |
| 131 | +metadata: |
| 132 | + name: <argocd-instance-name> |
| 133 | +spec: |
| 134 | + rbac: |
| 135 | + policy.csv: | |
| 136 | + g, foo-admins, role:admin |
| 137 | +``` |
| 138 | + |
| 139 | +More information regarding Argo CD RBAC can be found [here](https://argo-cd.readthedocs.io/en/stable/operator-manual/rbac/). |
| 140 | + |
| 141 | +#### User Level Access |
| 142 | + |
| 143 | +Admin can control access at individual user level by adding rbac configurations under `.spec.rbac.policy` in ArgoCD CR. |
| 144 | + |
| 145 | +> **Important** |
| 146 | +It is not recommended to use user level RBAC with OpenShift login as it poses security risk. Refer [this](https://github.com/argoproj/argo-cd/discussions/8160#discussioncomment-1975554) discussion for more details. |
| 147 | + |
| 148 | +For example, below will give admin level access to a user with email `foo@example.com` & user with username `bar` |
| 149 | + |
| 150 | +```yaml |
| 151 | +apiVersion: argoproj.io/v1alpha1 |
| 152 | +kind: ArgoCD |
| 153 | +metadata: |
| 154 | + name: <argocd-instance-name> |
| 155 | +spec: |
| 156 | + rbac: |
| 157 | + policy.csv: | |
| 158 | + g, foo@example.com, role:admin |
| 159 | + g, bar, role:admin |
| 160 | + scopes: '[groups,name,email]' |
| 161 | +``` |
| 162 | + |
| 163 | +More information regarding Argo CD RBAC can be found [here](https://argo-cd.readthedocs.io/en/stable/operator-manual/rbac/). |
| 164 | + |
| 165 | +## Dex Resource requests/limits |
| 166 | + |
| 167 | +Dex container by default gets created with following resource requests and limits. |
| 168 | + |
| 169 | +|Resource|Requests|Limits |
| 170 | +|:-:|:-:|:-:| |
| 171 | +|CPU|250m|500m| |
| 172 | +|Memory|128 Mi|256 Mi| |
| 173 | + |
| 174 | +Admin can modify the Dex resource requests/limits by updating `.spec.sso.dex.resources` field in ArgoCD CR. |
| 175 | + |
| 176 | +```yaml |
| 177 | +apiVersion: argoproj.io/v1alpha1 |
| 178 | +kind: ArgoCD |
| 179 | +metadata: |
| 180 | + name: <argocd-instance-name> |
| 181 | +spec: |
| 182 | + sso: |
| 183 | + provider: dex |
| 184 | + dex: |
| 185 | + resources: |
| 186 | + requests: |
| 187 | + cpu: 512m |
| 188 | + memory: 512Mi |
| 189 | + limits: |
| 190 | + cpu: 1024m |
| 191 | + memory: 1024Mi |
| 192 | +``` |
| 193 | + |
| 194 | +## Uninstall |
| 195 | + |
| 196 | +**NOTE:** `DISABLE_DEX` environment variable & `.spec.dex` fields are no longer supported in OpenShift GitOps v1.10 onwards. Please use `.spec.sso.provider` to enable/disable Dex. |
| 197 | + |
| 198 | +Dex can be uninstalled either by removing `.spec.sso` from the Argo CD CR, or switching to a different SSO provider. |
| 199 | + |
| 200 | +```bash |
| 201 | +oc -n <namespace> patch argocd <argocd-instance-name> --type json -p='[{"op": "remove", "path": "/spec/sso"}]' |
| 202 | +``` |
| 203 | + |
| 204 | +Or |
| 205 | + |
| 206 | +```yaml |
| 207 | +apiVersion: argoproj.io/v1alpha1 |
| 208 | +kind: ArgoCD |
| 209 | +metadata: |
| 210 | + name: <argocd-instance-name> |
| 211 | +spec: |
| 212 | + sso: {} |
| 213 | +``` |
0 commit comments