Dex Okta Connector

This guide shows how to connect Argo CD to an external identity provider (IdP) — Okta — using Dex as a SAML connector. The full flow:

Create users and group(s) in Okta.
Create a SAML application in Okta and capture the SSO URL and X.509 certificate.
Add a Dex SAML connector configuration into the Argo CD ConfigMap (argocd-cm).
Map Okta group(s) to Argo CD RBAC roles in argocd-rbac-cm.

By default Argo CD uses local username/password authentication. This walkthrough configures Argo CD to use Okta SAML via Dex for Single Sign-On (SSO).

A browser screenshot of the Argo CD documentation site showing an "Okta" / "SAML (with Dex)" setup guide, with a left navigation menu of topics and the main content area containing instructions and screenshots.

Quick reference: Steps and resources

Step	Purpose	Reference
Create Okta org & users	Provision users/groups for Argo CD access	Okta Developer Docs
Create SAML app in Okta	Generate Identity Provider SSO URL and X.509 cert	Okta Admin → Applications → Create App Integration → SAML 2.0
Configure Dex in Argo CD	Add `dex.config` to `argocd-cm` with SAML connector	See `dex.config` example below
Map groups to roles	Add `policy.csv` to `argocd-rbac-cm`	See RBAC example below

Creating an Okta org and users

Use an Okta trial org for evaluation if needed. Sign in to the Okta Admin dashboard.
Create the users who will access Argo CD (e.g., Alice, John).
Create a group (e.g., argocd-developers) and add the users to that group. This group will be mapped to an Argo CD role.

A screenshot of the Okta admin dashboard web interface showing an Overview panel with users, groups and SSO apps and a Status panel. The left navigation menu and sections for Tasks, Org changes, and Security Monitoring (33% complete) are also visible.

Create user accounts (example)

In Okta Admin → Directory → People, create user accounts for each person who needs Argo CD access (e.g., Alice and John).

A screenshot of the Okta admin console showing the "People" directory. The main panel lists two user accounts with their email/status columns and action buttons, while a navigation sidebar appears on the left.

Create a group and add members

Create a group such as argocd-developers and add the demo users. This group name will be used in RBAC mapping within Argo CD.

A screenshot of the Okta admin console open to the "argocd-developers" group page. The page shows a list of group members with their status and standard navigation/actions on the left and top.

Create the Okta SAML application

In Okta Admin → Applications → Create App Integration → SAML 2.0.
Name the app (e.g., “ArgoCD Okta App”). Optionally hide the icon from users.
In SAML settings set:
- Assertion Consumer Service (ACS) / Single sign-on URL
- Audience URI (SP Entity ID) These values are derived from Argo CD’s Dex endpoint (your Argo CD server URL + Dex callback).
Add Attribute Statements (claims) and Group Attribute Statements so Dex can read attributes such as email and group membership.

A screenshot of the Okta admin dashboard on the "Create SAML Integration" page showing SAML Settings fields. The form includes inputs like Single sign-on URL, Audience URI, Name ID format, and application username.

Typical attribute mapping advice

Okta attribute	Maps to Dex attribute
`user.email`	`email` (`emailAttr` / `usernameAttr`)
`groups` or filtered groups (e.g., `argocd-*`)	`groups` (`groupsAttr`)

Use Attribute Statements in the SAML app like:

Name: email → Value: user.email
Name: groups → Value: groups (or a filtered expression to only send argocd-* groups)

A screenshot of the Okta admin console on the SAML app settings page, showing Attribute Statements and Group Attribute Statements fields (e.g., user.email and a group filter starting with "argocd-"). The left navigation and trial banner are also visible.

Assign the application to the group

Assign the SAML application to the argocd-developers group (or specific users) so they can authenticate via this app.

A screenshot of the Okta admin console showing the "Argco Okta App" details on the Assignments tab, with a group ("argocd-developers") assigned. The left sidebar shows navigation options like Dashboard, Directory, and Applications.

Retrieve the SAML configuration from Okta

In the app’s Sign On tab choose “View SAML setup instructions.” Copy the Identity Provider Single Sign-On URL and download (or copy) the X.509 certificate. You will use these values in the Dex connector configuration in Argo CD.

A screenshot of the Okta admin interface showing SAML configuration details for an app, including the Identity Provider Single Sign-On URL, Identity Provider Issuer, and a large X.509 certificate block. A "Download certificate" button is visible below the certificate.

Configure Argo CD’s ConfigMap (argocd-cm) You must add two keys under data: in argocd-cm:

