Entertainment at it's peak. The news is by your side.

How to Set Up Kubernetes SSO with SAML


kubernetes sso saml

Kubernetes has some spectacular baked-in function primarily primarily based uncover admission to controls (RBAC). These controls allow directors to interpret nuanced permissions when querying Kubernetes resources, adore Pods, Deployments, ReplicaSets, and heaps others. For these familiar with Kubernetes, the worth of RBAC is straight away recognizable. A single Kubernetes cluster can have your group’s total CI/CD pipeline, highly accessible SaaS products, or infrastructure that’s within the process of being moved to the cloud. For what’s at stake, aged uncover admission to controls are a nonstarter.

Authenticating with SAML

Authorization is handiest half of the fight. Even the strictest uncover admission to policy is archaic if the authentication would possibly possibly even be spoofed. For this motive, Kubernetes supports a vary of standard authentication patterns, corresponding to static tokens, client certificates, OIDC, and other solutions. With the total parts accessible, true uncover admission to have to be simple: (1) query uncover admission to to a cluster via SSO, (2) dangle the K8s API authenticate against your id provider (IDP), and (3) note tips in accordance to id data. Voila.

Unfortunately, if your protocol of assorted is SAML, which it is for a total lot of endeavor organizations, this setup requires extension. We are in a position to achieve this by placing a proxy between the user and Kubernetes API that can learn SAML assertions and translate attributes into a layout the API is built to learn and process. There are three readily documented ways to achieve this, authenticating proxy, webhooks, or user impersonation. This blog post focuses particularly on user impersonation. Why? On story of if you are using a hosted Kubernetes provider, which many are doing due to its complexity, customers don’t dangle alter over the kube-apiserver flag required to plan up webhooks or an authenticating proxy.

By the head of this text, we are in a position to dangle:

  • Understood what Consumer Impersonation is
  • Created a SAML connector
  • Assigned a proxy impersonation privileges
  • Impersonated a user
  • Mapped SAML attributes to Kubernetes Groups

What is Single Signal On (SSO)?

Single signal on, or SSO, is a in actuality indispensable tool in federating id across a pair of assorted programs. SSO disposes the necessity to uncover a fresh plan of credentials for every application accessed. As an different, the process of authentication is outsourced to id providers adore Okta, GSuite, or Keycloak. This permits organizations to position in drive a consistent blueprint of authentication across all internal company companies.

What is SAML?

To enable SSO for a explicit application, it have to toughen an authentication protocol. This sort of protocols is the Safety Assertion Markup Language (SAML). These protocols allow id providers to authenticate customers on behalf of the applying and creep on authorization data assist to the applying. Within the occasion you are no longer familiar with SAML, I imply reading via How SAML 2.0 Authentication Works.

What is Kubernetes Consumer Impersonation?

To make a decision on up what impersonation is and why it is vital, let’s utilize a step assist and rapid creep over Kubernetes RBAC. The RBAC API makes exhaust of the Role and ClusterRole objects to interpret a plan of permissions. These roles are then drag to accounts that the roles note to using RoleBindings and ClusterRoleBindings respectively. Win this snippet that would possibly possibly grant learn handiest uncover admission to to all pods.

# pod-reader-function.yaml
form: Role
  namespace: default
  title: pod-reader
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "watch", "list"]

We are in a position to utilize this pod-reader function and bind it to a explicit user, jane.

# pod-reader-jane-binding.yaml
form: RoleBinding
  title: learn-pods
  namespace: default
- form: Consumer
  title: jane
  form: Role
  title: pod-reader

After Jane authenticates herself against the core API, the RBAC layer will scheme Jane to the pod-reader function and plan her permissions as such. But because Kubernetes does no longer toughen SAML as an authentication protocol, Jane by no blueprint makes it past the first step. The API would no longer know what function to set to Jane or every other story for that topic. As an different, we desire a scheme of extending the authentication tips on how to consist of SAML.

The trick is to no longer let Jane authenticate herself straight with the API, however moderately exhaust a ServiceAccount as a proxy id that would possibly utilize on Jane’s story attributes. The ServiceAccount still needs to authenticate itself to the API, however since it is no longer tied to an exterior IDP, SAML does no longer enter the equation in any admire. As an different, the ServiceAccount would straight authenticate with the Kubernetes API and translate traits adore title: jane. This blueprint of impersonation bypasses the need for the Kubernetes API to straight authenticate Jane whereas still allowing the RBAC API to set the pod-reader function. The correct process of impersonation is finished by passing HTTP headers between the impersonating proxy and Kubernetes API adore Impersonation-Consumer and Impersonate-Neighborhood.

