OpenShift clusters (including single-node deployments) come with a default kubeadmin user for initial access, but no regular user accounts by default. To allow developers or admins to log in with their own credentials, you can set up an HTPasswd identity provider. This approach uses a simple file with usernames and hashed passwords (an htpasswd file) for authentication. It’s convenient for lab or demo environments, though not recommended for production use.

In this step-by-step guide, we will configure HTPasswd authentication on an existing OpenShift 4.15+ single-node cluster. We’ll create user accounts, update the cluster’s OAuth settings to use HTPasswd, and verify access via both the CLI and the web console. We’ll also cover how to assign admin privileges to a new user and remove the default kubeadmin user for security.

Overview: At a high level, the process involves: (1) creating an htpasswd file with one or more user credentials, (2) creating a Kubernetes Secret from that file, (3) updating the cluster’s OAuth configuration to add the HTPasswd identity provider, and (4) testing logging in with the new user.

Prerequisites

• OpenShift Cluster Access: You need a running OpenShift 4.15+ single-node cluster with cluster-admin access (initially via the kubeadmin user). Ensure you can log in as kubeadmin (e.g. run oc whoami and confirm it prints “kubeadmin”).
• OC CLI: Install the OpenShift CLI (oc) and make sure it’s in your PATH.
• htpasswd Utility: Install the htpasswd command-line tool to manage the credentials file. For example, on Red Hat-based Linux systems install the httpd-tools package (e.g. sudo yum install httpd-tools), on Ubuntu/Debian install apache2-utils, and on macOS use Homebrew (brew install httpd). Ensure the htpasswd command is available.

---

Step 1: Create an HTPasswd File with User Accounts

First, generate an htpasswd file that will store the usernames and passwords for the users you want to add. Each line in this file will be of the form username:hashed_password. We will use the htpasswd utility (part of Apache httpd tools) to create this file and hash the passwords.

1. Choose a filename and location. Decide where to store your htpasswd file (for example, in your home directory or another secure location). In this guide, we will create a file named users.htpasswd in the current directory.

2. Create the first user account in the htpasswd file. Use the htpasswd command with the -c flag (to create a new file) and -B (to use bcrypt hashing) to add the first user. The -b option lets you supply the password inline (you can omit -b to be prompted for the password interactively). For example, to create a user alice with password StrongPass1:

htpasswd -c -B -b users.htpasswd alice StrongPass1

This command creates the users.htpasswd file (because of -c) and adds an entry for alice with an encrypted password. The output “Adding password for user alice” confirms the entry was added.

3. Add additional users (if needed). To append more users to the same file, run htpasswd without the -c flag (so that it doesn’t overwrite the file). For example, to add a second user bob with password SecretPass2:

htpasswd -B -b users.htpasswd bob SecretPass2

This appends bob’s credentials to the existing users.htpasswd file. Again, you should see the confirmation “Adding password for user bob”. Repeat this step for any other users you need to create. Each user will have their own line in the file.

4. (Optional) Verify the file contents. You can open or cat the htpasswd file to ensure both users are listed (the passwords will be hashed, not in clear text). For example:

$ cat users.htpasswd
alice:$2y$05$fs2oIkCWUmL9ylfTlO2EZO1XecpdrPbm6CUvgXgGwdhveF7VCvbRO
bob:$2y$05$eY9E9dfJNcouMh/UiJZk5.sDjv2s1oxXoSEzFytZVEma.XCGFAIHC

Each line contains a username and a bcrypt-hashed password. If the entries are present, the file is ready to use.

Note: Be careful with the -c option. Using htpasswd -c always creates a new file, so if the file already exists, the -c flag will truncate and replace it. Use -c only for the initial creation of the file. For adding or updating users later, omit -c to avoid overwriting the existing file. Also, ensure you have the htpasswd tool installed before running these commands.

Step 2: Create a Secret from the HTPasswd File

OpenShift uses a Kubernetes Secret to hold the htpasswd file. We need to create a secret in the openshift-config namespace containing our users.htpasswd file. The OpenShift OAuth server will read this secret to perform authentication.

Run the following command to create a generic secret named htpass-secret (you can choose a different name, but we’ll use this convention) with the htpasswd file data:

oc create secret generic htpass-secret \
 --from-file=htpasswd=users.htpasswd \
 -n openshift-config

