github.com/argoproj/argo-cd/v2@v2.10.9/docs/operator-manual/user-management/okta.md (about)

     1  # Okta
     2  
     3  !!! note "Are you using this? Please contribute!"
     4      If you're using this IdP please consider [contributing](../../developer-guide/site.md) to this document.
     5  
     6  A working Single Sign-On configuration using Okta via at least two methods was achieved using:
     7  
     8  * [SAML (with Dex)](#saml-with-dex)
     9  * [OIDC (without Dex)](#oidc-without-dex)
    10  
    11  ## SAML (with Dex)
    12  
    13  !!! note "Okta app group assignment"
    14      The Okta app's **Group Attribute Statements** regex will be used later to map Okta groups to Argo CD RBAC roles.
    15  
    16  1. Create a new SAML application in Okta UI.
    17      * ![Okta SAML App 1](../../assets/saml-1.png)
    18          I've disabled `App Visibility` because Dex doesn't support Provider-initiated login flows.
    19      * ![Okta SAML App 2](../../assets/saml-2.png)
    20  1. Click `View setup instructions` after creating the application in Okta.
    21      * ![Okta SAML App 3](../../assets/saml-3.png)
    22  1. Copy the Argo CD URL to the `argocd-cm` in the data.url
    23  
    24  <!-- markdownlint-disable MD046 -->
    25  ```yaml
    26  data:
    27    url: https://argocd.example.com
    28  ```
    29  <!-- markdownlint-disable MD046 -->
    30  
    31  1. Download the CA certificate to use in the `argocd-cm` configuration.
    32      * If you are using this in the caData field, you will need to pass the entire certificate (including `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` stanzas) through base64 encoding, for example, `base64 my_cert.pem`.
    33      * If you are using the ca field and storing the CA certificate separately as a secret, you will need to mount the secret to the `dex` container in the `argocd-dex-server` Deployment.
    34      * ![Okta SAML App 4](../../assets/saml-4.png)
    35  1. Edit the `argocd-cm` and configure the `data.dex.config` section:
    36  
    37  <!-- markdownlint-disable MD046 -->
    38  ```yaml
    39  dex.config: |
    40    logger:
    41      level: debug
    42      format: json
    43    connectors:
    44    - type: saml
    45      id: okta
    46      name: Okta
    47      config:
    48        ssoURL: https://yourorganization.oktapreview.com/app/yourorganizationsandbox_appnamesaml_2/rghdr9s6hg98s9dse/sso/saml
    49        # You need `caData` _OR_ `ca`, but not both.
    50        caData: |
    51          <CA cert passed through base64 encoding>
    52        # You need `caData` _OR_ `ca`, but not both.
    53        # Path to mount the secret to the dex container
    54        ca: /path/to/ca.pem
    55        redirectURI: https://ui.argocd.yourorganization.net/api/dex/callback
    56        usernameAttr: email
    57        emailAttr: email
    58        groupsAttr: group
    59  ```
    60  <!-- markdownlint-enable MD046 -->
    61  
    62  ----
    63  
    64  ### Private deployment
    65  It is possible to setup Okta SSO with a private Argo CD installation, where the Okta callback URL is the only publicly exposed endpoint.
    66  The settings are largely the same with a few changes in the Okta app configuration and the `data.dex.config` section of the `argocd-cm` ConfigMap.
    67  
    68  Using this deployment model, the user connects to the private Argo CD UI and the Okta authentication flow seamlessly redirects back to the private UI URL.
    69  
    70  Often this public endpoint is exposed through an [Ingress object](../../ingress/#private-argo-cd-ui-with-multiple-ingress-objects-and-byo-certificate).
    71  
    72  
    73  1. Update the URLs in the Okta app's General settings
    74      * ![Okta SAML App Split](../../assets/saml-split.png)
    75          The `Single sign on URL` field points to the public exposed endpoint, and all other URL fields point to the internal endpoint.
    76  1. Update the `data.dex.config` section of the `argocd-cm` ConfigMap with the external endpoint reference.
    77  
    78  <!-- markdownlint-disable MD046 -->
    79  ```yaml
    80  dex.config: |
    81    logger:
    82      level: debug
    83    connectors:
    84    - type: saml
    85      id: okta
    86      name: Okta
    87      config:
    88        ssoURL: https://yourorganization.oktapreview.com/app/yourorganizationsandbox_appnamesaml_2/rghdr9s6hg98s9dse/sso/saml
    89        # You need `caData` _OR_ `ca`, but not both.
    90        caData: |
    91          <CA cert passed through base64 encoding>
    92        # You need `caData` _OR_ `ca`, but not both.
    93        # Path to mount the secret to the dex container
    94        ca: /path/to/ca.pem
    95        redirectURI: https://external.path.to.argocd.io/api/dex/callback
    96        usernameAttr: email
    97        emailAttr: email
    98        groupsAttr: group
    99  ```
   100  <!-- markdownlint-enable MD046 -->
   101  
   102  ### Connect Okta Groups to Argo CD Roles
   103  Argo CD is aware of user memberships of Okta groups that match the *Group Attribute Statements* regex.
   104  The example above uses the `argocd-*` regex, so Argo CD would be aware of a group named `argocd-admins`.
   105  
   106  Modify the `argocd-rbac-cm` ConfigMap to connect the `argocd-admins` Okta group to the builtin Argo CD `admin` role.
   107  <!-- markdownlint-disable MD046 -->
   108  ```yaml
   109  apiVersion: v1
   110  kind: ConfigMap
   111  metadata:
   112    name: argocd-rbac-cm
   113  data:
   114    policy.csv: |
   115      g, argocd-admins, role:admin
   116    scopes: '[email,groups]'
   117  ```
   118  
   119  ## OIDC (without Dex)
   120  
   121  !!! warning "Do you want groups for RBAC later?"
   122      If you want `groups` scope returned from Okta you need to unfortunately 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)
   123  
   124      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.
   125  
   126  1. On the `Okta Admin` page, navigate to the Okta API Management at `Security > API`.
   127      ![Okta API Management](../../assets/api-management.png)
   128  1. Choose your `default` authorization server.
   129  1. Click `Scopes > Add Scope`
   130      1. Add a scope called `groups`.
   131      ![Groups Scope](../../assets/groups-scope.png)
   132  1. Click `Claims > Add Claim.`
   133      1. Add a claim called `groups`
   134      1. Choose the matching options you need, one example is:
   135          * 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-.*`
   136      ![Groups Claim](../../assets/groups-claim.png)
   137  1. Edit the `argocd-cm` and configure the `data.oidc.config` section:
   138  
   139  <!-- markdownlint-disable MD046 -->
   140  ```yaml
   141  oidc.config: |
   142    name: Okta
   143    issuer: https://yourorganization.oktapreview.com
   144    clientID: 0oaltaqg3oAIf2NOa0h3
   145    clientSecret: ZXF_CfUc-rtwNfzFecGquzdeJ_MxM4sGc8pDT2Tg6t
   146    requestedScopes: ["openid", "profile", "email", "groups"]
   147    requestedIDTokenClaims: {"groups": {"essential": true}}
   148  ```
   149  <!-- markdownlint-enable MD046 -->
   150  
   151