djpbessems/ContainerImage.Pinniped
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

More adjustments to configure-supervisor-with-gitlab.md.

Browse Source 
- Use `nickname` claim as an example, which means we only need the `openid` scope.
  This is also more stable since emails can change over time.

- Put the OIDCIdentityProvider and Secret into one YAML blob, since they will likely be copy-pasted together anyway.

- Add a separate section for using alternate claims.

- Add a separate section for using a private GitLab instance.

Signed-off-by: Matt Moyer <moyerm@vmware.com>
This commit is contained in:
Matt Moyer 2021-05-04 15:33:33 -05:00
parent 3e13b5f39d
commit 8136c787a7
No known key found for this signature in database
GPG Key ID: EAE88AD172C5AE2D
1 changed files with 57 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

87
site/content/docs/howto/configure-supervisor-with-gitlab.md
View File

@ -19,7 +19,7 @@ cluster using their GitLab credentials.
This how-to guide assumes that you have already [installed the Pinniped Supervisor]({{< ref "install-supervisor" >}}) with working ingress, This how-to guide assumes that you have already [installed the Pinniped Supervisor]({{< ref "install-supervisor" >}}) with working ingress,
and that you have [configured a `FederationDomain` to issue tokens for your downstream clusters]({{< ref "configure-supervisor" >}}). and that you have [configured a `FederationDomain` to issue tokens for your downstream clusters]({{< ref "configure-supervisor" >}}).
## Configuring your GitLab Application ## Configure your GitLab Application
Follow the instructions for [using GitLab as an OAuth2 authentication service provider](https://docs.gitlab.com/ee/integration/oauth_provider.html) and create a user, group, or instance-wide application. Follow the instructions for [using GitLab as an OAuth2 authentication service provider](https://docs.gitlab.com/ee/integration/oauth_provider.html) and create a user, group, or instance-wide application.
@ -27,17 +27,17 @@ For example, to create a user-owned application:
1. In GitLab, navigate to [_User Settings_ > _Applications_](https://gitlab.com/-/profile/applications) 1. In GitLab, navigate to [_User Settings_ > _Applications_](https://gitlab.com/-/profile/applications)
1. Create a new application: 1. Create a new application:
1. Enter the name of your application. 1. Enter a name for your application, such as "My Kubernetes Clusters".
1. Enter the redirect URI. This is the `spec.issuer` you configured in your `FederationDomain` appended with `/callback`. 1. Enter the redirect URI. This is the `spec.issuer` you configured in your `FederationDomain` appended with `/callback`.
1. Check the box saying that the application is _Confidential_. 1. Check the box saying that the application is _Confidential_.
1. Select scope `openid`. Optionally select `profile` and `email`. 1. Select scope `openid`. This provides access to the `nickname` (GitLab username) and `groups` (GitLab groups) claims.
1. Save the application and make note of the _Application ID_ and _Secret_. 1. Save the application and make note of the _Application ID_ and _Secret_.
## Configuring the Supervisor cluster ## Configure the Supervisor cluster
Create an [`OIDCIdentityProvider`](https://github.com/vmware-tanzu/pinniped/blob/main/generated/1.20/README.adoc#oidcidentityprovider) in the same namespace as the Supervisor. Create an [OIDCIdentityProvider](https://github.com/vmware-tanzu/pinniped/blob/main/generated/1.20/README.adoc#oidcidentityprovider) in the same namespace as the Supervisor.
For example, here is an `OIDCIdentityProvider` that works against [gitlab.com](https://gitlab.com) and uses the GitLab `email` claim as the Kubernetes username: For example, this OIDCIdentityProvider and corresponding Secret for [gitlab.com](https://gitlab.com) use the `nickname` claim (GitLab username) as the Kubernetes username:
```yaml ```yaml
apiVersion: idp.supervisor.pinniped.dev/v1alpha1 apiVersion: idp.supervisor.pinniped.dev/v1alpha1
@ -47,30 +47,15 @@ metadata:
name: gitlab name: gitlab
spec: spec:
# Specify the upstream issuer name. This should be something like # Specify the upstream issuer URL.
# https://gitlab.com or https://gitlab.your-company.example.com.
issuer: https://gitlab.com issuer: https://gitlab.com
# Specify the CA bundle for the GitLab server as base64-encoded PEM
# data. This will only be needed for self-managed GitLab.
# tls:
# certificateAuthorityData: "<gitlab-ca-bundle>"
# Request any scopes other than "openid" that you selected when
# creating your GitLab application.
authorizationConfig:
additionalScopes: [ email, profile ]
# Specify how GitLab claims are mapped to Kubernetes identities. # Specify how GitLab claims are mapped to Kubernetes identities.
claims: claims:
# Specify the name of the claim in your GitLab token that will be mapped # Specify the name of the claim in your GitLab token that will be mapped
# to the "username" claim in downstream tokens minted by the Supervisor. # to the "username" claim in downstream tokens minted by the Supervisor.
# For example, "email" or "sub". username: nickname
#
# See here for a full list of available claims:
# https://docs.gitlab.com/ee/integration/openid_connect_provider.html
username: email
# Specify the name of the claim in GitLab that represents the groups # Specify the name of the claim in GitLab that represents the groups
# that the user belongs to. Note that GitLab's "groups" claim comes from # that the user belongs to. Note that GitLab's "groups" claim comes from
@ -81,11 +66,7 @@ spec:
# application's client credentials (created below). # application's client credentials (created below).
client: client:
secretName: gitlab-client-credentials secretName: gitlab-client-credentials
``` ---
Then, create a `Secret` containing the Client ID and Client Secret in the same namespace as the Supervisor:
```yaml
apiVersion: v1 apiVersion: v1
kind: Secret kind: Secret
metadata: metadata:
@ -101,14 +82,60 @@ stringData:
clientSecret: "<your-client-secret>" clientSecret: "<your-client-secret>"
``` ```
To validate your configuration, run: Once your OIDCIdentityProvider has been created, you can validate your configuration by running:
```shell ```shell
kubectl describe OIDCIdentityProvider gitlab kubectl describe OIDCIdentityProvider -n pinniped-supervisor gitlab
``` ```
Look at the `status` field. If it was configured correctly, you should see `phase: Ready`. Look at the `status` field. If it was configured correctly, you should see `phase: Ready`.
### (Optional) Use a different GitLab claim for Kubernetes usernames
You can also use other GitLab claims as the username.
To do this, make sure you have configured the appropriate scopes on your GitLab application, such as `email`.
You must also adjust the `spec.authorizationConfig` to request those scopes at login and adjust `spec.claims` to use those claims in Kubernetes, for example:
```yaml
# [...]
spec:
# Request any scopes other than "openid" that you selected when
# creating your GitLab application. The "openid" scope is always
# included.
#
# See here for a full list of available claims:
# https://docs.gitlab.com/ee/integration/openid_connect_provider.html
authorizationConfig:
additionalScopes: [ email ]
claims:
username: email
groups: groups
# [...]
```
### (Optional) Use a private GitLab instance
To use privately hosted instance of GitLab, you can change the `spec.issuer` and `spec.tls.certificateAuthorityData` fields, for example:
```yaml
apiVersion: idp.supervisor.pinniped.dev/v1alpha1
kind: OIDCIdentityProvider
# [...]
spec:
# Specify your GitLab instance URL.
issuer: https://gitlab.your-company.example.com.
# Specify the CA bundle for the GitLab server as base64-encoded PEM
# data. This will only be needed for self-managed GitLab. For example,
# the output of `cat my-ca-bundle.pem | base64`.
#
# This configuration is only necessary if your instance uses a custom CA.
tls:
certificateAuthorityData: "<gitlab-ca-bundle>"
# [...]
```
## Next Steps ## Next Steps
Now that you have configured the Supervisor to use GitLab, you may want to [configure the Concierge to validate JWTs issued by the Supervisor]({{< ref "configure-concierge-jwt" >}}). Now that you have configured the Supervisor to use GitLab, you may want to [configure the Concierge to validate JWTs issued by the Supervisor]({{< ref "configure-concierge-jwt" >}}).