How to Establish and Modify Viewer Account on ArgoCD

July 09, 2026 — LiveStream

Ever wondered how to set up a secure, read-only viewer account in ArgoCD for your team, or even integrate it with your existing Single Sign-On (SSO) solution like JumpCloud? This comprehensive guide will walk you through establishing and modifying an ArgoCD viewer account, covering essential configuration map adjustments, robust backup strategies, and critical RBAC settings to streamline your GitOps workflows and enhance security.

ArgoCD, the powerhouse for continuous delivery on Kubernetes, makes managing applications a breeze, isn't it? But, as your team scales, giving everyone full admin access can be, well, a bit risky, yaar. That's where the concept of a viewer account in ArgoCD comes in handy. It’s all about granting least privilege – letting developers, auditors, or even management stakeholders peek into application health and deployment statuses without accidentally breaking anything. Think of it as giving them a window to observe, but no keys to the engine room.

Today, we're going to deep dive into how you can not only establish such an account but also modify its underlying configuration, including setting it up with an external identity provider using SAML, just like our reference example shows for JumpCloud. We'll cover everything from taking proper backups to tweaking Kubernetes ConfigMaps and ensuring your ArgoCD RBAC is locked down tight. So, grab a chai, and let's get cracking!

The ArgoCD Configuration Landscape: Understanding What We're Touching

Before we start making changes, it's crucial to understand the key components of ArgoCD's configuration that we'll be interacting with. In Kubernetes, applications often store their configuration in special objects called ConfigMaps. ArgoCD is no different. The two primary ConfigMaps we'll focus on are:

• argocd-cm: The Core Configuration Map
  This ConfigMap holds the primary operational parameters for your ArgoCD instance. It includes things like the base URL for your ArgoCD server, resource customizations, and, importantly for us today, the definitions for local accounts, including the ArgoCD viewer account. When you see entries like accounts.viewer: apiKey, login, you know this is where you enable a local user account and specify its authentication methods. It can also house configurations for external identity providers, like Dex, which we’ll explore in detail.
• argocd-rbac-cm: The Role-Based Access Control ConfigMap
  This is where the magic of authorization happens. While argocd-cm enables an account, argocd-rbac-cm defines what that account (or any user/group) can actually *do* within ArgoCD. It contains policies that map users or groups to specific roles, granting permissions over applications, projects, and resources. Without proper RBAC configuration here, even if your viewer account is enabled in argocd-cm, it won't be able to see anything! This is a common pitfall, so pay attention, my friend.

We'll also briefly touch upon backing up the argocd-server service manifest, which, while not directly modified for account management, is a good practice for comprehensive disaster recovery.

The Golden Rule: Always Backup Your ArgoCD Configuration First

Any seasoned DevOps engineer will tell you: before you touch anything critical, take a backup. This isn't just good practice; it's non-negotiable, boss. A proper backup ensures that if something goes sideways during your configuration changes – a typo, a misconfigured YAML, anything – you can quickly revert to a known stable state. It’s your safety net. Let's create backups for the relevant ArgoCD configuration objects.

1. Export the Current ArgoCD Configuration

We'll use kubectl get to pull the current state of our ConfigMaps and the argocd-server service, saving them as YAML files. This is like taking a snapshot.

kubectl get cm argocd-cm -oyaml -n argocd > argocd-cm_qa_backup.yaml
kubectl get services argocd-server -o yaml -n argocd > argocd-server_service_qa_backup.yaml
kubectl get cm argocd-rbac-cm -o yaml -n argocd > argocd-rbac-cm_qa_backup.yaml

A quick note on namespaces: By default, ArgoCD components are often installed in the argocd namespace. Always double-check your installation's namespace to ensure you're targeting the correct resources. The -n argocd flag is crucial here.

2. Verify the Contents of the Backup Files

Once you've run the commands, it's good to verify that the files actually contain the data you expect. A quick cat command will do the trick.

cat argocd-cm_qa_backup.yaml
cat argocd-rbac-cm_qa_backup.yaml

