Manage OpenShift / OKD Users with HTPasswd Identity Provider

Posted on 267 views

We now have a number of articles discussing on OpenShift Container platform. This tutorial will explain how one can configure HTPasswd as an identity provider for OCP / OKD cluster. You can configure the OpenShift OAuth server to use a number of identity providers, namely:

HTPasswd Validate user names and passwords against a secret that stores credentials generated using the htpasswd.
LDAP Configure the LDAP identity provider to validate user names and passwords against an LDAPv3 server, using simple bind authentication.
Keystone Enables shared authentication with an OpenStack Keystone v3 server.
OpenID Connect Integrates with an OpenID Connect identity provider using an Authorization Code Flow.
GitHub Configure a GitHub identity provider to validate user names and passwords against GitHub or the GitHub Enterprises OAuth authentication server.

The HTPasswd OAuth provider

This provider validates users against a secret that that contains user names and passwords generated with the htpasswd command from the Apache HTTP Server project. As a cluster administrator, you can change the data inside the secret. Which means update usernames and passwords used for authentication.

Managing Cluster users with HTPasswd Identity Provider is only fit for development environments with few number of users. In most production environments with hundreds to thousands of users, a more powerful identity provider that integrates with the organization’s identity management system is essential.

Manage OpenShift / OKD users with HTPasswd Identity Provider

For you to add another Identity provider to OpenShift / OKD, you need to access your OpenShift cluster as a cluster administrator. If you’re working on a freshly installed OpenShift cluster, two ways to authenticate API requests are available:

  • With the kubeadmin virtual user and password that grants an OAuth access token.
  • Using kubeconfig file that embeds an X.509 client certificate that never expires.

In this guide, we’ll use the kubeconfig authentication method to add an HTPasswd provider to OpenShift. The oc client is required for this operation. Depending on the location of the kubeconfig file, you may need to export it.

export KUBECONFIG=/root/auth/kubeconfig

Confirm that it is working by checking the available nodes in the cluster.

$ oc get nodes

As an alternative, you can use the --config option of the oc command:

$ oc --config /path/to/kubeconfig get nodes

For authentication with the kubeadm virtual user, you’ll run a command similar to below.

$ oc login -u kubeadmin -p KubeadmUserPassword

Configuring the HTPasswd Identity Provider

We’ll start by generating the required htpasswd file that will hold the user credentials. One package that need to be installed that provides the htpasswd command.

### CentOS / RHEL / Fedora ### 
sudo yum -y install httpd-tools

### Ubuntu / Debian ###
sudo apt install apache2-utils

### Arch Linux / Manjaro ###
sudo pacman -S apache

Creating an HTPasswd File

Create a new or update existing htpasswd file.

htpasswd -c -B -b ocp_users.htpasswd user1 password1

To add or update credentials, use:

htpasswd -Bb ocp_users.htpasswd user2 password2
htpasswd -Bb ocp_users.htpasswd user3 password3

Confirm the file has been created.

$ cat ocp_users.htpasswd 

To delete the user from htpasswd, run the following command:

$ htpasswd -D ocp_users.htpasswd user3
Deleting password for user user3

Create HTPasswd Secret

We need to define a secret that contains the HTPasswd user file before we can use the HTPasswd identity provider.

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

Configuring the OAuth Custom Resource

To use the HTPasswd identity provider, the OAuth custom resource must be edited to add an entry to the .spec.identity Providers array. Let’s create a new file.

vim htpasswd-oauth.yaml

Add and edit contents below.

kind: OAuth
  name: cluster
  - name: Local Password
    mappingMethod: claim 
    type: HTPasswd
        name: htpass-secret 


  • ocp-htpasswd-provider is the name of the provider. This name is prefixed to provider user names to form an identity name.
  • htpass-secret is the name of an existing secret containing a file generated using htpasswd.

Apply the defined CR:

oc apply -f htpasswd-oauth.yaml

The pods in openshift-authentication namespace are restarted:

$ oc  get pods -n openshift-authentication
NAME                               READY   STATUS    RESTARTS   AGE
oauth-openshift-5d66cbb6bd-j9g5z   1/1     Running   0          43s
oauth-openshift-5d66cbb6bd-jspwl   1/1     Running   0          55s

You ca now select the ‘Local Password‘ on OpenShift Login screen to authenticate with the HTPasswd provider using added credentials.


You can also log in to the cluster from CLI with the oc command as a user from added identity provider.

$ oc login -u 

Enter password when prompted.

Updating the HTPasswd Secret on OpenShift

Whenever you add, change or delete users in the htpasswd file, the secret must be updated on OpenShift Cluster as well. All data inside a secret must be encoded in base64.

One way to encode the data is using the oc create secret by sending the output YAML to the standard output and then piping the output to the oc replace command to update the existing secret.

oc create secret generic htpass-secret \
  --from-file htpasswd=./ocp_users.htpasswd \
  --dry-run -o yaml \
  | oc replace -n openshift-config -f -

Updating the OAuth Custom Resource

If you want to edit the OAuth custom resource, use the oc get command to export the existing OAuth cluster resource to a file in YAML format.

 oc get -o yaml oauth cluster > htpasswd-oauth.yaml

Make the needed changes to the embedded identity provider settings and then apply the new custom resource using the oc replace command.

$ oc apply -f htpasswd-oauth.yaml

Assign Administrative Privileges to User

The cluster-wide cluster-admin role grants cluster administration privileges to users and groups. You can grant the cluster-admin role to a standard user with the command below.

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

You could also create an Admin group with relevant permissions:

# Create a group and bind cluster role
$ oc adm groups new openshift-cluster-admins created
$ oc adm policy add-cluster-role-to-group cluster-admin openshift-cluster-admins added: "openshift-cluster-admins"

# Add users to created group
$ oc adm groups add-users openshift-cluster-admins 

Login as the user with admin perms, and if all works you can delete kubeadm user:

$ oc delete secrets kubeadmin -n kube-system
secret "kubeadmin" deleted

Extracting Secret Data

You can extract secret data and save them to a file which can the be viewed or modified. Use the oc extract for this operation.

oc extract secret/htpass-secret -n openshift-config --to - > temp-secrets

Stay connected for more OpenShift Cluster operation guides.


Gravatar Image
A systems engineer with excellent skills in systems administration, cloud computing, systems deployment, virtualization, containers, and a certified ethical hacker.