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

Merge pull request #599 from mattmoyer/docs-tweak-configure-supervisor-with-gitlab

Browse Source 
Do some minor copyediting on "configure-supervisor-with-gitlab.md".
This commit is contained in:
Matt Moyer 2021-05-04 17:32:14 -05:00 committed by GitHub
commit a8bccc5432
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 105 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,92 +1,140 @@
--- ---
title: Configure the Pinniped Supervisor to use Gitlab as an OIDC Provider title: Configure the Pinniped Supervisor to use GitLab as an OIDC Provider
description: Set up the Pinniped Supervisor to use Gitlab login. description: Set up the Pinniped Supervisor to use GitLab login.
cascade: cascade:
layout: docs layout: docs
menu: menu:
docs: docs:
name: Configure Supervisor With Gitlab name: Configure Supervisor With GitLab
weight: 35 weight: 35
parent: howtos parent: howtos
--- ---
The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer that supports connecting a single "upstream" OIDC identity provider to many "downstream" cluster clients. The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer that supports connecting a single "upstream" OIDC identity provider to many "downstream" cluster clients.
This guide shows you how to configure the Supervisor so that users can authenticate to their Kubernetes This guide shows you how to configure the Supervisor so that users can authenticate to their Kubernetes
cluster using their Gitlab credentials. cluster using their GitLab credentials.
## Prerequisites ## Prerequisites
This how-to guide assumes that you have already installed the Pinniped 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, as and that you have [configured a `FederationDomain` to issue tokens for your downstream clusters]({{< ref "configure-supervisor" >}}).
described [here](https://pinniped.dev/docs/howto/configure-supervisor/).
## Configuring your Gitlab Application ## Configure your GitLab Application
1. In Gitlab, navigate to User Settings > Applications
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.
For example, to create a user-owned application:
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 `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_.
## 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.
For example, this OIDCIdentityProvider and corresponding Secret for [gitlab.com](https://gitlab.com) use the `nickname` claim (GitLab username) as the Kubernetes username:
## Configuring 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.
For example, here is an `OIDCIdentityProvider` that works against https://gitlab.com, and uses the email claim as the username.
```yaml ```yaml
apiVersion: idp.supervisor.pinniped.dev/v1alpha1 apiVersion: idp.supervisor.pinniped.dev/v1alpha1
kind: OIDCIdentityProvider kind: OIDCIdentityProvider
metadata: metadata:
name: my-oidc-provider namespace: pinniped-supervisor
name: gitlab
spec: spec:
# The upstream issuer name.
# This should be something like https://gitlab.com or https://gitlab.your-company-name.example.com.
issuer: "https://gitlab.com"
# If needed, specify the CA bundle for the GitLab server as base64 encoded PEM data.
#tls:
# certificateAuthorityData: "<gitlab-ca-bundle>"
authorizationConfig:
# Any scopes other than "openid" that you selected when creating your GitLab application.
additionalScopes: [ email, profile ]
# See here for a list of available claims: https://docs.gitlab.com/ee/integration/openid_connect_provider.html#shared-information
claims:
# The name of the claim in your GitLab token that will be mapped to the "username" claim in downstream
# tokens minted by the Supervisor.
# For example, "email" or "sub".
username: "email"
# The name of the claim in GitLab that represents the groups that the user belongs to.
# Note that GitLab's "groups" claim comes from their /userinfo endpoint, not the token.
groups: "groups"
client:
# The name of the kubernetes secret that contains your GitLab application's client ID and client secret.
secretName: my-oidc-provider-client-secret
```
Then, create a `Secret` containing the Client ID and Client Secret in the same namespace as the Supervisor. # Specify the upstream issuer URL.
```yaml issuer: https://gitlab.com
# Specify how GitLab claims are mapped to Kubernetes identities.
claims:
# 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.
username: nickname
# 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
# their "/userinfo" endpoint, not the token.
groups: groups
# Specify the name of the Kubernetes Secret that contains your GitLab
# application's client credentials (created below).
client:
secretName: gitlab-client-credentials
---
apiVersion: v1 apiVersion: v1
kind: Secret kind: Secret
metadata: metadata:
name: my-oidc-provider-client-secret namespace: pinniped-supervisor
name: gitlab-client-credentials
type: secrets.pinniped.dev/oidc-client
stringData: stringData:
# clientID should be the Application ID that you got from GitLab.
clientID: xxx # The "Application ID" that you got from GitLab.
# clientSecret should be the Secret that you got from GitLab. clientID: "<your-client-id>"
clientSecret: yyy
type: "secrets.pinniped.dev/oidc-client" # The "Secret" that you got from GitLab.
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 my-oidc-identity-provider 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. For example, the output of `cat my-ca-bundle.pem | base64`.
#
# This 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, 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" >}}).
you may want to check out [Configure Concierge JWT Authentication](https://pinniped.dev/docs/howto/configure-concierge-jwt/)
to learn how to configure the Concierge to use the JWTs that the Supervisor now issues.