Preparing for users
After installing OpenShift Container Platform, you can further expand and customize your cluster to your requirements, including taking steps to prepare for users.
Understanding identity provider configuration
The OpenShift Container Platform control plane includes a built-in OAuth server. Developers and administrators obtain OAuth access tokens to authenticate themselves to the API.
As an administrator, you can configure OAuth to specify an identity provider after you install your cluster.
About identity providers in OpenShift Container Platform
By default, only a kubeadmin user exists on your cluster. To specify an
identity provider, you must create a custom resource (CR) that describes
that identity provider and add it to the cluster.
Note
OpenShift Container Platform user names containing /, :, and % are not supported.
Supported identity providers
You can configure the following types of identity providers:
| Identity provider | Description |
|---|---|
Configure the |
|
Configure the |
|
Configure the |
|
Configure a |
|
Configure a |
|
Configure a |
|
Configure a |
|
Configure a |
|
Configure an |
After you define an identity provider, you can use RBAC to define and apply permissions.
Identity provider parameters
The following parameters are common to all identity providers:
| Parameter | Description |
|---|---|
|
The provider name is prefixed to provider user names to form an identity name. |
|
Defines how new identities are mapped to users when they log in. Enter one of the following values:
|
Note
When adding or changing identity providers, you can map identities from the new provider to existing users by setting themappingMethod parameter to
add.
Sample identity provider CR
The following custom resource (CR) shows the parameters and default values that you use to configure an identity provider. This example uses the htpasswd identity provider.
apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
name: cluster
spec:
identityProviders:
- name: my_identity_provider
mappingMethod: claim
type: HTPasswd
htpasswd:
fileData:
name: htpass-secret
- This provider name is prefixed to provider user names to form an identity name.
- Controls how mappings are established between this provider’s
identities and
Userobjects. - An existing secret containing a file generated using
htpasswd.
Using RBAC to define and apply permissions
Understand and apply role-based access control.
RBAC overview
Role-based access control (RBAC) objects determine whether a user is allowed to perform a given action within a project.
can use the cluster roles and bindings to control who has various access levels to the OpenShift Container Platform platform itself and all projects.
Developers can use local roles and bindings to control who has access to their projects. Note that authorization is a separate step from authentication, which is more about determining the identity of who is taking the action.
Authorization is managed using:
| Authorization object | Description |
|---|---|
Rules |
Sets of permitted verbs on a set of objects. For example,
whether a user or service account can |
Roles |
Collections of rules. You can associate, or bind, users and groups to multiple roles. |
Bindings |
Associations between users and/or groups with a role. |
Be mindful of the difference between local and cluster bindings. For example,
if you bind the cluster-admin role to a user by using a local role binding,
it might appear that this user has the privileges of a cluster administrator.
This is not the case. Binding the cluster-admin to a user in a project
grants super administrator privileges for only that project to the user. That user has the permissions of the cluster role admin, plus a few additional permissions like the ability to edit rate limits, for that project. This binding can be confusing via the web console UI, which does not list cluster role bindings that are bound to true cluster administrators. However, it does list local role bindings that you can use to locally bind cluster-admin.
The relationships between cluster roles, local roles, cluster role bindings, local role bindings, users, groups and service accounts are illustrated below.
Warning
The get pods/exec, get pods/*, and get * rules grant execution privileges when they are applied to a role. Apply the principle of least privilege and assign only the minimal RBAC rights required for users and agents. For more information, see RBAC rules allow execution privileges.
Evaluating authorization
OpenShift Container Platform evaluates authorization by using:
- Identity
-
The user name and list of groups that the user belongs to.
- Action
-
The action you perform. In most cases, this consists of:
-
Project: The project you access. A project is a Kubernetes namespace with additional annotations that allows a community of users to organize and manage their content in isolation from other communities.
-
Verb : The action itself:
get,list,create,update,delete,deletecollection, orwatch. -
Resource name: The API endpoint that you access.
-
- Bindings
-
The full list of bindings, the associations between users or groups with a role.
OpenShift Container Platform evaluates authorization by using the following steps:
-
The identity and the project-scoped action is used to find all bindings that apply to the user or their groups.
-
Bindings are used to locate all the roles that apply.
-
Roles are used to find all the rules that apply.
-
The action is checked against each rule to find a match.
-
If no matching rule is found, the action is then denied by default.
including a matrix of the verbs and resources each are associated with.
Projects and namespaces
A Kubernetes namespace provides a mechanism to scope resources in a cluster. The Kubernetes documentation has more information on namespaces.
Namespaces provide a unique scope for:
-
Named resources to avoid basic naming collisions.
-
Delegated management authority to trusted users.
-
The ability to limit community resource consumption.
Most objects in the system are scoped by namespace, but some are excepted and have no namespace, including nodes and users.
A project is a Kubernetes namespace with additional annotations and is the central vehicle by which access to resources for regular users is managed. A project allows a community of users to organize and manage their content in isolation from other communities. Users must be given access to projects by administrators, or if allowed to create projects, automatically have access to their own projects.
Projects can have a separate name, displayName, and description.
-
The mandatory
nameis a unique identifier for the project and is most visible when using the CLI tools or API. The maximum name length is 63 characters. -
The optional
displayNameis how the project is displayed in the web console (defaults toname). -
The optional
descriptioncan be a more detailed description of the project and is also visible in the web console.
Each project scopes its own set of:
| Object | Description |
|---|---|
|
Pods, services, replication controllers, etc. |
|
Rules for which users can or cannot perform actions on objects. |
|
Quotas for each kind of object that can be limited. |
|
Service accounts act automatically with designated access to objects in the project. |
Cluster administrators can create projects and delegate administrative rights for the project to any member of the user community. Cluster administrators can also allow developers to create their own projects.
Developers and administrators can interact with projects by using the CLI or the web console.
Default projects
OpenShift Container Platform comes with a number of default projects, and projects
starting with openshift- are the most essential to users.
These projects host master components that run as pods and other infrastructure
components. The pods created in these namespaces that have a
critical pod annotation
are considered critical, and the have guaranteed admission by kubelet.
Pods created for master components in these namespaces are already marked as
critical.
Important
Do not run workloads in or share access to default projects. Default projects are reserved for running core cluster components.
The following default projects are considered highly privileged: default, kube-public, kube-system, openshift, openshift-infra, openshift-node, and other system-created projects that have the openshift.io/run-level label set to 0 or 1. Functionality that relies on admission plugins, such as pod security admission, security context constraints, cluster resource quotas, and image reference resolution, does not work in highly privileged projects.
Viewing cluster roles and bindings
You can use the oc CLI to view cluster roles and bindings by using the
oc describe command.
-
Install the
ocCLI. -
Obtain permission to view the cluster roles and bindings.
-
To view the cluster roles and their associated rule sets:
-
To view the current set of cluster role bindings, which shows the users and groups that are bound to various roles:
Viewing local roles and bindings
You can use the oc CLI to view local roles and bindings by using the
oc describe command.
-
Install the
ocCLI. -
Obtain permission to view the local roles and bindings:
-
Users with the
admindefault cluster role bound locally can view and manage roles and bindings in that project.
-
-
To view the current set of local role bindings, which show the users and groups that are bound to various roles for the current project:
$ oc describe rolebinding.rbac -
To view the local role bindings for a different project, add the
-nflag to the command:$ oc describe rolebinding.rbac -n joe-projectExample outputName: admin Labels: <none> Annotations: <none> Role: Kind: ClusterRole Name: admin Subjects: Kind Name Namespace ---- ---- --------- User kube:admin Name: system:deployers Labels: <none> Annotations: openshift.io/description: Allows deploymentconfigs in this namespace to rollout pods in this namespace. It is auto-managed by a controller; remove subjects to disa... Role: Kind: ClusterRole Name: system:deployer Subjects: Kind Name Namespace ---- ---- --------- ServiceAccount deployer joe-project Name: system:image-builders Labels: <none> Annotations: openshift.io/description: Allows builds in this namespace to push images to this namespace. It is auto-managed by a controller; remove subjects to disable. Role: Kind: ClusterRole Name: system:image-builder Subjects: Kind Name Namespace ---- ---- --------- ServiceAccount builder joe-project Name: system:image-pullers Labels: <none> Annotations: openshift.io/description: Allows all pods in this namespace to pull images from this namespace. It is auto-managed by a controller; remove subjects to disable. Role: Kind: ClusterRole Name: system:image-puller Subjects: Kind Name Namespace ---- ---- --------- Group system:serviceaccounts:joe-project
Adding roles to users
You can use the oc adm administrator CLI to manage the roles and bindings.
Binding, or adding, a role to users or groups gives the user or group the access
that is granted by the role. You can add and remove roles to and from users and
groups using oc adm policy commands.
You can bind any of the default cluster roles to local users or groups in your project.
-
Add a role to a user in a specific project:
$ oc adm policy add-role-to-user <role> <user> -n <project>For example, you can add the
adminrole to thealiceuser injoeproject by running:$ oc adm policy add-role-to-user admin alice -n joeTip
You can alternatively apply the following YAML to add the role to the user:
apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: admin-0 namespace: joe roleRef: apiGroup: rbac.authorization.k8s.io kind: ClusterRole name: admin subjects: - apiGroup: rbac.authorization.k8s.io kind: User name: alice -
View the local role bindings and verify the addition in the output:
$ oc describe rolebinding.rbac -n <project>For example, to view the local role bindings for the
joeproject:$ oc describe rolebinding.rbac -n joeExample outputName: admin Labels: <none> Annotations: <none> Role: Kind: ClusterRole Name: admin Subjects: Kind Name Namespace ---- ---- --------- User kube:admin Name: admin-0 Labels: <none> Annotations: <none> Role: Kind: ClusterRole Name: admin Subjects: Kind Name Namespace ---- ---- --------- User alice Name: system:deployers Labels: <none> Annotations: openshift.io/description: Allows deploymentconfigs in this namespace to rollout pods in this namespace. It is auto-managed by a controller; remove subjects to disa... Role: Kind: ClusterRole Name: system:deployer Subjects: Kind Name Namespace ---- ---- --------- ServiceAccount deployer joe Name: system:image-builders Labels: <none> Annotations: openshift.io/description: Allows builds in this namespace to push images to this namespace. It is auto-managed by a controller; remove subjects to disable. Role: Kind: ClusterRole Name: system:image-builder Subjects: Kind Name Namespace ---- ---- --------- ServiceAccount builder joe Name: system:image-pullers Labels: <none> Annotations: openshift.io/description: Allows all pods in this namespace to pull images from this namespace. It is auto-managed by a controller; remove subjects to disable. Role: Kind: ClusterRole Name: system:image-puller Subjects: Kind Name Namespace ---- ---- --------- Group system:serviceaccounts:joe- The
aliceuser has been added to theadminsRoleBinding.
- The
Local role binding commands
When you manage a user or group’s associated roles for local role bindings using the
following operations, a project may be specified with the -n flag. If it is
not specified, then the current project is used.
You can use the following commands for local RBAC management.
| Command | Description |
|---|---|
|
Indicates which users can perform an action on a resource. |
|
Binds a specified role to specified users in the current project. |
|
Removes a given role from specified users in the current project. |
|
Removes specified users and all of their roles in the current project. |
|
Binds a given role to specified groups in the current project. |
|
Removes a given role from specified groups in the current project. |
|
Removes specified groups and all of their roles in the current project. |
Cluster role bindings for unauthenticated groups
Note
Before OpenShift Container Platform 4.17, unauthenticated groups were allowed access to some cluster roles. Clusters updated from versions before OpenShift Container Platform 4.17 retain this access for unauthenticated groups.
For security reasons OpenShift Container Platform 4.19 does not allow unauthenticated groups to have default access to cluster roles.
There are use cases where it might be necessary to add system:unauthenticated to a cluster role.
Cluster administrators can add unauthenticated users to the following cluster roles:
-
system:scope-impersonation -
system:webhook -
system:oauth-token-deleter -
self-access-reviewer
Important
Always verify compliance with your organization’s security standards when modifying unauthenticated access.
Adding unauthenticated groups to cluster roles
As a cluster administrator, you can add unauthenticated users to the following cluster roles in OpenShift Container Platform by creating a cluster role binding. Unauthenticated users do not have access to non-public cluster roles. This should only be done in specific use cases when necessary.
You can add unauthenticated users to the following cluster roles:
-
system:scope-impersonation -
system:webhook -
system:oauth-token-deleter -
self-access-reviewer
Important
Always verify compliance with your organization’s security standards when modifying unauthenticated access.
-
You have access to the cluster as a user with the
cluster-adminrole. -
You have installed the OpenShift CLI (
oc).
-
Create a YAML file named
add-<cluster_role>-unauth.yamland add the following content:apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: annotations: rbac.authorization.kubernetes.io/autoupdate: "true" name: <cluster_role>access-unauthenticated roleRef: apiGroup: rbac.authorization.k8s.io kind: ClusterRole name: <cluster_role> subjects: - apiGroup: rbac.authorization.k8s.io kind: Group name: system:unauthenticated -
Apply the configuration by running the following command:
$ oc apply -f add-<cluster_role>.yaml
The kubeadmin user
OpenShift Container Platform creates a cluster administrator, kubeadmin, after the
installation process completes.
This user has the cluster-admin role automatically applied and is treated
as the root user for the cluster. The password is dynamically generated
and unique to your OpenShift Container Platform environment. After installation
completes the password is provided in the installation program’s output.
For example:
INFO Install complete!
INFO Run 'export KUBECONFIG=<your working directory>/auth/kubeconfig' to manage the cluster with 'oc', the OpenShift CLI.
INFO The cluster is ready when 'oc login -u kubeadmin -p <provided>' succeeds (wait a few minutes).
INFO Access the OpenShift web-console here: https://console-openshift-console.apps.demo1.openshift4-beta-abcorp.com
INFO Login to the console with user: kubeadmin, password: <provided>
Removing the kubeadmin user
After you define an identity provider and create a new cluster-admin
user, you can remove the kubeadmin to improve cluster security.
Warning
If you follow this procedure before another user is a cluster-admin,
then OpenShift Container Platform must be reinstalled. It is not possible to undo
this command.
-
You must have configured at least one identity provider.
-
You must have added the
cluster-adminrole to a user. -
You must be logged in as an administrator.
-
Remove the
kubeadminsecrets:$ oc delete secrets kubeadmin -n kube-system
Populating the software catalog from mirrored Operator catalogs
If you mirrored Operator catalogs for use with disconnected clusters, you can populate the software catalog with the Operators from your mirrored catalogs. You can use the generated manifests from the mirroring process to create the required ImageContentSourcePolicy and CatalogSource objects.
Prerequisites
Creating the ImageContentSourcePolicy object
After mirroring Operator catalog content to your mirror registry, create the required ImageContentSourcePolicy (ICSP) object. The ICSP object configures nodes to translate between the image references stored in Operator manifests and the mirrored registry.
-
On a host with access to the disconnected cluster, create the ICSP by running the following command to specify the
imageContentSourcePolicy.yamlfile in your manifests directory:$ oc create -f <path/to/manifests/dir>/imageContentSourcePolicy.yamlwhere
<path/to/manifests/dir>is the path to the manifests directory for your mirrored content.You can now create a
CatalogSourceobject to reference your mirrored index image and Operator content.
Adding a catalog source to a cluster
Adding a catalog source to an OpenShift Container Platform cluster enables the discovery and installation of Operators for users.
Cluster administrators
can create a CatalogSource object that references an index image. The software catalog uses catalog sources to populate the user interface.
Tip
Alternatively, you can use the web console to manage catalog sources. From the Administration → Cluster Settings → Configuration → OperatorHub page, click the Sources tab, where you can create, update, delete, disable, and enable individual sources.
-
You built and pushed an index image to a registry.
-
You have access to the cluster as a user with the
cluster-adminrole.
-
Create a
CatalogSourceobject that references your index image. If you used theoc adm catalog mirrorcommand to mirror your catalog to a target registry, you can use the generatedcatalogSource.yamlfile in your manifests directory as a starting point.-
Modify the following to your specifications and save it as a
catalogSource.yamlfile:apiVersion: operators.coreos.com/v1alpha1 kind: CatalogSource metadata: name: my-operator-catalog namespace: openshift-marketplace spec: sourceType: grpc grpcPodConfig: securityContextConfig: <security_mode> image: <registry>/<namespace>/redhat-operator-index:v4.19 displayName: My Operator Catalog publisher: <publisher_name> updateStrategy: registryPoll: interval: 30m- If you mirrored content to local files before uploading to a registry, remove any backslash (
/) characters from themetadata.namefield to avoid an "invalid resource name" error when you create the object. - If you want the catalog source to be available globally to users in all namespaces, specify the
openshift-marketplacenamespace. Otherwise, you can specify a different namespace for the catalog to be scoped and available only for that namespace. - Specify the value of
legacyorrestricted. If the field is not set, the default value islegacy. In a future OpenShift Container Platform release, it is planned that the default value will berestricted.Note
If your catalog cannot run with
restrictedpermissions, it is recommended that you manually set this field tolegacy. - Specify your index image. If you specify a tag after the image name, for example
:v4.19, the catalog source pod uses an image pull policy ofAlways, meaning the pod always pulls the image prior to starting the container. If you specify a digest, for example@sha256:<id>, the image pull policy isIfNotPresent, meaning the pod pulls the image only if it does not already exist on the node. - Specify your name or an organization name publishing the catalog.
- Catalog sources can automatically check for new versions to keep up to date.
- If you mirrored content to local files before uploading to a registry, remove any backslash (
-
Use the file to create the
CatalogSourceobject:$ oc apply -f catalogSource.yaml
-
-
Verify the following resources are created successfully.
-
Check the pods:
$ oc get pods -n openshift-marketplaceExample outputNAME READY STATUS RESTARTS AGE my-operator-catalog-6njx6 1/1 Running 0 28s marketplace-operator-d9f549946-96sgr 1/1 Running 0 26h -
Check the catalog source:
$ oc get catalogsource -n openshift-marketplaceExample outputNAME DISPLAY TYPE PUBLISHER AGE my-operator-catalog My Operator Catalog grpc 5s -
Check the package manifest:
$ oc get packagemanifest -n openshift-marketplaceExample outputNAME CATALOG AGE jaeger-product My Operator Catalog 93s
-
You can now install the Operators from the Software Catalog page on your OpenShift Container Platform web console.
About Operator installation from the software catalog
The software catalog is a user interface for discovering Operators; it works in conjunction with Operator Lifecycle Manager (OLM), which installs and manages Operators on a cluster.
As a cluster administrator, you can install an Operator from the software catalog by using the OpenShift Container Platform
During installation, you must determine the following initial settings for the Operator:
- Update Channel
-
If an Operator is available through multiple channels, you can choose which channel you want to subscribe to. For example, to deploy from the stable channel, if available, select it from the list.
- Approval Strategy
-
You can choose automatic or manual updates.
If you choose automatic updates for an installed Operator, when a new version of that Operator is available in the selected channel, Operator Lifecycle Manager (OLM) automatically upgrades the running instance of your Operator without human intervention.
If you select manual updates, when a newer version of an Operator is available, OLM creates an update request. As a cluster administrator, you must then manually approve that update request to have the Operator updated to the new version.
Installing from the software catalog by using the web console
You can install and subscribe to an Operator from software catalog by using the OpenShift Container Platform web console.
-
Access to an OpenShift Container Platform cluster using an account with
-
Navigate in the web console to the Ecosystem → Software Catalog page.
-
Scroll or type a keyword into the Filter by keyword box to find the Operator you want. For example, type
jaegerto find the Jaeger Operator.You can also filter options by Infrastructure Features. For example, select Disconnected if you want to see Operators that work in disconnected environments, also known as restricted network environments.
-
Select the Operator to display additional information.
Note
Choosing a Community Operator warns that Red Hat does not certify Community Operators; you must acknowledge the warning before continuing.
-
Read the information about the Operator and click Install.
-
On the Install Operator page, configure your Operator installation:
-
If you want to install a specific version of an Operator, select an Update channel and Version from the lists. You can browse the various versions of an Operator across any channels it might have, view the metadata for that channel and version, and select the exact version you want to install.
Note
The version selection defaults to the latest version for the channel selected. If the latest version for the channel is selected, the Automatic approval strategy is enabled by default. Otherwise, Manual approval is required when not installing the latest version for the selected channel.
Installing an Operator with Manual approval causes all Operators installed within the namespace to function with the Manual approval strategy and all Operators are updated together. If you want to update Operators independently, install Operators into separate namespaces.
-
Confirm the installation mode for the Operator:
-
All namespaces on the cluster (default) installs the Operator in the default
openshift-operatorsnamespace to watch and be made available to all namespaces in the cluster. This option is not always available. -
A specific namespace on the cluster allows you to choose a specific, single namespace in which to install the Operator. The Operator will only watch and be made available for use in this single namespace.
-
-
For clusters on cloud providers with token authentication enabled:
-
If the cluster uses AWS Security Token Service (STS Mode in the web console), enter the Amazon Resource Name (ARN) of the AWS IAM role of your service account in the role ARN field. To create the role’s ARN, follow the procedure described in Preparing AWS account.
-
If the cluster uses Microsoft Entra Workload ID (Workload Identity / Federated Identity Mode in the web console), add the client ID, tenant ID, and subscription ID in the appropriate fields.
-
If the cluster uses Google Cloud Platform Workload Identity (GCP Workload Identity / Federated Identity Mode in the web console), add the project number, pool ID, provider ID, and service account email in the appropriate fields.
-
-
For Update approval, select either the Automatic or Manual approval strategy.
Important
If the web console shows that the cluster uses AWS STS, Microsoft Entra Workload ID, or GCP Workload Identity, you must set Update approval to Manual.
Subscriptions with automatic approvals for updates are not recommended because there might be permission changes to make before updating. Subscriptions with manual approvals for updates ensure that administrators have the opportunity to verify the permissions of the later version, take any necessary steps, and then update.
-
-
Click Install to make the Operator available to the selected namespaces on this OpenShift Container Platform cluster:
-
If you selected a Manual approval strategy, the upgrade status of the subscription remains Upgrading until you review and approve the install plan.
After approving on the Install Plan page, the subscription upgrade status moves to Up to date.
-
If you selected an Automatic approval strategy, the upgrade status should resolve to Up to date without intervention.
-
-
After the upgrade status of the subscription is Up to date, select Ecosystem → Installed Operators to verify that the cluster service version (CSV) of the installed Operator eventually shows up. The Status should eventually resolve to Succeeded in the relevant namespace.
Note
For the All namespaces… installation mode, the status resolves to Succeeded in the
openshift-operatorsnamespace, but the status is Copied if you check in other namespaces.If it does not:
-
Check the logs in any pods in the
openshift-operatorsproject (or other relevant namespace if A specific namespace… installation mode was selected) on the Workloads → Pods page that are reporting issues to troubleshoot further.
-
-
When the Operator is installed, the metadata indicates which channel and version are installed.
Note
The Channel and Version dropdown menus are still available for viewing other version metadata in this catalog context.