SAML user management

Overview

Tectonic Identity authenticates clients, such as kubectl and Tectonic Console, for access to the Kubernetes API and, through it, to Tectonic cluster services. All Tectonic clusters use Role Based Access Control (RBAC) to govern access to cluster services. Tectonic Identity authenticates a user's identity, and RBAC enforces authorization based on that identity. Tectonic Identity can map cluster RBAC bindings to an existing Security Assertion Markup Language (SAML) Identity Provider (IdP) over a secure channel.

This document describes managing Tectonic users, groups, and access control in concert with a SAML IdP.

Integrating Tectonic Identity with SAML

Authentication workflow

The message flow begins with a request to access Tectonic Console. Tectonic Identity constructs a SAML AuthnRequest and redirects the user to the IdP. Once the user is verified, IdP constructs an AuthnResponse to send to Tectonic Identity. Tectonic Identity verifies the response and retrieves various user information, such as email, username, and groups from AuthnResponse.

1. The Tectonic user attempts to log in to the Tectonic Console.

2. Tectonic Identity identifies the user’s origin and redirects the user to the IdP, requesting authentication. This is the authentication request (AuthnRequest).

3. The IdP builds the authentication response in the form of an XML file containing the user’s username or email address (NameID) as agreed upon, signs it using the private key of an X.509 certificate, and posts this information to Tectonic Identity.

4. Tectonic Identity, which has already established an association with the IdP, retrieves the authentication response and validates it using the public key of the X.509 certificate.

5. If the identity is established, the user is provided access to the Tectonic cluster.

Prerequisites and guidelines

Parameters must be configured on both Tectonic Identity and the SAML IdP to enable them to exchange user data. These parameters are defined for Tectonic Identity in the config-dev.yaml file, which must be mapped directly to those configured on the IdP side.

Once configured, SAML IdP exchanges security tokens with Tectonic Identity, acting as a SAML consumer, to exchange user authentication data.

The SAML IdP parameters referred to in this document are specific to Okta and are subject to change from one SAML IdP to another. See your IdP documentation for more information on SAML configuration options.

The table below describes the parameters that configure Tectonic Identity federation with IdPs:

Configuring identity federation

1. Ensure the IdP has been configured for access by Tectonic. Okta and some other IdPs refer to these clients as applications. For more information, see Prerequisites and guidelines

2. Ensure that users are added to the Tectonic application on the IdP side.

3. Ensure that Tectonic clusters are up and running.

4. Configure Tectonic Identity: Tectonic Identity pulls its configuration options from a configuration file stored in a ConfigMap, which admins can view and edit by using kubectl. To prevent misconfiguration, use kubeconfig downloaded during installation to edit Tectonic Identity's ConfigMap.

   1. Backup the existing config using kubectl:

      kubectl get configmaps tectonic-identity --namespace=tectonic-system -o yaml > identity-config.yaml.bak

   2. Edit the current ConfigMap with the desired changes:

      kubectl edit configmaps tectonic-identity --namespace=tectonic-system

   3. Add the connectors configuration.

      Replace example.com with your IdP domain name, and tectonic-domain with your Tectonic domain name.

          connectors:
          - type: saml    
            id: saml        
            name: SAML
            config:
              ssoURL: https://example.com/sso/saml
              redirectURI: https://tectonic-domain/identity/callback
              usernameAttr: name
              emailAttr: email
              groupsAttr: groups # optional
              caData: /path/to/ca.pem
              entityIssuer: https://tectonic-domain/identity/callback
              ssoIssuer: https://example.com/sso/saml
              nameIDPolicyFormat: persistent             
   

5. Trigger a rolling update using kubectl:

     kubectl patch deployment tectonic-identity \
         --patch "{\"spec\":{\"template\":{\"metadata\":{\"annotations\":{\"date\":\"`date +'%s'`\"}}}}}" \
         --namespace tectonic-system
   

