Added SSO and RBAC (#2503)

README.md

@@ -43,6 +43,7 @@ Organizations below are **officially** using Argo CD. Please send a PR with your
 1. [Tesla](https://tesla.com/)
 1. [tZERO](https://www.tzero.com/)
 1. [Ticketmaster](https://ticketmaster.com)
+1. [Twilio SendGrid](https://sendgrid.com)
 1. [Yieldlab](https://www.yieldlab.de/)
 1. [UBIO](https://ub.io/)
 1. [Volvo Cars](https://www.volvocars.com/)

docs/CONTRIBUTING.md

@@ -1,4 +1,5 @@
 # Contributing
+
 ## Before You Start
 
 You must install and run the ArgoCD using a local Kubernetes (e.g. Docker for Desktop or Minikube) first. This will help you understand the application, but also get your local environment set-up.
@@ -21,14 +22,14 @@ Install:
 * [minikube](https://kubernetes.io/docs/setup/minikube/) or Docker for Desktop
 
 Brew users can quickly install the lot:
-    
+
 ```bash
-brew install go git-lfs kubectl kubectx dep ksonnet/tap/ks kubernetes-helm kustomize kustomize
+brew install go git-lfs kubectl kubectx dep ksonnet/tap/ks kubernetes-helm kustomize
 ```
 
 Check the versions:
 
-```
+```bash
 go version ;# must be v1.12.x
 helm version ;# must be v2.13.x
 kustomize version ;# must be v3.10.x
@@ -84,7 +85,7 @@ kubectl -n argocd scale deployment/argocd-redis --replicas 0
 Download Yarn dependencies and Compile:
 
 ```bash
-~/go/src/github.com/argoproj/argo-cd/ui 
+~/go/src/github.com/argoproj/argo-cd/ui
 yarn install
 yarn build
 ```
@@ -102,7 +103,7 @@ You can now execute `argocd` command against your locally running ArgoCD by appe
 argocd app create guestbook --path guestbook --repo https://github.com/argoproj/argocd-example-apps.git --dest-server https://kubernetes.default.svc  --dest-namespace default --server localhost:8080 --plaintext --insecure
 ```
 
-You can open the UI: http://localhost:4000
+You can open the UI: [http://localhost:4000](http://localhost:4000)
 
 As an alternative to using the above command line parameters each time you call `argocd` CLI, you can set the following environment variables:
 

docs/core_concepts.md

@@ -4,13 +4,13 @@ Let's assume you're familiar with core Git, Docker, Kubernetes, Continuous Deliv
 
 * **Application** A group of Kubernetes resources as defined by a manifest. This is a Custom Resource Definition (CRD).
 * **Application source type** Which **Tool** is used to build the application.
-* **Target state** The desired state of an application, as represented by files in a Git repository. 
+* **Target state** The desired state of an application, as represented by files in a Git repository.
 * **Live state** The live state of that application. What pods etc are deployed.
-* **Sync status** Whether or not the live state matches the target state. Is the deployed application the same as Git says it should be? 
-* **Sync** The process of making an application move to its target state. E.g. by applying changes to a Kubernetes cluster. 
+* **Sync status** Whether or not the live state matches the target state. Is the deployed application the same as Git says it should be?
+* **Sync** The process of making an application move to its target state. E.g. by applying changes to a Kubernetes cluster.
 * **Sync operation status** Whether or not a sync succeeded.
 * **Refresh** Compare the latest code in Git with the live state. Figure out what is different.
-* **Health** The health the application, is it running correctly? Can it serve requests? 
+* **Health** The health the application, is it running correctly? Can it serve requests?
 * **Tool** A tool to create manifests from a directory of files. E.g. Kustomize or Ksonnet. See **Application Source Type**.
 * **Configuration management tool** See **Tool**.
 * **Configuration management plugin** A custom tool.

docs/index.md

@@ -1,12 +1,16 @@
 # Overview
 
+<!-- markdownlint-disable MD026 -->
 ## What Is Argo CD?
+<!-- markdownlint-enable MD026 -->
 
 Argo CD is a declarative, GitOps continuous delivery tool for Kubernetes.
 
 ![Argo CD UI](assets/argocd-ui.gif)
 
+<!-- markdownlint-disable MD026 -->
 ## Why Argo CD?
+<!-- markdownlint-enable MD026 -->
 
 Application definitions, configurations, and environments should be declarative and version controlled.
 Application deployment and lifecycle management should be automated, auditable, and easy to understand.
@@ -31,7 +35,7 @@ the desired application state. Kubernetes manifests can be specified in several
 * [kustomize](https://kustomize.io) applications
 * [helm](https://helm.sh) charts
 * [ksonnet](https://ksonnet.io) applications
-* [jsonnet](https://jsonnet.org) files 
+* [jsonnet](https://jsonnet.org) files
 * Plain directory of YAML/json manifests
 * Any custom config management tool configured as a config management plugin
 
@@ -44,7 +48,6 @@ For a quick 10 minute overview of Argo CD, check out the demo presented to the S
 meeting:
 [![Alt text](https://img.youtube.com/vi/aWDIQMbp1cc/0.jpg)](https://youtu.be/aWDIQMbp1cc?t=1m4s)
 
-
 ## Architecture
 
 ![Argo CD Architecture](assets/argocd_architecture.png)
@@ -82,4 +85,3 @@ For additional details, see [architecture overview](operator-manual/architecture
 ## Development Status
 
 Argo CD is actively developed and is being used in production to deploy SaaS services at Intuit
-

docs/operator-manual/argocd-cm.yaml

@@ -27,7 +27,7 @@ data:
   help.chatText: 'Chat now!'
 
   # A dex connector configuration (optional). See SSO configuration documentation:
-  # https://github.com/argoproj/argo-cd/blob/master/docs/operator-manual/sso.md
+  # https://github.com/argoproj/argo-cd/blob/master/docs/operator-manual/sso
   # https://github.com/dexidp/dex/tree/master/Documentation/connectors
   dex.config: |
     connectors:

docs/operator-manual/declarative-setup.md

@@ -3,6 +3,7 @@
 Argo CD applications, projects and settings can be defined declaratively using Kubernetes manifests.
 
 ## Quick Reference
+
 | Name | Kind | Description |
 |------|------|-------------|
 | [`argocd-cm.yaml`](argocd-cm.yaml) | ConfigMap | General Argo CD configuration |
@@ -47,7 +48,7 @@ See [application.yaml](application.yaml) for additional fields
 
 !!! warning
     By default, deleting an application will not perform a cascade delete, thereby deleting its resources. You must add the finalizer if you want this behaviour - which you may well not want.
-    
+
 ```yaml
 metadata:
   finalizers:
@@ -56,12 +57,13 @@ metadata:
 
 ### App of Apps
 
-You can create an app that creates other apps, which in turn can create other apps. 
+You can create an app that creates other apps, which in turn can create other apps.
 This allows you to declaratively manage a group of app that can be deployed and configured in concert.
 
 See [cluster bootstrapping](cluster-bootstrapping.md).
 
 ## Projects
+
 The AppProject CRD is the Kubernetes resource object representing a logical grouping of applications.
 It is defined by the following key pieces of information:
 
@@ -168,8 +170,7 @@ data:
 ```
 
 !!! tip
-    The Kubernetes documentation has [instructions for creating a secret containing a private key](https://kubernetes.io/docs/concepts/configuration/secret/#use-case-pod-with-ssh-keys). 
-
+    The Kubernetes documentation has [instructions for creating a secret containing a private key](https://kubernetes.io/docs/concepts/configuration/secret/#use-case-pod-with-ssh-keys).
 
 ### Repository Credentials
  
@@ -205,7 +206,7 @@ Argo CD will only use the credentials if you omit `usernameSecret`, `passwordSec
 A credential may be match if it's URL is the prefix of the repository's URL. The means that credentials may match, e.g in the above example both [https://github.com/argoproj](https://github.com/argoproj) and [https://github.com](https://github.com) would match. Argo CD selects the first one that matches.
 
 !!! tip
-    Order your credentials with the most specific at the top and the least specific at the bottom. 
+    Order your credentials with the most specific at the top and the least specific at the bottom.
 
 A complete example.
 
@@ -366,7 +367,7 @@ data:
 ```
 
 !!! note
-    The `argocd-tls-certs-cm` ConfigMap will be mounted as a volume at the mount path `/app/config/tls` in the pods of `argocd-server` and `argocd-repo-server`. It will create files for each data key in the mount path directory, so above example would leave the file `/app/config/tls/server.example.com`, which contains the certificate data. It might take a while for changes in the ConfigMap to be reflected in your pods, depending on your Kubernetes configuration. 
+    The `argocd-tls-certs-cm` ConfigMap will be mounted as a volume at the mount path `/app/config/tls` in the pods of `argocd-server` and `argocd-repo-server`. It will create files for each data key in the mount path directory, so above example would leave the file `/app/config/tls/server.example.com`, which contains the certificate data. It might take a while for changes in the ConfigMap to be reflected in your pods, depending on your Kubernetes configuration.
 
 ### SSH known host public keys
 
@@ -395,8 +396,7 @@ data:
 ```
 
 !!! note
-    The `argocd-ssh-known-hosts-cm` ConfigMap will be mounted as a volume at the mount path `/app/config/ssh` in the pods of `argocd-server` and `argocd-repo-server`. It will create a file `ssh_known_hosts` in that directory, which contains the SSH known hosts data used by ArgoCD for connecting to Git repositories via SSH. It might take a while for changes in the ConfigMap to be reflected in your pods, depending on your Kubernetes configuration. 
-
+    The `argocd-ssh-known-hosts-cm` ConfigMap will be mounted as a volume at the mount path `/app/config/ssh` in the pods of `argocd-server` and `argocd-repo-server`. It will create a file `ssh_known_hosts` in that directory, which contains the SSH known hosts data used by ArgoCD for connecting to Git repositories via SSH. It might take a while for changes in the ConfigMap to be reflected in your pods, depending on your Kubernetes configuration.
 
 ## Clusters
 
@@ -435,7 +435,6 @@ tlsClientConfig:
     serverName: string
 ```
 
-
 Cluster secret example:
 
 ```yaml
@@ -517,7 +516,7 @@ Resources can be excluded from discovery and sync so that ArgoCD is unaware of t
 
 To configure this, edit the `argcd-cm` config map:
 
-```
+```shell
 kubectl edit configmap argocd-cm -n argocdconfigmap/argocd-cm edited
 ```
 
@@ -538,9 +537,9 @@ kind: ConfigMap
 
 The `resource.exclusions` node is a list of objects. Each object can have:
 
-- `apiGroups` A list of globs to match the API group.
-- `kinds` A list of kinds to match. Can be "*" to match all.
-- `cluster` A list of globs to match the cluster.
+* `apiGroups` A list of globs to match the API group.
+* `kinds` A list of kinds to match. Can be "*" to match all.
+* `cluster` A list of globs to match the cluster.
 
 If all three match, then the resource is ignored.
 
@@ -552,13 +551,13 @@ Notes:
 
 ## SSO & RBAC
 
-* SSO configuration details: [SSO](sso.md)
-* RBAC configuration details: [RBAC](rbac.md)
+* SSO configuration details: [SSO](../sso)
+* RBAC configuration details: [RBAC](../rbac)
 
 ## Manage Argo CD Using Argo CD
 
 Argo CD is able to manage itself since all settings are represented by Kubernetes manifests. The suggested way is to create [Kustomize](https://github.com/kubernetes-sigs/kustomize)
-based application which uses base Argo CD manifests from [https://github.com/argoproj/argo-cd] and apply required changes on top.
+based application which uses base Argo CD manifests from [https://github.com/argoproj/argo-cd](https://github.com/argoproj/argo-cd/tree/stable/manifests) and apply required changes on top.
 
 Example of `kustomization.yaml`:
 
@@ -576,8 +575,8 @@ patchesStrategicMerge:
 - overlays/argo-cd-cm.yaml
 ```
 
-The live example of self managed Argo CD config is available at https://cd.apps.argoproj.io and with configuration
+The live example of self managed Argo CD config is available at [https://cd.apps.argoproj.io](https://cd.apps.argoproj.io) and with configuration
 stored at [argoproj/argoproj-deployments](https://github.com/argoproj/argoproj-deployments/tree/master/argocd).
 
 !!! note
-    You will need to sign-in using your github account to get access to https://cd.apps.argoproj.io
+    You will need to sign-in using your github account to get access to [https://cd.apps.argoproj.io](https://cd.apps.argoproj.io)

docs/operator-manual/rbac.md

@@ -1,27 +1,45 @@
-# RBAC
-
-## Overview
+# RBAC Configuration
 
 The RBAC feature enables restriction of access to Argo CD resources. Argo CD does not have its own
 user management system and has only one built-in user `admin`. The `admin` user is a superuser and
-it has unrestricted access to the system. RBAC requires [SSO configuration](./sso.md). Once SSO is
+it has unrestricted access to the system. RBAC requires [SSO configuration](sso/index.md). Once SSO is
 configured, additional RBAC roles can be defined, and SSO groups can man be mapped to roles.
 
-## Configure RBAC
+## Basic Built-in Roles
 
-RBAC configuration allows defining roles and groups. Argo CD has two pre-defined roles:
+Argo CD has two pre-defined roles but RBAC configuration allows defining roles and groups (see below).
 
 * `role:readonly` - read-only access to all resources
 * `role:admin` - unrestricted access to all resources
 
-These role definitions can be seen in [builtin-policy.csv](https://github.com/argoproj/argo-cd/blob/master/assets/builtin-policy.csv)
+These default built-in role definitions can be seen in [builtin-policy.csv](https://github.com/argoproj/argo-cd/blob/master/assets/builtin-policy.csv)
+
+### RBAC Permission Structure
+
+Breaking down the permissions definition differs slightly between applications and every other resource type in Argo CD.
+
+* All resources *except* applications permissions (see next bullet):
+
+    `p, <role/user/group>, <resource>, <action>, <object>`
+
+* Applications (which belong to an AppProject):
+
+    `p, <role/user/group>, <resource>, <action>, <appproject>/<object>`
+
+### RBAC Resources and Actions
+
+Resources: `clusters`, `projects`, `applications`, `repositories`, `certificates`
+
+Actions: `get`, `create`, `update`, `delete`, `sync`, `override`, `action`
+
+## Tying It All Together
 
 Additional roles and groups can be configured in `argocd-rbac-cm` ConfigMap. The example below
 configures a custom role, named `org-admin`. The role is assigned to any user which belongs to
 `your-github-org:your-team` group. All other users get the default policy of `role:readonly`,
 which cannot modify Argo CD settings.
 
-*ConfigMap `argocd-rbac-cm` example:*
+*ArgoCD ConfigMap `argocd-rbac-cm` Example:*
 
 ```yaml
 apiVersion: v1
@@ -41,8 +59,24 @@ data:
 
     g, your-github-org:your-team, role:org-admin
 ```
+----
+
+Another `policy.csv` example might look as follows:
+
+```csv
+p, role:staging-db-admins, applications, create, staging-db-admins/*, allow
+p, role:staging-db-admins, applications, delete, staging-db-admins/*, allow
+p, role:staging-db-admins, applications, get, staging-db-admins/*, allow
+p, role:staging-db-admins, applications, override, staging-db-admins/*, allow
+p, role:staging-db-admins, applications, sync, staging-db-admins/*, allow
+p, role:staging-db-admins, applications, update, staging-db-admins/*, allow
+p, role:staging-db-admins, projects, get, staging-db-admins, allow
+g, db-admins, role:staging-db-admins
+```
+
+This example defines a *role* called `staging-db-admins` with *seven permissions* that allow that role to perform the *actions* (`create`/`delete`/`get`/`override`/`sync`/`update` applications, and `get` appprojects) against `*` (all) objects in the `staging-db-admins` Argo CD AppProject.
 
 ## Anonymous Access
 
-The anonymous access to Argo CD can be enabled using `users.anonymous.enabled` field in `argocd-cm` (see [./argocd-cm.yaml](argocd-cm.yaml)).
-The anonymous users get default role permissions specified by `policy.default` in `argocd-rbac-cm.yaml. For read-only access you'll want `policy.default: role:readonly` as above
+The anonymous access to Argo CD can be enabled using `users.anonymous.enabled` field in `argocd-cm` (see [argocd-cm.yaml](argocd-cm.yaml)).
+The anonymous users get default role permissions specified by `policy.default` in `argocd-rbac-cm.yaml`. For read-only access you'll want `policy.default: role:readonly` as above

docs/operator-manual/security.md

@@ -4,7 +4,6 @@ Argo CD has undergone rigourous internal security reviews and penetration testin
 compliance](https://www.pcisecuritystandards.org) requirements. The following are some security
 topics and implementation details of Argo CD.
 
-
 ## Authentication
 
 Authentication to Argo CD API server is performed exclusively using [JSON Web Tokens](https://jwt.io)
@@ -27,21 +26,18 @@ in one of the following ways:
    JWTs have a configurable expiration and can be immediately revoked by deleting the JWT reference
    ID from the project role.
 
-
 ## Authorization
 
 Authorization is performed by iterating the list of group membership in a user's JWT groups claims,
-and comparing each group against the roles/rules in the [RBAC](rbac.md) policy. Any matched rule
+and comparing each group against the roles/rules in the [RBAC](../rbac) policy. Any matched rule
 permits access to the API request.
 
-
 ## TLS
 
 All network communication is performed over TLS including service-to-service communication between
 the three components (argocd-server, argocd-repo-server, argocd-application-controller). The Argo CD
 API server can enforce the use of TLS 1.2 using the flag: `--tlsminversion 1.2`.
 
-
 ## Sensitive Information
 
 ### Secrets
@@ -79,15 +75,16 @@ cluster, and remove the cluster entry from Argo CD:
 
 ```bash
 # run using a kubeconfig for the externally managed cluster
-kubectl delete sa argocd-manager -n kube-system 
+kubectl delete sa argocd-manager -n kube-system
 kubectl delete clusterrole argocd-manager-role
 kubectl delete clusterrolebinding argocd-manager-role-binding
 argocd cluster rm https://your-kubernetes-cluster-addr
 ```
-
+<!-- markdownlint-disable MD027 -->
 > NOTE: for AWS EKS clusters, [aws-iam-authenticator](https://github.com/kubernetes-sigs/aws-iam-authenticator)
   is used to authenticate to the external cluster, which uses IAM roles in lieu of locally stored
   tokens, so token rotation is not needed, and revokation is handled through IAM.
+<!-- markdownlint-enable MD027 -->
 
 ## Cluster RBAC
 
@@ -110,7 +107,7 @@ To fine-tune privileges of externally managed clusters, edit the ClusterRole of
 kubectl edit clusterrole argocd-manager-role
 ```
 
-To fine-tune privileges which Argo CD has against its own cluster (i.e. https://kubernetes.default.svc),
+To fine-tune privileges which Argo CD has against its own cluster (i.e. `https://kubernetes.default.svc`),
 edit the following cluster roles where Argo CD is running in:
 
 ```bash
@@ -120,7 +117,7 @@ kubectl edit clusterrole argocd-application-controller
 ```
 
 !!! tip
-    If you want to deny ArgoCD access to a kind of resource then add it as an [excluded resource](declarative-setup.md#resource-exclusion). 
+    If you want to deny ArgoCD access to a kind of resource then add it as an [excluded resource](declarative-setup.md#resource-exclusion).
 
 ## Auditing
 
@@ -150,7 +147,6 @@ These events can be then be persisted for longer periods of time using other too
 [Event Exporter](https://github.com/GoogleCloudPlatform/k8s-stackdriver/tree/master/event-exporter) or
 [Event Router](https://github.com/heptiolabs/eventrouter).
 
-
 ## WebHook Payloads
 
 Payloads from webhook events are considered untrusted. Argo CD only examines the payload to infer
@@ -158,7 +154,6 @@ the involved applications of the webhook event (e.g. which repo was modified), t
 the related application for reconciliation. This refresh is the same refresh which occurs regularly
 at three minute intervals, just fast-tracked by the webhook event.
 
-
 ## Reporting Vulnerabilities
 
 Please report security vulnerabilities by e-mailing:

docs/operator-manual/sso/auth0.md

@@ -0,0 +1,8 @@
+# Auth0
+
+!!! note "Are you using this? Please contribute!"
+    If you're using this IdP please consider [contributing](../../developer-guide/site.md) to this document.
+
+<!-- markdownlint-disable MD033 -->
+<div style="text-align:center"><img src="../../../assets/argo.png" /></div>
+<!-- markdownlint-enable MD033 -->

docs/operator-manual/sso/index.md

@@ -1,16 +1,14 @@
-# SSO Configuration
-
-## Overview
+# SSO Overview
 
 Argo CD does not have any local users other than the built-in `admin` user. All other users are
 expected to login via SSO. There are two ways that SSO can be configured:
 
-* Bundled Dex OIDC provider - use this option if your current provider does not support OIDC (e.g. SAML,
+* [Bundled Dex OIDC provider](#dex) - use this option if your current provider does not support OIDC (e.g. SAML,
   LDAP) or if you wish to leverage any of Dex's connector features (e.g. the ability to map GitHub
   organizations and teams to OIDC groups claims).
 
-* Existing OIDC provider - use this if you already have an OIDC provider which you are using (e.g.
-  Okta, OneLogin, Auth0, Microsoft), where you manage your users, groups, and memberships.
+* [Existing OIDC provider](#existing-oidc-provider) - use this if you already have an OIDC provider which you are using (e.g.
+  [Okta](okta.md), [OneLogin](onelogin.md), [Auth0](auth0.md), [Microsoft](microsoft.md)), where you manage your users, groups, and memberships.
 
 ## Dex
 
@@ -26,14 +24,14 @@ steps should be similar for other identity providers.
 ### 1. Register the application in the identity provider
 
 In GitHub, register a new application. The callback address should be the `/api/dex/callback`
-endpoint of your Argo CD URL (e.g. https://argocd.example.com/api/dex/callback).
+endpoint of your Argo CD URL (e.g. `https://argocd.example.com/api/dex/callback`).
 
-![Register OAuth App](../assets/register-app.png "Register OAuth App")
+![Register OAuth App](../../assets/register-app.png "Register OAuth App")
 
 After registering the app, you will receive an OAuth2 client ID and secret. These values will be
 inputted into the Argo CD configmap.
 
-![OAuth2 Client Config](../assets/oauth2-config.png "OAuth2 Client Config")
+![OAuth2 Client Config](../../assets/oauth2-config.png "OAuth2 Client Config")
 
 ### 2. Configure Argo CD for SSO
 
@@ -43,7 +41,7 @@ Edit the argocd-cm configmap:
 kubectl edit configmap argocd-cm -n argocd
 ```
 
-* In the `url` key, input the base URL of Argo CD. In this example, it is https://argocd.example.com
+* In the `url` key, input the base URL of Argo CD. In this example, it is `https://argocd.example.com`
 * In the `dex.config` key, add the `github` connector to the `connectors` sub field. See Dex's
   [GitHub connector](https://github.com/coreos/dex/blob/master/Documentation/connectors/github.md)
   documentation for explanation of the fields. A minimal config should populate the clientID,
@@ -86,14 +84,11 @@ NOTES:
 
 * Any values which start with '$' will look to a key in argocd-secret of the same name (minus the $),
   to obtain the actual value. This allows you to store the `clientSecret` as a kubernetes secret.
-    * If you are editing the secret using `kubectl edit secret` remember that the `data` field expects a base64 encoded value (`echo -n "<CLIENT_SECRET>" | base64`).
-    * The error: *Failed to authenticate: github: get user: github: get URL Get https://api.github.com/user: oauth2: token expired and refresh token is not set* can be attributed to the secret value not being interpreted correctly by dex (e.g. incorrect client secret value).
 * There is no need to set `redirectURI` in the `connectors.config` as shown in the dex documentation.
   Argo CD will automatically use the correct `redirectURI` for any OAuth2 connectors, to match the
-  correct external callback URL (e.g. https://argocd.example.com/api/dex/callback)
+  correct external callback URL (e.g. `https://argocd.example.com/api/dex/callback`)
 
-
-## Existing OIDC Provider 
+## Existing OIDC Provider
 
 To configure Argo CD to delegate authenticate to your existing OIDC provider, add the OAuth2
 configuration to the `argocd-cm` ConfigMap under the `oidc.config` key:

docs/operator-manual/sso/microsoft.md

@@ -0,0 +1,8 @@
+# Microsoft
+
+!!! note "Are you using this? Please contribute!"
+    If you're using this IdP please consider [contributing](../../developer-guide/site.md) to this document.
+
+<!-- markdownlint-disable MD033 -->
+<div style="text-align:center"><img src="../../../assets/argo.png" /></div>
+<!-- markdownlint-enable MD033 -->

docs/operator-manual/sso/okta.md

@@ -0,0 +1,80 @@
+# Okta
+
+!!! note "Are you using this? Please contribute!"
+    If you're using this IdP please consider [contributing](../../developer-guide/site.md) to this document.
+
+A working Single Sign-On configuration using Okta via at least two methods was achieved using:
+
+* [SAML (with Dex)](#saml-with-dex)
+* [OIDC (without Dex)](#oidc-without-dex)
+
+## SAML (with Dex)
+
+1. Create a new SAML application in Okta UI.
+    * ![Okta SAML App 1](../../assets/saml-1.png)
+        I've disabled `App Visibility` because Dex doesn't support Provider-initated login flows.
+    * ![Okta SAML App 2](../../assets/saml-2.png)
+1. Click `View setup instructions` after creating the application in Okta.
+    * ![Okta SAML App 3](../../assets/saml-3.png)
+1. Copy the SSO URL to the `argocd-cm` in the data.oicd
+1. Download the CA certificate to use in the `argocd-cm` configuration.
+    * ![Okta SAML App 4](../../assets/saml-4.png)
+1. Edit the `argocd-cm` and configure the `data.dex.config` section:
+
+<!-- markdownlint-disable MD046 -->
+```yaml
+dex.config: |
+  logger:
+    level: debug
+    format: json
+  connectors:
+  - type: saml
+    id: okta
+    name: Okta
+    config:
+      ssoURL: https://yourorganization.oktapreview.com/app/yourorganizationsandbox_appnamesaml_2/rghdr9s6hg98s9dse/sso/saml
+      # You need `caData` _OR_ `ca`, but not both.
+      caData: |
+        <base64 encoded CA cert>
+      # You need `caData` _OR_ `ca`, but not both.
+      ca: /path/to/ca.pem
+      redirectURI: https://ui.argocd.yourorganization.net/api/dex/callback
+      usernameAttr: email
+      emailAttr: email
+      groupsAttr: group
+```
+<!-- markdownlint-enable MD046 -->
+
+----
+
+## OIDC (without Dex)
+
+!!! warning "Do you want groups for RBAC later?"
+    If you want `groups` scope returned from Okta you need to unforunately contact support to enable [API Access Management with Okta](https://developer.okta.com/docs/concepts/api-access-management/) or [_just use SAML above!_](#saml-with-dex)
+
+    Next you may need the API Access Management feature, which the support team can enable for your OktaPreview domain for testing, to enable "custom scopes" and a separate endpoint to use instead of the "public" `/oauth2/v1/authorize` API Access Management endpoint. This might be a paid feature if you want OIDC unfortunately. The free alternative I found was SAML.
+
+1. On the `Okta Admin` page, navigate to the Okta API Management at `Security > API`.
+    ![Okta API Management](../../assets/api-management.png)
+1. Choose your `default` authorization server.
+1. Click `Scopes > Add Scope`
+    1. Add a scope called `groups`.
+    ![Groups Scope](../../assets/groups-scope.png)
+1. Click `Claims > Add Claim.`
+    1. Add a claim called `groups`
+    1. Choose the matching options you need, one example is:
+        * e.g. to match groups starting with `argocd-` you'd return an `ID Token` using your scope name from step 3 (e.g. `groups`) where the groups name `matches` the `regex` `argocd-.*`
+    ![Groups Claim](../../assets/groups-claim.png)
+1. Edit the `argocd-cm` and configure the `data.oidc.config` section:
+
+<!-- markdownlint-disable MD046 -->
+```yaml
+oidc.config: |
+  name: Okta
+  issuer: https://yourorganization.oktapreview.com
+  clientID: 0oaltaqg3oAIf2NOa0h3
+  clientSecret: ZXF_CfUc-rtwNfzFecGquzdeJ_MxM4sGc8pDT2Tg6t
+  requestedScopes: ["openid", "profile", "email", "groups"].
+  requestedIDTokenClaims: {"groups": {"essential": true}}
+```
+<!-- markdownlint-enable MD046 -->

docs/operator-manual/sso/onelogin.md

@@ -0,0 +1,8 @@
+# OneLogin
+
+!!! note "Are you using this? Please contribute!"
+    If you're using this IdP please consider [contributing](../../developer-guide/site.md) to this document.
+
+<!-- markdownlint-disable MD033 -->
+<div style="text-align:center"><img src="../../../assets/argo.png" /></div>
+<!-- markdownlint-enable MD033 -->

docs/user-guide/helm.md

@@ -30,7 +30,7 @@ argocd app set helm-guestbook -p service.type=LoadBalancer
 
 ## Helm Release Name
 
-By default the Helm release name is equal to the Application name to which it belongs. Sometimes, especially on a centralised ArgoCD, 
+By default the Helm release name is equal to the Application name to which it belongs. Sometimes, especially on a centralised ArgoCD,
 you may want to override that  name, and it is possible with the `release-name` flag on the cli:
 
 ```bash
@@ -46,16 +46,16 @@ source:
 ```
 
 !!! warning "Important notice on overriding the release name"
-    Please note that overriding the Helm release name might cause problems when the chart you are deploying is using the `app.kubernetes.io/instance` label. ArgoCD injects this label with the value of the Application name for tracking purposes. So when overriding the release name, the Application name will stop being equal to the release name. Because ArgoCD will overwrite the label with the Application name it might cause some selectors on the resources to stop working. In order to avoid this we can configure ArgoCD to use another label for tracking in the [ArgoCD configmap argocd-cm.yaml](./../operator-manual/argocd-cm.yaml) - check the lines describing `application.instanceLabelKey`.
+    Please note that overriding the Helm release name might cause problems when the chart you are deploying is using the `app.kubernetes.io/instance` label. ArgoCD injects this label with the value of the Application name for tracking purposes. So when overriding the release name, the Application name will stop being equal to the release name. Because ArgoCD will overwrite the label with the Application name it might cause some selectors on the resources to stop working. In order to avoid this we can configure ArgoCD to use another label for tracking in the [ArgoCD configmap argocd-cm.yaml](../operator-manual/argocd-cm.yaml) - check the lines describing `application.instanceLabelKey`.
 
 ## Helm Hooks
 
 > v1.3 or later
 
 Helm hooks are similar to [Argo CD hooks](resource_hooks.md). In Helm, a hook
-is any normal Kubernetes resource annotated with the `helm.sh/hook` annotation. 
+is any normal Kubernetes resource annotated with the `helm.sh/hook` annotation.
 
-Argo CD supports many (most?) Helm hooks by mapping the Helm annotations onto Argo CD's own hook annotations: 
+Argo CD supports many (most?) Helm hooks by mapping the Helm annotations onto Argo CD's own hook annotations:
 
 | Helm Annotation | Notes |
 |---|---|
@@ -81,12 +81,12 @@ Unsupported hooks are ignored. In Argo CD, hooks are created by using `kubectl a
 
 ### Hook Tips
 
-* Make your hook idempotent. 
+* Make your hook idempotent.
 * Annotate `crd-install` with `hook-weight: "-2"` to make sure it runs to success before any install or upgrade hooks.
 * Annotate  `pre-install` and `post-install` with `hook-weight: "-1"`. This will make sure it runs to success before any upgrade hooks.
 * Annotate `pre-upgrade` and `post-upgrade` with `hook-delete-policy: before-hook-creation` to make sure it runs on every sync.
 
-Read more about [Argo hooks](resource_hooks.md) and [Helm hooks](https://github.com/kubernetes/helm/blob/master/docs/charts_hooks.md). 
+Read more about [Argo hooks](resource_hooks.md) and [Helm hooks](https://github.com/kubernetes/helm/blob/master/docs/charts_hooks.md).
 
 ## Random Data
 
@@ -113,4 +113,3 @@ value, in the values.yaml such that the value is stable between each comparison.
 ```bash
 argocd app set redis -p password=abc123
 ```
-

mkdocs.yml

@@ -26,8 +26,13 @@ nav:
     - operator-manual/architecture.md
     - operator-manual/declarative-setup.md
     - operator-manual/ingress.md
-    - operator-manual/sso.md
-    - operator-manual/rbac.md
+    - Single Sign On (SSO) & Role-Based Access Control (RBAC):
+      - operator-manual/sso/index.md
+      - operator-manual/sso/auth0.md
+      - operator-manual/sso/microsoft.md
+      - operator-manual/sso/okta.md
+      - operator-manual/sso/onelogin.md
+      - operator-manual/rbac.md
     - operator-manual/security.md
     - operator-manual/cluster-bootstrapping.md
     - operator-manual/high_availability.md