Bug 1568437 - [DOCS] Improve docs for user impersonation to include group information
Summary: [DOCS] Improve docs for user impersonation to include group information
Keywords:
Status: CLOSED CURRENTRELEASE
Alias: None
Product: OpenShift Container Platform
Classification: Red Hat
Component: Documentation
Version: 3.7.0
Hardware: Unspecified
OS: Unspecified
unspecified
unspecified
Target Milestone: ---
: ---
Assignee: Kathryn Alexander
QA Contact: Chuan Yu
Vikram Goyal
URL:
Whiteboard: 3.10-release-plan
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2018-04-17 13:47 UTC by Mo
Modified: 2018-05-09 00:52 UTC (History)
5 users (show)

Fixed In Version:
Doc Type: If docs needed, set a value
Doc Text:
Clone Of:
Environment:
Last Closed: 2018-04-20 19:45:41 UTC
Target Upstream Version:


Attachments (Terms of Use)

Description Mo 2018-04-17 13:47:49 UTC
Document URL: https://docs.openshift.com/container-platform/3.7/architecture/additional_concepts/authentication.html#authentication-impersonation

Section Number and Name: authentication-impersonation

Describe the issue: 

The correct docs are correct but lack information on how to impersonate a specific group (which is required to create a project request on behalf of a user).

Suggestions for improvement: 

Add a new subsection to the impersonation docs that demonstrate that

-as=<user> --as-group=<group1> --as-group=<group2>

is how group impersonation is handled.

Then add a specific example that points out that group impersonation of system:authenticated:oauth is required to create a project request on behalf of a user (because system:authenticated:oauth is the only bootstrap group that can create project requests):

oc new-project <project> --as=<user> --as-group=system:authenticated --as-group=system:authenticated:oauth

To confirm that the project was correctly requested as the user, check the openshift.io/requester annotation:

oc get project <project> -o jsonpath='{.metadata.annotations.openshift\.io/requester}'

Additional information: 

Unrelated change:

The line "You can add a user to that group using oc adm policy add-cluster-role-to-user sudoer <username>." should be changed to "You can grant a user that permission by running:

oc create clusterrolebinding <any_valid_name> --clusterrole=sudoer --user=<username>"

Comment 1 Kathryn Alexander 2018-04-17 15:25:28 UTC
Mo, when would a user need to impersonate a user without also impersonating a group?

Is the group impersonation required only when you're creating a project, or are there other cases where you'd need to provide the group information, too?

Comment 2 Mo 2018-04-17 18:26:56 UTC
(In reply to Kathryn Alexander from comment #1)
> Mo, when would a user need to impersonate a user without also impersonating
> a group?

When the user directly has the permissions needed to perform some action (instead of indirectly having the permission based on group membership).

Impersonation, in general, is rarely used.  The most common use case is the sudoer example given in the current docs, which works without any group impersonation.

> 
> Is the group impersonation required only when you're creating a project, or
> are there other cases where you'd need to provide the group information, too?

It depends on the actions you want to take as the impersonated user.  Creating project requests is bound to system:authenticated:oauth, so you have to impersonate that group as well as the user.  But that is just one of an infinite set of arbitrary situations that could occur.

The real issue is that we used to automagically impersonate groups for you.  But as part of normalizing ourselves on top of kube, we had to give up that feature.  The specific case of project requests is one of possibly many flows that broke because of this.  That being said, we have had zero customer issues because of this (likely because no one really uses impersonation).

Comment 3 Kathryn Alexander 2018-04-19 20:33:39 UTC
@Mo, that's totally fair. It's good to know that not many people are using impersonation, but since you've already given me all of the information for this particular broken flow, I'm going to make the change. If more people start using it and report issues, maybe we can create better rules for this function. Thank you.

The PR is here: https://github.com/openshift/openshift-docs/pull/8819

Chaun, will you please take a look?

Comment 4 Chuan Yu 2018-04-20 03:01:02 UTC
@kalexand@redhat.com Just a typo, other is Ok, verified with OCP v3.10.0-0.22.0

Comment 5 Kathryn Alexander 2018-04-20 13:16:10 UTC
Thank you! I've fixed the typo and requested peer review before I merge.

Comment 6 Kathryn Alexander 2018-04-20 13:16:25 UTC
Thank you! I've fixed the typo and requested peer review before I merge.


Note You need to log in before you can comment on or make changes to this bug.