1.3. API authentication
Requests to the OpenShift Container Platform API are authenticated using the following methods:
- OAuth access tokens
-
Obtained from the OpenShift Container Platform OAuth server using the
<namespace_route>/oauth/authorizeand<namespace_route>/oauth/tokenendpoints. -
Sent as an
Authorization: Bearer…header. -
Sent as a websocket subprotocol header in the form
base64url.bearer.authorization.k8s.io.<base64url-encoded-token>for websocket requests.
-
Obtained from the OpenShift Container Platform OAuth server using the
- X.509 client certificates
- Requires an HTTPS connection to the API server.
- Verified by the API server against a trusted certificate authority bundle.
- 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.
1.3.1. OpenShift Container Platform OAuth server
The OpenShift Container Platform master includes a built-in OAuth server. Users obtain OAuth access tokens to authenticate themselves to the API.
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.
1.3.1.1. OAuth token requests
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:
| OAuth Client | Usage |
|---|---|
|
|
Requests tokens at |
|
|
Requests tokens with a user-agent that can handle |
<namespace_route> refers to the namespace’s route. This is found by running the following command.
$ oc get route oauth-openshift -n openshift-authentication -o json | jq .spec.host
All requests for OAuth tokens involve a request to <namespace_route>/oauth/authorize. Most authentication integrations place an authenticating proxy in front of this endpoint, or configure OpenShift Container Platform to validate credentials against a backing identity provider. Requests to <namespace_route>/oauth/authorize can come from user-agents that cannot display interactive login pages, such as the CLI. Therefore, OpenShift Container Platform supports authenticating using a WWW-Authenticate challenge in addition to interactive login flows.
If an authenticating proxy is placed in front of the <namespace_route>/oauth/authorize endpoint, it sends unauthenticated, non-browser user-agents WWW-Authenticate challenges rather than displaying an interactive login page or redirecting to an interactive login flow.
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.
If the authenticating proxy cannot support WWW-Authenticate challenges, or if OpenShift Container Platform is configured to use an identity provider that does not support WWW-Authenticate challenges, you must use a browser to manually obtain a token from <namespace_route>/oauth/token/request.
1.3.1.2. API impersonation
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.
1.3.1.3. Authentication metrics for Prometheus
OpenShift Container Platform captures the following Prometheus system metrics during authentication attempts:
-
openshift_auth_basic_password_countcounts the number ofoc loginuser name and password attempts. -
openshift_auth_basic_password_count_resultcounts the number ofoc loginuser name and password attempts by result,successorerror. -
openshift_auth_form_password_countcounts the number of web console login attempts. -
openshift_auth_form_password_count_resultcounts the number of web console login attempts by result,successorerror. -
openshift_auth_password_totalcounts the total number ofoc loginand web console login attempts.
