Chapter 18. Managing user access


18.1. Managing RBAC in Red Hat Advanced Cluster Security for Kubernetes

Red Hat Advanced Cluster Security for Kubernetes (RHACS) comes with role-based access control (RBAC) that you can use to configure roles and grant various levels of access to Red Hat Advanced Cluster Security for Kubernetes for different users.

Beginning with version 3.63, RHACS includes a scoped access control feature that enables you to configure fine-grained and specific sets of permissions that define how a given RHACS user or a group of users can interact with RHACS, which resources they can access, and which actions they can perform.

  • Roles are a collection of permission sets and access scopes. You can assign roles to users and groups by specifying rules. You can configure these rules when you configure an authentication provider. There are two types of roles in Red Hat Advanced Cluster Security for Kubernetes:

    • System roles that are created by Red Hat and cannot be changed.
    • Custom roles, which Red Hat Advanced Cluster Security for Kubernetes administrators can create and change at any time.

      Note
      • If you assign multiple roles for a user, they get access to the combined permissions of the assigned roles.
      • If you have users assigned to a custom role, and you delete that role, all associated users transfer to the minimum access role that you have configured.
  • Permission sets are a set of permissions that define what actions a role can perform on a given resource. Resources are the functionalities of Red Hat Advanced Cluster Security for Kubernetes for which you can set view (read) and modify (write) permissions. There are two types of permission sets in Red Hat Advanced Cluster Security for Kubernetes:

    • System permission sets, which are created by Red Hat and cannot be changed.
    • Custom permission sets, which Red Hat Advanced Cluster Security for Kubernetes administrators can create and change at any time.
  • Access scopes are a set of Kubernetes and OpenShift Container Platform resources that users can access. For example, you can define an access scope that only allows users to access information about pods in a given project. There are two types of access scopes in Red Hat Advanced Cluster Security for Kubernetes:

    • System access scopes, which are created by Red Hat and cannot be changed.
    • Custom access scopes, which Red Hat Advanced Cluster Security for Kubernetes administrators can create and change at any time.

18.1.1. System roles

Red Hat Advanced Cluster Security for Kubernetes (RHACS) includes some default system roles that you can apply to users when you create rules. You can also create custom roles as required.

System roleDescription

Admin

This role is targeted for administrators. Use it to provide read and write access to all resources.

Analyst

This role is targeted for a user who cannot make any changes, but can view everything. Use it to provide read-only access for all resources.

Continuous Integration

This role is targeted for CI (continuous integration) systems and includes the permission set required to enforce deployment policies.

Network Graph Viewer

This role is targeted for users who need to view the network graph.

None

This role has no read and write access to any resource. You can set this role as the minimum access role for all users.

Sensor Creator

RHACS uses this role to automate new cluster setups. It includes the permission set to create Sensors in secured clusters.

Vulnerability Management Approver

This role allows you to provide access to approve vulnerability deferrals or false positive requests.

Vulnerability Management Requester

This role allows you to provide access to request vulnerability deferrals or false positives.

Vulnerability Report Creator

This role allows you to create and manage vulnerability reporting configurations for scheduled vulnerability reports.

18.1.1.1. Viewing the permission set and access scope for a system role

You can view the permission set and access scope for the default system roles.

Procedure

  1. In the RHACS portal, go to Platform Configuration Access control.
  2. Select Roles.
  3. Click on one of the roles to view its details. The details page shows the permission set and access scope for the slected role.
Note

You cannot modify permission set and access scope for the default system roles.

18.1.1.2. Creating a custom role

You can create new roles from the Access Control view.

Prerequisites

  • You must have the Admin role, or read and write permissions for the Access resource to create, modify, and delete custom roles.
  • You must create a permissions set and an access scope for the custom role before creating the role.

Procedure

  1. In the RHACS portal, go to Platform Configuration Access Control.
  2. Select Roles.
  3. Click Create role.
  4. Enter a Name and Description for the new role.
  5. Select a Permission set for the role.
  6. Select an Access scope for the role.
  7. Click Save.

18.1.1.3. Assigning a role to a user or a group

You can use the RHACS portal to assign roles to a user or a group.

Procedure

  1. In the RHACS portal, go to Platform Configuration Access Control.
  2. From the list of authentication providers, select the authentication provider.
  3. Click Edit minimum role and rules.
  4. Under the Rules section, click Add new rule.
  5. For Key, select one of the values from userid, name, email or group.
  6. For Value, enter the value of the user ID, name, email address or group based on the key you selected.
  7. Click the Role drop-down menu and select the role you want to assign.
  8. Click Save.

You can repeat these instructions for each user or group and assign different roles.

18.1.2. System permission sets

Red Hat Advanced Cluster Security for Kubernetes includes some default system permission sets that you can apply to roles. You can also create custom permission sets as required.

Permission setDescription

Admin

Provides read and write access to all resources.

Analyst

Provides read-only access for all resources.

Continuous Integration

This permission set is targeted for CI (continuous integration) systems and includes the permissions required to enforce deployment policies.

Network Graph Viewer

Provides the minimum permissions to view network graphs.

None

No read and write permissions are allowed for any resource.

Sensor Creator

Provides permissions for resources that are required to create Sensors in secured clusters.

18.1.2.1. Viewing the permissions for a system permission set

You can view the permissions for a system permission set in the RHACS portal.

Procedure

  1. In the RHACS portal, go to Platform Configuration Access control.
  2. Select Permission sets.
  3. Click on one of the permission sets to view its details. The details page shows a list of resources and their permissions for the selected permission set.
Note

You cannot modify permissions for a system permission set.

18.1.2.2. Creating a custom permission set

You can create new permission sets from the Access Control view.

Prerequisites

  • You must have the Admin role, or read and write permissions for the Access resource to create, modify, and delete permission sets.

