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.

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

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

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.

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.

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.

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:

Tectonic Identity (config-dev.yaml)

SAML IdP

Description

Name ID Format

Name ID Format

The unique identifier string for the user’s linked account. Tectonic Identity assumes that this value is both unique and constant. Therefore, your SAML IdP and Tectonic Identity should be in agreement with this choice. The identifier specification, called NameIDPolicy, determines what format should be requested in the SAML assertion. The NameID format indicated in the NameIDPolicy is included in the SAML assertion. If Tectonic Identity requests a NameID format unknown to the IdP or for which the IdP is not configured, the authentication flow will fail. Select the default value, unspecified unless you require a specific format.

Single sign-on URL received from your SAML IdP. The URL carries the SAML2 security token with user information. Example: https://coreos.com/sso/saml

ca

X.509 Certificate

The path to your Certificate Authority Data. Alternatively, enter the base64 value of X.509 Certificate.It is used to validate the signature of the SAML response. CA Data is the base64 value of X.509 Certificate.

usernameAttr

name

The username attribute set in the SAML IdP. It could be name or email. The attribute in the returned assertion used to map to ID token and claims from the callback URL. Example: name

emailAttr

email

The email attribute in the returned assertion. This maps to the ID token and claims from the callback URL. Example: email

groupsAttr

group

The group attribute in the returned assertion. This maps to the ID token and claims from the callback URL. Example: tstgrp

Configuring identity federation

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

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

Ensure that Tectonic clusters are up and running.

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.

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:

Log in to your Tectonic Console as the desired user.

Navigate to My Account.

Verify your identity and download kubectl configuration.

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.