Output:

secret/htpass-secret created

Here, the –from-file=htpasswd=users.htpasswd flag tells OpenShift to take the file users.htpasswd and store it in the secret with the key htpasswd. We create the secret in the openshift-config project, which is where the OAuth server expects to find it. The output confirms the secret creation.

You can double-check that the secret contains the expected data (optional step) by extracting it and viewing the content:

oc extract secret/htpass-secret -n openshift-config --to=-
# users.htpasswd
alice:$2y$05$fs2oIkCWUmL9ylfTlO2EZO1XecpdrPbm6CUvgXgGwdhveF7VCvbRO
bob:$2y$05$eY9E9dfJNcouMh/UiJZk5.sDjv2s1oxXoSEzFytZVEma.XCGFAIHC

This command prints the contents of the secret to stdout (the –to=- flag), and you should see the entries for alice and bob that you added, with their hashed passwords. This sanity check confirms the secret was created correctly with the right data.

Note: The secret key must be named htpasswd – this is the key that the OAuth server looks for in the secret. In our command above, we explicitly set htpasswd=users.htpasswd to ensure the key is correct. Also, make sure the secret is created in the openshift-config namespace (as shown), since the OAuth configuration will read it from there.

Step 3: Configure the OAuth Identity Provider (HTPasswd)

Now we will tell OpenShift’s OAuth server to use the htpasswd file/secret as an identity provider (often abbreviated as IDP). In OpenShift 4, the cluster’s authentication configuration is defined by a cluster-wide OAuth resource (which is always named cluster). We need to update this OAuth configuration to include our new HTPasswd identity provider.

There are two ways to do this:

• Using the CLI (with a YAML file): Suitable for automation or when you’re comfortable editing YAML. We will demonstrate this method first.
• Using the Web Console (UI): A more beginner-friendly way to add an IDP through the OpenShift web console. We will cover this in the next section.

3.1 Using the CLI (YAML method)

We will create a YAML file for the OAuth configuration and then apply it with the CLI.

Prepare the OAuth configuration YAML. Create a file (e.g. oauth-htpasswd.yaml) with the following content to define the HTPasswd identity provider:

apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
  name: cluster  # This is the fixed name for the cluster OAuth configuration
spec:
  identityProviders:
  - name: my_htpasswd_provider            # A name for this identity provider (can be any unique identifier)
    challenge: true                      # Allow CLI logins (challenge authentication)
    login: true                          # Allow web console login with this IDP
    mappingMethod: claim                 # Map identities to users one-to-one
    type: HTPasswd                       # Type of identity provider
    htpasswd:
      fileData:
        name: htpass-secret              # Name of the secret containing the htpasswd file

In this YAML: – We are editing the OAuth cluster configuration (metadata.name: cluster). – Under spec.identityProviders, we add a new entry for our HTPasswd provider. – name is an arbitrary identifier for the IDP (we chose “my_htpasswd_provider”). – challenge: true and login: true enable this IDP for both CLI logins (which use challenge/response flows) and web console logins. These are usually set to true for HTPasswd providers so that both console and CLI authentication are allowed. – mappingMethod: claim means each identity maps to a unique user (prevents ID collision, using one-to-one mapping). – type: HTPasswd specifies the kind of IDP. – Under htpasswd.fileData.name, we reference the Kubernetes secret we created in Step 2 (here it’s htpass-secret). This tells the OAuth server which secret contains the htpasswd file.

If you used a different secret name or file key, make sure to update the YAML accordingly. Save this file once you have edited the values as needed.

Apply the OAuth configuration. Once the YAML is ready, apply it to the cluster:

oc apply -f oauth-htpasswd.yaml

Warning: resource oauths/cluster is missing the kubectl.kubernetes.io/last-applied-configuration annotation which is required by oc apply. oc apply should only be used on resources created declaratively by either oc create –save-config or oc apply. The missing annotation will be patched automatically.
oauth.config.openshift.io/cluster configured

The CLI may show a warning about a missing annotation – this is because the OAuth resource was initially created by the cluster installer, not via oc apply. The tool will automatically attach a last-applied-configuration annotation for future use. The key part is the final line: “oauth.config.openshift.io/cluster configured”, which indicates that the OAuth resource was updated successfully.