This simple check confirms that your backup files are not empty and contain valid YAML. It might seem basic, but trust me, it can save you from bigger headaches later.

Enabling the Viewer Account in argocd-cm: Your First Step

Now that we have our backups, we can start modifying the argocd-cm to enable the ArgoCD viewer account. This involves creating a new configuration file based on our backup and then making the necessary edits.

1. Create a New Configuration File

It's always better to work on a copy. This way, your original backup remains untouched. We'll use cp for this.

cp -v argocd-cm_qa_backup.yaml argocd-cm_qa_new.yaml

The -v flag gives you verbose output, confirming the copy operation. Nice and clean.

2. Edit the New Configuration File

Open argocd-cm_qa_new.yaml in your favorite editor (nano, vim, VS Code, whatever you prefer). We need to add an entry under the data section to define the viewer account.

Look for the data: section. You might already have other entries there. We're going to add a new line:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
  labels:
    app.kubernetes.io/name: argocd-cm
    app.kubernetes.io/part-of: argocd
  annotations:
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"v1", ... } # This annotation can be removed or ignored for now
data:
  accounts.viewer: apiKey, login # <-- This is the line we're adding/modifying
  # ... other existing data fields ...
  url: https://argo.yourcompany.com # (Example: Your ArgoCD's public URL)
  dex.config: |
    # ... SAML/SSO configuration will go here, as seen in the source ...

Let's break down accounts.viewer: apiKey, login:

• accounts.viewer: This defines a local user account named viewer within ArgoCD. You can, of course, name it something else, but viewer is a standard convention.
• apiKey: This grants the viewer account the ability to generate and use API tokens. This is super useful for programmatic access, scripting, or integrating ArgoCD with other tools. Think CI/CD pipelines needing read-only access to check deployment status.
• login: This enables the viewer account to log into the ArgoCD UI using a username and password. By default, for locally configured accounts, the initial password will be set the first time a user logs in via the UI or can be explicitly set via the argocd CLI.

Important Note: You'll see fields like resourceVersion and uid in the exported YAML. These are Kubernetes internal fields. When you're applying changes, it's generally a good practice to remove these lines from your YAML file. Kubernetes will automatically regenerate them. Leaving them in sometimes causes conflicts, especially if the resource has been modified between your `get` and `apply` operations.

Integrating Identity: SAML/SSO with Dex (The JumpCloud Example)

The provided source snippet shows a much richer argocd-cm example that includes a dex.config section. This is a game-changer, especially for enterprise environments! It indicates that ArgoCD is being configured to use an external identity provider (IdP) via Dex, which is ArgoCD's default OpenID Connect (OIDC) provider.

In our example, the dex.config is set up for SAML integration with JumpCloud. This means instead of managing local ArgoCD passwords, users will authenticate using their existing JumpCloud credentials. This is fantastic for centralized user management, security policies, and providing a seamless single sign-on experience. Ekdum sahi!

Understanding Dex and SAML

• Dex: ArgoCD uses Dex as an authentication proxy. Dex supports various identity connectors, including OIDC, LDAP, SAML, GitHub, etc.
• SAML (Security Assertion Markup Language): An XML-based open standard for exchanging authentication and authorization data between an identity provider (IdP) and a service provider (SP). In our case, JumpCloud is the IdP, and ArgoCD (via Dex) is the SP.

Configuring Dex for SAML (JumpCloud Specifics)

Let's look at the dex.config section from our source and break it down:

data:
  # ... other configs ...
  dex.config: |
    logger:
      level: debug
    connectors:
      - type: saml
        id: jumpcloud
        name: JumpCloud
        config:
          ssoURL: https://sso.jumpcloud.com/saml2/argo
          caData: |
            LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tDQpNSUlGZkRDQ0EyU2dBd0lCQWdJVWF0YXJRaTBlU2ZJcEVtYUFsN0h0RUlYTWt5WXdEUVlKS29aSWh2Y05BUUVMDQpCUUF3QURFTE1Ba0dBMVVFQmhNQ1ZWTXhDekFKQmdOVkJBZ1RBa05QTVJBd0RnWURWUVFIRXdkQ2IzVnNaR1Z5DQpNUk13RVFZRFZRUUtFd3BqYjJ4c2FYbGpiMjlzTVJrd0Z3WURWUVFMRXhCS2RXMXdRMnh2ZFdSVFFVMU1TV1JRDQpNUm93R0FZRFZRUURFeEZLZFcxd1EyeHZkV1JUUVUxTVZYTmxjakFlRncweU16QTJNVFF4T1RFMk16VmFGdzB5DQpPREEyTVRReE9URTJNelZhTUhneEN6QUpCZ05WQkFZVEFsVlRNUXN3Q1FZRFZRUUlFd0pEVHpFUU1BNEdBMVVFDQpCeE1IUW05MWJHUmxjakVUTUJFR0ExVUVDaE1LWTI5c2JHbDVZMjl2YkRFWk1CY0dBMVVFQ3hNUVNuVnRjRU5zDQpiM1ZrVTBGTlRFbGtVREVhTUJnR0ExVUVBeE1SU25WdGNFTnNiM1ZrVTBGTlRGVnpaWEl3Z2dJaU1BMEdDU3FHDQpTSWIzRFFFQkFRVUFBNElDRHdBd2dnSUtBb0lDQVFDb0RydUkvVXB0RlpHU0xDaktXN3ZTSUc5VWEyUzdobGMrDQp5WVU2TUtPQlRTNW9ZTi80M1RKN082N0JIUXpiV2NLUXJtZWxwcVN0U3ZlYUZ4ZHhUeHZJZjFyS2c5b00xMlVHDQpUME1McX... # (truncated for brevity)

• logger.level: debug: This sets the logging level for Dex. Handy for troubleshooting during initial setup, but you might want to switch it to info or warn in production to avoid excessive logs.
• connectors: This is an array where you define one or more identity connectors for Dex.
  • type: saml: Specifies that this connector uses the SAML protocol.
  • id: jumpcloud: A unique identifier for this connector within Dex. ArgoCD will use this ID to refer to this authentication method.
  • name: JumpCloud: The display name that users will see on the ArgoCD login screen (e.g., "Log in with JumpCloud").
  • config: Contains SAML-specific configuration details.
    • ssoURL: This is the Single Sign-On URL provided by your IdP (JumpCloud in this case). When a user clicks "Log in with JumpCloud" on ArgoCD, they will be redirected to this URL for authentication.
    • caData: This is the base64 encoded certificate authority (CA) certificate of your IdP. It's crucial for ArgoCD (Dex) to trust the SAML assertions coming from JumpCloud. You typically obtain this from your IdP's metadata. You'll need to copy the *actual* certificate data (often provided as an X.509 PEM certificate) and base64 encode it, then paste it here, maintaining the proper YAML indentation.

How to get caData: Usually, your IdP (JumpCloud) provides an XML metadata file or a direct link to download its signing certificate. You'll extract the X.509 certificate data (the part between -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----, including these markers) and then use a command like base64 -w 0 on Linux/macOS or online tools to encode it. The -w 0 prevents line wrapping, which is important for inline YAML strings. Thoda dhyan se karna yeh step, boss!

After making these modifications, your argocd-cm_qa_new.yaml should be ready for application.

Defining Permissions: Configuring RBAC for the Viewer Account in argocd-rbac-cm

Enabling the viewer account in argocd-cm is just half the battle. Without defining what permissions that account has, it's just a user without access – like having a library card but no books. This is where argocd-rbac-cm comes in. We need to tell ArgoCD what a "viewer" role can actually do and then assign our viewer account (or a SAML group) to that role.

Recall we took a backup of argocd-rbac-cm. Let's create a new file for modifications:

cp -v argocd-rbac-cm_qa_backup.yaml argocd-rbac-cm_qa_new.yaml

Open argocd-rbac-cm_qa_new.yaml. The core of RBAC in ArgoCD revolves around policies, defined using a syntax similar to Casbin. You'll typically find a data: section with a policy.csv: | key.

1. Define the Viewer Role and its Permissions