Procedure

  1. In the RHACS portal, go to Platform Configuration Access Control.
  2. Select Permission sets.
  3. Click Create permission set.
  4. Enter a Name and Description for the new permission set.
  5. For each resource, under the Access level column, select one of the permissions from No access, Read access, or Read and Write access.

    Warning
    • If you are configuring a permission set for users, you must grant read-only permissions for the following resources:

      • Alert
      • Cluster
      • Deployment
      • Image
      • NetworkPolicy
      • NetworkGraph
      • WorkflowAdministration
      • Secret
    • These permissions are preselected when you create a new permission set.
    • If you do not grant these permissions, users will experience issues with viewing pages in the RHACS portal.
  6. Click Save.

18.1.3. System access scopes

Red Hat Advanced Cluster Security for Kubernetes includes some default system access scopes that you can apply on roles. You can also create custom access scopes as required.

Acces scopeDescription

Unrestricted

Provides access to all clusters and namespaces that Red Hat Advanced Cluster Security for Kubernetes monitors.

Deny All

Provides no access to any Kubernetes and OpenShift Container Platform resources.

18.1.3.1. Viewing the details for a system access scope

You can view the Kubernetes and OpenShift Container Platform resources that are allowed and not allowed for an access scope in the RHACS portal.

Procedure

  1. In the RHACS portal, go to Platform Configuration Access control.
  2. Select Access scopes.
  3. Click on one of the access scopes to view its details. The details page shows a list of clusters and namespaces, and which ones are allowed for the selected access scope.
Note

You cannot modify allowed resources for a system access scope.

18.1.3.2. Creating a custom access scope

You can create new access scopes from the Access Control view.

Prerequisites

  • You must have the Admin role, or a role with the permission set with read and write permissions for the AuthProvider and Role resources to create, modify, and delete permission sets.

Procedure

  1. In the RHACS portal, go to Platform Configuration Access control.
  2. Select Access scopes.
  3. Click Create access scope.
  4. Enter a Name and Description for the new access scope.
  5. Under the Allowed resources section:

    • Use the Cluster filter and Namespace filter fields to filter the list of clusters and namespaces visible in the list.
    • Expand the Cluster name to see the list of namespaces in that cluster.
    • To allow access to all namespaces in a cluster, toggle the switch in the Manual selection column.

      Note

      Access to a specific cluster provides users with access to the following resources within the scope of the cluster:

      • OpenShift Container Platform or Kubernetes cluster metadata and security information
      • Compliance information for authorized clusters
      • Node metadata and security information
      • Access to all namespaces in that cluster and their associated security information
    • To allow access to a namespace, toggle the switch in the Manual selection column for a namespace.

      Note

      Access to a specific namespace gives access to the following information within the scope of the namespace:

      • Alerts and violations for deployments
      • Vulnerability data for images
      • Deployment metadata and security information
      • Role and user information
      • Network graph, policy, and baseline information for deployments
      • Process information and process baseline configuration
      • Prioritized risk information for each deployment
  6. If you want to allow access to clusters and namespaces based on labels, click Add label selector under the Label selection rules section. Then click Add rule to specify Key and Value pairs for the label selector. You can specify labels for clusters and namespaces.
  7. Click Save.

18.1.4. Resource definitions

Red Hat Advanced Cluster Security for Kubernetes includes many resources. The following table lists the Red Hat Advanced Cluster Security for Kubernetes resources and describes the actions that users can perform with the read or write permission.

Note
  • To prevent privilege escalation, when you create a new token, your role’s permissions limit the permission you can assign to that token. For example, if you only have read permission for the Integration resource, you cannot create a token with write permission.
  • If you want a custom role to create tokens for other users to use, you must assign the required permissions to that custom role.
  • Use short-lived tokens for machine-to-machine communication, such as CI/CD pipelines, scripts, and other automation. Also, use the roxctl central login command for human-to-machine communication, such as roxctl CLI or API access.
ResourceRead permissionWrite permission

Access

View configurations for single sign-on (SSO) and role-based access control (RBAC) rules that match user metadata to Red Hat Advanced Cluster Security for Kubernetes roles and users that have accessed your Red Hat Advanced Cluster Security for Kubernetes instance, including the metadata that the authentication providers give about them.

Create, modify, or delete SSO configurations and configured RBAC rules.

Administration

View the following items:

  • Options for data retention, security notices and other related configurations
  • The current logging verbosity level in Red Hat Advanced Cluster Security for Kubernetes components
  • Manifest content for the uploaded probe files
  • Existing image scanner integrations
  • The status of automatic upgrades
  • Metadata about Red Hat Advanced Cluster Security for Kubernetes service-to-service authentication
  • The content of the scanner bundle (download)

Edit the following items:

  • Data retention, security notices, and related configurations
  • The logging level
  • Support packages in Central (upload)
  • Image scanner integrations (create/modify/delete)
  • Automatic upgrades for secured clusters (enable/disable)
  • Service-to-service authentication credentials (revoke/re-issue)

Alert

View existing policy violations.

Resolve or edit policy violations.

CVE

Internal use only

Internal use only

Cluster

View existing secured clusters.

Add new secured clusters and modify or delete existing clusters.

Compliance

View compliance standards and results, recent compliance runs, and the associated completion status.

Trigger compliance runs.

Deployment

View deployments (workloads) in secured clusters.

N/A

DeploymentExtension

View the following items:

  • Process baselines
  • Process activity in deployments
  • Risk results

Modify the following items:

  • Process baselines (add or remove processes)

Detection

Check build-time policies against images or deployment YAML.

N/A

Image

View images, their components, and their vulnerabilities.

N/A

Integration

View integrations and their configuration, including backup, registry, image signature, notification systems, and API tokens.

