Authentication

The Stackable Platform uses the AuthenticationClass as a central mechanism to handle user authentication across supported products. The authentication mechanism needs to be configured only in the AuthenticationClass which is then referenced in the Stacklet definition. Multiple different authentication providers are supported.

AuthenticationClass

The AuthenticationClass is a resource describing a generic authentication method like LDAP or Kerberos. It has cluster scope, so it does not belong to a specific namespace. Multiple operators use this CRD as a way to express and configure the authentication methods of their respective product.

The following authentication providers are supported:

  • LDAP: Authenticate users using an LDAP server.

  • OpenID Connect: Authenticate users using an OpenID connect provider.

  • TLS: Authenticate users with client TLS certificates.

  • Static: Authenticate users against a static list of users and passwords in a simple Kubernetes Secret.

LDAP

A very simple AuthenticationClass with LDAP Authentication looks like this:

apiVersion: authentication.stackable.tech/v1alpha1
kind: AuthenticationClass
metadata:
  name: ldap-simple
spec:
  provider:
    ldap:
      hostname: my.ldap.server (1)
      port: 389 (2)
      searchBase: ou=users,dc=example,dc=org (3)
      bindCredentials:
        secretClass: openldap-bind-credentials  (4)
1 The hostname of the LDAP server without any protocol or port
2 The port of the LDAP server. If TLS is used it defaults to 636 otherwise to 389
3 An optional searchBase where the users should be searched
4 The reference to the SecretClass for the bind credentials

In a diagram it would look like this:

image$authentication overview.drawio
Learn more in the OpenLDAP tutorial and get a full overview of all the properties in the AuthenticationClass LDAP provider CRD reference.

OpenID Connect

An OIDC provider like Keycloak could be configured as follows:

apiVersion: authentication.stackable.tech/v1alpha1
kind: AuthenticationClass
metadata:
  name: keycloak
spec:
  provider:
    oidc:
      hostname: my.keycloak.server        (1)
      port: 8080                          (2)
      rootPath: /realms/master            (3)
      scopes:                             (4)
      - email
      - openid
      - profile
      principalClaim: preferred_username  (5)
      providerHint: Keycloak              (6)
      tls:                                (7)
        verification:
          server:
            caCert:
              webPki: {}                  (8)
1 Hostname of the identity provider.
2 Port of the identity provider. If TLS is used defaults to 443, otherwise to 80.
3 Root HTTP path of the identity provider. Defaults to /.
4 Scopes to request from your identity provider. It is recommended to request the openid, email, and profile scopes.
5 If a product extracts some sort of "effective user" that is represented by a string internally, this config determines which claim is used to extract that string.
6 This is a hint about which identity provider is used by the AuthenticationClass.
7 Optionally enable TLS and configure verification. When present, connections to the idP will use https:// instead of http://. See TLS server verification.
8 Trust certificates signed by commonly trusted Certificate Authorities.
Get a full overview of all the properties in the AuthenticationClass OIDC provider CRD reference.

TLS

The TLS provider configures a product to authenticate users using TLS certificates. When establishing a connection the client will first validate the certificate of the server. This step is not influenced by this AuthenticationClass, it only affects the next step: Afterwards the server checks the validity of the certificate the client has provided. This includes the usual checks - such as checking that it hasn’t expired and matches the hostname of the client. Additionally the client certificate needs to be signed with the ca certificate, which is provided by the SecretClass specified in clientCertSecretClass.

A sample TLS provider looks as follows:

apiVersion: authentication.stackable.tech/v1alpha1
kind: AuthenticationClass
metadata:
  name: client-auth-tls
spec:
  provider:
    tls:
      clientCertSecretClass: client-auth-tls

Static

The static provider is used to represent a simple - static - set of users. Users are identified by a username and a password.

First, the AuthenticationClass needs to be defined as follows:

apiVersion: authentication.stackable.tech/v1alpha1
kind: AuthenticationClass
metadata:
  name: simple-users
spec:
  provider:
    static:
      userCredentialsSecret:
        name: simple-users-credentials (1)
1 The name of the Secret containing the credentials

Afterwards the referenced Secret needs to be created:

apiVersion: v1
kind: Secret
metadata:
  name: simple-users-credentials (1)
  namespace: default (2)
type: kubernetes.io/opaque
stringData:
  admin: admin
  alice: superpass
  bob: secret
1 The name of the Secret, which needs to match the Secret name specified in the AuthenticationClass above
2 The namespace of the Secret. The Secret needs to be in the same namespace as the product that tries to use the static AuthenticationClass

Further reading