Installing OIDC Authentication

OIDC Authentication is an application for authenticating users in a Managed Service for Kubernetes cluster with third-party authentication providers supporting the following identity and access management protocols: OIDC, Active Directory, [LDAP]https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol, or GitHub. OIDC Authentication uses OAuth 2.0 to issue user access tokens by ID and secret key received from the provider.

The application has two components:

• Concierge, a proxy server for the Kubernetes API.
• Supervisor, a cluster authorization OIDC server for the proxy server.

The solution is powered by Pinniped.

Getting startedGetting started

1. If you do not have the Yandex Cloud CLI installed yet, install and initialize it.

   By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

2. Register a new OAuth client in your organization's OIDC server and obtain the client's ID and secret key.

   For information on how to obtain the ID and secret key, see these official guides on configuring IdPs.

3. Reserve a public IP address for Supervisor using Yandex Virtual Private Cloud.

4. Register a DNS record for Supervisor (usually a supervisor.<your_domain> subdomain) using Yandex Cloud DNS and associate it with the reserved IP address.

5. Issue a certificate for your registered Supervisor domain in Yandex Certificate Manager.

6. Get the contents of the issued certificate and save it to a file named cert.json:

   yc certificate-manager certificate content <certificate_ID> \
     --format json > cert.json
   

Installing OIDC Authentication from Yandex Cloud MarketplaceInstalling OIDC Authentication from Yandex Cloud Marketplace

1. Navigate to the folder dashboard and select Managed Service for Kubernetes.

2. Click the name of the Managed Service for Kubernetes cluster you need and select the Marketplace tab.

3. Under Application available for installation, select OIDC Authentication and click Go to install.

4. Configure the application:

   • Namespace: Create a namespace named pinniped-concierge. The application uses it by default. If you leave the default namespace, OIDC Authentication may work incorrectly.
   • Application name: Specify the application name.
   • Company OIDC domain: Specify the URL of your organization's main domain.
   • Client ID: Specify the OAuth client ID.
   • Client secret: Specify the OAuth client secret key.
   • Additional access permissions: Specify additional access permissions for the token.
   • Username field in token: Specify the name of the field containing the user name.
   • Group field in token: Specify the name of the field containing the user group.
   • Supervisor domain: Specify the Supervisor subdomain you created earlier.
   • Supervisor IP address: Specify the IP address you reserved earlier.
   • Supervisor domain certificate: Paste the cert.json file contents.

5. Click Install.

6. Wait for the application status to change to Deployed.

Installation using a Helm chartInstallation using a Helm chart

1. Install Helm v3.8.0 or higher.

2. Install kubect and configure it to work with the new cluster.

3. To install a Helm chart with OIDC Authentication, run this command:

   helm pull oci://cr.yandex/yc-marketplace/yandex-cloud/external-secrets/chart/external-secrets \
     --version 0.1.0 \
     --untar && \
   helm install \
     --namespace pinniped-concierge \
     --create-namespace \
     --set domain=<organization_main_domain> \
     --set client_id=<OAuth_client_ID> \
     --set client_secret=<OAuth_client_secret_key> \
     --set username_claim=<token_field_with_username> \
     --set group_claim=<token_field_with_group> \
     --set domain=<organization_Supervisor_subdomain> \
     --set ip=<Supervisor_subdomain_IP_address> \
     --set additional_scopes=<additional_access_permissions_for_token> \
     --set-file certificate=<cert.json_file_path> \
     oidc-authenticator ./oidc-authenticator/
   

   This command creates a new namespace required for OIDC Authentication.

   Note

   If you are using a Helm version below 3.8.0, append the export HELM_EXPERIMENTAL_OCI=1 && \ string to the command to enable Open Container Initiative (OCI) support in the Helm client.

Getting cluster accessGetting cluster access

1. Assign roles in the cluster to the relevant user in the organization.

   Example of assigning a role

   kind: ClusterRoleBinding
   apiVersion: rbac.authorization.k8s.io/v1
   metadata:
     name: clusterroleall-user
   subjects:
   - kind: User
     name: <user_account_ID_in_organization>
   roleRef:
     kind: ClusterRole
     name: <role_in_cluster>
     apiGroup: rbac.authorization.k8s.io
   

2. Perform the following steps on a computer with access permissions for Supervisor resources in the cluster:

   1. Install pinniped-cli.

   2. To get the public configuration file, run this command:

      pinniped get kubeconfig \
        --upstream-identity-provider-flow browser_authcode > public_config.yaml
      

      For LDAP and Active Directory providers, the command uses different parameters:

      pinniped get kubeconfig \
        --upstream-identity-provider-flow cli_password > public_config.yaml 
      

      Learn more about the command parameters in the official documentation.

3. Install the required resources on the employee's computer:

   1. Install pinniped-cli.
   2. Copy the public configuration. In the public configuration file, specify the local path to pinniped-cli in the users.user.exec.command parameter.

4. Specify the public configuration file when running commands in the cluster, e.g.:

   kubectl get namespaces \
     --kubeconfig "$HOME/public_config.yaml"
   

   When first running the kubectl command, the employee will be redirected to the browser to get authenticated with OIDC and issue an OAuth token to access the cluster.

   Further kubectl commands will run without authentication until the access token expires.

See alsoSee also

• Pinniped documentation