Add, modify, and delete integrations and their configurations, and API tokens.

K8sRole

View roles for Kubernetes RBAC in secured clusters.

N/A

K8sRoleBinding

View role bindings for Kubernetes RBAC in secured clusters.

N/A

K8sSubject

View users and groups for Kubernetes RBAC in secured clusters.

N/A

Namespace

View existing Kubernetes namespaces in secured clusters.

N/A

NetworkGraph

View active and allowed network connections in secured clusters.

N/A

NetworkPolicy

View existing network policies in secured clusters and simulate changes.

Apply network policy changes in secured clusters.

Node

View existing Kubernetes nodes in secured clusters.

N/A

WorkflowAdministration

View all resource collections.

Add, modify, or delete resource collections.

Role

View existing Red Hat Advanced Cluster Security for Kubernetes RBAC roles and their permissions.

Add, modify, or delete roles and their permissions.

Secret

View metadata about secrets in secured clusters.

N/A

ServiceAccount

List Kubernetes service accounts in secured clusters.

N/A

VulnerabilityManagementApprovals

View all pending deferral or false positive requests for vulnerabilities.

Approve or deny any pending deferral or false positive requests and move any previously approved requests back to observed.

VulnerabilityManagementRequests

View all pending deferral or false positive requests for vulnerabilities.

Request a deferral on a vulnerability, mark it as a false positive, or move a pending or previously approved request made by the same user back to observed.

WatchedImage

View undeployed and monitored watched images.

Configure watched images.

WorkflowAdministration

View all resource collections.

Create, modify, or delete resource collections.

18.1.5. Declarative configuration for authentication and authorization resources

You can use declarative configuration for authentication and authorization resources such as authentication providers, roles, permission sets, and access scopes. For instructions on how to use declarative configuration, see "Using declarative configuration" in the "Additional resources" section.

Additional resources

18.2. Enabling PKI authentication

If you use an enterprise certificate authority (CA) for authentication, you can configure Red Hat Advanced Cluster Security for Kubernetes (RHACS) to authenticate users by using their personal certificates.

After you configure PKI authentication, users and API clients can log in using their personal certificates. Users without certificates can still use other authentication options, including API tokens, the local administrator password, or other authentication providers. PKI authentication is available on the same port number as the Web UI, gRPC, and REST APIs.

When you configure PKI authentication, by default, Red Hat Advanced Cluster Security for Kubernetes uses the same port for PKI, web UI, gRPC, other single sign-on (SSO) providers, and REST APIs. You can also configure a separate port for PKI authentication by using a YAML configuration file to configure and expose endpoints.

18.2.1. Configuring PKI authentication by using the RHACS portal

You can configure Public Key Infrastructure (PKI) authentication by using the RHACS portal.

Procedure

  1. In the RHACS portal, go to Platform Configuration Access Control.
  2. Click Create Auth Provider and select User Certificates from the drop-down list.
  3. In the Name field, specify a name for this authentication provider.
  4. In the CA certificate(s) (PEM) field, paste your root CA certificate in PEM format.
  5. Assign a Minimum access role for users who access RHACS using PKI authentication. A user must have the permissions granted to this role or a role with higher permissions to log in to RHACS.

    Tip

    For security, Red Hat recommends first setting the Minimum access role to None while you complete setup. Later, you can return to the Access Control page to set up more tailored access rules based on user metadata from your identity provider.

  6. To add access rules for users and groups accessing RHACS, click Add new rule in the Rules section. For example, to give the Admin role to a user called administrator, you can use the following key-value pairs to create access rules:

    Key

    Value

    Name

    administrator

    Role

    Admin

  7. Click Save.

18.2.2. Configuring PKI authentication by using the roxctl CLI

You can configure PKI authentication by using the roxctl CLI.

Procedure

  • Run the following command:

    $ roxctl -e <hostname>:<port_number> central userpki create -c <ca_certificate_file> -r <default_role_name> <provider_name>

18.2.3. Updating authentication keys and certificates

You can update your authentication keys and certificates by using the RHACS portal.

Procedure

  1. Create a new authentication provider.
  2. Copy the role mappings from your old authentication provider to the new authentication provider.
  3. Rename or delete the old authentication provider with the old root CA key.

18.2.4. Logging in by using a client certificate

After you configure PKI authentication, users see a certificate prompt in the RHACS portal login page. The prompt only shows up if a client certificate trusted by the configured root CA is installed on the user’s system.

Use the procedure described in this section to log in by using a client certificate.

Procedure

  1. Open the RHACS portal.
  2. Select a certificate in the browser prompt.
  3. On the login page, select the authentication provider name option to log in with a certificate. If you do not want to log in by using the certificate, you can also log in by using the administrator password or another login method.
Note

Once you use a client certificate to log into the RHACS portal, you cannot log in with a different certificate unless you restart your browser.

18.3. Understanding authentication providers

An authentication provider connects to a third-party source of user identity (for example, an identity provider or IDP), gets the user identity, issues a token based on that identity, and returns the token to Red Hat Advanced Cluster Security for Kubernetes (RHACS). This token allows RHACS to authorize the user. RHACS uses the token within the user interface and API calls.

After installing RHACS, you must set up your IDP to authorize users.

Note

If you are using OpenID Connect (OIDC) as your IDP, RHACS relies on mapping rules that examine the values of specific claims like groups, email, userid and name from either the user ID token or the UserInfo endpoint response to authorize the users. If these details are absent, the mapping cannot succeed and the user does not get access to the required resources. Therefore, you need to ensure that the claims required to authorize users from your IDP, for example, groups, are included in the authentication response of your IDP to enable successful mapping.

18.3.1. Claim mappings

A claim is the data an identity provider includes about a user inside the token they issue.

