Simple Authentication and Security Layer (SASL)

This authentication method is commonly used with an EventHub such as Kafka.

Synopsis

apiVersion: kannika.io/v1alpha
kind: Credentials
metadata:
  name: kafka-sasl-plain-creds
spec:
  sasl:
    mechanism: PLAIN # or SCRAM-SHA-256, SCRAM-SHA-512, OAUTHBEARER
    # For PLAIN and SCRAM mechanisms:
    usernameFrom:
      secretKeyRef:
        name: kafka-sasl-creds
        key: username
    passwordFrom:
      secretKeyRef:
        name: kafka-sasl-creds
        key: password
    # For OAUTHBEARER mechanism:
    tokenEndpoint: https://idp.example.com/oauth2/token
    clientIdFrom:
      secretKeyRef:
        name: oauth-secret
        key: client-id
    clientSecretFrom:
      secretKeyRef:
        name: oauth-secret
        key: client-secret
    # Optional. OAuth scope(s), space-delimited per RFC 6749
    scope: "kafka"
    # Optional. Key/value pairs for OAUTHBEARER extensions
    extensions:
      - key: "logicalCluster"
        value: "lkc-abc123"
    # sslConf below is optional.
    # If it is defined, then SASL_SSL will be configured
    sslConf:
      # Explicitly set, but assumed 'true' if not present.
      enabled: true
      # Optional. Configure an explicit CA for server authentication.
      caCertificatePemFrom:
        secretKeyRef:
          name: tls-secret
          key: ca.crt
      # Optional. Set a client certificate if the server requires it.
      certificatePemFrom:
        secretKeyRef:
          name: tls-secret
          key: tls.crt
      # Optional. Set a client key if the server requires it. PKCS#8 only.
      privateKeyPemFrom:
        secretKeyRef:
          name: tls-secret
          key: tls.key
      # Optional. Set the password to unlock the client's private key
      privateKeyPasswordFrom:
        secretKeyRef:
          name: tls-key-password
          key: password

SASL/PLAIN

To use the SASL/PLAIN authentication method, set the mechanism field to PLAIN.

apiVersion: kannika.io/v1alpha
kind: Credentials
metadata:
  name: kafka-sasl-plain-creds
spec:
  sasl:
    mechanism: PLAIN
    usernameFrom:
      secretKeyRef:
        name: kafka-sasl-creds
        key: username
    passwordFrom:
      secretKeyRef:
        name: kafka-sasl-creds
        key: password
9 collapsed lines
---
apiVersion: v1
kind: Secret
metadata:
  name: kafka-sasl-creds
type: Opaque
stringData:
  username: my-user
  password: my-password

SASL/SCRAM

To use the SASL/SCRAM authentication method, set the mechanism field to SCRAM-SHA-256 or SCRAM-SHA-512.

apiVersion: kannika.io/v1alpha
kind: Credentials
metadata:
  name: kafka-sasl-scram-creds
spec:
  sasl:
    mechanism: SCRAM-SHA-512
    usernameFrom:
      secretKeyRef:
        name: kafka-sasl-creds
        key: username
    passwordFrom:
      secretKeyRef:
        name: kafka-sasl-creds
        key: password
9 collapsed lines
---
apiVersion: v1
kind: Secret
metadata:
  name: kafka-sasl-creds
type: Opaque
stringData:
  username: my-user
  password: my-password

SASL/OAUTHBEARER

To use the SASL/OAUTHBEARER authentication method, set the mechanism field to OAUTHBEARER. This mechanism uses the OAuth 2.0 Client Credentials flow to obtain access tokens from an identity provider.

apiVersion: kannika.io/v1alpha
kind: Credentials
metadata:
  name: kafka-sasl-oauth-creds
spec:
  sasl:
    mechanism: OAUTHBEARER
    tokenEndpoint: https://idp.example.com/oauth2/token
    clientIdFrom:
      secretKeyRef:
        name: oauth-secret
        key: client-id
    clientSecretFrom:
      secretKeyRef:
        name: oauth-secret
        key: client-secret
    scope: "kafka"
    extensions:
      - key: "logicalCluster"
        value: "lkc-abc123"
    sslConf:
      enabled: true
      caCertificatePemFrom:
        secretKeyRef:
          name: tls-secret
9 collapsed lines
          key: ca.crt
---
apiVersion: v1
kind: Secret
metadata:
  name: oauth-secret
type: Opaque
stringData:
  client-id: my-client-id
  client-secret: my-client-secret

When sslConf is defined, the Kafka broker connection uses the SASL_SSL security protocol. The configured CA certificate is also used to verify the token endpoint’s TLS connection. If the broker and the token endpoint use different CAs, concatenate both CA certificates into a single PEM secret.

Using SSL/TLS

Using SASL for authentication alone doesn’t mean the resulting connection between Armory and the EventHub is encrypted. To enable SSL/TLS, you need to define the sslConf property in accordance with your particular situation.

Using the default CA

In the most simple case, define sslConf with an enabled: true property:

apiVersion: kannika.io/v1alpha
kind: Credentials
metadata:
  name: creds
spec:
  sasl:
    mechanism: PLAIN # or SCRAM-SHA-256 or SCRAM-SHA-512
    usernameFrom:
      secretKeyRef:
        name: kafka-sasl-creds
        key: username
    passwordFrom:
      secretKeyRef:
        name: kafka-sasl-creds
        key: password
    sslConf:
      enabled: true

This is enough when:

the server doesn’t require additional authentication from the client (through a client certificate),
the server’s certificate can be validated with the ca-certificates package included in Kannika Armory’s image,

Server authentication

If the server’s certificate needs to be validated with a custom CA (self-signed certificate), then use the caCertificatePemFrom field to reference a secret in PEM format.

apiVersion: kannika.io/v1alpha
kind: Credentials
metadata:
  name: kafka-sasl-plain-creds
spec:
  sasl:
    mechanism: PLAIN # or SCRAM-SHA-256 or SCRAM-SHA-512
    usernameFrom:
      secretKeyRef:
        name: kafka-sasl-creds
        key: username
    passwordFrom:
      secretKeyRef:
        name: kafka-sasl-creds
        key: password
    sslConf:
      enabled: true
      caCertificatePemFrom:
        secretKeyRef:
          name: tls-secret
          key: ca.crt

Client authentication

In some rare cases, the server may require TLS authentication from the client. In this situation, load the certificate and key in a secret and configure sslConf accordingly:

apiVersion: kannika.io/v1alpha
kind: Credentials
metadata:
  name: kafka-sasl-plain-creds
spec:
  sasl:
    mechanism: PLAIN # or SCRAM-SHA-256 or SCRAM-SHA-512
    usernameFrom:
      secretKeyRef:
        name: kafka-sasl-creds
        key: username
    passwordFrom:
      secretKeyRef:
        name: kafka-sasl-creds
        key: password
    sslConf:
      enabled: true
      certificatePemFrom:
        secretKeyRef:
          name: tls-secret
          key: tls.crt
      privateKeyPemFrom: # PKCS#8 only
        secretKeyRef:
          name: tls-secret
          key: tls.key

explicitly set using a secret in PEM format with caCertificatePemFrom.