Understanding authentication

    As an administrator, you can configure authentication for OKD.

    A user in OKD is an entity that can make requests to the OKD API. An OKD 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 OKD.

    Several types of users can exist:

    Each user must authenticate in some way to access OKD. API requests with no authentication or invalid authentication are authenticated as requests by the anonymous system user. After authenticated, policy determines what the user is authorized to do.

    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.

    The following default virtual groups are most important:

    Requests to the OKD API are authenticated using the following methods:

    OAuth access tokens

    • Obtained from the OKD OAuth server using the *<namespace_route>*/oauth/authorize and *<namespace_route>*/oauth/token endpoints.

    • 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.

    X.509 client certificates

    • Requires an HTTPS connection to the API server.

    • 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.

    The OKD 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.

    OAuth token requests

    1. <namespace_route> refers to the namespace route. This is found by running the following command:

    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 OKD 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, OKD 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 challenges rather than displaying an interactive login page or redirecting to an interactive login flow.

    API impersonation

    You can configure a request to the OKD API to act as though it originated from another user. For more information, see User impersonation in the Kubernetes documentation.

    Authentication metrics for Prometheus

    OKD captures the following Prometheus system metrics during authentication attempts:

    • openshift_auth_basic_password_count counts the number of oc login user name and password attempts.

    • openshift_auth_basic_password_count_result counts the number of oc login user name and password attempts by result, success or error.

    • openshift_auth_form_password_count counts the number of web console login attempts.

    • openshift_auth_password_total counts the total number of oc login and web console login attempts.