We need to add a policy that defines what the role:viewer can do. For a read-only viewer, this usually means get (read) access to applications across all projects.

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
  namespace: argocd
  # ... other metadata ...
data:
  policy.csv: |
    # Existing policies...
    p, role:viewer, applications, get, */*, allow
    p, role:viewer, projects, get, *, allow
    p, role:viewer, clusters, get, *, allow
    p, role:viewer, repositories, get, *, allow
    # Add optional read-only access to logs
    p, role:viewer, applications, logs, */*, allow
    # ... other policies ...
  # ... other data fields ...

Let's break down the viewer policy:

• p: Denotes a policy rule.
• role:viewer: This is the name of our role.
• applications: The resource type this policy applies to (e.g., applications, projects, clusters, repositories, certificates).
• get: The action allowed (e.g., get for read, create, update, delete, sync for write actions).
• */*: The object scope. The first * is for the project, the second * is for the application name. */* means "all applications in all projects." You could restrict this to a specific project like my-dev-project/*.
• allow: The effect of the policy (either allow or deny).

The policies for projects, clusters, and repositories with get, *, allow ensure the viewer can see the configured projects, Kubernetes clusters, and Git repositories, respectively.

2. Assign Users/Groups to the Viewer Role

Now, we need to associate our defined viewer with this role:viewer. This step differs slightly based on whether you're using a local ArgoCD account or an external IdP (SAML).

A. For a Local Viewer Account (enabled in argocd-cm with accounts.viewer: apiKey, login):

ArgoCD automatically maps local users defined in argocd-cm to roles if their username matches. So, the viewer account will automatically be associated with role:viewer if you add:

data:
  policy.csv: |
    # ... existing policies ...
    p, role:viewer, applications, get, */*, allow
    # ... other viewer policies ...
    g, viewer, role:viewer # <-- This maps the 'viewer' account to 'role:viewer'

The g denotes a group (or user) mapping rule:

• g: Denotes a group/user mapping.
• viewer: The username of the local account (which we enabled in argocd-cm).
• role:viewer: The role we want to assign to this user.

B. For SAML/SSO Integration (JumpCloud Example):

If you're using SAML via Dex, you'll likely want to map *groups* from your IdP (JumpCloud) to ArgoCD roles. This is a much more scalable approach. Your IdP will send claims (attributes) about the user during login, including their group memberships. ArgoCD can then use these groups to assign roles.

Assuming JumpCloud sends a group claim (e.g., groups or memberOf) and you have a group named "ArgoCD-Viewers" in JumpCloud, you would map it like this:

data:
  policy.csv: |
    # ... existing policies ...
    p, role:viewer, applications, get, */*, allow
    # ... other viewer policies ...
    g, group:ArgoCD-Viewers, role:viewer # <-- Maps JumpCloud group to ArgoCD role
  # You might also need this for JWT authentication if not already present
  # The format of the 'sub' field depends on your IdP and how Dex processes claims.
  # Check ArgoCD documentation for 'claim.mapping' if your IdP groups are in a different claim.
  # Example: If your SAML group claim is "memberOf" and not "groups"
  # initial.groups: "[ 'ArgoCD-Viewers' ]"

Here, group:ArgoCD-Viewers refers to a group that is passed as a claim by your IdP. When a user logs in via JumpCloud, if they are a member of the "ArgoCD-Viewers" group, they will automatically be granted the role:viewer permissions in ArgoCD. This is super powerful for enterprise-grade authentication, yaar. For SAML, ensuring your Dex configuration (`dex.config`) correctly extracts the group claims from the SAML assertion is key. Sometimes, you might need to specify a `groupsClaim` in your Dex SAML connector configuration for it to pass the correct group information to ArgoCD's RBAC system.

For more advanced RBAC setups, refer to the official ArgoCD RBAC documentation. It's a goldmine of information.

Applying and Verifying Your Changes

Once both argocd-cm_qa_new.yaml and argocd-rbac-cm_qa_new.yaml are edited to your satisfaction, it’s time to apply them to your Kubernetes cluster. This will update the running ArgoCD instance.

1. Apply the Changes to the ArgoCD Configuration

kubectl apply -f argocd-cm_qa_new.yaml -n argocd
kubectl apply -f argocd-rbac-cm_qa_new.yaml -n argocd

The kubectl apply command is idempotent. It will create the resources if they don't exist or update them if they do. For ConfigMaps, changes are usually picked up dynamically by ArgoCD controllers within a minute or two. However, significant changes like modifying dex.config might sometimes require a restart of the argocd-server and argocd-repo-server pods to ensure all components reload the new configuration. You can do this by deleting the pods, and Kubernetes will automatically recreate them:

kubectl rollout restart deployment argocd-server -n argocd
kubectl rollout restart deployment argocd-repo-server -n argocd # Optional, but good for completeness

Monitor the rollout status:

kubectl rollout status deployment argocd-server -n argocd

2. Verify the Configuration and Test Login

After applying, it's critical to verify everything is working as expected.

• Check ConfigMap status:

  kubectl get cm argocd-cm -oyaml -n argocd | grep accounts.viewer
  kubectl get cm argocd-cm -oyaml -n argocd | grep -A 10 "dex.config" # Check SAML config
  kubectl get cm argocd-rbac-cm -oyaml -n argocd | grep "role:viewer" # Verify RBAC policies
  

  This confirms your changes were applied to the live ConfigMap objects.
• Check ArgoCD server logs:

  kubectl logs -f $(kubectl get pod -l app.kubernetes.io/name=argocd-server -o jsonpath='{.items[0].metadata.name}' -n argocd) -n argocd

  Look for any errors related to authentication, Dex, or RBAC loading. If Dex configuration is incorrect, you’ll usually see errors here.
• Attempt to log in as the viewer:
  • For local viewer account: Navigate to your ArgoCD UI. Enter viewer as the username. The first time, it might prompt you to set a password. If not, you might need to use the ArgoCD CLI to set the password:

    argocd account update-password --account viewer --current-password '' --new-password <YOUR_NEW_PASSWORD>

    (Note: --current-password '' is used for setting a password for a newly enabled account).
  • For SAML (JumpCloud) integration: On the ArgoCD login page, you should now see an option like "LOG IN VIA JUMPCLOUD." Click it and authenticate with your JumpCloud credentials. After successful authentication, you should be redirected back to ArgoCD.
• Verify permissions: Once logged in as the viewer, try navigating through applications. You should be able to see application details, sync status, and logs, but you should NOT be able to initiate syncs, delete applications, or modify anything. If you can, your RBAC policy needs adjustment.

Best Practices for Managing ArgoCD Configuration

Configuring ArgoCD is a critical task, and treating its own configuration with GitOps principles is the ultimate best practice.

• GitOps for ArgoCD Itself: Instead of manually applying ConfigMaps with kubectl apply -f, store your argocd-cm.yaml and argocd-rbac-cm.yaml (and any other ArgoCD-related manifests) in a Git repository. Then, use an ArgoCD application (yes, an ArgoCD app deploying ArgoCD's config!) to manage these resources. This way, all changes are version-controlled, reviewed, and automatically applied. This is the true GitOps way, my friend.
• Secret Management: If your dex.config or other ArgoCD configurations require sensitive data (e.g., client secrets for OIDC, private keys), never put them directly in a ConfigMap. Use Kubernetes Secrets, and if possible, encrypt those secrets using tools like SOPS or integration with a secret manager like Vault.
• Testing in Dev/Staging: Always test significant configuration changes in a non-production environment first. This prevents unexpected outages or permission issues in your live systems.
• Regular Backups: Maintain a schedule for backing up your ArgoCD configurations and other vital data. Automate this process if possible.

Troubleshooting Common Viewer Account Issues

Even with careful steps, things can sometimes go wrong. Here are some common issues and how to approach them:

• Viewer cannot log in (Local Account):
  • Check argocd-cm: Ensure accounts.viewer: apiKey, login is correctly present.
  • Password not set: Try setting the password using argocd account update-password.
  • ArgoCD server issues: Check argocd-server logs for authentication errors.
• Viewer cannot log in (SAML/SSO):
  • Check dex.config in argocd-cm:
    • Is ssoURL correct?
    • Is caData correct and properly base64 encoded?
    • Are there any YAML indentation errors?
  • IdP configuration: Verify your ArgoCD (SP) settings in JumpCloud match what Dex expects (e.g., Assertion Consumer Service URL, Entity ID).
  • Dex logs: Check the logs for Dex (which usually runs as part of the argocd-server pod or a dedicated Dex pod if you have a separate installation) for SAML assertion errors, certificate trust issues, or authentication failures.
• Viewer can log in but sees nothing or has too many permissions:
  • Check argocd-rbac-cm:
    • No access: Ensure p, role:viewer, applications, get, */*, allow and similar policies are present and correctly formatted.
    • Too much access: Review all p policies associated with role:viewer. Ensure no unintended write permissions (create, update, delete, sync) are present.
    • User/Group mapping: Verify that the g, viewer, role:viewer (for local) or g, group:YourSAMLGroup, role:viewer (for SAML) rule is correctly applied.
  • Cache issues: Sometimes ArgoCD's RBAC cache needs to clear. Restarting the argocd-server pod can help.
  • SAML Group Claim: For SSO, ensure your IdP is sending the correct group claims and Dex is configured to interpret them, passing them on to ArgoCD's RBAC system.