Using claim mappings, you can specify if RHACS should customize the claim attribute it receives from an IDP to another attribute in the RHACS-issued token. If you do not use the claim mapping, RHACS does not include the claim attribute in the RHACS-issued token.

For example, you can map from roles in the user identity to groups in the RHACS-issued token using claim mapping.

RHACS uses different default claim mappings for every authentication provider.

18.3.1.1. OIDC default claim mappings

The following list provides the default OIDC claim mappings:

  • sub to userid
  • name to name
  • email to email
  • groups to groups

18.3.1.2. Auth0 default claim mappings

The Auth0 default claim mappings are the same as the OIDC default claim mappings.

18.3.1.3. SAML 2.0 default claim mappings

The following list applies to SAML 2.0 default claim mappings:

  • Subject.NameID is mapped to userid
  • every SAML AttributeStatement.Attribute from the response gets mapped to its name

18.3.1.4. Google IAP default claim mappings

The following list provides the Google IAP default claim mappings:

  • sub to userid
  • email to email
  • hd to hd
  • google.access_levels to access_levels

18.3.1.5. User certificates default claim mappings

User certificates differ from all other authentication providers because instead of communicating with a third-party IDP, they get user information from certificates used by the user.

The default claim mappings for user certificates include:

  • CertFingerprint to userid
  • Subject Common Name to name
  • EmailAddresses to email
  • Subject Organizational Unit to groups

18.3.1.6. OpenShift Auth default claim mappings

The following list provides the OpenShift Auth default claim mappings:

  • groups to groups
  • uid to userid
  • name to name

18.3.2. Rules

To authorize users, RHACS relies on mapping rules that examine the values of specific claims such as groups, email, userid, and name from the user identity. Rules allow mapping of users who have attributes with a specific value to a specific role. As an example, a rule could include the following:`key` is email, value is john@redhat.com, role is Admin.

If the claim is missing, the mapping cannot succeed, and the user does not get access to the required resources. Therefore, to enable successful mapping, you must ensure that the authentication response from your IDP includes the required claims to authorize users, for example, groups.

18.3.3. Minimum access role

RHACS assigns a minimum access role to every caller with a RHACS token issued by a particular authentication provider. The minimum access role is set to None by default.

For example, suppose there is an authentication provider with the minimum access role of Analyst. In that case, all users who log in using this provider will have the Analyst role assigned to them.

18.3.4. Required attributes

Required attributes can restrict issuing of the RHACS token based on whether a user identity has an attribute with a specific value.

For example, you can configure RHACS only to issue a token when the attribute with key is_internal has the attribute value true. Users with the attribute is_internal set to false or not set do not get a token.

18.4. Configuring identity providers

18.4.1. Configuring Okta Identity Cloud as a SAML 2.0 identity provider

You can use Okta as a single sign-on (SSO) provider for Red Hat Advanced Cluster Security for Kubernetes (RHACS).

18.4.1.1. Creating an Okta app

Before you can use Okta as a SAML 2.0 identity provider for Red Hat Advanced Cluster Security for Kubernetes, you must create an Okta app.

Warning

Okta’s Developer Console does not support the creation of custom SAML 2.0 applications. If you are using the Developer Console, you must first switch to the Admin Console (Classic UI). To switch, click Developer Console in the top left of the page and select Classic UI.

Prerequisites

  • You must have an account with administrative privileges for the Okta portal.

Procedure

  1. On the Okta portal, select Applications from the menu bar.
  2. Click Add Application and then select Create New App.
  3. In the Create a New Application Integration dialog box, leave Web as the platform and select SAML 2.0 as the protocol that you want to sign in users.
  4. Click Create.
  5. On the General Settings page, enter a name for the app in the App name field.
  6. Click Next.
  7. On the SAML Settings page, set values for the following fields:

    1. Single sign on URL

      • Specify it as https://<RHACS_portal_hostname>/sso/providers/saml/acs.
      • Leave the Use this for Recipient URL and Destination URL option checked.
      • If your RHACS portal is accessible at different URLs, you can add them here by checking the Allow this app to request other SSO URLs option and add the alternative URLs using the specified format.
    2. Audience URI (SP Entity ID)

      • Set the value to RHACS or another value of your choice.
      • Remember the value you choose; you will need this value when you configure Red Hat Advanced Cluster Security for Kubernetes.
    3. Attribute Statements

      • You must add at least one attribute statement.
      • Red Hat recommends using the email attribute:

        • Name: email
        • Format: Unspecified
        • Value: user.email
  8. Verify that you have configured at least one Attribute Statement before continuing.
  9. Click Next.
  10. On the Feedback page, select an option that applies to you.
  11. Select an appropriate App type.
  12. Click Finish.

After the configuration is complete, you are redirected to the Sign On settings page for the new app. A yellow box contains links to the information that you need to configure Red Hat Advanced Cluster Security for Kubernetes.

After you have created the app, assign Okta users to this application. Go to the Assignments tab, and assign the set of individual users or groups that can access Red Hat Advanced Cluster Security for Kubernetes. For example, assign the group Everyone to allow all users in the organization to access Red Hat Advanced Cluster Security for Kubernetes.

18.4.1.2. Configuring a SAML 2.0 identity provider

Use the instructions in this section to integrate a Security Assertion Markup Language (SAML) 2.0 identity provider with Red Hat Advanced Cluster Security for Kubernetes (RHACS).

Prerequisites

  • You must have permissions to configure identity providers in RHACS.
  • For Okta identity providers, you must have an Okta app configured for RHACS.