Which Proxy Will We Employ?

Shall we configure a proxy from scratch, organising a ServiceAccount or typical user and giving it impersonation privileges. But this obtained’t allow us to scheme SAML attributes to Kubernetes groups since a vanilla story has no blueprint to translate attributes to groups. As an different, we exhaust an OSS tool known as Teleport, which, for causes later defined, offers us that skill. If this mapping is no longer indispensable to you, the relief of this text is still relevant, however in situation of using the Teleport proxy valid uncover a generic proxy story.

Teleport contains two companies: a Proxy service, which accepts credentials from customers, and an Auth service, which disorders and validates these credentials. While Teleport is mighty more, this simplified description is enough.

single cluster kubernetes integration

Diagram 1 – Single Cluster Kubernetes Integration

The map above displays a generic implementation of how we would exhaust Teleport as a gateway to uncover admission to a Kubernetes cluster. The float is as follows:

  1. Consumer identifies which compute handy resource they would possibly are searching to uncover admission to, corresponding to a Pod
  2. Consumer is caused to signal into their IDP using SAML on the backend
  3. As soon as verified, the user will receive a certificate generated by the certificate authority hosted on the Auth service
  4. Consumer will store the certificate within the community for later exhaust
  5. Upon user query, the proxy will authenticate against the Kubernetes API and impersonate the user’s query

SAML Connector

Sooner than we contact impersonation, we should always first plan up a SAML connector to our proxy. Effectively in actuality, first we have to plan up the companies, however let’s design some assumptions for the sake of time:

  1. Teleport is working with the proxy and auth companies deployed as pods
  2. We’ve registered ourselves as a user with Teleport proxy

Have impersonation makes exhaust of an story as a proxy between the API. This means the process for user authentication by skill of SAML is an fully separate process than the proxy authentication with the Kubernetes API. The user authentication occurs with the proxy and auth companies, no longer the API. Utilizing some technical terminology, Teleport is our Service Provider requesting authentication and id data from our IDP of assorted.

teleport and autho saml authentication

Diagram 2 – Teleport and Auth0 SAML Authentication

To abet out so, we should always interpret and uncover a SAML connector as a YAML file. The next snippet builds off Diagram 2 and would uncover a handy resource for Teleport to make exhaust of that contains the Auth0 SAML endpoint and an ACS URL redirecting assist to Teleport.

# saml-connector.yaml
form: saml
version: v2
  title: saml_connector
  show: "Auth0"
  acs: 3080/v1/webapi/saml/acs
    - {title: "groups", worth: "admins", roles: ["root"]}

For now, let’s ignore attributes_to_roles. I’ll uncover assist to this later. Our integration is taking a look somewhat more adore:

Impersonation Privileges

To let Teleport impersonate customers, it have to be authorized to raise out so. So valid as Jane has the pod-reader function above, we have to uncover a identical object and bind it to the proxy.

form: ClusterRole
  title: impersonator
- apiGroups: [""]
  resources: ["users", "groups", "serviceaccounts"]
  verbs: ["impersonate"]
- apiGroups: [""]
  resources: ["selfsubjectaccessreviews"]
  verbs: ["create"]

For the reason that Kubernetes API is written to be RESTful, it makes exhaust of the HTTP verbs to manipulate Kubernetes resources. But some verbs dangle particular meanings, the authentication layer makes exhaust of the “impersonate” verb to permit HTTP headers prepended with Impersonate-. The YAML file above lets the ServiceAccount impersonate customers, groups, serviceaccounts.

We pause up with the ClusterRoleBinding and level the API to which story the RBAC layer ought to note the cluster function to.

form: ClusterRoleBinding
  title: teleport-proxy
  form: ClusterRole
  title: impersonator
- form: ServiceAccount
  # Teleport proxy ServiceAccount title
  title: teleport-serviceaccount
  namespace: default

Having drag the impersonator cluster function to teleport-serviceaccount, the Kubernetes API can take a look at that Teleport has impersonation privileges upon authentication.

Inserting it All Collectively

In honest two steps, we have every thing required for a SAML authenticated user to uncover admission to a Kubernetes handy resource. Combining every thing we’ve configured above, let’s look what occurs when Jane executes kubectl uncover pods in her show line.

Authenticate with SAML