After a minute or two, the OpenShift OAuth operator will process this change. You have now added the HTPasswd identity provider to the cluster. You can verify that the configuration has been applied by running oc describe oauth/cluster and looking under the spec.identityProviders section to see your entry. The web console login page will also reflect the new provider (usually within a minute or so).

3.2 Using the Web Console to Add HTPasswd (Alternative Method)

Instead of using the CLI and YAML, OpenShift’s web console provides a graphical way to add an identity provider, which can be more intuitive for beginners. Here’s how to add the HTPasswd IDP via the web console:

1. Log in to the console as an admin: Use your kubeadmin credentials (or another admin account) to access the OpenShift web console. You must have cluster-admin privileges to modify cluster settings.

2. Navigate to Cluster Settings: In the web console, click on the Administration menu and select Cluster Settings. Then click the Configuration tab. In the list of cluster configuration resources, find and select OAuth (it may be listed as “Authentication” in some console versions).

3. Add a new Identity Provider: In the OAuth (Authentication) configuration page, there will be a section for Identity Providers. Click the Add dropdown button and choose HTPasswd from the list of provider types.

4. Fill in the HTPasswd provider details: A form will appear for the new HTPasswd IDP. Provide the following:

A Name for the provider (this is equivalent to the name field in the YAML, e.g. “my_htpasswd_provider”).

Upload your htpasswd file or paste its contents into the provided field. The console allows you to either select the file from your local machine or directly paste the file content into a text box.

(If prompted) set the challenge/login options. Some OpenShift console versions might let you specify whether to allow CLI (challenge) and web (login) authentication for this provider. Ensure these are enabled (set to true) so that the provider can be used from both CLI and web console.

5. Save the configuration: Click Add (or Save) to create the identity provider. The console will show a message that the provider is being added. Behind the scenes, the console will create the Kubernetes secret (if you chose to upload a file, it creates a secret for you) and update the OAuth cluster configuration accordingly. It may take a minute for the changes to propagate.

6. Test the new provider: Once the operation completes, log out of the web console. On the login page, you should now see an option or tile for the new HTPasswd identity provider (often labeled with the name you gave it). Select that provider (if there are multiple) and log in with one of the usernames from your htpasswd file (e.g. alice with her password). This should log you into the OpenShift console as that user.

The end result of using the console method is the same as the CLI method – your cluster’s OAuth configuration now includes the HTPasswd provider, and you have one or more user accounts able to authenticate. Use whichever method you are more comfortable with; the web console approach is great for quick setups and avoids editing YAML, while the CLI approach is scriptable and clear for audit trails.

---

Step 4: Verify the New User Login (CLI and Web Console)

With the HTPasswd identity provider configured, it’s time to test that our new users can authenticate and access the cluster.

4.1 Log in via the OpenShift CLI: Use the oc login command with one of the new usernames and passwords you added. For example, to log in as alice from a terminal:

oc login -u alice -p StrongPass1

If the credentials are correct, you should see a message indicating a successful login:

Login successful.
You don't have any projects. You can try to create a new project, by running

oc new-project my-projectname

This confirms that Alice is now recognized by the cluster and can authenticate. The message about not having any projects is normal for a brand new user – by default, a new user doesn’t have any projects or specific roles yet. They can create a project (if self-provisioning is allowed) or an admin can grant them access to existing projects.

4.2 Log in via the Web Console: Next, verify that you can log in through the OpenShift web console using the new credentials: – Open the OpenShift web console in your browser (the URL was provided at cluster install, or you can get it via oc get route -n openshift-console console). – If you are currently logged in as kubeadmin in the console, log out to return to the login page. – On the login page, you should see the new identity provider listed (e.g., a button or option for “my_htpasswd_provider” or whatever name you gave it). Select it if needed, then enter the username (e.g. alice) and password. – If the login is successful, the web console will load and you will see the standard OpenShift Overview dashboard for Alice.

At this point, Alice is a normal authenticated user on the cluster. In the web console, notice that any temporary admin warning banner that existed for kubeadmin is now gone – OpenShift displays a warning banner when using the built-in kubeadmin account to remind you it’s meant for temporary access, but when logged in as a normal user, that banner is not shown.