6. Inspect the update's success by watching the pods in the tectonic-system namespace.

   kubectl get pods --namespace=tectonic-system

   Identity's deployment is intended to be resilient against invalid config files, but admins should verify the new state and restore the ConfigMap backup if Identity enters a crash loop.

Editing Tectonic Identity configuration

To apply a new Tectonic Identity configuration to a Kubernetes cluster:

1. Make necessary changes to the configuration file.

2. Run kubectl apply:

   $ kubectl apply -f ~/Downloads/new-tectonic-config.yaml

   If successful, the following message is displayed:

   configmap "tectonic-identity" configured

3. Restart the Tectonic Identity pods for the changes to take effect.

4. Verify the pods are patched. The following command triggers a rolling update and attaches the current date as an annotation:

   $ kubectl patch deployment tectonic-identity \ --patch "{\"spec\":{\"template\":{\"metadata\":{\"annotations\":{\"date\":\"date +'%s'\"}}}}}" \ --namespace tectonic-system

   if successful, the following message is displayed:

   "tectonic-identity" patched

5. Log out of Tectonic Console and log in again by using the SAML authentication credentials.

Create role bindings to allow SAML users access to Kubernetes resources through both Tectonic Console and kubectl. See Configuring RBAC for more details.

Using kubectl as a SAML user

To use kubectl as a SAML user:

1. Log in to your Tectonic Console as the desired user.
2. Navigate to My Account.
3. Verify your identity and download kubectl configuration.

4. Set the KUBECONFIG environment variable to the kubectl configuration file. For example:

   export KUBECONFIG=~/Download/kubectl-config

   Until otherwise modified, you can still use your static account for further administrative setup.

Handling SAML authentication expiration

Every twenty four hours, access tokens for the session will expire and a user will need to enter their credentials and log in again to regain access to the cluster.

Configuring RBAC

Access configuration requires understanding Kubernetes Roles, RoleBindings, ClusterRoles, and ClusterRoleBindings. SAML-based users do not alter this model. SAML usernames and groups can be used with Kubernetes bindings; visit the Kubernetes authorization docs to learn how to setup these configurations.

An example configuration

The following shows an example of granting user jane.doe@coreos.com admin access to the cluster.

1. Add a role binding named jane-admin:

              apiVersion: rbac.authorization.k8s.io/v1beta1
              kind: ClusterRoleBinding
              metadata:
                name: jane-admin
              roleRef:
                apiGroup: rbac.authorization.k8s.io
                kind: ClusterRole
                name: cluster-admin
              subjects:
              - kind: User
                name: jane.doe@coreos.com
   

   Tectonic Console and kubectl now reflect the updated role and binding.

2. Log in to the Tectonic Console as jane.doe.
3. Verify identity and download the kubeconfig file from the My Account page in the Tectonic Console.

4. Verify all pods are up and running:

   $ kubectl --kubeconfig=janeDoeConfig --namespace=tectonic-system get pods

   If successful, the following is displayed:

   tectonic-console-3077630014-gw253 1/1 Running 1 2h tectonic-identity-2726305807-8lqkx 1/1 Running 6 1h

Troubleshooting SAML user management

To troubleshoot users and groups configuration, check the tectonic-identity's logs to see what SAML query is being sent.

Locate the Identity's pod name:

$ kubectl --namespace=tectonic-system get pods

NAME                                         READY     STATUS    RESTARTS   AGE
tectonic-console-3077630014-gw253            1/1       Running   0          2h
tectonic-identity-2726305807-8lqkx           1/1       Running   0          1h
tectonic-ingress-controller-99581103-rd0cj   1/1       Running   0          2h

Using kubectl, tail the logs for the identity pod:

$ kubectl --namespace=tectonic-system logs -f tectonic-identity-2726305807-8lqkx

time="2017-05-08T22:37:02Z" level=error msg="Failed to authenticate: no attribute with name \"groups\": [name email]"

In the above example, the group attribute was not configured for jane.doe@coreos.com in the IdP.