Skip to main content
This guide explains how to integrate ArgoCD with an external Identity Provider (IDP) such as Okta for user management. By default, ArgoCD uses basic username and password authentication. In this tutorial, you will learn how to configure ArgoCD to use Okta via SAML for Single Sign-On (SSO).

​
Overview of ArgoCD and Okta Integration

First, refer to the ArgoCD documentation on user management to review the supported third-party IDPs, including Okta. In this example, we use Okta with SAML configured through the DEX connector. The documentation provides a detailed guide on creating an Okta application and configuring it within ArgoCD.
The image shows a webpage from the Argo CD documentation, specifically focusing on user management with Okta integration. It includes a section on SAML settings with various configuration options.

​
Creating an Application in Okta

​
1. Access the Okta Admin Dashboard

Log in to your Okta trial account. In the admin space, you can create users, groups, and configure an application for ArgoCD integration.

​
2. Adding Users and Groups

Start by creating a set of users (e.g., “Alice” and “John”) using dummy data for demonstration purposes. Next, add these users to a group such as ArgoCD Developers Group.
The image shows an Okta admin dashboard displaying a list of users with their usernames, primary emails, and statuses. The interface includes options to add a person, reset passwords, and perform more actions.
The image shows an Okta admin dashboard displaying a list of groups, including "argocd-developers," "kia-team," and "Everyone," along with the number of people and applications associated with each group. The interface includes options for searching and adding groups.
For demonstration purposes, we will use the group name ArgoCD-Developers.

​
3. Creating the Okta Application

In the Okta admin console, navigate to the Applications section and create a new app integration. Select SAML 2.0 as the sign-on method.
The image shows an Okta admin dashboard with a focus on the "Applications" section, displaying options to create app integrations and a list of inactive applications.

​
4. Configure SAML Settings in Okta

When prompted, configure the SAML settings with the following details:
  • Single Sign-On URL: Set this to point to your ArgoCD server’s DEX endpoint. For instance, if your ArgoCD URL is https://argocd.example.com, the SSO URL should be: 
    https://argocd.example.com/api/dex
  • Audience URI: Use the same URL as above.
  • Attribute Statements:
    • Username Attribute: user.email
    • Group Attribute: Use a filter like argocd- (to capture groups starting with this string).
The image shows a web interface for creating a SAML integration in Okta, with fields for configuring SAML settings such as Single sign-on URL and Audience URI.
The image shows an Okta admin interface for configuring SAML settings, including options for application username, attribute statements, and group attribute statements. The interface includes a navigation menu on the left and fields for entering specific configuration details.

​
5. Finalize the Application Setup

Complete the configuration by selecting the appropriate customer type (for example, “Okta customer” with an internal application) and click “Finish.” Before moving forward, assign the ArgoCD Developers Group to this application.
The image shows a screenshot of the Okta admin dashboard, specifically the "Sign On" settings page for an application named "Argco Okta App." It includes options for configuring sign-on methods and application username settings.
On the sign-on settings page, click “View SAML Setup Instructions” to retrieve the Identity Provider SSO URL and the X.509 certificate. These details are necessary for the ArgoCD configuration.
The image shows a webpage from Okta with instructions on configuring SAML 2.0 for an application, including details like the Identity Provider Single Sign-On URL, Identity Provider Issuer, and an X.509 Certificate.

​
Configuring ArgoCD with Okta

Update your ArgoCD ConfigMap with both your server URL and the custom DEX connector configuration for Okta.

​
1. Add the ArgoCD Server URL

In your ConfigMap, add the URL for your ArgoCD server: 
data:
  url: https://argocd.example.com

​
2. Configure the DEX Connector for Okta

Below is an example configuration for the Okta SAML connector. Note that you must provide either caData (Base64-encoded certificate data) or ca (a path to the certificate file), but not both. If you experience issues with the redirect URL, consider omitting it. 
dex.config: |
  logger:
    level: debug
    format: json
  connectors:
    - type: saml
      id: okta
      name: Okta
      config:
        ssoURL: https://yourorganization.oktapreview.com/app/yourorganizationsandbox_appnamesaml1/sso/saml
        caData: |
          <CA cert passed through base64 encoding>
        usernameAttr: email
        emailAttr: email
        groupsAttr: group