Key Takeaways

• Always prioritize backups before making any changes to your ArgoCD configuration, especially for critical ConfigMaps.
• The argocd-cm is used to enable the viewer account (e.g., accounts.viewer: apiKey, login) and integrate external identity providers via Dex.
• dex.config within argocd-cm is crucial for setting up SSO using SAML, ensuring proper ssoURL and base64 encoded caData.
• The argocd-rbac-cm defines the actual permissions for the role:viewer and maps users or groups to this role, enforcing the principle of least privilege.
• After applying changes, always verify them by checking ConfigMap contents, reviewing ArgoCD server logs, and performing a test login.

Frequently Asked Questions

What is the primary purpose of an ArgoCD viewer account?

An ArgoCD viewer account is designed to provide read-only access to your ArgoCD instance. It allows users like developers, auditors, or non-technical stakeholders to monitor application deployments, check health statuses, view logs, and inspect configurations without having the ability to modify, sync, or delete applications, thus enhancing security and maintaining GitOps integrity.

How do I set the password for a local ArgoCD viewer account?

When you enable a local viewer account (e.g., accounts.viewer: apiKey, login) in argocd-cm, the password is not set directly in the ConfigMap for security reasons. The first time a user attempts to log in via the ArgoCD UI, they will typically be prompted to set a password. Alternatively, you can explicitly set the password using the ArgoCD CLI command: argocd account update-password --account viewer --current-password '' --new-password <YOUR_NEW_PASSWORD>.

Can I integrate ArgoCD viewer accounts with corporate SSO solutions like Okta, Azure AD, or Google Workspace?

Absolutely! ArgoCD leverages Dex, an OpenID Connect (OIDC) identity provider, which can be configured to connect to various external identity providers using different protocols. As demonstrated, SAML is supported for services like JumpCloud, Okta, and Azure AD. OIDC is another popular option for Google Workspace, Azure AD, and others. The configuration for these integrations resides within the dex.config section of the argocd-cm.

What happens if I forget to configure RBAC for my viewer account?

If you enable an ArgoCD viewer account in argocd-cm but forget to configure appropriate policies and role assignments in argocd-rbac-cm, the viewer account will likely be able to log in but will not see any applications or resources. This is because, by default, users have no permissions until explicitly granted through RBAC policies. It's a security-first approach, where permissions are 'deny by default'.

There you have it, folks! A complete walkthrough on establishing and modifying an ArgoCD viewer account, including the crucial details for SAML/SSO integration and robust RBAC. Implementing these practices will not only improve your security posture but also make your GitOps workflows smoother for everyone involved. If you found this useful, do check out the original video on @explorenystream for a visual guide, and consider subscribing for more insightful DevOps content. Happy deploying!