Procedure

  1. In the RHACS portal, go to Platform Configuration Access Control.
  2. Click Create auth provider and select SAML 2.0 from the drop-down list.
  3. In the Name field, enter a name to identify this authentication provider; for example, Okta or Google. The integration name is shown on the login page to help users select the correct sign-in option.
  4. In the ServiceProvider issuer field, enter the value that you are using as the Audience URI or SP Entity ID in Okta, or a similar value in other providers.
  5. Select the type of Configuration:

    • Option 1: Dynamic Configuration: If you select this option, enter the IdP Metadata URL, or the URL of Identity Provider metadata available from your identity provider console. The configuration values are acquired from the URL.
    • Option 2: Static Configuration: Copy the required static fields from the View Setup Instructions link in the Okta console, or a similar location for other providers:

      • IdP Issuer
      • IdP SSO URL
      • Name/ID Format
      • IdP Certificate(s) (PEM)
  6. Assign a Minimum access role for users who access RHACS using SAML.

    Tip

    Set the Minimum access role to Admin while you complete setup. Later, you can return to the Access Control page to set up more tailored access rules based on user metadata from your identity provider.

  7. Click Save.
Important

If your SAML identity provider’s authentication response meets the following criteria:

  • Includes a NotValidAfter assertion: The user session remains valid until the time specified in the NotValidAfter field has elapsed. After the user session expires, users must reauthenticate.
  • Does not include a NotValidAfter assertion: The user session remains valid for 30 days, and then users must reauthenticate.

Verification

  1. In the RHACS portal, go to Platform Configuration Access Control.
  2. Select the Auth Providers tab.
  3. Click the authentication provider for which you want to verify the configuration.
  4. Select Test login from the Auth Provider section header. The Test login page opens in a new browser tab.
  5. Sign in with your credentials.

    • If you logged in successfully, RHACS shows the User ID and User Attributes that the identity provider sent for the credentials that you used to log in to the system.
    • If your login attempt failed, RHACS shows a message describing why the identity provider’s response could not be processed.
  6. Close the Test login browser tab.

    Note

    Even if the response indicates successful authentication, you might need to create additional access rules based on the user metadata from your identity provider.

18.4.2. Configuring Google Workspace as an OIDC identity provider

You can use Google Workspace as a single sign-on (SSO) provider for Red Hat Advanced Cluster Security for Kubernetes.

18.4.2.1. Setting up OAuth 2.0 credentials for your GCP project

To configure Google Workspace as an identity provider for Red Hat Advanced Cluster Security for Kubernetes, you must first configure OAuth 2.0 credentials for your GCP project.

Prerequisites

  • You must have administrator-level access to your organization’s Google Workspace account to create a new project, or permissions to create and configure OAuth 2.0 credentials for an existing project. Red Hat recommends that you create a new project for managing access to Red Hat Advanced Cluster Security for Kubernetes.

Procedure

  1. Create a new Google Cloud Platform (GCP) project, see the Google documentation topic creating and managing projects.
  2. After you have created the project, open the Credentials page in the Google API Console.
  3. Verify the project name listed in the upper left corner near the logo to make sure that you are using the correct project.
  4. To create new credentials, go to Create Credentials OAuth client ID.
  5. Choose Web application as the Application type.
  6. In the Name box, enter a name for the application, for example, RHACS.
  7. In the Authorized redirect URIs box, enter https://<stackrox_hostname>:<port_number>/sso/providers/oidc/callback.

    • replace <stackrox_hostname> with the hostname on which you expose your Central instance.
    • replace <port_number> with the port number on which you expose Central. If you are using the standard HTTPS port 443, you can omit the port number.
  8. Click Create. This creates an application and credentials and redirects you back to the credentials page.
  9. An information box opens, showing details about the newly created application. Close the information box.
  10. Copy and save the Client ID that ends with .apps.googleusercontent.com. You can check this client ID by using the Google API Console.
  11. Select OAuth consent screen from the navigation menu on the left.

    Note

    The OAuth consent screen configuration is valid for the entire GCP project, and not only to the application you created in the previous steps. If you already have an OAuth consent screen configured in this project and want to apply different settings for Red Hat Advanced Cluster Security for Kubernetes login, create a new GCP project.

  12. On the OAuth consent screen page:

    1. Choose the Application type as Internal. If you select Public, anyone with a Google account can sign in.
    2. Enter a descriptive Application name. This name is shown to users on the consent screen when they sign in. For example, use RHACS or <organization_name> SSO for Red Hat Advanced Cluster Security for Kubernetes.
    3. Verify that the Scopes for Google APIs only lists email, profile, and openid scopes. Only these scopes are required for single sign-on. If you grant additional scopes it increases the risk of exposing sensitive data.

18.4.2.2. Specifying a client secret

Red Hat Advanced Cluster Security for Kubernetes version 3.0.39 and newer supports the OAuth 2.0 Authorization Code Grant authentication flow when you specify a client secret. When you use this authentication flow, Red Hat Advanced Cluster Security for Kubernetes uses a refresh token to keep users logged in beyond the token expiration time configured in your OIDC identity provider.

When users log out, Red Hat Advanced Cluster Security for Kubernetes deletes the refresh token from the client-side. Additionally, if your identity provider API supports refresh token revocation, Red Hat Advanced Cluster Security for Kubernetes also sends a request to your identity provider to revoke the refresh token.

You can specify a client secret when you configure Red Hat Advanced Cluster Security for Kubernetes to integrate with an OIDC identity provider.

Note
  • You cannot use a Client Secret with the Fragment Callback mode.
  • You cannot edit configurations for existing authentication providers.
  • You must create a new OIDC integration in Red Hat Advanced Cluster Security for Kubernetes if you want to use a Client Secret.

Red Hat recommends using a client secret when connecting Red Hat Advanced Cluster Security for Kubernetes with an OIDC identity provider. If you do not want to use a Client Secret, you must select the Do not use Client Secret (not recommended) option.

18.4.2.3. Configuring an OIDC identity provider

