Merge pull request #13051 from kalexand-rh/osdocs-59

tokens and user agent and impersonation

Author: kalexand-rh

_topic_map.yml

@@ -51,9 +51,28 @@ Name: Authentication
 Dir: authentication
 Distros: openshift-*
 Topics:
+- Name: Understanding authentication
+  File: understanding-authentication  
+- Name: Configuring the internal OAuth server
+  File: configuring-internal-oauth  
 - Name: Using RBAC to define and apply permissions
-  File: using-rbac
+  File: using-rbac  
+- Name: Configuring the user agent
+  File: configuring-user-agent
+- Name: Using a service account as an OAuth client
+  File: using-service-accounts-as-oauth-client 
 ---
+Name: Users and roles
+Dir: users_and_roles
+Distros: openshift-*
+Topics:
+- Name: Impersonating the system:admin user
+  File: impersonating-system-admin
+  Distros: openshift-enterprise,openshift-origin 
+- Name: Creating a project as another user
+  File: creating-project-other-user
+  Distros: openshift-enterprise,openshift-origin  
+---   
 Name: Installing clusters
 Dir: installation
 Distros: openshift-origin, openshift-enterprise

authentication/configuring-internal-oauth.adoc

@@ -0,0 +1,26 @@
+[id='configuring-internal-oauth']
+= Configuring the internal OAuth server
+include::modules/common-attributes.adoc[]
+:context: configuring-internal-oauth
+toc::[]
+
+
+[IMPORTANT]
+====
+Configuring these options will need to change because they're set in the master
+config file now.
+====
+
+include::modules/oauth-server-overview.adoc[leveloffset=+2]
+
+include::modules/oauth-internal-tokens.adoc[leveloffset=+1]
+
+include::modules/oauth-internal-options.adoc[leveloffset=+1]
+
+include::modules/oauth-configuring-internal-oauth.adoc[leveloffset=+1]
+
+include::modules/oauth-register-additional-server.adoc[leveloffset=+1]
+
+include::modules/oauth-server-metadata.adoc[leveloffset=+1]
+
+include::modules/oauth-troubleshooting-api-events.adoc[leveloffset=+1]

authentication/configuring-user-agent.adoc

@@ -0,0 +1,9 @@
+[id='configuring-user-agent']
+= Configuring the user agent
+include::modules/common-attributes.adoc[]
+:context: configuring-user-agent
+toc::[]
+ 
+include::modules/user-agent-overview.adoc[leveloffset=+1]
+
+include::modules/user-agent-configuring.adoc[leveloffset=+1]

authentication/understanding-authentication.adoc

@@ -0,0 +1,16 @@
+[id='understanding-authentication']
+= Understanding authentication
+include::modules/common-attributes.adoc[]
+:context: understanding-authentication
+toc::[]
+ 
+include::modules/authentication-overview.adoc[leveloffset=+1]
+
+include::modules/oauth-server-overview.adoc[leveloffset=+2]
+
+include::modules/oauth-token-requests.adoc[leveloffset=+2]
+
+include::modules/authentication-api-impersonation.adoc[leveloffset=+3]
+
+
+include::modules/authentication-prometheus-system-metrics.adoc[leveloffset=+3]

authentication/using-service-accounts-as-oauth-client.adoc

@@ -0,0 +1,7 @@
+[id='using-service-accounts-as-oauth-client']
+= Using a service account as an OAuth client
+include::modules/common-attributes.adoc[]
+:context: using-service-accounts-as-oauth-client
+toc::[]
+ 
+include::modules/service-accounts-as-oauth-clients.adoc[leveloffset=+1]

modules/authentication-api-impersonation.adoc