Jane have to first authenticate herself to Teleport sooner than she can bustle her show. Pondering that is Jane’s first time having access to the Kubernetes API, she does no longer dangle a within the community kept credential that would possibly possibly automatically authenticate her. As an different, Teleport pulls from the connector file we created and redirects her by skill of web browser for SSO.

teleport initiated workflow

Diagram 3 – Service Provider (Teleport) Initiated Workflow

After authentication via username/creep, MFA, Yubikey, and heaps others, Jane will redirect assist to 3080/v1/webapi/saml/acs and creep her SAML assertions to Teleport.

Generate Certificate

Having successfully authenticated herself, the auth service will generate and signal a fresh certificate for Jane, containing data adore user id, a time-to-are residing, and roles. This certificate is kept within the community on her client, so on every occasion Jane queries a Kubernetes handy resource she can creep the credentials with out having to study in every other time till the certificate expires.

Impersonate Consumer

Having authenticated herself and offered professional credentials, the proxy can now impersonate Jane. teleport-serviceaccount will creep its dangle credentials as successfully as impersonation headers by skill of HTTP to the Kubernetes API. In other words, the proxy will ship its ServiceAccount token and consist of Impersonate-Consumer: jane within the HTTP header.

The Kubernetes API will first authenticate teleport-serviceaccount and take a look at for impersonation privileges. As we have created an impersonator function and drag it to the story, the Kubernetes RBAC layer will allow teleport-serviceaccount to impersonate user jane. The Kubernetes API will then authorize acts in accordance to the impersonated files. On this case, jane is drag to the pod-reader function and ought to limit her uncover admission to to learn valid for all pods.

We have successfully granted permissioned uncover admission to to a user authenticated by skill of SAML!

Mapping SAML Assertions to Kubernetes Groups

It’s doubtless you’ll possibly be questioning why Teleport’s certificate authority is crucial in any admire. Here’s an even demand. Finally, every thing we’ve done as a lot as now would possibly possibly even be done with any ServiceAccount, why raise out we need one other plan of credentials if SAML can authenticate and authorize? While there are moderately just a few causes to utilize a certificate authority, the the biggest ingredient is synchronizing RBAC across a pair of assorted forms of compute resources. In other words, when assigning an Admin function in Auth0, it will also inform the admin function across SSH, Kubernetes, databases, applications, and heaps others. (Learn more on Finest Practices for Trusty Infrastructure Get entry to.) For a supported protocol adore OIDC, by using the flag --oidc-groups-explain, the Kubernetes API will note claims as a user’s groups, giving us RBAC parity between IDP and Kubernetes. But when an XML file asserts:


The API is no longer going to note SAML attributes to a acknowledged Kubernetes neighborhood because, as we know, SAML is no longer supported. And so, valid as we required a proxy to impersonate a user, we also need that same proxy to impersonate Kubernetes groups derived from SAML attributes. Here’s the set apart the second plan of credentials comes in. Teleport will utilize a SAML attribute, scheme them to a Teleport function, which is then mapped to a Kubernetes neighborhood, which appears to be like as a part of the Impersonate-Neighborhood: header.

mapping samle attributes to kubernetes subjects

Diagram 4 – Mapping SAML Attributes to Kubernetes Topics

Going assist to the SAML connector, we pushed apart attributes_to_roles: {title: "groups", worth: "admins", roles: ["root"]} as a part of the spec. This line permits us to scheme a SAML attribute to a explicit Teleport function. On this case, the SAML attribute groups: admins is mapped to the Teleport root function. We also need to uncover a function object for root so we are in a position to full the mapping of SAML attribute to Kubernetes neighborhood:

form: function
version: v3
  title: root
    # If no user is specified, customers will impersonate themselves (Jane)
    kubernetes_groups: ["system:masters"]

When Jane signs into Auth0 using SAML, she shall be placed within the system:masters neighborhood automatically.


On this text, we’ve realized how we are in a position to SSO into a Kubernetes cluster using impersonation to lengthen authentication toughen for SAML. In transient, we realized to:

  • Make a proxy to face between the user and Kubernetes API
  • Place up a SAML connector to our proxy
  • Give the proxy impersonation privileges by binding a ClusterRole to it
  • Diagram SAML attributes to Kubernetes Groups

All these steps allow us to design fleshy exhaust of Kubernetes’ RBAC layer using data from an authentication protocol no longer natively supported by the Kubernetes API.

Linked Posts



Want to defend rapid?

Subscribe to our e-newsletter to uncover articles and product updates.

Read More

Leave A Reply

Your email address will not be published.