You can configure Red Hat Advanced Cluster Security for Kubernetes (RHACS) to use your OpenID Connect (OIDC) identity provider.

Prerequisites

  • You must have already configured an application in your identity provider, such as Google Workspace.
  • You must have permissions to configure identity providers in RHACS.

Procedure

  1. In the RHACS portal, go to Platform Configuration Access Control.
  2. Click Create auth provider and select OpenID Connect from the drop-down list.
  3. Enter information in the following fields:

    • Name: A name to identify your authentication provider; for example, Google Workspace. The integration name is shown on the login page to help users select the correct sign-in option.
    • Callback mode: Select Auto-select (recommended), which is the default value, unless the identity provider requires another mode.

      Note

      Fragment mode is designed around the limitations of Single Page Applications (SPAs). Red Hat only supports the Fragment mode for early integrations and does not recommended using it for later integrations.

    • Issuer: The root URL of your identity provider; for example, https://accounts.google.com for Google Workspace. See your identity provider documentation for more information.

      Note

      If you are using RHACS version 3.0.49 and later, for Issuer you can perform these actions:

      • Prefix your root URL with https+insecure:// to skip TLS validation. This configuration is insecure and Red Hat does not recommended it. Only use it for testing purposes.
      • Specify query strings; for example, ?key1=value1&key2=value2 along with the root URL. RHACS appends the value of Issuer as you entered it to the authorization endpoint. You can use it to customize your provider’s login screen. For example, you can optimize the Google Workspace login screen to a specific hosted domain by using the hd parameter, or preselect an authentication method in PingFederate by using the pfidpadapterid parameter.
    • Client ID: The OIDC Client ID for your configured project.
    • Client Secret: Enter the client secret provided by your identity provider (IdP). If you are not using a client secret, which is not recommended, select Do not use Client Secret.
  4. Assign a Minimum access role for users who access RHACS using the selected identity provider.

    Tip

    Set the Minimum access role to Admin while you complete setup. Later, you can return to the Access Control page to set up more tailored access rules based on user metadata from your identity provider.

  5. To add access rules for users and groups accessing RHACS, click Add new rule in the Rules section. For example, to give the Admin role to a user called administrator, you can use the following key-value pairs to create access rules:

    Key

    Value

    Name

    administrator

    Role

    Admin

  6. Click Save.

Verification

  1. In the RHACS portal, go to Platform Configuration Access Control.
  2. Select the Auth providers tab.
  3. Select the authentication provider for which you want to verify the configuration.
  4. Select Test login from the Auth Provider section header. The Test login page opens in a new browser tab.
  5. Log in with your credentials.

    • If you logged in successfully, RHACS shows the User ID and User Attributes that the identity provider sent for the credentials that you used to log in to the system.
    • If your login attempt failed, RHACS shows a message describing why the identity provider’s response could not be processed.
  6. Close the Test Login browser tab.

18.4.3. Configuring OpenShift Container Platform OAuth server as an identity provider

OpenShift Container Platform includes a built-in OAuth server that you can use as an authentication provider for Red Hat Advanced Cluster Security for Kubernetes (RHACS).

18.4.3.1. Configuring OpenShift Container Platform OAuth server as an identity provider

To integrate the built-in OpenShift Container Platform OAuth server as an identity provider for RHACS, use the instructions in this section.

Prerequisites

  • You must have the Access permission to configure identity providers in RHACS.
  • You must have already configured users and groups in OpenShift Container Platform OAuth server through an identity provider. For information about the identity provider requirements, see Understanding identity provider configuration.
Note

The following procedure configures only a single main route named central for the OpenShift Container Platform OAuth server.

Procedure

  1. In the RHACS portal, go to Platform Configuration Access Control.
  2. Click Create auth provider and select OpenShift Auth from the drop-down list.
  3. Enter a name for the authentication provider in the Name field.
  4. Assign a Minimum access role for users that access RHACS using the selected identity provider. A user must have the permissions granted to this role or a role with higher permissions to log in to RHACS.

    Tip

    For security, Red Hat recommends first setting the Minimum access role to None while you complete setup. Later, you can return to the Access Control page to set up more tailored access rules based on user metadata from your identity provider.

  5. Optional: To add access rules for users and groups accessing RHACS, click Add new rule in the Rules section, then enter the rule information and click Save. You will need attributes for the user or group so that you can configure access.

    Tip

    Group mappings are more robust because groups are usually associated with teams or permissions sets and require modification less often than users.

    To get user information in OpenShift Container Platform, you can use one of the following methods:

    • Click User Management Users <username> YAML.
    • Access the k8s/cluster/user.openshift.io~v1~User/<username>/yaml file and note the values for name, uid (userid in RHACS), and groups.
    • Use the OpenShift Container Platform API as described in the OpenShift Container Platform API reference.

    The following configuration example describes how to configure rules for an Admin role with the following attributes:

    • name: administrator
    • groups: ["system:authenticated", "system:authenticated:oauth", "myAdministratorsGroup"]
    • uid: 12345-00aa-1234-123b-123fcdef1234

    You can add a rule for this administrator role using one of the following steps:

    • To configure a rule for a name, select name from the Key drop-down list, enter administrator in the Value field, then select Administrator under Role.
    • To configure a rule for a group, select groups from the Key drop-down list, enter myAdministratorsGroup in the Value field, then select Admin under Role.
    • To configure a rule for a user name, select userid from the Key drop-down list, enter 12345-00aa-1234-123b-123fcdef1234 in the Value field, then select Admin under Role.
