OpenShift Container Platform-4.6-Authentication and authorization-en-US
OpenShift Container Platform-4.6-Authentication and authorization-en-US
OpenShift Container Platform-4.6-Authentication and authorization-en-US
Configuring user authentication and access controls for users and services
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons
Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is
available at
http://creativecommons.org/licenses/by-sa/3.0/
. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must
provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert,
Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift,
Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States
and other countries.
Linux ® is the registered trademark of Linus Torvalds in the United States and other countries.
XFS ® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States
and/or other countries.
MySQL ® is a registered trademark of MySQL AB in the United States, the European Union and
other countries.
Node.js ® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the
official Joyent Node.js open source or commercial project.
The OpenStack ® Word Mark and OpenStack logo are either registered trademarks/service marks
or trademarks/service marks of the OpenStack Foundation, in the United States and other
countries and are used with the OpenStack Foundation's permission. We are not affiliated with,
endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
Abstract
This document provides instructions for defining identity providers in OpenShift Container
Platform. It also discusses how to configure role-based access control to secure the cluster.
Table of Contents
Table of Contents
.CHAPTER
. . . . . . . . . . 1.. .UNDERSTANDING
. . . . . . . . . . . . . . . . . . . AUTHENTICATION
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6. . . . . . . . . . . . .
1.1. USERS 6
1.2. GROUPS 6
1.3. API AUTHENTICATION 7
1.3.1. OpenShift Container Platform OAuth server 7
1.3.1.1. OAuth token requests 7
1.3.1.2. API impersonation 8
1.3.1.3. Authentication metrics for Prometheus 8
.CHAPTER
. . . . . . . . . . 2.
. . CONFIGURING
. . . . . . . . . . . . . . . . THE
. . . . . INTERNAL
. . . . . . . . . . . OAUTH
. . . . . . . . .SERVER
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
..............
2.1. OPENSHIFT CONTAINER PLATFORM OAUTH SERVER 10
2.2. OAUTH TOKEN REQUEST FLOWS AND RESPONSES 10
2.3. OPTIONS FOR THE INTERNAL OAUTH SERVER 10
2.3.1. OAuth token duration options 11
2.3.2. OAuth grant options 11
2.4. CONFIGURING THE INTERNAL OAUTH SERVER’S TOKEN DURATION 11
2.5. CONFIGURING TOKEN INACTIVITY TIMEOUT FOR THE INTERNAL OAUTH SERVER 12
2.6. OAUTH SERVER METADATA 14
2.7. TROUBLESHOOTING OAUTH API EVENTS 15
.CHAPTER
. . . . . . . . . . 3.
. . CONFIGURING
. . . . . . . . . . . . . . . . OAUTH
. . . . . . . . .CLIENTS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
..............
3.1. DEFAULT OAUTH CLIENTS 17
3.2. REGISTERING AN ADDITIONAL OAUTH CLIENT 17
3.3. CONFIGURING TOKEN INACTIVITY TIMEOUT FOR AN OAUTH CLIENT 18
3.4. ADDITIONAL RESOURCES 19
.CHAPTER
. . . . . . . . . . 4.
. . .UNDERSTANDING
. . . . . . . . . . . . . . . . . . .IDENTITY
. . . . . . . . . . PROVIDER
. . . . . . . . . . . .CONFIGURATION
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
..............
4.1. ABOUT IDENTITY PROVIDERS IN OPENSHIFT CONTAINER PLATFORM 20
4.2. SUPPORTED IDENTITY PROVIDERS 20
4.3. REMOVING THE KUBEADMIN USER 21
4.4. IDENTITY PROVIDER PARAMETERS 21
4.5. SAMPLE IDENTITY PROVIDER CR 22
.CHAPTER
. . . . . . . . . . 5.
. . CONFIGURING
. . . . . . . . . . . . . . . . IDENTITY
. . . . . . . . . . .PROVIDERS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
..............
5.1. CONFIGURING AN HTPASSWD IDENTITY PROVIDER 24
5.1.1. About identity providers in OpenShift Container Platform 24
5.1.2. Creating an HTPasswd file using Linux 24
5.1.3. Creating an HTPasswd file using Windows 25
5.1.4. Creating the HTPasswd Secret 25
5.1.5. Sample HTPasswd CR 26
5.1.6. Adding an identity provider to your clusters 26
5.1.7. Updating users for an HTPasswd identity provider 27
5.1.8. Configuring identity providers using the web console 28
5.2. CONFIGURING A KEYSTONE IDENTITY PROVIDER 28
5.2.1. About identity providers in OpenShift Container Platform 29
5.2.2. Creating the secret 29
5.2.3. Creating a config map 29
5.2.4. Sample Keystone CR 29
5.2.5. Adding an identity provider to your clusters 30
5.3. CONFIGURING AN LDAP IDENTITY PROVIDER 31
5.3.1. About identity providers in OpenShift Container Platform 31
5.3.2. About LDAP authentication 31
1
OpenShift Container Platform 4.6 Authentication and authorization
. . . . . . . . . . . 6.
CHAPTER . . .USING
. . . . . . .RBAC
. . . . . . TO
. . . .DEFINE
. . . . . . . . AND
. . . . . APPLY
. . . . . . . .PERMISSIONS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
..............
6.1. RBAC OVERVIEW 63
6.1.1. Default cluster roles 64
2
Table of Contents
. . . . . . . . . . . 7.
CHAPTER . . REMOVING
. . . . . . . . . . . . .THE
. . . . .KUBEADMIN
. . . . . . . . . . . . .USER
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
..............
7.1. THE KUBEADMIN USER 81
7.2. REMOVING THE KUBEADMIN USER 81
. . . . . . . . . . . 8.
CHAPTER . . .CONFIGURING
. . . . . . . . . . . . . . . THE
. . . . . USER
. . . . . . AGENT
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82
..............
8.1. ABOUT THE USER AGENT 82
8.2. CONFIGURING THE USER AGENT 82
.CHAPTER
. . . . . . . . . . 9.
. . .UNDERSTANDING
. . . . . . . . . . . . . . . . . . .AND
. . . . . CREATING
. . . . . . . . . . . .SERVICE
. . . . . . . . . ACCOUNTS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
..............
9.1. SERVICE ACCOUNTS OVERVIEW 84
9.2. CREATING SERVICE ACCOUNTS 84
9.3. EXAMPLES OF GRANTING ROLES TO SERVICE ACCOUNTS 85
.CHAPTER
. . . . . . . . . . 10.
. . . USING
. . . . . . . .SERVICE
. . . . . . . . . ACCOUNTS
. . . . . . . . . . . . .IN
. . .APPLICATIONS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
..............
10.1. SERVICE ACCOUNTS OVERVIEW 87
10.2. DEFAULT SERVICE ACCOUNTS 87
10.2.1. Default cluster service accounts 87
10.2.2. Default project service accounts and roles 88
10.3. CREATING SERVICE ACCOUNTS 88
10.4. USING A SERVICE ACCOUNT’S CREDENTIALS EXTERNALLY 89
. . . . . . . . . . . 11.
CHAPTER . . .USING
. . . . . . .A. .SERVICE
. . . . . . . . . .ACCOUNT
. . . . . . . . . . .AS
. . . AN
. . . .OAUTH
. . . . . . . .CLIENT
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
..............
11.1. SERVICE ACCOUNTS AS OAUTH CLIENTS 91
11.1.1. Redirect URIs for service accounts as OAuth clients 91
. . . . . . . . . . . 12.
CHAPTER . . . SCOPING
. . . . . . . . . . .TOKENS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94
..............
12.1. ABOUT SCOPING TOKENS 94
12.1.1. User scopes 94
12.1.2. Role scope 94
. . . . . . . . . . . 13.
CHAPTER . . . USING
. . . . . . . .BOUND
. . . . . . . .SERVICE
. . . . . . . . . .ACCOUNT
. . . . . . . . . . .TOKENS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95
..............
13.1. ABOUT BOUND SERVICE ACCOUNT TOKENS 95
13.2. CONFIGURING BOUND SERVICE ACCOUNT TOKENS USING VOLUME PROJECTION 95
. . . . . . . . . . . 14.
CHAPTER . . . MANAGING
. . . . . . . . . . . . .SECURITY
. . . . . . . . . . .CONTEXT
. . . . . . . . . . .CONSTRAINTS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
..............
14.1. ABOUT SECURITY CONTEXT CONSTRAINTS 97
14.1.1. SCC Strategies 99
14.1.2. Controlling volumes 100
14.1.3. Admission 101
14.1.4. SCC prioritization 102
14.2. ABOUT PRE-ALLOCATED SECURITY CONTEXT CONSTRAINTS VALUES 102
14.3. EXAMPLE SECURITY CONTEXT CONSTRAINTS 103
3
OpenShift Container Platform 4.6 Authentication and authorization
. . . . . . . . . . . 15.
CHAPTER . . . IMPERSONATING
. . . . . . . . . . . . . . . . . . .THE
. . . . .SYSTEM:ADMIN
. . . . . . . . . . . . . . . . .USER
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
..............
15.1. API IMPERSONATION 111
15.2. IMPERSONATING THE SYSTEM:ADMIN USER 111
15.3. IMPERSONATING THE SYSTEM:ADMIN GROUP 111
. . . . . . . . . . . 16.
CHAPTER . . . SYNCING
. . . . . . . . . . .LDAP
. . . . . .GROUPS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112
..............
16.1. ABOUT CONFIGURING LDAP SYNC 112
16.1.1. About the RFC 2307 configuration file 114
16.1.2. About the Active Directory configuration file 115
16.1.3. About the augmented Active Directory configuration file 116
16.2. RUNNING LDAP SYNC 117
16.2.1. Syncing the LDAP server with OpenShift Container Platform 117
16.2.2. Syncing OpenShift Container Platform groups with the LDAP server 117
16.2.3. Syncing subgroups from the LDAP server with OpenShift Container Platform 117
16.3. RUNNING A GROUP PRUNING JOB 118
16.4. LDAP GROUP SYNC EXAMPLES 119
16.4.1. Syncing groups using the RFC 2307 schema 119
16.4.2. Syncing groups using the RFC2307 schema with user-defined name mappings 121
16.4.3. Syncing groups using RFC 2307 with user-defined error tolerances 122
16.4.4. Syncing groups using the Active Directory schema 125
16.4.5. Syncing groups using the augmented Active Directory schema 126
16.4.5.1. LDAP nested membership sync example 128
16.5. LDAP SYNC CONFIGURATION SPECIFICATION 132
16.5.1. v1.LDAPSyncConfig 132
16.5.2. v1.StringSource 134
16.5.3. v1.LDAPQuery 134
16.5.4. v1.RFC2307Config 135
16.5.5. v1.ActiveDirectoryConfig 137
16.5.6. v1.AugmentedActiveDirectoryConfig 138
. . . . . . . . . . . 17.
CHAPTER . . . CREATING
. . . . . . . . . . . .AND
. . . . .USING
. . . . . . . CONFIG
. . . . . . . . . MAPS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140
...............
17.1. UNDERSTANDING CONFIGMAPS 140
Config map restrictions 141
17.2. CREATING A CONFIG MAP IN THE OPENSHIFT CONTAINER PLATFORM WEB CONSOLE 141
17.3. CREATING A CONFIG MAP 141
17.3.1. Creating a config map from a directory 142
17.3.2. Creating a ConfigMap from a file 143
17.3.3. Creating a config map from literal values 145
17.4. USE CASES: CONSUMING CONFIGMAPS IN PODS 146
17.4.1. Populating environment variables in containers by using config maps 146
17.4.2. Setting command-line arguments for container commands with ConfigMaps 148
17.4.3. Injecting content into a volume by using config maps 149
4
Table of Contents
5
OpenShift Container Platform 4.6 Authentication and authorization
1.1. USERS
A user in OpenShift Container Platform is an entity that can make requests to the OpenShift Container
Platform API. An OpenShift Container Platform User object represents an actor which can be granted
permissions in the system by adding roles to them or to their groups. Typically, this represents the
account of a developer or administrator that is interacting with OpenShift Container Platform.
Regular users This is the way most interactive OpenShift Container Platform users are represented.
Regular users are created automatically in the system upon first login or can be created
via the API. Regular users are represented with the User object. Examples: joe alice
System users Many of these are created automatically when the infrastructure is defined, mainly for
the purpose of enabling the infrastructure to interact with the API securely. They
include a cluster administrator (with access to everything), a per-node user, users for
use by routers and registries, and various others. Finally, there is an anonymous
system user that is used by default for unauthenticated requests. Examples:
system:admin system:openshift-registry system:node:node1.example.com
Service These are special system users associated with projects; some are created
accounts automatically when the project is first created, while project administrators can create
more for the purpose of defining access to the contents of each project. Service
accounts are represented with the ServiceAccount object. Examples:
system:serviceaccount:default:deployer
system:serviceaccount:foo:builder
Each user must authenticate in some way in order to access OpenShift Container Platform. API requests
with no authentication or invalid authentication are authenticated as requests by the anonymous
system user. Once authenticated, policy determines what the user is authorized to do.
1.2. GROUPS
A user can be assigned to one or more groups, each of which represent a certain set of users. Groups are
useful when managing authorization policies to grant permissions to multiple users at once, for example
allowing access to objects within a project, versus granting them to users individually.
In addition to explicitly defined groups, there are also system groups, or virtual groups, that are
automatically provisioned by the cluster.
6
CHAPTER 1. UNDERSTANDING AUTHENTICATION
system:authenticated:oa Automatically associated with all users authenticated with an OAuth access
uth token.
Obtained from the OpenShift Container Platform OAuth server using the
<namespace_route>/oauth/authorize and <namespace_route>/oauth/token endpoints.
The API server creates and distributes certificates to controllers to authenticate themselves.
Any request with an invalid access token or an invalid certificate is rejected by the authentication layer
with a 401 error.
If no access token or certificate is presented, the authentication layer assigns the system:anonymous
virtual user and the system:unauthenticated virtual group to the request. This allows the authorization
layer to determine which requests, if any, an anonymous user is allowed to make.
When a person requests a new OAuth token, the OAuth server uses the configured identity provider to
determine the identity of the person making the request.
It then determines what user that identity maps to, creates an access token for that user, and returns
the token for use.
Every request for an OAuth token must specify the OAuth client that will receive and use the token. The
7
OpenShift Container Platform 4.6 Authentication and authorization
Every request for an OAuth token must specify the OAuth client that will receive and use the token. The
following OAuth clients are automatically created when starting the OpenShift Container Platform API:
1. <namespace_route> refers to the namespace route. This is found by running the following
command:
NOTE
To prevent cross-site request forgery (CSRF) attacks against browser clients, only send
Basic authentication challenges with if a X-CSRF-Token header is on the request. Clients
that expect to receive Basic WWW-Authenticate challenges must set this header to a
non-empty value.
You can configure a request to the OpenShift Container Platform API to act as though it originated
from another user. For more information, see User impersonation in the Kubernetes documentation.
OpenShift Container Platform captures the following Prometheus system metrics during authentication
attempts:
8
CHAPTER 1. UNDERSTANDING AUTHENTICATION
openshift_auth_password_total counts the total number of oc login and web console login
attempts.
9
OpenShift Container Platform 4.6 Authentication and authorization
When a person requests a new OAuth token, the OAuth server uses the configured identity provider to
determine the identity of the person making the request.
It then determines what user that identity maps to, creates an access token for that user, and returns
the token for use.
When requesting an OAuth token using the implicit grant flow (response_type=token) with a client_id
configured to request WWW-Authenticate challenges (like openshift-challenging-client), these are
the possible server responses from /oauth/authorize, and how they should be handled:
302 Location header containing an Use the access_token value as the OAuth
access_token parameter in the URL token.
fragment (RFC 4.2.2)
302 Location header containing an error query Fail, optionally surfacing the error (and
parameter (RFC 4.1.2.1) optional error_description) query values to
the user.
302 Other Location header Follow the redirect, and process the result
using these rules.
10
CHAPTER 2. CONFIGURING THE INTERNAL OAUTH SERVER
Token Description
Authorize codes Short-lived tokens whose only use is to be exchanged for an access
token.
You can configure the default duration for both types of token. If necessary, you can override the
duration of the access token by using an OAuthClient object definition.
The OAuth client requesting token must provide its own grant strategy.
IMPORTANT
By default, tokens are only valid for 24 hours. Existing sessions expire after this time
elapses.
If the default time is insufficient, then this can be modified using the following procedure.
Procedure
1. Create a configuration file that contains the token duration options. The following file sets this
to 48 hours, twice the default.
apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
name: cluster
11
OpenShift Container Platform 4.6 Authentication and authorization
spec:
tokenConfig:
accessTokenMaxAgeSeconds: 172800 1
NOTE
Because you update the existing OAuth server, you must use the oc apply
command to apply the change.
$ oc apply -f </path/to/file.yaml>
$ oc describe oauth.config.openshift.io/cluster
Example output
...
Spec:
Token Config:
Access Token Max Age Seconds: 172800
...
NOTE
If the token inactivity timeout is also configured in your OAuth client, that value overrides
the timeout that is set in the internal OAuth server configuration.
Prerequisites
You have access to the cluster as a user with the cluster-admin role.
Procedure
12
CHAPTER 2. CONFIGURING THE INTERNAL OAUTH SERVER
apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
...
spec:
tokenConfig:
accessTokenInactivityTimeout: 400s 1
1 Set a value with the appropriate units, for example 400s for 400 seconds, or 30m for
30 minutes. The minimum allowed timeout value is 300s.
Do not continue to the next step until PROGRESSING is listed as False, as shown in the
following output:
Example output
3. Check that a new revision of the Kubernetes API server pods has rolled out. This will take several
minutes.
Do not continue to the next step until PROGRESSING is listed as False, as shown in the
following output:
Example output
Verification steps
3. Wait longer than the configured timeout without using the identity. In this procedure’s example,
wait longer than 400 seconds.
13
OpenShift Container Platform 4.6 Authentication and authorization
Example output
Thus, any application running inside the cluster can issue a GET request to
https://openshift.default.svc/.well-known/oauth-authorization-server to fetch the following
information:
{
"issuer": "https://<namespace_route>", 1
"authorization_endpoint": "https://<namespace_route>/oauth/authorize", 2
"token_endpoint": "https://<namespace_route>/oauth/token", 3
"scopes_supported": [ 4
"user:full",
"user:info",
"user:check-access",
"user:list-scoped-projects",
"user:list-projects"
],
"response_types_supported": [ 5
"code",
"token"
],
"grant_types_supported": [ 6
"authorization_code",
"implicit"
],
"code_challenge_methods_supported": [ 7
"plain",
"S256"
]
}
1 The authorization server’s issuer identifier, which is a URL that uses the https scheme and has no
query or fragment components. This is the location where .well-known RFC 5785 resources
containing information about the authorization server are published.
4 JSON array containing a list of the OAuth 2.0 RFC 6749 scope values that this authorization server
supports. Note that not all supported scope values are advertised.
14
CHAPTER 2. CONFIGURING THE INTERNAL OAUTH SERVER
5 JSON array containing a list of the OAuth 2.0 response_type values that this authorization server
supports. The array values used are the same as those used with the response_types parameter
6 JSON array containing a list of the OAuth 2.0 grant type values that this authorization server
supports. The array values used are the same as those used with the grant_types parameter
defined by OAuth 2.0 Dynamic Client Registration Protocol in RFC 7591.
7 JSON array containing a list of PKCE RFC 7636 code challenge methods supported by this
authorization server. Code challenge method values are used in the code_challenge_method
parameter defined in Section 4.3 of RFC 7636 . The valid code challenge method values are those
registered in the IANA PKCE Code Challenge Methods registry. See IANA OAuth Parameters.
A subset of these errors is related to service account OAuth configuration issues. These issues are
captured in events that can be viewed by non-administrator users. When encountering an unexpected
condition server error during OAuth, run oc get events to view these events under ServiceAccount.
The following example warns of a service account that is missing a proper OAuth redirect URI:
Example output
Running oc describe sa/<service_account_name> reports any OAuth events associated with the
given service account name.
Example output
Events:
FirstSeen LastSeen Count From SubObjectPath Type Reason
Message
--------- -------- ----- ---- ------------- -------- ------ -------
3m 3m 1 service-account-oauth-client-getter Warning
NoSAOAuthRedirectURIs system:serviceaccount:myproject:proxy has no redirectURIs; set
serviceaccounts.openshift.io/oauth-redirecturi.<some-value>=<redirect> or create a dynamic URI
using serviceaccounts.openshift.io/oauth-redirectreference.<some-value>=<reference>
15
OpenShift Container Platform 4.6 Authentication and authorization
Reason Message
NoSAOAuthRedirectURIs system:serviceaccount:myproject:proxy has no redirectURIs; set
serviceaccounts.openshift.io/oauth-redirecturi.<some-value>=<redirect> or create a dynamic URI
using serviceaccounts.openshift.io/oauth-redirectreference.<some-value>=<reference>
Reason Message
NoSAOAuthRedirectURIs [routes.route.openshift.io "<name>" not found,
system:serviceaccount:myproject:proxy has no redirectURIs; set serviceaccounts.openshift.io/oauth-
redirecturi.<some-value>=<redirect> or create a dynamic URI using
serviceaccounts.openshift.io/oauth-redirectreference.<some-value>=<reference>]
Reason Message
NoSAOAuthRedirectURIs [no kind "<name>" is registered for version "v1",
system:serviceaccount:myproject:proxy has no redirectURIs; set serviceaccounts.openshift.io/oauth-
redirecturi.<some-value>=<redirect> or create a dynamic URI using
serviceaccounts.openshift.io/oauth-redirectreference.<some-value>=<reference>]
Missing SA tokens
Reason Message
NoSAOAuthTokens system:serviceaccount:myproject:proxy has no tokens
16
CHAPTER 3. CONFIGURING OAUTH CLIENTS
1. <namespace_route> refers to the namespace route. This is found by running the following
command:
Procedure
1 The name of the OAuth client is used as the client_id parameter when making requests to
<namespace_route>/oauth/authorize and <namespace_route>/oauth/token.
4 The grantMethod is used to determine what action to take when this client requests
tokens and has not yet been granted access by the user. Specify auto to automatically
approve the grant and retry the request, or prompt to prompt the user to approve or deny
the grant.
NOTE
If the token inactivity timeout is also configured in the internal OAuth server
configuration, the timeout that is set in the OAuth client overrides that value.
Prerequisites
You have access to the cluster as a user with the cluster-admin role.
Procedure
1 Replace <oauth_client> with the OAuth client to configure, for example, console.
apiVersion: oauth.openshift.io/v1
grantMethod: auto
kind: OAuthClient
metadata:
...
accessTokenInactivityTimeoutSeconds: 600 1
Verification steps
1. Log in to the cluster with an identity from your IDP. Be sure to use the OAuth client that you just
18
CHAPTER 3. CONFIGURING OAUTH CLIENTS
1. Log in to the cluster with an identity from your IDP. Be sure to use the OAuth client that you just
configured.
3. Wait longer than the configured timeout without using the identity. In this procedure’s example,
wait longer than 600 seconds.
19
OpenShift Container Platform 4.6 Authentication and authorization
As an administrator, you can configure OAuth to specify an identity provider after you install your
cluster.
NOTE
OpenShift Container Platform user names containing /, :, and % are not supported.
HTPasswd Configure the htpasswd identity provider to validate user names and passwords
against a flat file generated using htpasswd .
Keystone Configure the keystone identity provider to integrate your OpenShift Container
Platform cluster with Keystone to enable shared authentication with an OpenStack
Keystone v3 server configured to store users in an internal database.
LDAP Configure the ldap identity provider to validate user names and passwords against an
LDAPv3 server, using simple bind authentication.
Request header Configure a request-header identity provider to identify users from request header
values, such as X-Remote-User. It is typically used in combination with an
authenticating proxy, which sets the request header value.
GitHub or GitHub Configure a github identity provider to validate user names and passwords against
Enterprise GitHub or GitHub Enterprise’s OAuth authentication server.
GitLab Configure a gitlab identity provider to use GitLab.com or any other GitLab instance as
an identity provider.
20
CHAPTER 4. UNDERSTANDING IDENTITY PROVIDER CONFIGURATION
Google Configure a google identity provider using Google’s OpenID Connect integration.
OpenID Connect Configure an oidc identity provider to integrate with an OpenID Connect identity
provider using an Authorization Code Flow.
Once an identity provider has been defined, you can use RBAC to define and apply permissions .
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.
Prerequisites
Procedure
Parameter Description
name The provider name is prefixed to provider user names to form an identity name.
21
OpenShift Container Platform 4.6 Authentication and authorization
Parameter Description
mappingMethod Defines how new identities are mapped to users when they log in. Enter one of the
following values:
claim
The default value. Provisions a user with the identity’s preferred user name. Fails if a
user with that user name is already mapped to another identity.
lookup
Looks up an existing identity, user identity mapping, and user, but does not
automatically provision users or identities. This allows cluster administrators to set
up identities and users manually, or using an external process. Using this method
requires you to manually provision users.
generate
Provisions a user with the identity’s preferred user name. If a user with the preferred
user name is already mapped to an existing identity, a unique user name is
generated. For example, myuser2. This method should not be used in combination
with external processes that require exact matches between OpenShift Container
Platform user names and identity provider user names, such as LDAP group sync.
add
Provisions a user with the identity’s preferred user name. If a user with that user
name already exists, the identity is mapped to the existing user, adding to any
existing identity mappings for the user. Required when multiple identity providers
are configured that identify the same set of users and map to the same user names.
NOTE
When adding or changing identity providers, you can map identities from the new
provider to existing users by setting the mappingMethod parameter to add.
apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
name: cluster
spec:
identityProviders:
- name: my_identity_provider 1
mappingMethod: claim 2
type: HTPasswd
htpasswd:
fileData:
name: htpass-secret 3
1 This provider name is prefixed to provider user names to form an identity name.
22
CHAPTER 4. UNDERSTANDING IDENTITY PROVIDER CONFIGURATION
2 Controls how mappings are established between this provider’s identities and User objects.
23
OpenShift Container Platform 4.6 Authentication and authorization
NOTE
OpenShift Container Platform user names containing /, :, and % are not supported.
To define an HTPasswd identity provider you must perform the following steps:
1. Create an htpasswd file to store the user and password information. Instructions are provided
for Linux and Windows.
Prerequisites
Have access to the htpasswd utility. On Red Hat Enterprise Linux this is available by installing
the httpd-tools package.
Procedure
1. Create or update your flat file with a user name and hashed password:
For example:
Example output
24
CHAPTER 5. CONFIGURING IDENTITY PROVIDERS
Prerequisites
Have access to htpasswd.exe. This file is included in the \bin directory of many Apache httpd
distributions.
Procedure
1. Create or update your flat file with a user name and hashed password:
For example:
Example output
Prerequisites
Procedure
Create an OpenShift Container Platform Secret object that contains the HTPasswd users file.
NOTE
The secret key containing the users file for the --from-file argument must be
named htpasswd, as shown in the above command.
25
OpenShift Container Platform 4.6 Authentication and authorization
HTPasswd CR
apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
name: cluster
spec:
identityProviders:
- name: my_htpasswd_provider 1
mappingMethod: claim 2
type: HTPasswd
htpasswd:
fileData:
name: htpass-secret 3
1 This provider name is prefixed to provider user names to form an identity name.
2 Controls how mappings are established between this provider’s identities and User objects.
Prerequisites
Procedure
$ oc apply -f </path/to/CR>
NOTE
If a CR does not exist, oc apply creates a new CR and might trigger the following
warning: Warning: oc apply should be used on resources created by either
oc create --save-config or oc apply. In this case you can safely ignore this
warning.
2. Log in to the cluster as a user from your identity provider, entering the password when
26
CHAPTER 5. CONFIGURING IDENTITY PROVIDERS
2. Log in to the cluster as a user from your identity provider, entering the password when
prompted.
$ oc login -u <username>
3. Confirm that the user logged in successfully, and display the user name.
$ oc whoami
Prerequisites
You have created a Secret object that contains the HTPasswd user file. This procedure
assumes that it is named htpass-secret.
You have configured an HTPasswd identity provider. This procedure assumes that it is named
my_htpasswd_provider.
You have access to the htpasswd utility. On Red Hat Enterprise Linux this is available by
installing the httpd-tools package.
Procedure
1. Retrieve the HTPasswd file from the htpass-secret Secret object and save the file to your file
system:
Example output
Example output
27
OpenShift Container Platform 4.6 Authentication and authorization
3. Replace the htpass-secret Secret object with the updated users in the users.htpasswd file:
4. If you removed one or more users, you must additionally remove existing resources for each
user.
Example output
Be sure to remove the user, otherwise the user can continue using their token as long as it
has not expired.
Example output
Prerequisites
Procedure
3. Under the Identity Providers section, select your identity provider from the Add drop-down
menu.
NOTE
You can specify multiple IDPs through the web console without overwriting existing IDPs.
28
CHAPTER 5. CONFIGURING IDENTITY PROVIDERS
users in an internal database. This configuration allows users to log in to OpenShift Container Platform
with their Keystone credentials.
Keystone is an OpenStack project that provides identity, token, catalog, and policy services.
You can configure the integration with Keystone so that the new OpenShift Container Platform users
are based on either the Keystone user names or unique Keystone IDs. With both methods, users log in
by entering their Keystone user name and password. Basing the OpenShift Container Platform users off
of the Keystone ID is more secure. If you delete a Keystone user and create a new Keystone user with
that user name, the new user might have access to the old user’s resources.
NOTE
OpenShift Container Platform user names containing /, :, and % are not supported.
You can define an OpenShift Container Platform Secret object containing a string by using the
following command.
You can define an OpenShift Container Platform Secret object containing the contents of a
file, such as a certificate file, by using the following command.
Define an OpenShift Container Platform ConfigMap object containing the certificate authority
by using the following command. The certificate authority must be stored in the ca.crt key of
the ConfigMap object.
29
OpenShift Container Platform 4.6 Authentication and authorization
Keystone CR
apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
name: cluster
spec:
identityProviders:
- name: keystoneidp 1
mappingMethod: claim 2
type: Keystone
keystone:
domainName: default 3
url: https://keystone.example.com:5000 4
ca: 5
name: ca-config-map
tlsClientCert: 6
name: client-cert-secret
tlsClientKey: 7
name: client-key-secret
1 This provider name is prefixed to provider user names to form an identity name.
2 Controls how mappings are established between this provider’s identities and User objects.
3 Keystone domain name. In Keystone, usernames are domain-specific. Only a single domain is
supported.
4 The URL to use to connect to the Keystone server (required). This must use https.
5 Optional: Reference to an OpenShift Container Platform ConfigMap object containing the PEM-
encoded certificate authority bundle to use in validating server certificates for the configured URL.
6 Optional: Reference to an OpenShift Container Platform Secret object containing the client
certificate to present when making requests to the configured URL.
7 Reference to an OpenShift Container Platform Secret object containing the key for the client
certificate. Required if tlsClientCert is specified.
Prerequisites
Procedure
30
CHAPTER 5. CONFIGURING IDENTITY PROVIDERS
$ oc apply -f </path/to/CR>
NOTE
If a CR does not exist, oc apply creates a new CR and might trigger the following
warning: Warning: oc apply should be used on resources created by either
oc create --save-config or oc apply. In this case you can safely ignore this
warning.
2. Log in to the cluster as a user from your identity provider, entering the password when
prompted.
$ oc login -u <username>
3. Confirm that the user logged in successfully, and display the user name.
$ oc whoami
NOTE
OpenShift Container Platform user names containing /, :, and % are not supported.
1. Generate a search filter by combining the attribute and filter in the configured url with the
user-provided user name.
2. Search the directory using the generated filter. If the search does not return exactly one entry,
deny access.
3. Attempt to bind to the LDAP server using the DN of the entry retrieved from the search, and
the user-provided password.
31
OpenShift Container Platform 4.6 Authentication and authorization
5. If the bind is successful, build an identity using the configured attributes as the identity, email
address, display name, and preferred user name.
The configured url is an RFC 2255 URL, which specifies the LDAP host and search parameters to use.
The syntax of the URL is:
ldap://host:port/basedn?attribute?scope?filter
ldap For regular LDAP, use the string ldap . For secure LDAP (LDAPS), useldaps instead.
host:port The name and port of the LDAP server. Defaults to localhost:389 for ldap and
localhost:636 for LDAPS.
basedn The DN of the branch of the directory where all searches should start from. At the very
least, this must be the top of your directory tree, but it could also specify a subtree in
the directory.
attribute The attribute to search for. Although RFC 2255 allows a comma-separated list of
attributes, only the first attribute will be used, no matter how many are provided. If no
attributes are provided, the default is to use uid. It is recommended to choose an
attribute that will be unique across all entries in the subtree you will be using.
scope The scope of the search. Can be either one or sub . If the scope is not provided, the
default is to use a scope of sub .
When doing searches, the attribute, filter, and provided user name are combined to create a search filter
that looks like:
(&(<filter>)(<attribute>=<username>))
ldap://ldap.example.com/o=Acme?cn?sub?(enabled=true)
When a client attempts to connect using a user name of bob, the resulting search filter will be (&
(enabled=true)(cn=bob)).
If the LDAP directory requires authentication to search, specify a bindDN and bindPassword to use to
perform the entry search.
32
CHAPTER 5. CONFIGURING IDENTITY PROVIDERS
Define an OpenShift Container Platform Secret object that contains the bindPassword field.
NOTE
The secret key containing the bindPassword for the --from-literal argument must
be called bindPassword, as shown in the above command.
Define an OpenShift Container Platform ConfigMap object containing the certificate authority
by using the following command. The certificate authority must be stored in the ca.crt key of
the ConfigMap object.
LDAP CR
apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
name: cluster
spec:
identityProviders:
- name: ldapidp 1
mappingMethod: claim 2
type: LDAP
ldap:
attributes:
id: 3
- dn
email: 4
- mail
name: 5
- cn
preferredUsername: 6
- uid
bindDN: "" 7
bindPassword: 8
name: ldap-secret
ca: 9
33
OpenShift Container Platform 4.6 Authentication and authorization
name: ca-config-map
insecure: false 10
url: "ldap://ldap.example.com/ou=users,dc=acme,dc=com?uid" 11
1 This provider name is prefixed to the returned user ID to form an identity name.
2 Controls how mappings are established between this provider’s identities and User objects.
3 List of attributes to use as the identity. First non-empty attribute is used. At least one attribute is
required. If none of the listed attribute have a value, authentication fails. Defined attributes are
retrieved as raw, allowing for binary values to be used.
4 List of attributes to use as the email address. First non-empty attribute is used.
5 List of attributes to use as the display name. First non-empty attribute is used.
6 List of attributes to use as the preferred user name when provisioning a user for this identity. First
non-empty attribute is used.
7 Optional DN to use to bind during the search phase. Must be set if bindPassword is defined.
8 Optional reference to an OpenShift Container Platform Secret object containing the bind
password. Must be set if bindDN is defined.
9 Optional: Reference to an OpenShift Container Platform ConfigMap object containing the PEM-
encoded certificate authority bundle to use in validating server certificates for the configured URL.
Only used when insecure is false.
10 When true, no TLS connection is made to the server. When false, ldaps:// URLs connect using TLS,
and ldap:// URLs are upgraded to TLS. This should be set to false when ldaps:// URLs are in use, as
these URLs always attempt to connect using TLS.
11 An RFC 2255 URL which specifies the LDAP host and search parameters to use.
NOTE
To whitelist users for an LDAP integration, use the lookup mapping method. Before a
login from LDAP would be allowed, a cluster administrator must create an Identity object
and a User object for each LDAP user.
Prerequisites
Procedure
34
CHAPTER 5. CONFIGURING IDENTITY PROVIDERS
$ oc apply -f </path/to/CR>
NOTE
If a CR does not exist, oc apply creates a new CR and might trigger the following
warning: Warning: oc apply should be used on resources created by either
oc create --save-config or oc apply. In this case you can safely ignore this
warning.
2. Log in to the cluster as a user from your identity provider, entering the password when
prompted.
$ oc login -u <username>
3. Confirm that the user logged in successfully, and display the user name.
$ oc whoami
NOTE
OpenShift Container Platform user names containing /, :, and % are not supported.
Because basic authentication is generic, you can use this identity provider for advanced authentication
configurations.
IMPORTANT
Basic authentication must use an HTTPS connection to the remote server to prevent
potential snooping of the user ID and password and man-in-the-middle attacks.
With basic authentication configured, users send their user name and password to OpenShift Container
Platform, which then validates those credentials against a remote server by making a server-to-server
request, passing the credentials as a basic authentication header. This requires users to send their
credentials to OpenShift Container Platform during login.
35
OpenShift Container Platform 4.6 Authentication and authorization
NOTE
This only works for user name/password login mechanisms, and OpenShift Container
Platform must be able to make network requests to the remote authentication server.
User names and passwords are validated against a remote URL that is protected by basic authentication
and returns JSON.
{"error":"Error message"}
{"sub":"userid"} 1
1 The subject must be unique to the authenticated user and must not be able to be modified.
A preferred user name using the preferred_username key. This is useful when the unique,
unchangeable subject is a database key or UID, and a more human-readable name exists. This is
used as a hint when provisioning the OpenShift Container Platform user for the authenticated
identity. For example:
You can define an OpenShift Container Platform Secret object containing a string by using the
following command.
You can define an OpenShift Container Platform Secret object containing the contents of a
file, such as a certificate file, by using the following command.
36
CHAPTER 5. CONFIGURING IDENTITY PROVIDERS
Define an OpenShift Container Platform ConfigMap object containing the certificate authority
by using the following command. The certificate authority must be stored in the ca.crt key of
the ConfigMap object.
Basic authentication CR
apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
name: cluster
spec:
identityProviders:
- name: basicidp 1
mappingMethod: claim 2
type: BasicAuth
basicAuth:
url: https://www.example.com/remote-idp 3
ca: 4
name: ca-config-map
tlsClientCert: 5
name: client-cert-secret
tlsClientKey: 6
name: client-key-secret
1 This provider name is prefixed to the returned user ID to form an identity name.
2 Controls how mappings are established between this provider’s identities and User objects.
4 Optional: Reference to an OpenShift Container Platform ConfigMap object containing the PEM-
encoded certificate authority bundle to use in validating server certificates for the configured URL.
5 Optional: Reference to an OpenShift Container Platform Secret object containing the client
certificate to present when making requests to the configured URL.
6 Reference to an OpenShift Container Platform Secret object containing the key for the client
certificate. Required if tlsClientCert is specified.
37
OpenShift Container Platform 4.6 Authentication and authorization
After you install your cluster, add an identity provider to it so your users can authenticate.
Prerequisites
Procedure
$ oc apply -f </path/to/CR>
NOTE
If a CR does not exist, oc apply creates a new CR and might trigger the following
warning: Warning: oc apply should be used on resources created by either
oc create --save-config or oc apply. In this case you can safely ignore this
warning.
2. Log in to the cluster as a user from your identity provider, entering the password when
prompted.
$ oc login -u <username>
3. Confirm that the user logged in successfully, and display the user name.
$ oc whoami
Example /etc/httpd/conf.d/login.conf
<VirtualHost *:443>
# CGI Scripts in here
DocumentRoot /var/www/cgi-bin
# SSL Directives
SSLEngine on
SSLCipherSuite PROFILE=SYSTEM
SSLProxyCipherSuite PROFILE=SYSTEM
SSLCertificateFile /etc/pki/tls/certs/localhost.crt
SSLCertificateKeyFile /etc/pki/tls/private/localhost.key
38
CHAPTER 5. CONFIGURING IDENTITY PROVIDERS
# Handles authentication
<Location /basic/login.cgi>
AuthType Basic
AuthName "Please Log In"
AuthBasicProvider file
AuthUserFile /etc/httpd/conf/passwords
Require valid-user
</Location>
</VirtualHost>
Example /var/www/cgi-bin/login.cgi
#!/bin/bash
echo "Content-Type: application/json"
echo ""
echo '{"sub":"userid", "name":"'$REMOTE_USER'"}'
exit 0
Example /var/www/cgi-bin/fail.cgi
#!/bin/bash
echo "Content-Type: application/json"
echo ""
echo '{"error": "Login failure"}'
exit 0
These are the requirements for the files you create on an Apache HTTPD web server:
login.cgi and fail.cgi must have proper SELinux contexts if SELinux is enabled: restorecon -
RFv /var/www/cgi-bin, or ensure that the context is httpd_sys_script_exec_t using ls -laZ.
login.cgi is only executed if your user successfully logs in per Require and Auth directives.
fail.cgi is executed if the user fails to log in, resulting in an HTTP 401 response.
Successful responses
39
OpenShift Container Platform 4.6 Authentication and authorization
{"sub":"userid"}
The subject must be unique to the authenticated user, and must not be able to be modified.
The preferred_username key is useful when the unique, unchangeable subject is a database
key or UID, and a more human-readable name exists. This is used as a hint when provisioning the
OpenShift Container Platform user for the authenticated identity.
Failed responses
A non-200 status or the presence of a non-empty "error" key indicates an error: {"error":"Error
message"}
NOTE
OpenShift Container Platform user names containing /, :, and % are not supported.
NOTE
40
CHAPTER 5. CONFIGURING IDENTITY PROVIDERS
NOTE
You can also use the request header identity provider for advanced configurations such
as the community-supported SAML authentication. Note that this solution is not
supported by Red Hat.
For users to authenticate using this identity provider, they must access
https://<namespace_route>/oauth/authorize (and subpaths) via an authenticating proxy. To
accomplish this, configure the OAuth server to redirect unauthenticated requests for OAuth tokens to
the proxy endpoint that proxies to https://<namespace_route>/oauth/authorize.
Set the provider.loginURL parameter to the authenticating proxy URL that will authenticate
interactive clients and then proxy the request to https://<namespace_route>/oauth/authorize.
Set the provider.challengeURL parameter to the authenticating proxy URL that will
authenticate clients expecting WWW-Authenticate challenges and then proxy the request to
https://<namespace_route>/oauth/authorize.
The provider.challengeURL and provider.loginURL parameters can include the following tokens in
the query portion of the URL:
${url} is replaced with the current URL, escaped to be safe in a query parameter.
For example: https://www.example.com/sso-login?then=${url}
IMPORTANT
As of OpenShift Container Platform 4.1, your proxy must support mutual TLS.
IMPORTANT
For more information on Red Hat Technology Preview features support scope, see
https://access.redhat.com/support/offerings/techpreview/.
The OpenShift CLI (oc) supports the Security Support Provider Interface (SSPI) to allow for SSO flows
on Microsft Windows. If you use the request header identity provider with a GSSAPI-enabled proxy to
connect an Active Directory server to OpenShift Container Platform, users can automatically
authenticate to OpenShift Container Platform by using the oc command line interface from a domain-
joined Microsoft Windows computer.
41
OpenShift Container Platform 4.6 Authentication and authorization
Define an OpenShift Container Platform ConfigMap object containing the certificate authority
by using the following command. The certificate authority must be stored in the ca.crt key of
the ConfigMap object.
Request header CR
apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
name: cluster
spec:
identityProviders:
- name: requestheaderidp 1
mappingMethod: claim 2
type: RequestHeader
requestHeader:
challengeURL: "https://www.example.com/challenging-proxy/oauth/authorize?${query}" 3
loginURL: "https://www.example.com/login-proxy/oauth/authorize?${query}" 4
ca: 5
name: ca-config-map
clientCommonNames: 6
- my-auth-proxy
headers: 7
- X-Remote-User
- SSO-User
emailHeaders: 8
- X-Remote-User-Email
nameHeaders: 9
- X-Remote-User-Display-Name
preferredUsernameHeaders: 10
- X-Remote-User-Login
1 This provider name is prefixed to the user name in the request header to form an identity name.
2 Controls how mappings are established between this provider’s identities and User objects.
3 Optional: URL to redirect unauthenticated /oauth/authorize requests to, that will authenticate
browser-based clients and then proxy their request to
https://<namespace_route>/oauth/authorize. The URL that proxies to
https://<namespace_route>/oauth/authorize must end with /authorize (with no trailing slash),
and also proxy subpaths, in order for OAuth approval flows to work properly. ${url} is replaced with
42
CHAPTER 5. CONFIGURING IDENTITY PROVIDERS
the current URL, escaped to be safe in a query parameter. ${query} is replaced with the current
query string. If this attribute is not defined, then loginURL must be used.
4 Optional: URL to redirect unauthenticated /oauth/authorize requests to, that will authenticate
clients which expect WWW-Authenticate challenges, and then proxy them to
https://<namespace_route>/oauth/authorize. ${url} is replaced with the current URL, escaped to
be safe in a query parameter. ${query} is replaced with the current query string. If this attribute is
not defined, then challengeURL must be used.
IMPORTANT
As of OpenShift Container Platform 4.1, the ca field is required for this identity
provider. This means that your proxy must support mutual TLS.
6 Optional: list of common names (cn). If set, a valid client certificate with a Common Name ( cn) in
the specified list must be presented before the request headers are checked for user names. If
empty, any Common Name is allowed. Can only be used in combination with ca.
7 Header names to check, in order, for the user identity. The first header containing a value is used as
the identity. Required, case-insensitive.
8 Header names to check, in order, for an email address. The first header containing a value is used as
the email address. Optional, case-insensitive.
9 Header names to check, in order, for a display name. The first header containing a value is used as
the display name. Optional, case-insensitive.
10 Header names to check, in order, for a preferred user name, if different than the immutable
identity determined from the headers specified in headers. The first header containing a value is
used as the preferred user name when provisioning. Optional, case-insensitive.
Prerequisites
Procedure
$ oc apply -f </path/to/CR>
NOTE
43
OpenShift Container Platform 4.6 Authentication and authorization
NOTE
If a CR does not exist, oc apply creates a new CR and might trigger the following
warning: Warning: oc apply should be used on resources created by either
oc create --save-config or oc apply. In this case you can safely ignore this
warning.
2. Log in to the cluster as a user from your identity provider, entering the password when
prompted.
$ oc login -u <username>
3. Confirm that the user logged in successfully, and display the user name.
$ oc whoami
Require the X-Csrf-Token header be set for all authentication requests using the challenge
flow.
Make sure only the /oauth/authorize endpoint and its subpaths are proxied; redirects must be
rewritten to allow the backend server to send the client to the correct location.
NOTE
The https://<namespace_route> address is the route to the OAuth server and can be
obtained by running oc get route -n openshift-authentication.
44
CHAPTER 5. CONFIGURING IDENTITY PROVIDERS
Prerequisites
Obtain the mod_auth_gssapi module from the Optional channel. You must have the following
packages installed on your local machine:
httpd
mod_ssl
mod_session
apr-util-openssl
mod_auth_gssapi
Generate a CA for validating requests that submit the trusted header. Define an OpenShift
Container Platform ConfigMap object containing the CA. This is done by running:
Generate a client certificate for the proxy. You can generate this certificate by using any x509
certificate tooling. The client certificate must be signed by the CA you generated for validating
requests that submit the trusted header.
Procedure
This proxy uses a client certificate to connect to the OAuth server, which is configured to trust the X-
Remote-User header.
1. Create the certificate for the Apache configuration. The certificate that you specify as the
SSLProxyMachineCertificateFile parameter value is the proxy’s client certificate that is used
to authenticate the proxy to the server. It must use TLS Web Client Authentication as the
extended key type.
2. Create the Apache configuration. Use the following template to provide your required settings
and values:
IMPORTANT
Carefully review the template and customize its contents to fit your environment.
# Nothing needs to be served over HTTP. This virtual host simply redirects to
# HTTPS.
<VirtualHost *:80>
DocumentRoot /var/www/html
RewriteEngine On
45
OpenShift Container Platform 4.6 Authentication and authorization
<VirtualHost *:443>
# This needs to match the certificates you generated. See the CN and X509v3
# Subject Alternative Name in the output of:
# openssl x509 -text -in /etc/pki/tls/certs/localhost.crt
ServerName www.example.com
DocumentRoot /var/www/html
SSLEngine on
SSLCertificateFile /etc/pki/tls/certs/localhost.crt
SSLCertificateKeyFile /etc/pki/tls/private/localhost.key
SSLCACertificateFile /etc/pki/CA/certs/ca.crt
SSLProxyEngine on
SSLProxyCACertificateFile /etc/pki/CA/certs/ca.crt
# It is critical to enforce client certificates. Otherwise, requests can
# spoof the X-Remote-User header by accessing the /oauth/authorize endpoint
# directly.
SSLProxyMachineCertificateFile /etc/pki/tls/certs/authproxy.pem
<Location /challenging-proxy/oauth/authorize>
# Insert your backend server name/ip here.
ProxyPass https://<namespace_route>/oauth/authorize
AuthName "SSO Login"
# For Kerberos
AuthType GSSAPI
Require valid-user
RequestHeader set X-Remote-User %{REMOTE_USER}s
GssapiCredStore keytab:/etc/httpd/protected/auth-proxy.keytab
# Enable the following if you want to allow users to fallback
# to password based authentication when they do not have a client
# configured to perform kerberos authentication.
GssapiBasicAuth On
# For ldap:
# AuthBasicProvider ldap
# AuthLDAPURL "ldap://ldap.example.com:389/ou=People,dc=my-domain,dc=com?uid?
sub?(objectClass=*)"
</Location>
<Location /login-proxy/oauth/authorize>
# Insert your backend server name/ip here.
ProxyPass https://<namespace_route>/oauth/authorize
46
CHAPTER 5. CONFIGURING IDENTITY PROVIDERS
GssapiCredStore keytab:/etc/httpd/protected/auth-proxy.keytab
# Enable the following if you want to allow users to fallback
# to password based authentication when they do not have a client
# configured to perform kerberos authentication.
GssapiBasicAuth On
</VirtualHost>
NOTE
identityProviders:
- name: requestheaderidp
type: RequestHeader
requestHeader:
challengeURL: "https://<namespace_route>/challenging-proxy/oauth/authorize?${query}"
loginURL: "https://<namespace_route>/login-proxy/oauth/authorize?${query}"
ca:
name: ca-config-map
clientCommonNames:
- my-auth-proxy
headers:
- X-Remote-User
a. Confirm that you can bypass the proxy by requesting a token by supplying the correct client
certificate and header:
b. Confirm that requests that do not supply the client certificate fail by requesting a token
without the certificate:
47
OpenShift Container Platform 4.6 Authentication and authorization
d. Run this command to show a 401 response with a WWW-Authenticate basic challenge, a
negotiate challenge, or both challenges:
e. Test logging in to the OpenShift CLI (oc) with and without using a Kerberos ticket:
# kdestroy -c cache_name 1
# oc login
# oc logout
# kinit
# oc login
If your configuration is correct, you are logged in without entering separate credentials.
You can use the GitHub integration to connect to either GitHub or GitHub Enterprise. For GitHub
Enterprise integrations, you must provide the hostname of your instance and can optionally provide a
ca certificate bundle to use in requests to the server.
NOTE
The following steps apply to both GitHub and GitHub Enterprise unless noted.
48
CHAPTER 5. CONFIGURING IDENTITY PROVIDERS
Configuring GitHub authentication allows users to log in to OpenShift Container Platform with their
GitHub credentials. To prevent anyone with any GitHub user ID from logging in to your OpenShift
Container Platform cluster, you can restrict access to only those in specific GitHub organizations.
NOTE
OpenShift Container Platform user names containing /, :, and % are not supported.
Procedure
For GitHub, click Settings → Developer settings → OAuth Apps → Register a new OAuth
application.
For GitHub Enterprise, go to your GitHub Enterprise home page and then click Settings →
Developer settings → Register a new application.
5. Enter the authorization callback URL, where the end of the URL contains the identity provider
name:
https://oauth-openshift.apps.<cluster-name>.<cluster-domain>/oauth2callback/<idp-provider-
name>
For example:
https://oauth-openshift.apps.example-openshift-cluster.com/oauth2callback/github/
6. Click Register application. GitHub provides a client ID and a client secret. You need these
values to complete the identity provider configuration.
You can define an OpenShift Container Platform Secret object containing a string by using the
following command.
49
OpenShift Container Platform 4.6 Authentication and authorization
You can define an OpenShift Container Platform Secret object containing the contents of a
file, such as a certificate file, by using the following command.
Define an OpenShift Container Platform ConfigMap object containing the certificate authority
by using the following command. The certificate authority must be stored in the ca.crt key of
the ConfigMap object.
GitHub CR
apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
name: cluster
spec:
identityProviders:
- name: githubidp 1
mappingMethod: claim 2
type: GitHub
github:
ca: 3
name: ca-config-map
clientID: {...} 4
clientSecret: 5
name: github-secret
hostname: ... 6
organizations: 7
- myorganization1
- myorganization2
teams: 8
- myorganization1/team-a
- myorganization2/team-b
1 This provider name is prefixed to the GitHub numeric user ID to form an identity name. It is also
used to build the callback URL.
50
CHAPTER 5. CONFIGURING IDENTITY PROVIDERS
2 Controls how mappings are established between this provider’s identities and User objects.
3 Optional: Reference to an OpenShift Container Platform ConfigMap object containing the PEM-
encoded certificate authority bundle to use in validating server certificates for the configured URL.
Only for use in GitHub Enterprise with a non-publicly trusted root certificate.
4 The client ID of a registered GitHub OAuth application. The application must be configured with a
callback URL of https://oauth-openshift.apps.<cluster-name>.<cluster-
domain>/oauth2callback/<idp-provider-name>.
5 Reference to an OpenShift Container Platform Secret object containing the client secret issued by
GitHub.
6 For GitHub Enterprise, you must provide the host name of your instance, such as example.com.
This value must match the GitHub Enterprise hostname value in in the /setup/settings file and
cannot include a port number. If this value is not set, then either teams or organizations must be
defined. For GitHub, omit this parameter.
7 The list of organizations. Either the organizations or teams field must be set unless the hostname
field is set, or if mappingMethod is set to lookup. Cannot be used in combination with the teams
field.
8 The list of teams. Either the teams or organizations field must be set unless the hostname field is
set, or if mappingMethod is set to lookup. Cannot be used in combination with the organizations
field.
NOTE
If organizations or teams is specified, only GitHub users that are members of at least
one of the listed organizations will be allowed to log in. If the GitHub OAuth application
configured in clientID is not owned by the organization, an organization owner must grant
third-party access in order to use this option. This can be done during the first GitHub
login by the organization’s administrator, or from the GitHub organization settings.
Prerequisites
Procedure
$ oc apply -f </path/to/CR>
NOTE
51
OpenShift Container Platform 4.6 Authentication and authorization
NOTE
If a CR does not exist, oc apply creates a new CR and might trigger the following
warning: Warning: oc apply should be used on resources created by either
oc create --save-config or oc apply. In this case you can safely ignore this
warning.
You can also access this page from the web console by navigating to (?) Help → Command
Line Tools → Copy Login Command.
$ oc login --token=<token>
NOTE
This identity provider does not support logging in with a user name and password.
4. Confirm that the user logged in successfully, and display the user name.
$ oc whoami
NOTE
OpenShift Container Platform user names containing /, :, and % are not supported.
You can define an OpenShift Container Platform Secret object containing a string by using the
following command.
52
CHAPTER 5. CONFIGURING IDENTITY PROVIDERS
You can define an OpenShift Container Platform Secret object containing the contents of a
file, such as a certificate file, by using the following command.
Define an OpenShift Container Platform ConfigMap object containing the certificate authority
by using the following command. The certificate authority must be stored in the ca.crt key of
the ConfigMap object.
GitLab CR
apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
name: cluster
spec:
identityProviders:
- name: gitlabidp 1
mappingMethod: claim 2
type: GitLab
gitlab:
clientID: {...} 3
clientSecret: 4
name: gitlab-secret
url: https://gitlab.com 5
ca: 6
name: ca-config-map
1 This provider name is prefixed to the GitLab numeric user ID to form an identity name. It is also
used to build the callback URL.
2 Controls how mappings are established between this provider’s identities and User objects.
3 The client ID of a registered GitLab OAuth application. The application must be configured with a
callback URL of https://oauth-openshift.apps.<cluster-name>.<cluster-
domain>/oauth2callback/<idp-provider-name>.
4 Reference to an OpenShift Container Platform Secret object containing the client secret issued by
GitLab.
53
OpenShift Container Platform 4.6 Authentication and authorization
5 The host URL of a GitLab provider. This could either be https://gitlab.com/ or any other self
hosted instance of GitLab.
6 Optional: Reference to an OpenShift Container Platform ConfigMap object containing the PEM-
encoded certificate authority bundle to use in validating server certificates for the configured URL.
Prerequisites
Procedure
$ oc apply -f </path/to/CR>
NOTE
If a CR does not exist, oc apply creates a new CR and might trigger the following
warning: Warning: oc apply should be used on resources created by either
oc create --save-config or oc apply. In this case you can safely ignore this
warning.
2. Log in to the cluster as a user from your identity provider, entering the password when
prompted.
$ oc login -u <username>
3. Confirm that the user logged in successfully, and display the user name.
$ oc whoami
NOTE
54
CHAPTER 5. CONFIGURING IDENTITY PROVIDERS
WARNING
Using Google as an identity provider allows any Google user to authenticate to your
server. You can limit authentication to members of a specific hosted domain with
the hostedDomain configuration attribute.
NOTE
OpenShift Container Platform user names containing /, :, and % are not supported.
You can define an OpenShift Container Platform Secret object containing a string by using the
following command.
You can define an OpenShift Container Platform Secret object containing the contents of a
file, such as a certificate file, by using the following command.
Google CR
apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
name: cluster
spec:
identityProviders:
- name: googleidp 1
mappingMethod: claim 2
type: Google
google:
clientID: {...} 3
55
OpenShift Container Platform 4.6 Authentication and authorization
clientSecret: 4
name: google-secret
hostedDomain: "example.com" 5
1 This provider name is prefixed to the Google numeric user ID to form an identity name. It is also
used to build the redirect URL.
2 Controls how mappings are established between this provider’s identities and User objects.
3 The client ID of a registered Google project. The project must be configured with a redirect URI of
https://oauth-openshift.apps.<cluster-name>.<cluster-domain>/oauth2callback/<idp-
provider-name>.
4 Reference to an OpenShift Container Platform Secret object containing the client secret issued by
Google.
5 A hosted domain used to restrict sign-in accounts. Optional if the lookup mappingMethod is
used. If empty, any Google account is allowed to authenticate.
Prerequisites
Procedure
$ oc apply -f </path/to/CR>
NOTE
If a CR does not exist, oc apply creates a new CR and might trigger the following
warning: Warning: oc apply should be used on resources created by either
oc create --save-config or oc apply. In this case you can safely ignore this
warning.
You can also access this page from the web console by navigating to (?) Help → Command
Line Tools → Copy Login Command.
56
CHAPTER 5. CONFIGURING IDENTITY PROVIDERS
$ oc login --token=<token>
NOTE
This identity provider does not support logging in with a user name and password.
4. Confirm that the user logged in successfully, and display the user name.
$ oc whoami
You can configure Red Hat Single Sign-On as an OpenID Connect identity provider for OpenShift
Container Platform.
IMPORTANT
NOTE
By default, the openid scope is requested. If required, extra scopes can be specified in the extraScopes
field.
Claims are read from the JWT id_token returned from the OpenID identity provider and, if specified,
from the JSON returned by the UserInfo URL.
At least one claim must be configured to use as the user’s identity. The standard identity claim is sub.
You can also indicate which claims to use as the user’s preferred user name, display name, and email
address. If multiple claims are specified, the first one with a non-empty value is used. The standard
claims are:
Claim Description
sub Short for "subject identifier." The remote identity for the user at the
issuer.
preferred_username The preferred user name when provisioning a user. A shorthand name
that the user wants to be referred to as, such as janedoe . Typically a
value that corresponding to the user’s login or username in the
authentication system, such as username or email.
57
OpenShift Container Platform 4.6 Authentication and authorization
Claim Description
NOTE
Using an OpenID Connect identity provider requires users to get a token using
<master>/oauth/token/request to use with command-line tools.
NOTE
OpenShift Container Platform user names containing /, :, and % are not supported.
You can define an OpenShift Container Platform Secret object containing a string by using the
following command.
You can define an OpenShift Container Platform Secret object containing the contents of a
file, such as a certificate file, by using the following command.
Define an OpenShift Container Platform ConfigMap object containing the certificate authority
by using the following command. The certificate authority must be stored in the ca.crt key of
the ConfigMap object.
58
CHAPTER 5. CONFIGURING IDENTITY PROVIDERS
If you must specify a custom certificate bundle, extra scopes, extra authorization request parameters, or
a userInfo URL, use the full OpenID Connect CR.
apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
name: cluster
spec:
identityProviders:
- name: oidcidp 1
mappingMethod: claim 2
type: OpenID
openID:
clientID: ... 3
clientSecret: 4
name: idp-secret
claims: 5
preferredUsername:
- preferred_username
name:
- name
email:
- email
issuer: https://www.idp-issuer.com 6
1 This provider name is prefixed to the value of the identity claim to form an identity name. It is also
used to build the redirect URL.
2 Controls how mappings are established between this provider’s identities and User objects.
3 The client ID of a client registered with the OpenID provider. The client must be allowed to redirect
to https://oauth-openshift.apps.<cluster_name>.
<cluster_domain>/oauth2callback/<idp_provider_name>.
4 Reference to an OpenShift Container Platform Secret object containing the client secret.
5 List of claims to use as the identity. First non-empty claim is used. At least one claim is required. If
none of the listed claims have a value, authentication fails. For example, this uses the value of the
sub claim in the returned id_token as the user’s identity.
6 Issuer Identifier described in the OpenID spec. Must use https without query or fragment
component.
apiVersion: config.openshift.io/v1
kind: OAuth
59
OpenShift Container Platform 4.6 Authentication and authorization
metadata:
name: cluster
spec:
identityProviders:
- name: oidcidp
mappingMethod: claim
type: OpenID
openID:
clientID: ...
clientSecret:
name: idp-secret
ca: 1
name: ca-config-map
extraScopes: 2
- email
- profile
extraAuthorizeParameters: 3
include_granted_scopes: "true"
claims:
preferredUsername: 4
- preferred_username
- email
name: 5
- nickname
- given_name
- name
email: 6
- custom_email_claim
- email
issuer: https://www.idp-issuer.com
1 Optional: Reference to an OpenShift Container Platform config map containing the PEM-encoded
certificate authority bundle to use in validating server certificates for the configured URL.
2 Optional list of scopes to request, in addition to the openid scope, during the authorization token
request.
4 List of claims to use as the preferred user name when provisioning a user for this identity. First non-
empty claim is used.
5 List of claims to use as the display name. First non-empty claim is used.
6 List of claims to use as the email address. First non-empty claim is used.
Prerequisites
60
CHAPTER 5. CONFIGURING IDENTITY PROVIDERS
Procedure
$ oc apply -f </path/to/CR>
NOTE
If a CR does not exist, oc apply creates a new CR and might trigger the following
warning: Warning: oc apply should be used on resources created by either
oc create --save-config or oc apply. In this case you can safely ignore this
warning.
You can also access this page from the web console by navigating to (?) Help → Command
Line Tools → Copy Login Command.
$ oc login --token=<token>
NOTE
Some OpenID Connect identity providers support logging in with a user name
and password.
4. Confirm that the user logged in successfully, and display the user name.
$ oc whoami
Prerequisites
Procedure
3. Under the Identity Providers section, select your identity provider from the Add drop-down
61
OpenShift Container Platform 4.6 Authentication and authorization
3. Under the Identity Providers section, select your identity provider from the Add drop-down
menu.
NOTE
You can specify multiple IDPs through the web console without overwriting existing IDPs.
62
CHAPTER 6. USING RBAC TO DEFINE AND APPLY PERMISSIONS
Cluster administrators 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 Description
object
Rules Sets of permitted verbs on a set of objects. For example, whether a user or service
account can create pods.
Roles Collections of rules. You can associate, or bind, users and groups to multiple roles.
There are two levels of RBAC roles and bindings that control authorization:
Cluster RBAC Roles and bindings that are applicable across all projects. Cluster roles exist cluster-
wide, and cluster role bindings can reference only cluster roles.
Local RBAC Roles and bindings that are scoped to a given project. While local roles exist only in a
single project, local role bindings can reference both cluster and local roles.
A cluster role binding is a binding that exists at the cluster level. A role binding exists at the project level.
The cluster role view must be bound to a user using a local role binding for that user to view the project.
Create local roles only if a cluster role does not provide the set of permissions needed for a particular
situation.
This two-level hierarchy allows reuse across multiple projects through the cluster roles while allowing
customization inside of individual projects through local roles.
During evaluation, both the cluster role bindings and the local role bindings are used. For example:
63
OpenShift Container Platform 4.6 Authentication and authorization
3. Deny by default.
admin A project manager. If used in a local binding, an admin has rights to view any resource
in the project and modify any resource in the project except for quota.
basic-user A user that can get basic information about projects and users.
cluster-admin A super-user that can perform any action in any project. When bound to a user with a
local binding, they have full control over quota and every action on every resource in the
project.
edit A user that can modify most objects in a project but does not have the power to view or
modify roles or bindings.
view A user who cannot make any modifications, but can see most objects in a project. They
cannot view or modify roles or bindings.
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.
64
CHAPTER 6. USING RBAC TO DEFINE AND APPLY PERMISSIONS
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, or watch.
Bindings
The full list of bindings, the associations between users or groups with a role.
1. The identity and the project-scoped action is used to find all bindings that apply to the user or
their groups.
65
OpenShift Container Platform 4.6 Authentication and authorization
TIP
Remember that users and groups can be associated with, or bound to, multiple roles at the same time.
Project administrators can use the CLI to view local roles and bindings, including a matrix of the verbs
and resources each are associated with.
IMPORTANT
The cluster role bound to the project administrator is limited in a project through a local
binding. It is not bound cluster-wide like the cluster roles granted to the cluster-admin or
system:admin.
Cluster roles are roles defined at the cluster level but can be bound either at the cluster
level or at the project level.
The default admin, edit, view, and cluster-reader cluster roles support cluster role aggregation , where
the cluster rules for each role are dynamically updated as new rules are created. This feature is relevant
only if you extend the Kubernetes API by creating custom resources.
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.
The mandatory name is 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 displayName is how the project is displayed in the web console (defaults to
66
CHAPTER 6. USING RBAC TO DEFINE AND APPLY PERMISSIONS
The optional displayName is how the project is displayed in the web console (defaults to
name).
The optional description can be a more detailed description of the project and is also visible in
the web console.
Object Description
Policies Rules for which users can or cannot perform actions on objects.
Service Service accounts act automatically with designated access to objects in the project.
accounts
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.
NOTE
You cannot assign an SCC to pods created in one of the default namespaces: default,
kube-system, kube-public, openshift-node, openshift-infra, and openshift. You cannot
use these namespaces for running pods or services.
Prerequisites
Users with the cluster-admin default cluster role bound cluster-wide can perform any action on any
resource, including viewing cluster roles and bindings.
67
OpenShift Container Platform 4.6 Authentication and authorization
Procedure
$ oc describe clusterrole.rbac
Example output
Name: admin
Labels: kubernetes.io/bootstrapping=rbac-defaults
Annotations: rbac.authorization.kubernetes.io/autoupdate: true
PolicyRule:
Resources Non-Resource URLs Resource Names Verbs
--------- ----------------- -------------- -----
.packages.apps.redhat.com [] [] [* create update
patch delete get list watch]
imagestreams [] [] [create delete
deletecollection get list patch update watch create get list watch]
imagestreams.image.openshift.io [] [] [create delete
deletecollection get list patch update watch create get list watch]
secrets [] [] [create delete deletecollection
get list patch update watch get list watch create delete deletecollection patch update]
buildconfigs/webhooks [] [] [create delete
deletecollection get list patch update watch get list watch]
buildconfigs [] [] [create delete
deletecollection get list patch update watch get list watch]
buildlogs [] [] [create delete deletecollection
get list patch update watch get list watch]
deploymentconfigs/scale [] [] [create delete
deletecollection get list patch update watch get list watch]
deploymentconfigs [] [] [create delete
deletecollection get list patch update watch get list watch]
imagestreamimages [] [] [create delete
deletecollection get list patch update watch get list watch]
imagestreammappings [] [] [create delete
deletecollection get list patch update watch get list watch]
imagestreamtags [] [] [create delete
deletecollection get list patch update watch get list watch]
processedtemplates [] [] [create delete
deletecollection get list patch update watch get list watch]
routes [] [] [create delete deletecollection
get list patch update watch get list watch]
templateconfigs [] [] [create delete
deletecollection get list patch update watch get list watch]
templateinstances [] [] [create delete
deletecollection get list patch update watch get list watch]
templates [] [] [create delete
deletecollection get list patch update watch get list watch]
deploymentconfigs.apps.openshift.io/scale [] [] [create delete
deletecollection get list patch update watch get list watch]
deploymentconfigs.apps.openshift.io [] [] [create delete
deletecollection get list patch update watch get list watch]
buildconfigs.build.openshift.io/webhooks [] [] [create delete
deletecollection get list patch update watch get list watch]
buildconfigs.build.openshift.io [] [] [create delete
deletecollection get list patch update watch get list watch]
68
CHAPTER 6. USING RBAC TO DEFINE AND APPLY PERMISSIONS
69
OpenShift Container Platform 4.6 Authentication and authorization
70
CHAPTER 6. USING RBAC TO DEFINE AND APPLY PERMISSIONS
deploymentconfigs/rollback [] [] [create]
imagestreamimports [] [] [create]
localresourceaccessreviews [] [] [create]
localsubjectaccessreviews [] [] [create]
podsecuritypolicyreviews [] [] [create]
podsecuritypolicyselfsubjectreviews [] [] [create]
podsecuritypolicysubjectreviews [] [] [create]
resourceaccessreviews [] [] [create]
routes/custom-host [] [] [create]
subjectaccessreviews [] [] [create]
subjectrulesreviews [] [] [create]
deploymentconfigrollbacks.apps.openshift.io [] [] [create]
deploymentconfigs.apps.openshift.io/instantiate [] [] [create]
deploymentconfigs.apps.openshift.io/rollback [] [] [create]
localsubjectaccessreviews.authorization.k8s.io [] [] [create]
localresourceaccessreviews.authorization.openshift.io [] [] [create]
localsubjectaccessreviews.authorization.openshift.io [] [] [create]
resourceaccessreviews.authorization.openshift.io [] [] [create]
subjectaccessreviews.authorization.openshift.io [] [] [create]
subjectrulesreviews.authorization.openshift.io [] [] [create]
buildconfigs.build.openshift.io/instantiate [] [] [create]
buildconfigs.build.openshift.io/instantiatebinary [] [] [create]
builds.build.openshift.io/clone [] [] [create]
imagestreamimports.image.openshift.io [] [] [create]
routes.route.openshift.io/custom-host [] [] [create]
podsecuritypolicyreviews.security.openshift.io [] [] [create]
podsecuritypolicyselfsubjectreviews.security.openshift.io [] [] [create]
podsecuritypolicysubjectreviews.security.openshift.io [] [] [create]
jenkins.build.openshift.io [] [] [edit view view admin
edit view]
builds [] [] [get create delete
deletecollection get list patch update watch get list watch]
builds.build.openshift.io [] [] [get create delete
deletecollection get list patch update watch get list watch]
projects [] [] [get delete get delete get patch
update]
projects.project.openshift.io [] [] [get delete get delete
get patch update]
namespaces [] [] [get get list watch]
pods/attach [] [] [get list watch create delete
deletecollection patch update]
pods/exec [] [] [get list watch create delete
deletecollection patch update]
pods/portforward [] [] [get list watch create
delete deletecollection patch update]
pods/proxy [] [] [get list watch create delete
deletecollection patch update]
services/proxy [] [] [get list watch create delete
deletecollection patch update]
routes/status [] [] [get list watch update]
routes.route.openshift.io/status [] [] [get list watch update]
appliedclusterresourcequotas [] [] [get list watch]
bindings [] [] [get list watch]
builds/log [] [] [get list watch]
deploymentconfigs/log [] [] [get list watch]
deploymentconfigs/status [] [] [get list watch]
71
OpenShift Container Platform 4.6 Authentication and authorization
Name: basic-user
Labels: <none>
Annotations: openshift.io/description: A user that can get basic information about projects.
rbac.authorization.kubernetes.io/autoupdate: true
PolicyRule:
Resources Non-Resource URLs Resource Names Verbs
--------- ----------------- -------------- -----
selfsubjectrulesreviews [] [] [create]
selfsubjectaccessreviews.authorization.k8s.io [] [] [create]
selfsubjectrulesreviews.authorization.openshift.io [] [] [create]
clusterroles.rbac.authorization.k8s.io [] [] [get list watch]
clusterroles [] [] [get list]
clusterroles.authorization.openshift.io [] [] [get list]
storageclasses.storage.k8s.io [] [] [get list]
users [] [~] [get]
users.user.openshift.io [] [~] [get]
projects [] [] [list watch]
projects.project.openshift.io [] [] [list watch]
projectrequests [] [] [list]
projectrequests.project.openshift.io [] [] [list]
Name: cluster-admin
Labels: kubernetes.io/bootstrapping=rbac-defaults
Annotations: rbac.authorization.kubernetes.io/autoupdate: true
PolicyRule:
Resources Non-Resource URLs Resource Names Verbs
--------- ----------------- -------------- -----
*.* [] [] [*]
[*] [] [*]
...
72
CHAPTER 6. USING RBAC TO DEFINE AND APPLY PERMISSIONS
2. To view the current set of cluster role bindings, which shows the users and groups that are
bound to various roles:
$ oc describe clusterrolebinding.rbac
Example output
Name: alertmanager-main
Labels: <none>
Annotations: <none>
Role:
Kind: ClusterRole
Name: alertmanager-main
Subjects:
Kind Name Namespace
---- ---- ---------
ServiceAccount alertmanager-main openshift-monitoring
Name: basic-users
Labels: <none>
Annotations: rbac.authorization.kubernetes.io/autoupdate: true
Role:
Kind: ClusterRole
Name: basic-user
Subjects:
Kind Name Namespace
---- ---- ---------
Group system:authenticated
Name: cloud-credential-operator-rolebinding
Labels: <none>
Annotations: <none>
Role:
Kind: ClusterRole
Name: cloud-credential-operator-role
Subjects:
Kind Name Namespace
---- ---- ---------
ServiceAccount default openshift-cloud-credential-operator
Name: cluster-admin
Labels: kubernetes.io/bootstrapping=rbac-defaults
Annotations: rbac.authorization.kubernetes.io/autoupdate: true
Role:
Kind: ClusterRole
Name: cluster-admin
Subjects:
Kind Name Namespace
---- ---- ---------
Group system:masters
73
OpenShift Container Platform 4.6 Authentication and authorization
Name: cluster-admins
Labels: <none>
Annotations: rbac.authorization.kubernetes.io/autoupdate: true
Role:
Kind: ClusterRole
Name: cluster-admin
Subjects:
Kind Name Namespace
---- ---- ---------
Group system:cluster-admins
User system:admin
Name: cluster-api-manager-rolebinding
Labels: <none>
Annotations: <none>
Role:
Kind: ClusterRole
Name: cluster-api-manager-role
Subjects:
Kind Name Namespace
---- ---- ---------
ServiceAccount default openshift-machine-api
...
Prerequisites
Users with the cluster-admin default cluster role bound cluster-wide can perform any
action on any resource, including viewing local roles and bindings.
Users with the admin default cluster role bound locally can view and manage roles and
bindings in that project.
Procedure
1. 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
2. To view the local role bindings for a different project, add the -n flag to the command:
Example output
74
CHAPTER 6. USING RBAC TO DEFINE AND APPLY PERMISSIONS
Name: 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
75
OpenShift Container Platform 4.6 Authentication and authorization
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.
Procedure
For example, you can add the admin role to the alice user in joe project by running:
2. View the local role bindings and verify the addition in the output:
For example, to view the local role bindings for the joe project:
Example output
Name: 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 1
Name: system:deployers
76
CHAPTER 6. USING RBAC TO DEFINE AND APPLY PERMISSIONS
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
Procedure
77
OpenShift Container Platform 4.6 Authentication and authorization
For example, to create a local role that allows a user to view pods in the blue project, run the
following command:
Procedure
For example, to create a cluster role that allows a user to view pods, run the following command:
You can use the following commands for local RBAC management.
78
CHAPTER 6. USING RBAC TO DEFINE AND APPLY PERMISSIONS
Command Description
$ oc adm policy who-can <verb> <resource> Indicates which users can perform an action on a
resource.
$ oc adm policy add-role-to-user <role> Binds a specified role to specified users in the
<username> current project.
$ oc adm policy remove-role-from-user Removes a given role from specified users in the
<role> <username> current project.
$ oc adm policy remove-user <username> Removes specified users and all of their roles in the
current project.
$ oc adm policy add-role-to-group <role> Binds a given role to specified groups in the current
<groupname> project.
$ oc adm policy remove-role-from-group Removes a given role from specified groups in the
<role> <groupname> current project.
$ oc adm policy remove-group <groupname> Removes specified groups and all of their roles in the
current project.
Command Description
$ oc adm policy add-cluster-role-to-user Binds a given role to specified users for all projects in
<role> <username> the cluster.
$ oc adm policy remove-cluster-role-from- Removes a given role from specified users for all
user <role> <username> projects in the cluster.
$ oc adm policy add-cluster-role-to-group Binds a given role to specified groups for all projects
<role> <groupname> in the cluster.
$ oc adm policy remove-cluster-role-from- Removes a given role from specified groups for all
group <role> <groupname> projects in the cluster.
79
OpenShift Container Platform 4.6 Authentication and authorization
Prerequisites
Procedure
80
CHAPTER 7. REMOVING THE KUBEADMIN USER
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:
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.
Prerequisites
Procedure
81
OpenShift Container Platform 4.6 Authentication and authorization
You construct user agents for the OpenShift Container Platform CLI from a set of values within
OpenShift Container Platform:
<command> = oc
<version> = The client version. For example, v4.3.0. Requests made against the Kubernetes API
at /api receive the Kubernetes version, while requests made against the OpenShift Container
Platform API at /oapi receive the OpenShift Container Platform version (as specified by oc
version)
<platform> = linux
<architecture> = amd64
<git_commit> = The Git commit of the client version (for example, f034127)
Procedure
Modify the master configuration file to include the user agent configuration. For example, the
following user agent denies the Kubernetes 1.2 client binary, OKD 1.1.3 binary, and the POST and
PUT httpVerbs:
policyConfig:
userAgentMatchingConfig:
defaultRejectionMessage: "Your client is too old. Go to https://example.org to update it."
deniedClients:
- regex: '\w+/v(?:(?:1\.1\.1)|(?:1\.0\.1)) \(.+/.+\) openshift/\w{7}'
- regex: '\w+/v(?:1\.1\.3) \(.+/.+\) openshift/\w{7}'
httpVerbs:
- POST
82
CHAPTER 8. CONFIGURING THE USER AGENT
- PUT
- regex: '\w+/v1\.2\.0 \(.+/.+\) kubernetes/\w{7}'
httpVerbs:
- POST
- PUT
requiredClients: null
The following example denies clients that do not exactly match an expected client:
policyConfig:
userAgentMatchingConfig:
defaultRejectionMessage: "Your client is too old. Go to https://example.org to update it."
deniedClients: []
requiredClients:
- regex: '\w+/v1\.1\.3 \(.+/.+\) openshift/\w{7}'
- regex: '\w+/v1\.2\.0 \(.+/.+\) kubernetes/\w{7}'
httpVerbs:
- POST
- PUT
83
OpenShift Container Platform 4.6 Authentication and authorization
When you use the OpenShift Container Platform CLI or web console, your API token authenticates you
to the API. You can associate a component with a service account so that they can access the API
without using a regular user’s credentials. For example, service accounts can allow:
Each service account’s user name is derived from its project and name:
system:serviceaccount:<project>:<name>
Group Description
An API token
The generated API token and registry credentials do not expire, but you can revoke them by deleting
the secret. When you delete the secret, a new one is automatically generated to take its place.
Procedure
$ oc get sa
Example output
84
CHAPTER 9. UNDERSTANDING AND CREATING SERVICE ACCOUNTS
$ oc create sa <service_account_name> 1
Example output
$ oc describe sa robot
Example output
Name: robot
Namespace: project1
Labels: <none>
Annotations: <none>
Tokens: robot-token-f4khf
robot-token-z8h44
You can modify the service accounts for the current project. For example, to add the view role
to the robot service account in the top-secret project:
You can also grant access to a specific service account in a project. For example, from the
project to which the service account belongs, use the -z flag and specify the
<service_account_name>
IMPORTANT
85
OpenShift Container Platform 4.6 Authentication and authorization
IMPORTANT
If you want to grant access to a specific service account in a project, use the -z
flag. Using this flag helps prevent typos and ensures that access is granted to
only the specified service account.
To modify a different namespace, you can use the -n option to indicate the project namespace
it applies to, as shown in the following examples.
For example, to allow all service accounts in all projects to view resources in the top-secret
project:
To allow all service accounts in the managers project to edit resources in the top-secret
project:
86
CHAPTER 10. USING SERVICE ACCOUNTS IN APPLICATIONS
When you use the OpenShift Container Platform CLI or web console, your API token authenticates you
to the API. You can associate a component with a service account so that they can access the API
without using a regular user’s credentials. For example, service accounts can allow:
Each service account’s user name is derived from its project and name:
system:serviceaccount:<project>:<name>
Group Description
An API token
The generated API token and registry credentials do not expire, but you can revoke them by deleting
the secret. When you delete the secret, a new one is automatically generated to take its place.
87
OpenShift Container Platform 4.6 Authentication and authorization
builder Used by build pods. It is given the system:image-builder role, which allows
pushing images to any imagestream in the project using the internal Docker
registry.
deployer Used by deployment pods and given the system:deployer role, which allows
viewing and modifying replication controllers and pods in the project.
default Used to run all other pods unless they specify a different service account.
All service accounts in a project are given the system:image-puller role, which allows pulling images
from any imagestream in the project using the internal container image registry.
Procedure
$ oc get sa
Example output
88
CHAPTER 10. USING SERVICE ACCOUNTS IN APPLICATIONS
$ oc create sa <service_account_name> 1
Example output
$ oc describe sa robot
Example output
Name: robot
Namespace: project1
Labels: <none>
Annotations: <none>
Tokens: robot-token-f4khf
robot-token-z8h44
In order to pull an image, the authenticated user must have get rights on the requested
imagestreams/layers. In order to push an image, the authenticated user must have update rights on the
requested imagestreams/layers.
By default, all service accounts in a project have rights to pull any image in the same project, and the
builder service account has rights to push any image in the same project.
Procedure
For example:
Example output
Name: robot-token-uzkbh
89
OpenShift Container Platform 4.6 Authentication and authorization
Labels: <none>
Annotations: kubernetes.io/service-account.name=robot,kubernetes.io/service-
account.uid=49f19e2e-16c6-11e5-afdc-3c970e4b7ffe
Type: kubernetes.io/service-account-token
Data
token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
$ oc login --token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Example output
You don't have any projects. You can try to create a new project, by running
$ oc new-project <projectname>
$ oc whoami
Example output
system:serviceaccount:top-secret:robot
90
CHAPTER 11. USING A SERVICE ACCOUNT AS AN OAUTH CLIENT
user:info
user:check-access
role:<any_role>:<service_account_namespace>
role:<any_role>:<service_account_namespace>:!
client_id is system:serviceaccount:<service_account_namespace>:
<service_account_name>.
client_secret can be any of the API tokens for that service account. For example:
$ oc sa get-token <service_account_name>
serviceaccounts.openshift.io/oauth-redirecturi.<name>
In its simplest form, the annotation can be used to directly specify valid redirect URIs. For example:
"serviceaccounts.openshift.io/oauth-redirecturi.first": "https://example.com"
"serviceaccounts.openshift.io/oauth-redirecturi.second": "https://other.com"
The first and second postfixes in the above example are used to separate the two valid redirect URIs.
In more complex configurations, static redirect URIs may not be enough. For example, perhaps you want
all Ingresses for a route to be considered valid. This is where dynamic redirect URIs via the
serviceaccounts.openshift.io/oauth-redirectreference. prefix come into play.
For example:
91
OpenShift Container Platform 4.6 Authentication and authorization
"serviceaccounts.openshift.io/oauth-redirectreference.first": "
{\"kind\":\"OAuthRedirectReference\",\"apiVersion\":\"v1\",\"reference\":
{\"kind\":\"Route\",\"name\":\"jenkins\"}}"
Since the value for this annotation contains serialized JSON data, it is easier to see in an expanded
format:
{
"kind": "OAuthRedirectReference",
"apiVersion": "v1",
"reference": {
"kind": "Route",
"name": "jenkins"
}
}
Now you can see that an OAuthRedirectReference allows us to reference the route named jenkins.
Thus, all Ingresses for that route will now be considered valid. The full specification for an
OAuthRedirectReference is:
{
"kind": "OAuthRedirectReference",
"apiVersion": "v1",
"reference": {
"kind": ..., 1
"name": ..., 2
"group": ... 3
}
}
1 kind refers to the type of the object being referenced. Currently, only route is supported.
2 name refers to the name of the object. The object must be in the same namespace as the service
account.
3 group refers to the group of the object. Leave this blank, as the group for a route is the empty
string.
Both annotation prefixes can be combined to override the data provided by the reference object. For
example:
"serviceaccounts.openshift.io/oauth-redirecturi.first": "custompath"
"serviceaccounts.openshift.io/oauth-redirectreference.first": "
{\"kind\":\"OAuthRedirectReference\",\"apiVersion\":\"v1\",\"reference\":
{\"kind\":\"Route\",\"name\":\"jenkins\"}}"
The first postfix is used to tie the annotations together. Assuming that the jenkins route had an Ingress
of https://example.com, now https://example.com/custompath is considered valid, but
https://example.com is not. The format for partially supplying override data is as follows:
92
CHAPTER 11. USING A SERVICE ACCOUNT AS AN OAUTH CLIENT
Type Syntax
Scheme "https://"
Hostname "//website.com"
Port "//:8000"
Path "examplepath"
NOTE
Specifying a host name override will replace the host name data from the referenced
object, which is not likely to be desired behavior.
Any combination of the above syntax can be combined using the following format:
<scheme:>//<hostname><:port>/<path>
The same object can be referenced more than once for more flexibility:
"serviceaccounts.openshift.io/oauth-redirecturi.first": "custompath"
"serviceaccounts.openshift.io/oauth-redirectreference.first": "
{\"kind\":\"OAuthRedirectReference\",\"apiVersion\":\"v1\",\"reference\":
{\"kind\":\"Route\",\"name\":\"jenkins\"}}"
"serviceaccounts.openshift.io/oauth-redirecturi.second": "//:8000"
"serviceaccounts.openshift.io/oauth-redirectreference.second": "
{\"kind\":\"OAuthRedirectReference\",\"apiVersion\":\"v1\",\"reference\":
{\"kind\":\"Route\",\"name\":\"jenkins\"}}"
Assuming that the route named jenkins has an Ingress of https://example.com, then both
https://example.com:8000 and https://example.com/custompath are considered valid.
Static and dynamic annotations can be used at the same time to achieve the desired behavior:
"serviceaccounts.openshift.io/oauth-redirectreference.first": "
{\"kind\":\"OAuthRedirectReference\",\"apiVersion\":\"v1\",\"reference\":
{\"kind\":\"Route\",\"name\":\"jenkins\"}}"
"serviceaccounts.openshift.io/oauth-redirecturi.second": "https://other.com"
93
OpenShift Container Platform 4.6 Authentication and authorization
A scoped token is a token that identifies as a given user but is limited to certain actions by its scope.
Only a user with the cluster-admin role can create scoped tokens.
Scopes are evaluated by converting the set of scopes for a token into a set of PolicyRules. Then, the
request is matched against those rules. The request attributes must match at least one of the scope
rules to be passed to the "normal" authorizer for further authorization checks.
user:full - Allows full read/write access to the API with all of the user’s permissions.
user:info - Allows read-only access to information about the user, such as name and groups.
user:list-projects - Allows read-only access to list the projects the user has access to.
role:<cluster-role name>:<namespace or * for all> - Limits the scope to the rules specified
by the cluster-role, but only in the specified namespace .
NOTE
Caveat: This prevents escalating access. Even if the role allows access to
resources like secrets, rolebindings, and roles, this scope will deny access to
those resources. This helps prevent unexpected escalations. Many people do not
think of a role like edit as being an escalating role, but with access to a secret it is.
94
CHAPTER 13. USING BOUND SERVICE ACCOUNT TOKENS
IMPORTANT
Because the cluster installation process does not use them, bound service account
tokens are configured post-installation.
Prerequisites
You have access to the cluster as a user with the cluster-admin role.
You have created a service account. This procedure assumes that the service account is named
build-robot.
Procedure
b. Set the spec.serviceAccountIssuer field to the desired service account issuer value:
spec:
serviceAccountIssuer: https://test.default.svc 1
1 This value should be a URL from which the recipient of a bound token can source the
public keys necessary to verify the signature of the token. The default is
https://kubernetes.default.svc.
2. Configure a pod to use a bound service account token by using volume projection.
apiVersion: v1
95
OpenShift Container Platform 4.6 Authentication and authorization
kind: Pod
metadata:
name: nginx
spec:
containers:
- image: nginx
name: nginx
volumeMounts:
- mountPath: /var/run/secrets/tokens
name: vault-token
serviceAccountName: build-robot 1
volumes:
- name: vault-token
projected:
sources:
- serviceAccountToken:
path: vault-token 2
expirationSeconds: 7200 3
audience: vault 4
2 The path relative to the mount point of the file to project the token into.
3 Optionally set the expiration of the service account token, in seconds. The default is
3600 seconds (1 hour) and must be at least 600 seconds (10 minutes). The kubelet will
start trying to rotate the token if the token is older than 80 percent of its time to live
or if the token is older than 24 hours.
4 Optionally set the intended audience of the token. The recipient of a token should
verify that the recipient identity matches the audience claim of the token, and should
otherwise reject the token. The audience defaults to the identifier of the API server.
$ oc create -f pod-projected-svc-token.yaml
The kubelet requests and stores the token on behalf of the pod, makes the token available
to the pod at a configurable file path, and refreshes the token as it approaches expiration.
3. The application that uses the bound token must handle reloading the token when it rotates.
The kubelet rotates the token if it is older than 80 percent of its time to live, or if the token is
older than 24 hours.
96
CHAPTER 14. MANAGING SECURITY CONTEXT CONSTRAINTS
Whether a container requires the use of a read only root file system.
Docker has a default list of capabilities that are allowed for each container of a pod. The containers use
the capabilities from this default list, but pod manifest authors can alter it by requesting additional
capabilities or removing some of the default behaviors. Use the allowedCapabilities,
defaultAddCapabilities, and requiredDropCapabilities parameters to control such requests from the
pods and to dictate which capabilities can be requested, which ones must be added to each container,
and which ones must be forbidden.
anyuid
hostaccess
hostmount-anyuid
hostnetwork
97
OpenShift Container Platform 4.6 Authentication and authorization
WARNING
If additional workloads are run on master hosts, use caution when providing
access to hostnetwork. A workload that runs hostnetwork on a master
host is effectively root on the cluster and must be trusted accordingly.
node-exporter
nonroot
privileged
restricted
IMPORTANT
Do not modify the default SCCs. Customizing the default SCCs can lead to issues when
OpenShift Container Platform is upgraded. Instead, create new SCCs.
98
CHAPTER 14. MANAGING SECURITY CONTEXT CONSTRAINTS
NOTE
For more information about each SCC, see the kubernetes.io/description annotation
available on the SCC.
SCCs are composed of settings and strategies that control the security features a pod has access to.
These settings fall into three categories:
Category Description
Controlled by a Fields of this type default to the most restrictive value. For example,
boolean AllowPrivilegedContainer is always set to false if unspecified.
Controlled by an Fields of this type are checked against the set to ensure their value is allowed.
allowable set
A mechanism to ensure that a specified value falls into the set of allowable
values.
RunAsUser
2. MustRunAsRange - Requires minimum and maximum values to be defined if not using pre-
allocated values. Uses the minimum as the default. Validates against the entire allowable range.
3. MustRunAsNonRoot - Requires that the pod be submitted with a non-zero runAsUser or have
the USER directive defined in the image. No default provided.
SELinuxContext
SupplementalGroups
1. MustRunAs - Requires at least one range to be specified if not using pre-allocated values. Uses
the minimum value of the first range as the default. Validates against all ranges.
99
OpenShift Container Platform 4.6 Authentication and authorization
FSGroup
1. MustRunAs - Requires at least one range to be specified if not using pre-allocated values. Uses
the minimum value of the first range as the default. Validates against the first ID in the first
range.
azureFile
azureDisk
flocker
flexVolume
hostPath
emptyDir
gcePersistentDisk
awsElasticBlockStore
gitRepo
secret
nfs
iscsi
glusterfs
persistentVolumeClaim
rbd
cinder
cephFS
downwardAPI
fc
configMap
vsphereVolume
100
CHAPTER 14. MANAGING SECURITY CONTEXT CONSTRAINTS
quobyte
photonPersistentDisk
projected
portworxVolume
scaleIO
storageos
none (a special value to disallow the use of all volumes types. Exist only for backwards
compatibility)
The recommended minimum set of allowed volumes for new SCCs are configMap, downwardAPI,
emptyDir, persistentVolumeClaim, secret, and projected.
NOTE
The list of allowable volume types is not exhaustive because new types are added with
each release of OpenShift Container Platform.
NOTE
14.1.3. Admission
Admission control with SCCs allows for control over the creation of resources based on the capabilities
granted to a user.
In terms of the SCCs, this means that an admission controller can inspect the user information made
available in the context to retrieve an appropriate set of SCCs. Doing so ensures the pod is authorized
to make requests about its operating environment or to generate a set of constraints to apply to the
pod.
The set of SCCs that admission uses to authorize a pod are determined by the user identity and groups
that the user belongs to. Additionally, if the pod specifies a service account, the set of allowable SCCs
includes any constraints accessible to the service account.
Admission uses the following approach to create the final security context for the pod:
2. Generate field values for security context settings that were not specified on the request.
If a matching set of constraints is found, then the pod is accepted. If the request cannot be matched to
an SCC, the pod is rejected.
101
OpenShift Container Platform 4.6 Authentication and authorization
A pod must validate every field against the SCC. The following are examples for just two of the fields
that must be validated:
NOTE
These examples are in the context of a strategy using the preallocated values.
If the pod defines a fsGroup ID, then that ID must equal the default fsGroup ID. Otherwise, the pod is
not validated by that SCC and the next SCC is evaluated.
If the SecurityContextConstraints.fsGroup field has value RunAsAny and the pod specification omits
the Pod.spec.securityContext.fsGroup, then this field is considered valid. Note that it is possible that
during validation, other SCC settings will reject other pod fields and thus cause the pod to fail.
If the pod specification defines one or more supplementalGroups IDs, then the pod’s IDs must equal
one of the IDs in the namespace’s openshift.io/sa.scc.supplemental-groups annotation. Otherwise,
the pod is not validated by that SCC and the next SCC is evaluated.
2. If priorities are equal, the SCCs will be sorted from most restrictive to least restrictive
3. If both priorities and restrictions are equal the SCCs will be sorted by name
By default, the anyuid SCC granted to cluster administrators is given priority in their SCC set. This
allows cluster administrators to run pods as any user by without specifying a RunAsUser on the pod’s
SecurityContext. The administrator may still specify a RunAsUser if they wish.
The following SCCs cause the admission controller to look for pre-allocated values when no ranges are
defined in the pod specification:
102
CHAPTER 14. MANAGING SECURITY CONTEXT CONSTRAINTS
2. An SELinuxContext strategy of MustRunAs with no level set. Admission looks for the
openshift.io/sa.scc.mcs annotation to populate the level.
During the generation phase, the security context provider uses default values for any parameter values
that are not specifically set in the pod. Default values are based on the selected strategy:
1. RunAsAny and MustRunAsNonRoot strategies do not provide default values. If the pod needs
a parameter value, such as a group ID, you must define the value in the pod specification.
2. MustRunAs (single value) strategies provide a default value that is always used. For example,
for group IDs, even if the pod specification defines its own ID value, the namespace’s default
parameter value also appears in the pod’s groups.
NOTE
NOTE
By default, the annotation-based FSGroup strategy configures itself with a single range
based on the minimum value for the annotation. For example, if your annotation reads
1/3, the FSGroup strategy configures itself with a minimum and maximum value of 1. If
you want to allow more groups to be accepted for the FSGroup field, you can configure a
custom SCC that does not use the annotation.
NOTE
allowHostDirVolumePlugin: true
allowHostIPC: true
103
OpenShift Container Platform 4.6 Authentication and authorization
allowHostNetwork: true
allowHostPID: true
allowHostPorts: true
allowPrivilegedContainer: true
allowedCapabilities: 1
- '*'
apiVersion: security.openshift.io/v1
defaultAddCapabilities: [] 2
fsGroup: 3
type: RunAsAny
groups: 4
- system:cluster-admins
- system:nodes
kind: SecurityContextConstraints
metadata:
annotations:
kubernetes.io/description: 'privileged allows access to all privileged and host
features and the ability to run as any user, any group, any fsGroup, and with
any SELinux context. WARNING: this is the most relaxed SCC and should be used
only for cluster administration. Grant with caution.'
creationTimestamp: null
name: privileged
priority: null
readOnlyRootFilesystem: false
requiredDropCapabilities: [] 5
runAsUser: 6
type: RunAsAny
seLinuxContext: 7
type: RunAsAny
seccompProfiles:
- '*'
supplementalGroups: 8
type: RunAsAny
users: 9
- system:serviceaccount:default:registry
- system:serviceaccount:default:router
- system:serviceaccount:openshift-infra:build-controller
volumes:
- '*'
1 A list of capabilities that a pod can request. An empty list means that none of capabilities can be
requested while the special symbol * allows any capabilities.
3 The FSGroup strategy, which dictates the allowable values for the security context.
6 The runAsUser strategy type, which dictates the allowable values for the Security Context.
7 The seLinuxContext strategy type, which dictates the allowable values for the Security Context.
104
CHAPTER 14. MANAGING SECURITY CONTEXT CONSTRAINTS
8 The supplementalGroups strategy, which dictates the allowable supplemental groups for the
Security Context.
The users and groups fields on the SCC control which users can access the SCC. By default, cluster
administrators, nodes, and the build controller are granted access to the privileged SCC. All
authenticated users are granted access to the restricted SCC.
apiVersion: v1
kind: Pod
metadata:
name: security-context-demo
spec:
securityContext: 1
containers:
- name: sec-ctx-demo
image: gcr.io/google-samples/node-hello:1.0
1 When a container or pod does not request a user ID under which it should be run, the effective UID
depends on the SCC that emits this pod. Because restricted SCC is granted to all authenticated
users by default, it will be available to all users and service accounts and used in most cases. The
restricted SCC uses MustRunAsRange strategy for constraining and defaulting the possible
values of the securityContext.runAsUser field. The admission plug-in will look for the
openshift.io/sa.scc.uid-range annotation on the current project to populate range fields, as it
does not provide this range. In the end, a container will have runAsUser equal to the first value of
the range that is hard to predict because every project has different ranges.
apiVersion: v1
kind: Pod
metadata:
name: security-context-demo
spec:
securityContext:
runAsUser: 1000 1
containers:
- name: sec-ctx-demo
image: gcr.io/google-samples/node-hello:1.0
1 A container or pod that requests a specific user ID will be accepted by OpenShift Container
Platform only when a service account or a user is granted access to a SCC that allows such a user
ID. The SCC can allow arbitrary IDs, an ID that falls into a range, or the exact user ID specific to the
request.
105
OpenShift Container Platform 4.6 Authentication and authorization
You can create security context constraints (SCCs) by using the CLI.
Prerequisites
Procedure
kind: SecurityContextConstraints
apiVersion: security.openshift.io/v1
metadata:
name: scc-admin
allowPrivilegedContainer: true
runAsUser:
type: RunAsAny
seLinuxContext:
type: RunAsAny
fsGroup:
type: RunAsAny
supplementalGroups:
type: RunAsAny
users:
- my-admin-user
groups:
- my-admin-group
Optionally, you can add drop capabilities to an SCC by setting the requiredDropCapabilities
field with the desired values. Any specified capabilities will be dropped from the container. For
example, to create an SCC with the KILL, MKNOD, and SYS_CHROOT required drop
capabilities, add the following to the SCC object:
requiredDropCapabilities:
- KILL
- MKNOD
- SYS_CHROOT
You can see the list of possible values in the Docker documentation.
TIP
Because capabilities are passed to the Docker, you can use a special ALL value to drop all
possible capabilities.
$ oc create -f scc_admin.yaml
106
CHAPTER 14. MANAGING SECURITY CONTEXT CONSTRAINTS
Example output
Example output
NOTE
You cannot assign a SCC to pods created in one of the default namespaces: default,
kube-system, kube-public, openshift-node, openshift-infra, openshift. These
namespaces should not be used for running pods or services.
To include access to SCCs for your role, specify the scc resource when creating a role.
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
...
name: role-name 1
namespace: namespace 2
...
rules:
- apiGroups:
- security.openshift.io 3
resourceNames:
- scc-name 4
resources:
107
OpenShift Container Platform 4.6 Authentication and authorization
- securitycontextconstraints 5
verbs: 6
- use
3 The API group that includes the SecurityContextConstraints resource. Automatically defined
when scc is specified as a resource.
5 Name of the resource group that allows users to specify SCC names in the resourceNames field.
A local or cluster role with such a rule allows the subjects that are bound to it with a role binding or a
cluster role binding to use the user-defined SCC called scc-name.
NOTE
Because RBAC is designed to prevent escalation, even project administrators are unable
to grant access to an SCC. By default, they are not allowed to use the verb use on SCC
resources, including the restricted SCC.
NOTE
IMPORTANT
Do not modify the default SCCs. Customizing the default SCCs can lead to issues when
upgrading. Instead, create new SCCs.
$ oc get scc
Example output
108
CHAPTER 14. MANAGING SECURITY CONTEXT CONSTRAINTS
Example output
Name: restricted
Priority: <none>
Access:
Users: <none> 1
Groups: system:authenticated 2
Settings:
Allow Privileged: false
Default Add Capabilities: <none>
Required Drop Capabilities: KILL,MKNOD,SYS_CHROOT,SETUID,SETGID
Allowed Capabilities: <none>
Allowed Seccomp Profiles: <none>
Allowed Volume Types:
configMap,downwardAPI,emptyDir,persistentVolumeClaim,projected,secret
Allow Host Network: false
Allow Host Ports: false
Allow Host PID: false
Allow Host IPC: false
Read Only Root Filesystem: false
Run As User Strategy: MustRunAsRange
UID: <none>
UID Range Min: <none>
UID Range Max: <none>
SELinux Context Strategy: MustRunAs
User: <none>
Role: <none>
Type: <none>
Level: <none>
FSGroup Strategy: MustRunAs
109
OpenShift Container Platform 4.6 Authentication and authorization
Ranges: <none>
Supplemental Groups Strategy: RunAsAny
Ranges: <none>
1 Lists which users and service accounts the SCC is applied to.
NOTE
To preserve customized SCCs during upgrades, do not edit settings on the default SCCs.
NOTE
If you delete a default SCC, it will regenerate when you restart the cluster.
NOTE
To preserve customized SCCs during upgrades, do not edit settings on the default SCCs.
110
CHAPTER 15. IMPERSONATING THE SYSTEM:ADMIN USER
Procedure
Procedure
111
OpenShift Container Platform 4.6 Authentication and authorization
For more information on configuring LDAP, see Configuring an LDAP identity provider .
NOTE
Sync configuration options that are dependent on the schema used in your LDAP server.
An administrator-defined list of name mappings that maps OpenShift Container Platform group
names to groups in your LDAP server.
The format of the configuration file depends upon the schema you are using: RFC 2307, Active
Directory, or augmented Active Directory.
The LDAP client configuration section of the configuration defines the connections to your LDAP
server.
url: ldap://10.0.0.0:389 1
bindDN: cn=admin,dc=example,dc=com 2
bindPassword: password 3
insecure: false 4
ca: my-ldap-ca-bundle.crt 5
1 The connection protocol, IP address of the LDAP server hosting your database, and the port to
connect to, formatted as scheme://host:port.
2 Optional distinguished name (DN) to use as the Bind DN. OpenShift Container Platform uses this if
elevated privilege is required to retrieve entries for the sync operation.
3 Optional password to use to bind. OpenShift Container Platform uses this if elevated privilege is
necessary to retrieve entries for the sync operation. This value may also be provided in an
environment variable, external file, or encrypted file.
112
CHAPTER 16. SYNCING LDAP GROUPS
4 When false, secure LDAP (ldaps://) URLs connect using TLS, and insecure LDAP ( ldap://) URLs
are upgraded to TLS. When true, no TLS connection is made to the server unless you specify an
5 The certificate bundle to use for validating server certificates for the configured URL. If empty,
OpenShift Container Platform uses system-trusted roots. This only applies if insecure is set to
false.
baseDN: ou=users,dc=example,dc=com 1
scope: sub 2
derefAliases: never 3
timeout: 0 4
filter: (objectClass=inetOrgPerson) 5
pageSize: 0 6
1 The distinguished name (DN) of the branch of the directory where all searches will start from. It is
required that you specify the top of your directory tree, but you can also specify a subtree in the
directory.
2 The scope of the search. Valid values are base, one, or sub. If this is left undefined, then a scope of
sub is assumed. Descriptions of the scope options can be found in the table below.
3 The behavior of the search with respect to aliases in the LDAP tree. Valid values are never, search,
base, or always. If this is left undefined, then the default is to always dereference aliases.
Descriptions of the dereferencing behaviors can be found in the table below.
4 The time limit allowed for the search by the client, in seconds. A value of 0 imposes no client-side
limit.
5 A valid LDAP search filter. If this is left undefined, then the default is (objectClass=*).
6 The optional maximum size of response pages from the server, measured in LDAP entries. If set to
0, no size restrictions will be made on pages of responses. Setting paging sizes is necessary when
queries return more entries than the client or server allow by default.
base Only consider the object specified by the base DN given for the query.
one Consider all of the objects on the same level in the tree as the base DN for the query.
sub Consider the entire subtree rooted at the base DN given for the query.
113
OpenShift Container Platform 4.6 Authentication and authorization
Dereferencing Description
behavior
groupUIDNameMapping:
"cn=group1,ou=groups,dc=example,dc=com": firstgroup
"cn=group2,ou=groups,dc=example,dc=com": secondgroup
"cn=group3,ou=groups,dc=example,dc=com": thirdgroup
For clarity, the group you create in OpenShift Container Platform should use attributes other than the
distinguished name whenever possible for user- or administrator-facing fields. For example, identify the
users of an OpenShift Container Platform group by their e-mail, and use the name of the group as the
common name. The following configuration file creates these relationships:
NOTE
kind: LDAPSyncConfig
apiVersion: v1
url: ldap://LDAP_SERVICE_IP:389 1
insecure: false 2
rfc2307:
groupsQuery:
114
CHAPTER 16. SYNCING LDAP GROUPS
baseDN: "ou=groups,dc=example,dc=com"
scope: sub
derefAliases: never
pageSize: 0
groupUIDAttribute: dn 3
groupNameAttributes: [ cn ] 4
groupMembershipAttributes: [ member ] 5
usersQuery:
baseDN: "ou=users,dc=example,dc=com"
scope: sub
derefAliases: never
pageSize: 0
userUIDAttribute: dn 6
userNameAttributes: [ mail ] 7
tolerateMemberNotFoundErrors: false
tolerateMemberOutOfScopeErrors: false
1 The IP address and host of the LDAP server where this group’s record is stored.
2 When false, secure LDAP (ldaps://) URLs connect using TLS, and insecure LDAP ( ldap://) URLs
are upgraded to TLS. When true, no TLS connection is made to the server unless you specify an
ldaps:// URL, in which case URLs still attempt to connect by using TLS.
3 The attribute that uniquely identifies a group on the LDAP server. You cannot specify
groupsQuery filters when using DN for groupUIDAttribute. For fine-grained filtering, use the
whitelist / blacklist method.
6 The attribute that uniquely identifies a user on the LDAP server. You cannot specify usersQuery
filters when using DN for userUIDAttribute. For fine-grained filtering, use the whitelist / blacklist
method.
7 The attribute to use as the name of the user in the OpenShift Container Platform group record.
For clarity, the group you create in OpenShift Container Platform should use attributes other than the
distinguished name whenever possible for user- or administrator-facing fields. For example, identify the
users of an OpenShift Container Platform group by their e-mail, but define the name of the group by
the name of the group on the LDAP server. The following configuration file creates these relationships:
kind: LDAPSyncConfig
apiVersion: v1
url: ldap://LDAP_SERVICE_IP:389
activeDirectory:
usersQuery:
115
OpenShift Container Platform 4.6 Authentication and authorization
baseDN: "ou=users,dc=example,dc=com"
scope: sub
derefAliases: never
filter: (objectclass=inetOrgPerson)
pageSize: 0
userNameAttributes: [ mail ] 1
groupMembershipAttributes: [ memberOf ] 2
1 The attribute to use as the name of the user in the OpenShift Container Platform group record.
For clarity, the group you create in OpenShift Container Platform should use attributes other than the
distinguished name whenever possible for user- or administrator-facing fields. For example, identify the
users of an OpenShift Container Platform group by their e-mail, and use the name of the group as the
common name. The following configuration file creates these relationships.
kind: LDAPSyncConfig
apiVersion: v1
url: ldap://LDAP_SERVICE_IP:389
augmentedActiveDirectory:
groupsQuery:
baseDN: "ou=groups,dc=example,dc=com"
scope: sub
derefAliases: never
pageSize: 0
groupUIDAttribute: dn 1
groupNameAttributes: [ cn ] 2
usersQuery:
baseDN: "ou=users,dc=example,dc=com"
scope: sub
derefAliases: never
filter: (objectclass=inetOrgPerson)
pageSize: 0
userNameAttributes: [ mail ] 3
groupMembershipAttributes: [ memberOf ] 4
1 The attribute that uniquely identifies a group on the LDAP server. You cannot specify
groupsQuery filters when using DN for groupUIDAttribute. For fine-grained filtering, use the
whitelist / blacklist method.
3 The attribute to use as the name of the user in the OpenShift Container Platform group record.
116
CHAPTER 16. SYNCING LDAP GROUPS
Prerequisites
Procedure
To sync all groups from the LDAP server with OpenShift Container Platform:
NOTE
By default, all group synchronization operations are dry-run, so you must set the -
-confirm flag on the oc adm groups sync command in order to make changes
to OpenShift Container Platform group records.
16.2.2. Syncing OpenShift Container Platform groups with the LDAP server
You can sync all groups already in OpenShift Container Platform that correspond to groups in the LDAP
server specified in the configuration file.
Prerequisites
Procedure
NOTE
By default, all group synchronization operations are dry-run, so you must set the -
-confirm flag on the oc adm groups sync command in order to make changes
to OpenShift Container Platform group records.
16.2.3. Syncing subgroups from the LDAP server with OpenShift Container Platform
You can sync a subset of LDAP groups with OpenShift Container Platform using whitelist files, blacklist
117
OpenShift Container Platform 4.6 Authentication and authorization
You can sync a subset of LDAP groups with OpenShift Container Platform using whitelist files, blacklist
files, or both.
NOTE
You can use any combination of blacklist files, whitelist files, or whitelist literals. Whitelist
and blacklist files must contain one unique group identifier per line, and you can include
whitelist literals directly in the command itself. These guidelines apply to groups found on
LDAP servers as well as groups already present in OpenShift Container Platform.
Prerequisite
Procedure
To sync a subset of LDAP groups with OpenShift Container Platform, use any the following
commands:
NOTE
By default, all group synchronization operations are dry-run, so you must set the -
-confirm flag on the oc adm groups sync command in order to make changes
to OpenShift Container Platform group records.
An administrator can also choose to remove groups from OpenShift Container Platform records if the
118
CHAPTER 16. SYNCING LDAP GROUPS
An administrator can also choose to remove groups from OpenShift Container Platform records if the
records on the LDAP server that created them are no longer present. The prune job will accept the
same sync configuration file and whitelists or blacklists as used for the sync job.
For example:
NOTE
These examples assume that all users are direct members of their respective groups.
Specifically, no groups have other groups as members. See the Nested Membership Sync
Example for information on how to sync nested groups.
How the group and users are added to the LDAP server.
What the resulting group record in OpenShift Container Platform will be after synchronization.
NOTE
These examples assume that all users are direct members of their respective groups.
Specifically, no groups have other groups as members. See the Nested Membership Sync
Example for information on how to sync nested groups.
In the RFC 2307 schema, both users (Jane and Jim) and groups exist on the LDAP server as first-class
entries, and group membership is stored in attributes on the group. The following snippet of ldif defines
the users and group for this schema:
dn: ou=users,dc=example,dc=com
objectClass: organizationalUnit
ou: users
dn: cn=Jane,ou=users,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
119
OpenShift Container Platform 4.6 Authentication and authorization
objectClass: inetOrgPerson
cn: Jane
sn: Smith
displayName: Jane Smith
mail: [email protected]
dn: cn=Jim,ou=users,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: Jim
sn: Adams
displayName: Jim Adams
mail: [email protected]
dn: ou=groups,dc=example,dc=com
objectClass: organizationalUnit
ou: groups
dn: cn=admins,ou=groups,dc=example,dc=com 1
objectClass: groupOfNames
cn: admins
owner: cn=admin,dc=example,dc=com
description: System Administrators
member: cn=Jane,ou=users,dc=example,dc=com 2
member: cn=Jim,ou=users,dc=example,dc=com
2 Members of a group are listed with an identifying reference as attributes on the group.
Prerequisites
Procedure
OpenShift Container Platform creates the following group record as a result of the above sync
operation:
apiVersion: user.openshift.io/v1
kind: Group
metadata:
annotations:
openshift.io/ldap.sync-time: 2015-10-13T10:08:38-0400 1
openshift.io/ldap.uid: cn=admins,ou=groups,dc=example,dc=com 2
openshift.io/ldap.url: LDAP_SERVER_IP:389 3
creationTimestamp:
name: admins 4
120
CHAPTER 16. SYNCING LDAP GROUPS
users: 5
- [email protected]
- [email protected]
1 The last time this OpenShift Container Platform group was synchronized with the LDAP
server, in ISO 6801 format.
3 The IP address and host of the LDAP server where this group’s record is stored.
5 The users that are members of the group, named as specified by the sync file.
16.4.2. Syncing groups using the RFC2307 schema with user-defined name
mappings
When syncing groups with user-defined name mappings, the configuration file changes to contain these
mappings as shown below.
LDAP sync configuration that uses RFC 2307 schema with user-defined name mappings:
rfc2307_config_user_defined.yaml
kind: LDAPSyncConfig
apiVersion: v1
groupUIDNameMapping:
"cn=admins,ou=groups,dc=example,dc=com": Administrators 1
rfc2307:
groupsQuery:
baseDN: "ou=groups,dc=example,dc=com"
scope: sub
derefAliases: never
pageSize: 0
groupUIDAttribute: dn 2
groupNameAttributes: [ cn ] 3
groupMembershipAttributes: [ member ]
usersQuery:
baseDN: "ou=users,dc=example,dc=com"
scope: sub
derefAliases: never
pageSize: 0
userUIDAttribute: dn 4
userNameAttributes: [ mail ]
tolerateMemberNotFoundErrors: false
tolerateMemberOutOfScopeErrors: false
2 The unique identifier attribute that is used for the keys in the user-defined name mapping. You
cannot specify groupsQuery filters when using DN for groupUIDAttribute. For fine-grained
filtering, use the whitelist / blacklist method.
The attribute to name OpenShift Container Platform groups with if their unique identifier is not in
121
OpenShift Container Platform 4.6 Authentication and authorization
3 The attribute to name OpenShift Container Platform groups with if their unique identifier is not in
the user-defined name mapping.
4 The attribute that uniquely identifies a user on the LDAP server. You cannot specify usersQuery
filters when using DN for userUIDAttribute. For fine-grained filtering, use the whitelist / blacklist
method.
Prerequisites
Procedure
OpenShift Container Platform creates the following group record as a result of the above sync
operation:
apiVersion: user.openshift.io/v1
kind: Group
metadata:
annotations:
openshift.io/ldap.sync-time: 2015-10-13T10:08:38-0400
openshift.io/ldap.uid: cn=admins,ou=groups,dc=example,dc=com
openshift.io/ldap.url: LDAP_SERVER_IP:389
creationTimestamp:
name: Administrators 1
users:
- [email protected]
- [email protected]
16.4.3. Syncing groups using RFC 2307 with user-defined error tolerances
By default, if the groups being synced contain members whose entries are outside of the scope defined
in the member query, the group sync fails with an error:
Error determining LDAP group membership for "<group>": membership lookup for user "<user>" in
group "<group>" failed because of "search for entry with dn="<user-dn>" would search outside of the
base dn specified (dn="<base-dn>")".
This often indicates a misconfigured baseDN in the usersQuery field. However, in cases where the
baseDN intentionally does not contain some of the members of the group, setting
tolerateMemberOutOfScopeErrors: true allows the group sync to continue. Out of scope members
will be ignored.
122
CHAPTER 16. SYNCING LDAP GROUPS
Similarly, when the group sync process fails to locate a member for a group, it fails outright with errors:
Error determining LDAP group membership for "<group>": membership lookup for user "<user>" in
group "<group>" failed because of "search for entry with base dn="<user-dn>" refers to a non-
existent entry".
Error determining LDAP group membership for "<group>": membership lookup for user "<user>" in
group "<group>" failed because of "search for entry with base dn="<user-dn>" and filter "<filter>" did
not return any results".
This often indicates a misconfigured usersQuery field. However, in cases where the group contains
member entries that are known to be missing, setting tolerateMemberNotFoundErrors: true allows the
group sync to continue. Problematic members will be ignored.
WARNING
Enabling error tolerances for the LDAP group sync causes the sync process to
ignore problematic member entries. If the LDAP group sync is not configured
correctly, this could result in synced OpenShift Container Platform groups missing
members.
LDAP entries that use RFC 2307 schema with problematic group membership:
rfc2307_problematic_users.ldif
dn: ou=users,dc=example,dc=com
objectClass: organizationalUnit
ou: users
dn: cn=Jane,ou=users,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: Jane
sn: Smith
displayName: Jane Smith
mail: [email protected]
dn: cn=Jim,ou=users,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: Jim
sn: Adams
displayName: Jim Adams
mail: [email protected]
dn: ou=groups,dc=example,dc=com
objectClass: organizationalUnit
ou: groups
dn: cn=admins,ou=groups,dc=example,dc=com
objectClass: groupOfNames
cn: admins
owner: cn=admin,dc=example,dc=com
description: System Administrators
123
OpenShift Container Platform 4.6 Authentication and authorization
member: cn=Jane,ou=users,dc=example,dc=com
member: cn=Jim,ou=users,dc=example,dc=com
member: cn=INVALID,ou=users,dc=example,dc=com 1
member: cn=Jim,ou=OUTOFSCOPE,dc=example,dc=com 2
2 A member that may exist, but is not under the baseDN in the user query for the sync job.
In order to tolerate the errors in the above example, the following additions to your sync configuration
file must be made:
LDAP sync configuration that uses RFC 2307 schema tolerating errors:
rfc2307_config_tolerating.yaml
kind: LDAPSyncConfig
apiVersion: v1
url: ldap://LDAP_SERVICE_IP:389
rfc2307:
groupsQuery:
baseDN: "ou=groups,dc=example,dc=com"
scope: sub
derefAliases: never
groupUIDAttribute: dn
groupNameAttributes: [ cn ]
groupMembershipAttributes: [ member ]
usersQuery:
baseDN: "ou=users,dc=example,dc=com"
scope: sub
derefAliases: never
userUIDAttribute: dn 1
userNameAttributes: [ mail ]
tolerateMemberNotFoundErrors: true 2
tolerateMemberOutOfScopeErrors: true 3
1 The attribute that uniquely identifies a user on the LDAP server. You cannot specify usersQuery
filters when using DN for userUIDAttribute. For fine-grained filtering, use the whitelist / blacklist
method.
2 When true, the sync job tolerates groups for which some members were not found, and members
whose LDAP entries are not found are ignored. The default behavior for the sync job is to fail if a
member of a group is not found.
3 When true, the sync job tolerates groups for which some members are outside the user scope
given in the usersQuery base DN, and members outside the member query scope are ignored.
The default behavior for the sync job is to fail if a member of a group is out of scope.
Prerequisites
Procedure
124
CHAPTER 16. SYNCING LDAP GROUPS
OpenShift Container Platform creates the following group record as a result of the above sync
operation:
apiVersion: user.openshift.io/v1
kind: Group
metadata:
annotations:
openshift.io/ldap.sync-time: 2015-10-13T10:08:38-0400
openshift.io/ldap.uid: cn=admins,ou=groups,dc=example,dc=com
openshift.io/ldap.url: LDAP_SERVER_IP:389
creationTimestamp:
name: admins
users: 1
- [email protected]
- [email protected]
1 The users that are members of the group, as specified by the sync file. Members for which
lookup encountered tolerated errors are absent.
dn: ou=users,dc=example,dc=com
objectClass: organizationalUnit
ou: users
dn: cn=Jane,ou=users,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: testPerson
cn: Jane
sn: Smith
displayName: Jane Smith
mail: [email protected]
memberOf: admins 1
dn: cn=Jim,ou=users,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: testPerson
125
OpenShift Container Platform 4.6 Authentication and authorization
cn: Jim
sn: Adams
displayName: Jim Adams
mail: [email protected]
memberOf: admins
1 The user’s group memberships are listed as attributes on the user, and the group does not exist as
an entry on the server. The memberOf attribute does not have to be a literal attribute on the user;
in some LDAP servers, it is created during search and returned to the client, but not committed to
the database.
Prerequisites
Procedure
OpenShift Container Platform creates the following group record as a result of the above sync
operation:
apiVersion: user.openshift.io/v1
kind: Group
metadata:
annotations:
openshift.io/ldap.sync-time: 2015-10-13T10:08:38-0400 1
openshift.io/ldap.uid: admins 2
openshift.io/ldap.url: LDAP_SERVER_IP:389 3
creationTimestamp:
name: admins 4
users: 5
- [email protected]
- [email protected]
1 The last time this OpenShift Container Platform group was synchronized with the LDAP
server, in ISO 6801 format.
3 The IP address and host of the LDAP server where this group’s record is stored.
5 The users that are members of the group, named as specified by the sync file.
126
CHAPTER 16. SYNCING LDAP GROUPS
In the augmented Active Directory schema, both users (Jane and Jim) and groups exist in the LDAP
server as first-class entries, and group membership is stored in attributes on the user. The following
snippet of ldif defines the users and group for this schema:
dn: ou=users,dc=example,dc=com
objectClass: organizationalUnit
ou: users
dn: cn=Jane,ou=users,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: testPerson
cn: Jane
sn: Smith
displayName: Jane Smith
mail: [email protected]
memberOf: cn=admins,ou=groups,dc=example,dc=com 1
dn: cn=Jim,ou=users,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: testPerson
cn: Jim
sn: Adams
displayName: Jim Adams
mail: [email protected]
memberOf: cn=admins,ou=groups,dc=example,dc=com
dn: ou=groups,dc=example,dc=com
objectClass: organizationalUnit
ou: groups
dn: cn=admins,ou=groups,dc=example,dc=com 2
objectClass: groupOfNames
cn: admins
owner: cn=admin,dc=example,dc=com
description: System Administrators
member: cn=Jane,ou=users,dc=example,dc=com
member: cn=Jim,ou=users,dc=example,dc=com
Prerequisites
Procedure
127
OpenShift Container Platform 4.6 Authentication and authorization
OpenShift Container Platform creates the following group record as a result of the above sync
operation:
apiVersion: user.openshift.io/v1
kind: Group
metadata:
annotations:
openshift.io/ldap.sync-time: 2015-10-13T10:08:38-0400 1
openshift.io/ldap.uid: cn=admins,ou=groups,dc=example,dc=com 2
openshift.io/ldap.url: LDAP_SERVER_IP:389 3
creationTimestamp:
name: admins 4
users: 5
- [email protected]
- [email protected]
1 The last time this OpenShift Container Platform group was synchronized with the LDAP
server, in ISO 6801 format.
3 The IP address and host of the LDAP server where this group’s record is stored.
5 The users that are members of the group, named as specified by the sync file.
Groups in OpenShift Container Platform do not nest. The LDAP server must flatten group membership
before the data can be consumed. Microsoft’s Active Directory Server supports this feature via the
LDAP_MATCHING_RULE_IN_CHAIN rule, which has the OID 1.2.840.113556.1.4.1941. Furthermore,
only explicitly whitelisted groups can be synced when using this matching rule.
This section has an example for the augmented Active Directory schema, which synchronizes a group
named admins that has one user Jane and one group otheradmins as members. The otheradmins
group has one user member: Jim. This example explains:
How the group and users are added to the LDAP server.
What the resulting group record in OpenShift Container Platform will be after synchronization.
In the augmented Active Directory schema, both users (Jane and Jim) and groups exist in the LDAP
server as first-class entries, and group membership is stored in attributes on the user or the group. The
following snippet of ldif defines the users and groups for this schema:
128
CHAPTER 16. SYNCING LDAP GROUPS
LDAP entries that use augmented Active Directory schema with nested members:
augmented_active_directory_nested.ldif
dn: ou=users,dc=example,dc=com
objectClass: organizationalUnit
ou: users
dn: cn=Jane,ou=users,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: testPerson
cn: Jane
sn: Smith
displayName: Jane Smith
mail: [email protected]
memberOf: cn=admins,ou=groups,dc=example,dc=com 1
dn: cn=Jim,ou=users,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: testPerson
cn: Jim
sn: Adams
displayName: Jim Adams
mail: [email protected]
memberOf: cn=otheradmins,ou=groups,dc=example,dc=com 2
dn: ou=groups,dc=example,dc=com
objectClass: organizationalUnit
ou: groups
dn: cn=admins,ou=groups,dc=example,dc=com 3
objectClass: group
cn: admins
owner: cn=admin,dc=example,dc=com
description: System Administrators
member: cn=Jane,ou=users,dc=example,dc=com
member: cn=otheradmins,ou=groups,dc=example,dc=com
dn: cn=otheradmins,ou=groups,dc=example,dc=com 4
objectClass: group
cn: otheradmins
owner: cn=admin,dc=example,dc=com
description: Other System Administrators
memberOf: cn=admins,ou=groups,dc=example,dc=com 5 6
member: cn=Jim,ou=users,dc=example,dc=com
1 2 5 The user’s and group’s memberships are listed as attributes on the object.
129
OpenShift Container Platform 4.6 Authentication and authorization
When syncing nested groups with Active Directory, you must provide an LDAP query definition for both
user entries and group entries, as well as the attributes with which to represent them in the internal
OpenShift Container Platform group records. Furthermore, certain changes are required in this
configuration:
The groupsQuery:
For clarity, the group you create in OpenShift Container Platform should use attributes other than the
distinguished name whenever possible for user- or administrator-facing fields. For example, identify the
users of an OpenShift Container Platform group by their e-mail, and use the name of the group as the
common name. The following configuration file creates these relationships:
LDAP sync configuration that uses augmented Active Directory schema with nested
members: augmented_active_directory_config_nested.yaml
kind: LDAPSyncConfig
apiVersion: v1
url: ldap://LDAP_SERVICE_IP:389
augmentedActiveDirectory:
groupsQuery: 1
derefAliases: never
pageSize: 0
groupUIDAttribute: dn 2
groupNameAttributes: [ cn ] 3
usersQuery:
baseDN: "ou=users,dc=example,dc=com"
scope: sub
derefAliases: never
filter: (objectclass=inetOrgPerson)
pageSize: 0
userNameAttributes: [ mail ] 4
groupMembershipAttributes: [ "memberOf:1.2.840.113556.1.4.1941:" ] 5
1 groupsQuery filters cannot be specified. The groupsQuery base DN and scope values are
ignored. groupsQuery must set a valid derefAliases.
2 The attribute that uniquely identifies a group on the LDAP server. It must be set to dn.
130
CHAPTER 16. SYNCING LDAP GROUPS
4 The attribute to use as the name of the user in the OpenShift Container Platform group record.
mail or sAMAccountName are preferred choices in most installations.
5 The attribute on the user that stores the membership information. Note the use of
LDAP_MATCHING_RULE_IN_CHAIN.
Prerequisites
Procedure
NOTE
OpenShift Container Platform creates the following group record as a result of the above sync
operation:
apiVersion: user.openshift.io/v1
kind: Group
metadata:
annotations:
openshift.io/ldap.sync-time: 2015-10-13T10:08:38-0400 1
openshift.io/ldap.uid: cn=admins,ou=groups,dc=example,dc=com 2
openshift.io/ldap.url: LDAP_SERVER_IP:389 3
creationTimestamp:
name: admins 4
users: 5
- [email protected]
- [email protected]
1 The last time this OpenShift Container Platform group was synchronized with the LDAP
server, in ISO 6801 format.
3 The IP address and host of the LDAP server where this group’s record is stored.
The users that are members of the group, named as specified by the sync file. Note that
131
OpenShift Container Platform 4.6 Authentication and authorization
5 The users that are members of the group, named as specified by the sync file. Note that
members of nested groups are included since the group membership was flattened by the
IMPORTANT
There is no support for binary attributes. All attribute data coming from the LDAP server
must be in the format of a UTF-8 encoded string. For example, never use a binary
attribute, such as objectGUID, as an ID attribute. You must use string attributes, such as
sAMAccountName or userPrincipalName, instead.
16.5.1. v1.LDAPSyncConfig
LDAPSyncConfig holds the necessary configuration options to define an LDAP group sync.
132
CHAPTER 16. SYNCING LDAP GROUPS
133
OpenShift Container Platform 4.6 Authentication and authorization
16.5.2. v1.StringSource
StringSource allows specifying a string inline, or externally via environment variable or file. When it
contains only a string value, it marshals to a simple JSON string.
16.5.3. v1.LDAPQuery
LDAPQuery holds the options necessary to build an LDAP query.
134
CHAPTER 16. SYNCING LDAP GROUPS
16.5.4. v1.RFC2307Config
RFC2307Config holds the necessary configuration options to define how an LDAP group sync interacts
with an LDAP server using the RFC2307 schema.
135
OpenShift Container Platform 4.6 Authentication and authorization
136
CHAPTER 16. SYNCING LDAP GROUPS
16.5.5. v1.ActiveDirectoryConfig
ActiveDirectoryConfig holds the necessary configuration options to define how an LDAP group sync
interacts with an LDAP server using the Active Directory schema.
137
OpenShift Container Platform 4.6 Authentication and authorization
16.5.6. v1.AugmentedActiveDirectoryConfig
AugmentedActiveDirectoryConfig holds the necessary configuration options to define how an LDAP
group sync interacts with an LDAP server using the augmented Active Directory schema.
138
CHAPTER 16. SYNCING LDAP GROUPS
139
OpenShift Container Platform 4.6 Authentication and authorization
The ConfigMap object provides mechanisms to inject containers with configuration data while keeping
containers agnostic of OpenShift Container Platform. A config map can be used to store fine-grained
information like individual properties or coarse-grained information like entire configuration files or
JSON blobs.
The ConfigMap API object holds key-value pairs of configuration data that can be consumed in pods or
used to store configuration data for system components such as controllers. For example:
kind: ConfigMap
apiVersion: v1
metadata:
creationTimestamp: 2016-02-18T19:14:38Z
name: example-config
namespace: default
data: 1
example.property.1: hello
example.property.2: world
example.property.file: |-
property.1=value-1
property.2=value-2
property.3=value-3
binaryData:
bar: L3Jvb3QvMTAw 2
2 Points to a file that contains non-UTF8 data, for example, a binary Java keystore file. Enter the file
data in Base 64.
NOTE
You can use the binaryData field when you create a config map from a binary file, such as
an image.
Configuration data can be consumed in pods in a variety of ways. A config map can be used to:
140
CHAPTER 17. CREATING AND USING CONFIG MAPS
Users and system components can store configuration data in a config map.
A config map is similar to a secret, but designed to more conveniently support working with strings that
do not contain sensitive information.
Controllers can be written to tolerate missing configuration data. Consult individual components
configured by using config maps on a case-by-case basis.
The Kubelet only supports the use of a config map for pods it gets from the API server.
This includes any pods created by using the CLI, or indirectly from a replication controller. It does not
include pods created by using the OpenShift Container Platform node’s --manifest-url flag, its --config
flag, or its REST API because these are not common ways to create pods.
Procedure
2. At the top right side of the page, select Create Config Map.
4. Select Create.
2. At the top right side of the page, select Create Config Map.
4. Select Create.
Procedure
141
OpenShift Container Platform 4.6 Authentication and authorization
Procedure
The following example procedure outlines how to create a config map from a directory.
1. Start with a directory with some files that already contain the data with which you want to
populate a config map:
$ ls example-files
Example output
game.properties
ui.properties
$ cat example-files/game.properties
Example output
enemies=aliens
lives=3
enemies.cheat=true
enemies.cheat.level=noGoodRotten
secret.code.passphrase=UUDDLRLRBABAS
secret.code.allowed=true
secret.code.lives=30
$ cat example-files/ui.properties
Example output
color.good=purple
color.bad=yellow
allow.textmode=true
how.nice.to.look=fairlyNice
2. Create a ConfigMap holding the content of each file in this directory by entering the following
command:
When the --from-file option points to a directory, each file directly in that directory is used to
populate a key in the ConfigMap, where the name of the key is the file name, and the value of
the key is the content of the file.
142
CHAPTER 17. CREATING AND USING CONFIG MAPS
Example output
Name: game-config
Namespace: default
Labels: <none>
Annotations: <none>
Data
You can see that the two keys in the map are created from the file names in the directory
specified in the command. Because the content of those keys might be large, the output of oc
describe only shows the names of the keys and their sizes.
3. Enter the oc get command for the object with the -o option to see the values of the keys:
Example output
apiVersion: v1
data:
game.properties: |-
enemies=aliens
lives=3
enemies.cheat=true
enemies.cheat.level=noGoodRotten
secret.code.passphrase=UUDDLRLRBABAS
secret.code.allowed=true
secret.code.lives=30
ui.properties: |
color.good=purple
color.bad=yellow
allow.textmode=true
how.nice.to.look=fairlyNice
kind: ConfigMap
metadata:
creationTimestamp: 2016-02-18T18:34:05Z
name: game-config
namespace: default
resourceVersion: "407"-
selflink: /api/v1/namespaces/default/configmaps/game-config
uid: 30944725-d66e-11e5-8cd0-68f728db1985
143
OpenShift Container Platform 4.6 Authentication and authorization
Procedure
The following example procedure outlines how to create a config map from a file.
NOTE
If you create a config map from a file, you can include files containing non-UTF8 data
that are placed in this field without corrupting the non-UTF8 data. OpenShift Container
Platform detects binary files and transparently encodes the file as MIME. On the server,
the MIME payload is decoded and stored without corrupting the data.
You can pass the --from-file option multiple times to the CLI. The following example yields equivalent
results to the creating from directories example.
Example output
apiVersion: v1
data:
game.properties: |-
enemies=aliens
lives=3
enemies.cheat=true
enemies.cheat.level=noGoodRotten
secret.code.passphrase=UUDDLRLRBABAS
secret.code.allowed=true
secret.code.lives=30
ui.properties: |
color.good=purple
color.bad=yellow
allow.textmode=true
how.nice.to.look=fairlyNice
kind: ConfigMap
metadata:
creationTimestamp: 2016-02-18T18:52:05Z
name: game-config-2
namespace: default
resourceVersion: "516"
selflink: /api/v1/namespaces/default/configmaps/game-config-2
uid: b4952dc3-d670-11e5-8cd0-68f728db1985
You can specify the key to set in a ConfigMap for content imported from a file. This can be set by
passing a key=value expression to the --from-file option. For example:
144
CHAPTER 17. CREATING AND USING CONFIG MAPS
Example output
apiVersion: v1
data:
game-special-key: |- 1
enemies=aliens
lives=3
enemies.cheat=true
enemies.cheat.level=noGoodRotten
secret.code.passphrase=UUDDLRLRBABAS
secret.code.allowed=true
secret.code.lives=30
kind: ConfigMap
metadata:
creationTimestamp: 2016-02-18T18:54:22Z
name: game-config-3
namespace: default
resourceVersion: "530"
selflink: /api/v1/namespaces/default/configmaps/game-config-3
uid: 05f8da22-d671-11e5-8cd0-68f728db1985
Procedure
The --from-literal option takes a key=value syntax that allows literal values to be supplied directly on
the command line.
Example output
apiVersion: v1
145
OpenShift Container Platform 4.6 Authentication and authorization
data:
special.how: very
special.type: charm
kind: ConfigMap
metadata:
creationTimestamp: 2016-02-18T19:14:38Z
name: special-config
namespace: default
resourceVersion: "651"
selflink: /api/v1/namespaces/default/configmaps/special-config
uid: dadce046-d673-11e5-8cd0-68f728db1985
apiVersion: v1
kind: ConfigMap
metadata:
name: special-config 1
namespace: default 2
data:
special.how: very 3
special.type: charm 4
2 The project in which the ConfigMap resides. Config maps can only be referenced by pods in the
same project.
apiVersion: v1
kind: ConfigMap
metadata:
name: env-config 1
namespace: default
data:
log_level: INFO 2
146
CHAPTER 17. CREATING AND USING CONFIG MAPS
Procedure
You can consume the keys of this ConfigMap in a pod using configMapKeyRef sections.
apiVersion: v1
kind: Pod
metadata:
name: dapi-test-pod
spec:
containers:
- name: test-container
image: gcr.io/google_containers/busybox
command: [ "/bin/sh", "-c", "env" ]
env: 1
- name: SPECIAL_LEVEL_KEY 2
valueFrom:
configMapKeyRef:
name: special-config 3
key: special.how 4
- name: SPECIAL_TYPE_KEY
valueFrom:
configMapKeyRef:
name: special-config 5
key: special.type 6
optional: true 7
envFrom: 8
- configMapRef:
name: env-config 9
restartPolicy: Never
2 Name of a Pod environment variable that you are injecting a key’s value into.
7 Makes the environment variable optional. As optional, the Pod will be started even if the
specified ConfigMap and keys do not exist.
When this Pod is run, the Pod logs will include the following output:
147
OpenShift Container Platform 4.6 Authentication and authorization
SPECIAL_LEVEL_KEY=very
log_level=INFO
NOTE
apiVersion: v1
kind: ConfigMap
metadata:
name: special-config
namespace: default
data:
special.how: very
special.type: charm
Procedure
To inject values into a command in a container, you must consume the keys you want to use as
environment variables, as in the consuming ConfigMaps in environment variables use case. Then
you can refer to them in a container’s command using the $(VAR_NAME) syntax.
apiVersion: v1
kind: Pod
metadata:
name: dapi-test-pod
spec:
containers:
- name: test-container
image: gcr.io/google_containers/busybox
command: [ "/bin/sh", "-c", "echo $(SPECIAL_LEVEL_KEY) $(SPECIAL_TYPE_KEY)" ]
1
env:
- name: SPECIAL_LEVEL_KEY
valueFrom:
configMapKeyRef:
name: special-config
key: special.how
- name: SPECIAL_TYPE_KEY
valueFrom:
configMapKeyRef:
name: special-config
key: special.type
restartPolicy: Never
148
CHAPTER 17. CREATING AND USING CONFIG MAPS
1 Inject the values into a command in a container using the keys you want to use as
environment variables.
When this Pod is run, the output from the echo command run in the test-container container is
as follows:
very charm
Example ConfigMap
apiVersion: v1
kind: ConfigMap
metadata:
name: special-config
namespace: default
data:
special.how: very
special.type: charm
Procedure
You have a couple different options for injecting content into a volume by using config maps.
The most basic way to inject content into a volume by using a config map is to populate the
volume with files where the key is the file name and the content of the file is the value of the
key:
apiVersion: v1
kind: Pod
metadata:
name: dapi-test-pod
spec:
containers:
- name: test-container
image: gcr.io/google_containers/busybox
command: [ "/bin/sh", "cat", "/etc/config/special.how" ]
volumeMounts:
- name: config-volume
mountPath: /etc/config
volumes:
- name: config-volume
configMap:
name: special-config 1
restartPolicy: Never
When this pod is run, the output of the cat command will be:
149
OpenShift Container Platform 4.6 Authentication and authorization
very
You can also control the paths within the volume where ConfigMap keys are projected:
apiVersion: v1
kind: Pod
metadata:
name: dapi-test-pod
spec:
containers:
- name: test-container
image: gcr.io/google_containers/busybox
command: [ "/bin/sh", "cat", "/etc/config/path/to/special-key" ]
volumeMounts:
- name: config-volume
mountPath: /etc/config
volumes:
- name: config-volume
configMap:
name: special-config
items:
- key: special.how
path: path/to/special-key 1
restartPolicy: Never
When this pod is run, the output of the cat command will be:
very
150