Be sure to copy the SSO URL from Okta’s setup instructions and insert a Base64 encoded version of the X.509 certificate in the caData field.

​
3. Generating the Base64 Certificate

Generate the Base64 version of your certificate without new lines using the following command in a Linux environment: 
cat okta.crt | base64 | tr -d '\n'
Copy the resulting single-line Base64 string into the caData field.

​
4. Example Final ArgoCD ConfigMap

Below is a complete example of an updated ConfigMap: 
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
  labels:
    app.kubernetes.io/name: argocd-cm
    app.kubernetes.io/part-of: argocd
data:
  url: http://139.59.21.103:30663
  accounts.sid: apiKey_login
  resource.customizations.health.ConfigMap: |
    hs = {}
    hs.status = "Healthy"
    if obj.data.TRIANGLE_COLOR == "white" then
      hs.status = "Degraded"
      hs.message = "Use a different COLOR for TRIANGLE"
    end
    return hs
  dex.config: |
    logger:
      level: debug
      format: json
    connectors:
      - type: saml
        id: okta
        name: Okta
        config:
          ssoURL: https://trial-2498773.okta.com/app/trial-2498773_argcooktaapp_1/exk2ixh7343JYQnw0697/sso/saml
          caData: |
            L5EtS1cJRdTiBDRVJUSUZJQF0tSL0tck1JSURxakNDQX...
          usernameAttr: email
          emailAttr: email
          groupsAttr: group
Ensure that the YAML formatting is preserved when editing your ConfigMap.

​
5. Testing the Integration

After updating the ConfigMap, refresh the ArgoCD UI. A new login option for Okta should appear. Click the Okta login option and you will be redirected to the Okta login page.

​
Logging in with Okta and Verifying Groups

Follow these steps after clicking the Okta login option:

​
1. Okta Login

Enter your Okta username (email) and complete any required multi-factor authentication processes based on your Okta settings.

​
2. Group Verification

After a successful login, your username will appear as the email address from Okta, and if group data is configured, it will be displayed as well. By default, without specific policies, new users might only have read-only permissions.
The image shows an Okta admin dashboard displaying a list of groups, including "argocd-developers," "kia-team," and "Everyone," with details on the number of people and applications associated with each group.

​
Assigning RBAC Policies in ArgoCD

To allow additional permissions based on roles, assign RBAC policies to groups. For example, you may want members of the ArgoCD-Developers group to have the ability to synchronize applications. Modify the RBAC ConfigMap with your desired policies.

​
1. Edit the RBAC ConfigMap

Below is a sample configuration for your RBAC policies: 
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
  namespace: argocd
  labels:
    app.kubernetes.io/name: argocd-rbac-cm
    app.kubernetes.io/part-of: argocd
data:
  policy.csv: |
    p, role:create-repo, repositories, create, *, allow
    p, role:crudApps, applications, *, special-project/*, allow
    g, argocd-developers, role:crudApps
    g, sid, role:create-repo
  policy.default: role:readonly
In this example, users in the argocd-developers group (as configured in Okta) receive full access to applications within a designated special project.
The image shows an Okta admin dashboard displaying a group named "argocd-developers" with two active users listed under the "People" tab.

​
2. Apply the Changes

Save your changes and update the ConfigMaps using the following commands: 
kubectl -n argocd edit cm argocd-cm
kubectl -n argocd edit cm argocd-rbac-cm

​
3. Verify the New Permissions

Once the policies are updated, try synchronizing an application in the special project. If the RBAC policies are correctly configured, the synchronization should complete without permission errors.

​
Conclusion

In this article, we demonstrated how to integrate ArgoCD with Okta using SAML, configure the DEX connector, and assign RBAC policies for managing access. With these settings applied, users can log in via SSO using Okta, and group memberships can effectively control permissions within ArgoCD.
Ensure that your SSO URL and certificate details in the ConfigMap match the values provided in Okta’s SAML setup instructions.
Thank you for reading!

Watch Video

Practice Lab