mirrors/pinniped
1
0
Fork 0
mirror of https://github.com/vmware-tanzu/pinniped.git synced 2026-07-29 11:32:58 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

change some wording in github doc

Browse Source
This commit is contained in:
Ryan Richard
2024-05-09 11:05:48 -07:00
parent 96e4442181
commit f377292ffe
1 changed files with 60 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
site/content/docs/howto/supervisor/configure-supervisor-with-github.md
+60 -36
View File
@@ -17,9 +17,6 @@ The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer
This guide shows you how to configure the Supervisor so that users can authenticate to their Kubernetes
cluster using their credentials from [GitHub.com](https://github.com) or [GitHub enterprise server](https://docs.github.com/en/enterprise-server@latest/admin/overview/about-github-enterprise-server).
Currently, Pinniped supports GitHub API version `2022-11-28` ([ref](https://docs.github.com/en/rest/about-the-rest-api/api-versions?apiVersion=2022-11-28)).
Future GitHub API versions may include breaking changes.
## Prerequisites
This how-to guide assumes that you have already [installed the Pinniped Supervisor]({{< ref "install-supervisor" >}}) with working ingress,
@@ -37,8 +34,11 @@ TODO: add text
Create a [GitHubIdentityProvider](https://github.com/vmware-tanzu/pinniped/blob/main/generated/{{< latestcodegenversion >}}/README.adoc#githubidentityprovider) in the same namespace as the Supervisor.
The simplest example uses https://github.com as the source of identity, and will allow any user with a GitHub account to log in.
The simplest example uses https://github.com as the source of identity.
Note that you do not need to explicitly specify a GitHub host since `github.com` is the default.
This example allows any user with a GitHub account to log in.
You may prefer to limit which users may authenticate by GitHub organization or team membership.
See the following examples for more information about limiting which users can authenticate.
```yaml
apiVersion: idp.supervisor.pinniped.dev/v1alpha1
@@ -66,8 +66,7 @@ stringData:
clientSecret: "<your-client-secret>"
```
For another example, let's fill out all fields.
Here we will configure a host and certificate for a GitHub Enterprise Server installation.
For another example, let's fill out all available fields.
```yaml
apiVersion: idp.supervisor.pinniped.dev/v1alpha1
@@ -77,39 +76,45 @@ metadata:
name: github-enterprise
spec:
githubAPI:
# This field is only required when using GitHub Enterprise Server.
# Only the hostname or IP address and optional port, without the protocol.
# Pinniped will always use HTTPS.
host: github.enterprise.tld
tls:
# This field is usually only used for GitHub Enterprise Server.
# Specify the CA certificate of the server as a
# base64-encoded PEM bundle.
certificateAuthorityData: LS0tLS1CRUdJTiBDRVJUSUZJQ0FU....
client:
secretName: github-enterprise-client-credentials
allowAuthentication:
allowAuthentication:
# "policy: OnlyUsersFromAllowedOrganizations" restricts authentication to only
# those users who belong in at least one of the "allowed" organizations.
# those users who belong to at least one of the "allowed" organizations.
# Additionally, their groups as presented to K8s will only reflect team
# membership within these organizations.
organizations:
policy: OnlyUsersFromAllowedOrganizations
allowed:
- my-enterprise-organization
- admin-organization
- my-other-organization
claims:
# Use the login attribute of a user as the username to present to K8s.
# This attribute is taken from GitHub API endpoint "Get the authenticated user".
# https://docs.github.com/en/rest/users/users?apiVersion=2022-11-28#get-the-authenticated-user.
username: login
# Use the name attribute of a team as the group name to present to K8s for RBAC .
# This attribute is taken from GitHub API endpoint "List teams for the authenticated user".
# https://docs.github.com/en/rest/teams/teams?apiVersion=2022-11-28#list-teams-for-the-authenticated-user.
groups: name
# This field chooses how the username will be presented to K8s.
# Allowed values are "id", "login", or "login:id". The login and id attributes
# are taken from the results of the GitHub "/user" API endpoint.
# See https://docs.github.com/en/rest/users/users.
# Using "id" or "login:id" is recommended because GitHub users can change their
# own login name, but cannot change their numeric ID.
username: "login:id"
# This field chooses how the team names will be presented to K8s as group names.
# Allowed values are "name" or "slug". The name and slug attributes
# are taken from the results of the GitHub "/user/teams" API endpoint.
# See https://docs.github.com/en/rest/teams/teams.
# E.g. for a team named "Kube admins!", the name will be "Kube admins!"
# while the slugs will be "kube-admins".
groups: slug
---
apiVersion: v1
@@ -134,32 +139,51 @@ kubectl describe GitHubIdentityProvider -n pinniped-supervisor <resource-name>
Look at the `status` field. If it was configured correctly, you should see `status.phase: Ready`.
Otherwise, inspect the `status.conditions` array for more information.
## Org and Team membership visibility
Pinniped may not be able to see which organizations to which a user belongs, or which teams to which a user
belongs within an org. When Pinniped is configured to restrict authentication by org membership, it will reject a user's
authentication when it cannot see that the user belongs to one of the required orgs.
Furthermore, the user's team memberships will only be presented to Kubernetes as group names for those
teams that Pinniped is allowed to see.
Which orgs and teams are returned by the GitHub API is controlled by the GitHub App or GitHub OAuth App that you configure.
In order for a GitHub App or GitHub OAuth App to see the team memberships with an org, the app must either:
1. Be owned (created) by that Org
2. Or, be approved by the owners of that Org for use with that Org
Note that for a Github OAuth app, the owner of an org may also choose to implicitly approve
all GitHub OAuth Apps owned by members of the org.
## Additional authentication restrictions
The GitHubIdentityProvider specification permits restricting authentication based on organization membership.
It's possible to use CEL expressions as part of a [policy expression pipeline]({{< ref "configure-supervisor-federationdomain-idps" >}}) to further restrict authentication.
It's possible to use CEL expressions as part of a [policy expression pipeline]({{< ref "configure-supervisor-federationdomain-idps" >}})
to further restrict authentication based on usernames and group names.
For example, to restrict authentication to a set of users who do not have any shared organization membership, you can add a policy similar to the following:
For example, when you use `spec.allowAuthentication.organizations.policy: AllGitHubUsers` then any GitHub user
can authenticate. A CEL expression could be used to further restrict authentication to a set of specific users
with a policy like this:
```yaml
transforms:
constants:
- name: allowedUsersByLogin
type: stringList
stringListValue:
- "cfryanr"
- "benjaminapetersen"
- "joshuatcasey"
expressions:
- type: policy/v1
expression: 'username in strListConst.allowedUsersByLogin'
message: "Only specified users may authenticate"
transforms:
constants:
- name: allowedUsers
type: stringList
stringListValue:
- "cfryanr"
- "joshuatcasey"
expressions:
- type: policy/v1
expression: 'username in strListConst.allowedUsers'
message: "Only certain GitHub users may authenticate"
```
In this case, you will need to set `spec.allowAuthentication.organizations.policy: AllGitHubUsers` so that organization membership will not be used to restrict authentication.
You could also use similar CEL expressions to limit authentication by GitHub team membership.
Remember that Pinniped may not be able to see the user's teams in every organization unless the GitHub App is installed in that organization and given appropriate permissions,
or the user's organization membership is public and that organization has chosen to make its team membership public.
## Notes
Currently, Pinniped supports GitHub API version `2022-11-28` ([ref](https://docs.github.com/en/rest/about-the-rest-api/api-versions?apiVersion=2022-11-28)).
## Next steps