SAML integration

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 Identity Provider (SAML IdP) over a secure channel.

Configure Tectonic Identity to map to your existing SAML IdP, to enable user authentication for defined users and groups.

Integrating Tectonic Identity with SAML

Authentication workflow

When a user logs in to Tectonic Console, Tectonic Identity constructs a SAML AuthnRequest and redirects the user to the SAML server. Once the user is verified, the SAML server returns an AuthnResponse to Tectonic Identity, which then verifies the response, and retrieves user data, such as username and groups.

1. A user logs in to Tectonic Console.

2. Tectonic Identity identifies the user’s origin and redirects the user to the SAML server, requesting authentication (AuthnRequest).

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

4. Tectonic Identity 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 Tectonic cluster.

Configuring Tectonic Identity for SAML authentication

To configure Tectonic Identity, first:

• Configure SAML for access by Tectonic.
• Add Tectonic users to the SAML database.
• Ensure that Tectonic clusters are up and running.

Tectonic Identity pulls its configuration options from a ConfigMap, which admins can view and edit using kubectl. To prevent misconfiguration, use the kubectl downloaded from Tectonic Console to edit Tectonic Identity's ConfigMap.

1. Use kubectl to back up the existing config:

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

1. Edit the current ConfigMap with the desired changes:

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

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

Run kubectl apply to apply the new configuration:

kubectl apply -f path/to/config/file/new-tectonic-config.yaml

Finally, trigger a rolling update of the Identity pods, which will read the new configuration:

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

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 Tectonic Console as the desired user. Then follow the standard process to download kubectl and configure credentials for the cluster.

Handling SAML authentication expiration

Every twenty four hours, access tokens for the session will expire. Users must log in again to regain access to the cluster.

Tectonic Identity configuration parameters

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.

See your provider's IdP documentation for more information on their specific SAML configuration options.

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