url: — the Argo CD server URL as visible to browser users (include scheme, e.g., https://ui.argocd.example.com).
dex.config: — the Dex YAML configuration containing a SAML connector for Okta.

Example ConfigMap excerpt (only relevant parts shown). Add or update these under data: in the existing argocd-cm:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  # public Argo CD URL (as seen by users)
  url: https://ui.argocd.example.com

  # Dex configuration (SAML connector for Okta)
  dex.config: |
    logger:
      level: debug
      format: json
    connectors:
    - type: saml
      id: okta
      name: Okta
      config:
        # Example SSO URL (replace placeholders below)
        ssoURL: `https://<your-okta-org>.okta.com/app/<your-app-id>/sso/saml`
        # Provide the IdP X.509 certificate (PEM) here. Use a YAML literal block.
        # Paste the certificate content exactly as in the downloaded cert (-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----).
        caData: |
          -----BEGIN CERTIFICATE-----
          MIID...
          -----END CERTIFICATE-----
        # Map attributes expected by Dex
        usernameAttr: email
        emailAttr: email
        groupsAttr: groups

Notes on caData vs ca:

Use caData to paste the PEM certificate directly into the Dex config (recommended for simplicity).
Alternatively, mount a certificate file into the Dex container and set ca to the file path inside the container.
Use either caData or ca, not both.

When pasting the certificate into caData, keep it as PEM (including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines). Avoid convenience tools that may modify the content — paste the raw PEM block.

Embed the certificate from a file (optional) If you prefer to create a PEM file locally and then paste it into caData:

# create okta.crt and paste the PEM contents into it
cat > okta.crt <<'EOF'
-----BEGIN CERTIFICATE-----
MIID...
-----END CERTIFICATE-----
EOF

Then copy the PEM block into the caData: YAML literal block above. Apply / edit the ConfigMap in-cluster:

kubectl -n argocd edit cm argocd-cm

Tip: preserve indentation inside the dex.config: | literal block and validate YAML before saving. Reload/apply behavior

Argo CD watches its ConfigMap and will reconfigure Dex when argocd-cm changes. If the new login option doesn’t appear, restart the Argo CD server:

kubectl -n argocd rollout restart deployment argocd-server

After updating argocd-cm and reloading Dex, the Argo CD login screen will show a SSO button such as “Login with Okta.” Clicking it redirects users to Okta for authentication.

After successful authentication, Argo CD will display the authenticated user’s info (username, issuer, groups). For SAML via Dex, the issuer will typically point to Dex (e.g., /api/dex) instead of the local “argocd” issuer.

A screenshot of a web app "User Info" page showing the username hakaya3596@pahed.com, a highlighted issuer URL, and the group "argocd-developers." The browser window also shows tabs and a left navigation sidebar.

Default RBAC policy and permission denied example

Many Argo CD installs include policy.default: role:readonly in argocd-rbac-cm. New users who authenticate via SAML without explicit RBAC mapping will often be able to log in but lack permission to perform write/sync actions.

A screenshot of the Argo CD web UI displaying application tiles on the left and a "Synchronize" dialog with sync options on the right. A red error toast in the bottom-right reports "Unable to deploy revision: permission denied."

Map Okta groups to Argo CD roles (argocd-rbac-cm) Edit the RBAC ConfigMap and add policy.csv entries that map Okta group names (as received in SAML attributes) to Argo CD roles. Example argocd-rbac-cm excerpt:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
  namespace: argocd
data:
  policy.csv: |-
    p, role:create-repo, repositories, create, *, allow
    p, role:crudApps, applications, *, special-project/*, allow
    g, argocd-developers, role:crudApps
  policy.default: role:readonly

g, <group-name>, <role> associates the external Okta group with an Argo CD role.
The group name must exactly match the value sent by Okta (case-sensitive).

Edit the RBAC ConfigMap:

kubectl -n argocd edit cm argocd-rbac-cm

After saving the updated RBAC config, reattempt the restricted action (e.g., sync). Users in the mapped Okta group should now have the permissions defined by the associated role.

Common troubleshooting tips

Verify url: in argocd-cm matches the exact URL users use to access Argo CD (include https:// if applicable).
Ensure the Okta SAML application is assigned to the correct users/groups.
Confirm attribute names in the Okta SAML app match the usernameAttr, emailAttr, and groupsAttr values in dex.config.
Check argocd-server logs for Dex errors if authentication fails:

kubectl -n argocd logs -l app.kubernetes.io/name=argocd-server -c argocd-server

If the login button does not appear after edits to argocd-cm, restart the server:

kubectl -n argocd rollout restart deployment argocd-server

When editing dex.config or pasting certificates, ensure YAML indentation and line breaks are exact. A malformed YAML block will cause Dex startup/configuration errors — validate YAML or check server logs immediately after applying changes.

Summary

Create the Okta app and groups, capture SSO URL and IdP certificate, configure Dex in argocd-cm, and map Okta group(s) to Argo CD roles in argocd-rbac-cm.
After configuration, Okta users can sign in to Argo CD via SSO and receive permissions mapped from Okta groups.

Links and references

Introduction

GitOps Introduction

ArgoCD Basics

ArgoCD Intermediate

ArgoCD Advanced/Admin

ArgoCD with Jenkins CI Pipeline

Dex Okta Connector

Watch Video

Practice Lab