Important
  • If you use a custom TLS certificate for OpenShift Container Platform OAuth server, you must add the root certificate of the CA to Red Hat Advanced Cluster Security for Kubernetes as a trusted root CA. Otherwise, Central cannot connect to the OpenShift Container Platform OAuth server.
  • To enable the OpenShift Container Platform OAuth server integration when installing Red Hat Advanced Cluster Security for Kubernetes using the roxctl CLI, set the ROX_ENABLE_OPENSHIFT_AUTH environment variable to true in Central:

    $ oc -n stackrox set env deploy/central ROX_ENABLE_OPENSHIFT_AUTH=true
  • For access rules, the OpenShift Container Platform OAuth server does not return the key Email.

18.4.3.2. Creating additional routes for OpenShift Container Platform OAuth server

When you configure OpenShift Container Platform OAuth server as an identity provider by using Red Hat Advanced Cluster Security for Kubernetes portal, RHACS configures only a single route for the OAuth server. However, you can create additional routes by specifying them as annotations in the Central custom resource.

Prerequisites

Procedure

  • If you installed RHACS using the RHACS Operator:

    1. Create a CENTRAL_ADDITIONAL_ROUTES environment variable that contains a patch for the Central custom resource:

      $ CENTRAL_ADDITIONAL_ROUTES='
      spec:
        central:
          exposure:
            loadBalancer:
              enabled: false
              port: 443
            nodePort:
              enabled: false
            route:
              enabled: true
          persistence:
            persistentVolumeClaim:
              claimName: stackrox-db
        customize:
          annotations:
            serviceaccounts.openshift.io/oauth-redirecturi.main: sso/providers/openshift/callback 1
            serviceaccounts.openshift.io/oauth-redirectreference.main: "{\"kind\":\"OAuthRedirectReference\",\"apiVersion\":\"v1\",\"reference\":{\"kind\":\"Route\",\"name\":\"central\"}}" 2
            serviceaccounts.openshift.io/oauth-redirecturi.second: sso/providers/openshift/callback 3
            serviceaccounts.openshift.io/oauth-redirectreference.second: "{\"kind\":\"OAuthRedirectReference\",\"apiVersion\":\"v1\",\"reference\":{\"kind\":\"Route\",\"name\":\"second-central\"}}" 4
      '
      1
      The redirect URI for setting the main route.
      2
      The redirect URI reference for the main route.
      3
      The redirect for setting the second route.
      4
      The redirect reference for the second route.
    2. Apply the CENTRAL_ADDITIONAL_ROUTES patch to the Central custom resource:

      $ oc patch centrals.platform.stackrox.io \
        -n <namespace> \ 1
        <custom-resource> \ 2
        --patch "$CENTRAL_ADDITIONAL_ROUTES" \
        --type=merge
      1
      Replace <namespace> with the name of the project that contains the Central custom resource.
      2
      Replace <custom-resource> with the name of the Central custom resource.
  • Or, if you installed RHACS using Helm:

    1. Add the following annotations to your values-public.yaml file:

      customize:
        central:
          annotations:
            serviceaccounts.openshift.io/oauth-redirecturi.main: sso/providers/openshift/callback 1
            serviceaccounts.openshift.io/oauth-redirectreference.main: "{\"kind\":\"OAuthRedirectReference\",\"apiVersion\":\"v1\",\"reference\":{\"kind\":\"Route\",\"name\":\"central\"}}" 2
            serviceaccounts.openshift.io/oauth-redirecturi.second: sso/providers/openshift/callback 3
            serviceaccounts.openshift.io/oauth-redirectreference.second: "{\"kind\":\"OAuthRedirectReference\",\"apiVersion\":\"v1\",\"reference\":{\"kind\":\"Route\",\"name\":\"second-central\"}}" 4
      1
      The redirect for setting the main route.
      2
      The redirect reference for the main route.
      3
      The redirect for setting the second route.
      4
      The redirect reference for the second route.
    2. Apply the custom annotations to the Central custom resource by using helm upgrade:

      $ helm upgrade -n stackrox \
        stackrox-central-services rhacs/central-services \
        -f <path_to_values_public.yaml> 1
      1
      Specify the path of the values-public.yaml configuration file using the -f option.

18.4.4. Connecting Azure AD to RHACS using SSO configuration

To connect an Azure Active Directory (AD) to RHACS using Sign-On (SSO) configuration, you need to add specific claims (for example, group claim to tokens) and assign users, groups, or both to the enterprise application.

18.4.4.1. Adding group claims to tokens for SAML applications using SSO configuration

Configure the application registration in Azure AD to include group claims in tokens. For instructions, see Add group claims to tokens for SAML applications using SSO configuration.

Important

Verify that you are using the latest version of Azure AD. For more information on how to upgrade Azure AD to the latest version, see Azure AD Connect: Upgrade from a previous version to the latest.

18.5. Removing the admin user

Red Hat Advanced Cluster Security for Kubernetes (RHACS) creates an administrator account, admin, during the installation process that can be used to log in with a user name and password. The password is dynamically generated unless specifically overridden and is unique to your RHACS instance.

In production environments, it is highly recommended to create an authentication provider and remove the admin user.

18.5.1. Removing the admin user after installation

After an authentication provider has been successfully created, it is strongly recommended to remove the admin user.

Removing the admin user is dependent on the installation method of the RHACS portal.

Procedure

Perform one of the following procedures:

  • For Operator installations, set central.adminPasswordGenerationDisabled to true in your Central custom resource.
  • For Helm installations:

    1. In your Central Helm configuration, set central.adminPassword.generate to false.
    2. Follow the steps to change the configuration. See "Changing configuration options after deployment" for more information.
  • For roxctl installations:

    1. When generating the manifest, set Disable password generation to false.
    2. Follow the steps to install Central by using roxctl to apply the changes. See "Install Central using the roxctl CLI" for more information.

After applying the configuration changes, you cannot log in as an admin user.

Note

You can add the admin user again as a fallback by reverting the configuration changes. When enabling the admin user again, a new password is generated.