Note: New users have no roles or permissions by default other than the ability to create their own projects (if allowed). So even though Alice can log in, she cannot see other projects or perform administrative actions yet. This is expected because we haven’t granted her any special permissions. In the next step, we’ll address giving users administrative rights if needed.

Step 5: (Optional) Grant Admin Rights and Remove kubeadmin

Now that you have one or more real user accounts authenticated via HTPasswd, you may want to give one of these users administrative privileges on the cluster (especially if the goal is to replace the default kubeadmin with a new admin user). Additionally, for better security, it’s advisable to disable the default kubeadmin account once you have another admin in place.

5.1 Grant cluster-admin role to a user

If you want one of your new users (say, alice) to be a cluster administrator with full control (equivalent to kubeadmin), you need to bind the cluster-admin role to that user. OpenShift has a built-in cluster role called cluster-admin which grants a user superuser privileges on the cluster. Use the following command (while logged in as kubeadmin or another admin) to grant this role to the user:

oc adm policy add-cluster-role-to-user cluster-admin alice

Output:

clusterrole.rbac.authorization.k8s.io/cluster-admin added: "alice"

This command adds a ClusterRoleBinding that ties the cluster-admin role to the user alice. The output confirms that the role was added to alice. You can verify the new binding by running oc get clusterrolebindings and looking for alice, or simply by attempting an admin-level action while logged in as alice.

If you have multiple users that need cluster-admin rights, run the above command for each username. For example, to also make bob an admin, you would run:

oc adm policy add-cluster-role-to-user cluster-admin bob

After granting these rights, if you log in as alice (or bob) again, you should now have the same capabilities as the kubeadmin user did. For instance, you can create or view all projects, install Operators, and access the Administration section in the web console. Essentially, alice is now a cluster admin.

5.2 Remove the default kubeadmin user (optional but recommended)

Once you have confirmed that your new admin user(s) can log in and have the necessary privileges, you can remove the default kubeadmin user. The kubeadmin account is intended as a temporary bootstrap user, and removing it is considered a best practice after setting up real authentication. This prevents anyone from using the well-known kubeadmin credentials moving forward.

The kubeadmin credentials are stored in a secret. To remove the kubeadmin account, delete the corresponding secret in the kube-system namespace:

oc delete secret kubeadmin -n kube-system

Output:

secret "kubeadmin" deleted

Deleting this secret immediately removes the kubeadmin login access. After running this, the kubeadmin user will no longer be able to authenticate (the account effectively ceases to exist). Make sure you have at least one other admin user working before you do this, otherwise you could lock yourself out of the cluster. OpenShift does not allow recovering the kubeadmin once its secret is deleted (short of reinstalling the cluster)[11]. So only delete kubeadmin after verifying your new admin account can perform all needed tasks.

---

Conclusion and Additional Tips

In this guide, we set up an HTPasswd identity provider on an OpenShift 4.15+ single-node cluster and created user accounts that can log in via both the CLI and web console. To recap, we accomplished the following:

• Created an htpasswd file with one or more users (using the htpasswd utility).
• Stored that file in an OpenShift Secret (htpass-secret in the openshift-config namespace).
• Updated the cluster’s OAuth configuration to include the HTPasswd identity provider, referencing the secret.
• Verified that new users can log in through the CLI (oc login) and the web console, and observed that by default they have limited access (no projects initially).
• (Optional) Granted admin rights to a user by adding the cluster-admin role, and then removed the default kubeadmin user for improved security.

Your OpenShift cluster is now configured to use basic user authentication with htpasswd. You can continue to add or remove users by updating the htpasswd file and then updating the secret (e.g., re-create or oc replace the secret with the new file). Keep in mind that if you change the htpasswd file, you need to update the secret and that OpenShift does not automatically know about new users until the secret is updated. Removing a user involves removing their line from the file and updating the secret, as well as cleaning up their OpenShift User and Identity objects if desired. Always regenerate the secret (oc create secret … or oc replace …) if you manually edit the htpasswd file.

Multiple IDPs: OpenShift supports having multiple identity providers configured simultaneously (for example, you could have both HTPasswd and LDAP, GitHub OAuth, etc.). If multiple IDPs are set up, the web console login page will show a choice of providers for the user to select. This can be useful if you want to integrate with an external auth system later while still keeping htpasswd for fallback or admin access.