OIDC Authenticator

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, 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.

1. 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.

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

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

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

5. 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
   

6. 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 contents.

7. Click Install.

8. Wait for the application to change its status to Deployed.

To access cluster resources:

1. Assign roles in the cluster to the relevant groups in the organization. Here is an example:

   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. Here is an example:

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

   When first running the kubectl command, the employee will be redirected to the browser to authenticate with OIDC and issue an OAuth token for accessing the cluster.

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

Yandex Cloud technical support is available 24/7. The types of requests available and their response time depend on your pricing plan. You can switch to the paid support plan in the management console. You can learn more about the technical support terms here.