18.6. Configuring short-lived access

Red Hat Advanced Cluster Security for Kubernetes (RHACS) provides the ability to configure short-lived access to the user interface and API calls.

You can configure this by exchanging OpenID Connect (OIDC) identity tokens for a RHACS-issued token.

We recommend this especially for Continuous Integration (CI) usage, where short-lived access is preferable over long-lived API tokens.

The following steps outline the high-level workflow on how to configure short-lived access to the user interface and API calls:

  1. Configuring RHACS to trust OIDC identity token issuers for exchanging short-lived RHACS-issued tokens.
  2. Exchanging an OIDC identity token for a short-lived RHACS-issued token by calling the API.
Note
  • To prevent privilege escalation, when you create a new token, your role’s permissions limit the permission you can assign to that token. For example, if you only have read permission for the Integration resource, you cannot create a token with write permission.
  • If you want a custom role to create tokens for other users to use, you must assign the required permissions to that custom role.
  • Use short-lived tokens for machine-to-machine communication, such as CI/CD pipelines, scripts, and other automation. Also, use the roxctl central login command for human-to-machine communication, such as roxctl CLI or API access.

18.6.1. Configure short-lived access for an OIDC identity token issuer

Start configuring short-lived access for an OpenID Connect (OIDC) identity token issuer.

Procedure

  1. In the RHACS portal, go to Platform Configuration Integrations.
  2. Scroll to the Authentication Tokens category, and then click Machine access configuration.
  3. Click Create configuration.
  4. Select the configuration type, choosing one of the following:

    • Generic if you use an arbitrary OIDC identity token issuer.
    • GitHub Actions if you plan to access RHACS from GitHub Actions.
  5. Enter the OIDC identity token issuer.
  6. Enter the token lifetime for tokens issued by the configuration.

    Note

    The format for the token lifetime is XhYmZs and you cannot set it for longer than 24 hours.

  7. Add rules to the configuration:

    • The Key is the OIDC token’s claim to use.
    • The Value is the expected OIDC token claim value.
    • The Role is the role to assign to the token if the OIDC token claim and value exist.

      Note

      Rules are similar to Authentication Provider rules to assign roles based on claim values.

      As a general rule, Red Hat recommends to use unique, immutable claims within Rules. The general recommendation is to use the sub claim within the OIDC identity token. For more information about OIDC token claims, see the list of standard OIDC claims.

  8. Click Save.

18.6.2. Exchanging an identity token

Prerequisites

  • You have a valid OpenID Connect (OIDC) token.
  • You added a Machine access configuration for the RHACS instance you want to access.

Procedure

  1. Prepare the POST request’s JSON data:

    {
        "idToken": "<id_token>"
    }
  2. Send a POST request to the API /v1/auth/m2m/exchange.
  3. Wait for the API response:

    {
        "accessToken": "<access_token>"
    }
  4. Use the returned access token to access the RHACS instance.
Note

If you are using GitHub Actions, you can use the stackrox/central-login GitHub Action.

18.7. Understanding multi-tenancy

Red Hat Advanced Cluster Security for Kubernetes provides ways to implement multi-tenancy within a Central instance.

You can implement multi-tenancy by using role-based access control (RBAC) and access scopes within RHACS.

18.7.1. Understanding resource scoping

RHACS includes resources which are used within RBAC. In addition to associating permissions for a resource, each resource is also scoped.

In RHACS, resources are scoped as the following types:

  • Global scope, where a resource is not assigned to any cluster or namespace
  • Cluster scope, where a resource is assigned to particular clusters
  • Namespace scope, where a resource is assigned to particular namespaces

The scope of resources is important when creating custom access scopes. Custom access scopes are used to create multi-tenancy within RHACS.

Only resources which are cluster or namespace scoped are applicable for scoping in access scopes. Globally scoped resources are not scoped by access scopes. Therefore, multi-tenancy within RHACS can only be achieved for resources that are scoped either by cluster or namespace.

18.7.2. Multi-tenancy per namespace configuration example

A common example for multi-tenancy within RHACS is associating users with a specific namespace and only allowing them access to their specific namespace.

The following example combines a custom permission set, access scope, and role. The user or group assigned with this role can only see CVE information, violations, and information about deployments in the particular namespace or cluster scoped to them.

Procedure

  1. In the RHACS portal, select Platform Configuration Access Control.
  2. Select Permission Sets.
  3. Click Create permission set.
  4. Enter a Name and Description for the permission set.
  5. Select the following resources and access level and click Save:

    • READ Alert
    • READ Deployment
    • READ DeploymentExtension
    • READ Image
    • READ K8sRole
    • READ K8sRoleBinding
    • READ K8sSubject
    • READ NetworkGraph
    • READ NetworkPolicy
    • READ Secret
    • READ ServiceAccount
  6. Select Access Scopes.
  7. Click Create access scope.
  8. Enter a Name and Description for the access scope.
  9. In the Allowed resources section, select the namespace you want to use for scoping and click Save.
  10. Select Roles.
  11. Click Create role.
  12. Enter a Name and Description for the role.
  13. Select the previously created Permission Set and Access scope for the role and click Save.
  14. Assign the role to your required user or group. See Assigning a role to a user or a group.
Note

The RHACS dashboard options for users with the sample role are minimal compared to options available to an administrator. Only relevant pages are visible for the user.

18.7.3. Limitations

Achieving multi-tenancy within RHACS is not possible for resources with a global scope.

The following resources have a global scope:

  • Access
  • Administration
  • Detection
  • Integration
  • VulnerabilityManagementApprovals
  • VulnerabilityManagementRequests
  • WatchedImage
  • WorkflowAdministration

These resources are shared across all users within a RHACS Central instance and cannot be scoped.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.