@@ -0,0 +1,30 @@
+// Module included in the following assemblies:
+//
+// * authentication/understanding-authentication.adoc
+// * users_and_roles/creating-project-other-user.adoc
+// * users_and_roles/impersonating-system-admin.adoc
+
+[id='authentication-api-impersonation-{context}']
+= API impersonation
+A request to the {product-title} API can include an `Impersonate-User` header,
+which indicates that the requester wants the request handled as though
+it came from the specified user.
+
+Before User A can impersonate User B, User A is authenticated.
+Then, an authorization check occurs to ensure that User A is allowed to
+impersonate the user named User B. If User A is requesting to impersonate a
+service account, `system:serviceaccount:namespace:name`, {product-title} confirms
+that User A can impersonate the `serviceaccount` named `name` in
+`namespace`. If the check fails, the request fails with a 403 (Forbidden) error
+code.
+
+By default, project administrators and editors can impersonate
+service accounts in their namespace.
+ifdef::openshift-origin,openshift-enterprise[]
+The `sudoers` role allows a user to
+impersonate `system:admin`, which in turn has cluster administrator permissions.
+The ability to impersonate `system:admin` grants some protection against typos,
+but not security, for someone
+administering the cluster. For example, running `oc delete nodes --all` fails,
+but running `oc delete nodes --all --as=system:admin` succeeds.
+endif::[]

modules/authentication-overview.adoc

@@ -0,0 +1,73 @@
+// Module included in the following assemblies:
+//
+// * authentication/understanding-authentication.adoc
+
+[id='authentication-overview-{context}']
+= Authentication overview
+
+For users to interact with {product-title}, they must first authenticate
+to the cluster. The authentication layer identifies the user associated with requests to the
+{product-title} API. The authorization layer then uses information about the
+requesting user to determine if the request should be allowed.
+
+ifdef::openshift-enterprise,openshift-origin[]
+As an administrator, you can configure authentication for {product-title}.
+endif::[]
+
+[id='users-and-groups-{context}']
+== Users and groups
+
+A _user_ in {product-title} is an entity that can make requests to the
+{product-title} API. Typically, this represents the account of a developer or
+administrator that is interacting with {product-title}.
+
+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:
+
+//WHY?
+
+[cols="2,5",options="header"]
+|===
+
+|Virtual group |Description
+
+|`system:authenticated` |Automatically associated with all authenticated users.
+|`system:authenticated:oauth` |Automatically associated with all users authenticated with an OAuth access token.
+|`system:unauthenticated` |Automatically associated with all unauthenticated users.
+
+|===
+
+[id='api-authentication-{context}']
+== API authentication
+Requests to the {product-title} API are authenticated using the following
+methods:
+
+OAuth Access Tokens::
+* Obtained from the {product-title} OAuth server using the
+`_<master>_/oauth/authorize` and `_<master>_/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 a 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.

modules/authentication-prometheus-system-metrics.adoc

@@ -0,0 +1,14 @@
+// Module included in the following assemblies:
+//
+// * authentication/understanding-authentication.adoc
+
+[id='authentication-prometheus-system-metrics-{context}']
+= Authentication metrics for Prometheus
+
+{product-title} 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_form_password_count_result` counts the number of web console login attempts by result, `success` or `error`.
+* `openshift_auth_password_total` counts the total number of `oc login` and web console login attempts.

modules/impersonation-project-creation.adoc

@@ -0,0 +1,20 @@
+// Module included in the following assemblies:
+//
+// * users_and_roles/creating-project-other-user.adoc
+
+[id='impersonation-project-creation-{context}']
+= Impersonating a user when you create a project
+
+You can impersonate a different user when you create a project request. Because
+`system:authenticated:oauth` is the only bootstrap group that can
+create project requests, you must impersonate that group.
+
+.Procedure
+
+* To create a project request on behalf of a different user:
++
+[source,bash]
+----
+$ oc new-project <project> --as=<user> \
+--as-group=system:authenticated --as-group=system:authenticated:oauth
+----

modules/impersonation-system-admin-user.adoc

@@ -0,0 +1,18 @@
+// Module included in the following assemblies:
+//
+// * users_and_roles/impersonating-system-admin.adoc
+
+[id='impersonation-system-admin-user-{context}']
+= Impersonating the `system:admin` user
+
+You can grant a user permission to impersonate `system:admin`, which grants them
+cluster administrator permissions.
+
+.Procedure
+
+* To grant a user permission to impersonate `system:admin`, run the following command:
++
+[source,bash]
+----
+$ oc create clusterrolebinding <any_valid_name> --clusterrole=sudoer --user=<username>
+----