SASL

Simple Authentication and Security Layer

Simple Authentication and Security Layer (SASL) is the default method for mutual authentication used by Axual components. It ensures that the parties at each side of the network connection are who they claim to be by verifying that their provided credentials are correct.

SASL support is implemented in Discovery API and Schema Registry by means of Basic Authentication. The same SASL credentials configured for applications are used to communicate with every service in the platform.

Broker

In order to enable Basic Authentication on the broker, you need to configure the broker to enable SASL. Add or modify the following configuration in the Broker config file for the cluster.

Using Axual CLI

Append the new Security Protocol to the SECURITY_PROTOCOL_MAP variable and add or modify the following configuration in the Broker config file for the cluster. You can configure which protocols you want enabled, currently SASL_PLAIN, SCRAM_SHA_256 and SCRAM_SHA_512 are supported.

platform-config/clusters/{cluster-name}/broker.sh
# Kafka property: listener.security.protocol.map
SECURITY_PROTOCOL_MAP="REPLICATION:SSL,INTRACLUSTER:SSL,APP:SSL,INTERCLUSTER:SSL,APPSASL:SASL_SSL"

# Enables sasl
BROKER_SASL_ENABLED=true

# Enabled protocols:
BROKER_SASL_PLAIN_ENABLED=false
BROKER_SCRAM_SHA_256_ENABLED=true
BROKER_SCRAM_SHA_512_ENABLED=true

BROKER_PLAIN_SASL_JAAS_CONFIG="'org.apache.kafka.common.security.plain.PlainLoginModule required;'"

# Optionally configure:
#PLAIN_SASL_SERVER_CALLBACK_HANDLER_CLASS="io.axual.test.authcallback.LoggingCallbackHandler"
#SCRAM_SHA_256_SASL_SERVER_CALLBACK_HANDLER_CLASS="io.axual.test.authcallback.LoggingCallbackHandler"
#SCRAM_SHA_512_SASL_SERVER_CALLBACK_HANDLER_CLASS="io.axual.test.authcallback.LoggingCallbackHandler"

  1. Edit nodes.sh file for that cluster and append APP_SASL_ADVERTISED to the NODE_ADDRESS_MAP variable. The value of APP_SASL_ADVERTISED should be the LoadBalancer (used to redirect calls to the broker) or the hostname where the broker runs.

  2. Then append the APP_BINDING_SASL and APP_SASL_ADVERTISED to the NODE_BROKER_PORT_MAP variable. The value of APP_BINDING_SASL need to be an available port in the host and the value of APP_SASL_ADVERTISED can be same as APP_BINDING_SASL if the broker is not behind a LoadBalancer otherwise the LoadBalancer port used for SASL.

The LoadBalancer port for SASL has to be different from the LoadBalancer port of SSL.

An example configuration for a broker running on localhost without a LoadBalancer can be like below:

platform-config/clusters/{cluster-name}/nodes.sh
#Please note INTERCLUSTER_ADVERTISED, APP_ADVERTISED and APP_SASL_ADVERTISED are used for advertised url construction of broker only. All other components need to maintain their advertised urls separately.
NODE1_ADDRESS_MAP=PRIVATE:platform.local:192.168.99.100,INTRACLUSTER:platform.local:192.168.99.100,INTERCLUSTER_BINDING::192.168.99.100,INTERCLUSTER_ADVERTISED:192.168.99.100:,APP_BINDING::192.168.99.100,APP_ADVERTISED::192.168.99.100,APP_SASL_ADVERTISED::192.168.99.100

NODE1_BROKER_PORT_MAP=PRIVATE:9092,INTRACLUSTER:9094,INTERCLUSTER_BINDING:9095,INTERCLUSTER_ADVERTISED:9095,APP_BINDING:9096,APP_ADVERTISED:9096,APP_BINDING_SASL:9097,APP_SASL_ADVERTISED:9097

  1. Restart the Broker after you have changed the configuration to apply the changes.

Repeat the above steps for every node where brokers are deployed. Here we demonstrate only for NODE1 as the variable name indicates.

Using Axual Helm Charts

  1. Enable Kafka broker SCRAM SHA-512 listener (Strimzi supports SCRAM-SHA-512 only)

    core:
  kafka:
    kafka:
      scramsha512listener:
        enabled: true # default false

  2. For each broker set the following configuration

    You can skip this step if you’re running locally with only one broker. The default listener is platform.local:31758 
    core:
  kafka:
    kafka:
      scramsha512listener:
        enabled: true # default false
        listenerType: loadbalancer # default nodeport
        listenerConfiguration:
            bootstrap:
              # To pass custom annotations on the bootstrap listener service
              annotations: {}
            brokers:
              - broker: 0 # broker ID
                # Advertised host the broker for the external listener
                # In case of external loadbalancer, use your SASL broker host
                # this is unique per broker
                advertisedHost: "[advertisedHost]"
                # Advertised port, default is 9095
                advertisedPort: [advertisedPort]
                # Only needed if `scramsha512listener.listenerType` is set to `nodeport`
                # You must ensure that the port is free and available for use.
                nodePort: [nodePort]
                # To pass custom annotations on the external broker listener service
                annotations: {}
              - broker: 1 # same structure as the broker-0
                # ...
              - broker: 2 # same structure as the broker-0
                # ...
    For more information about the different types of listeners, check out this documentation from Strimzi

  3. Upgrade Axual platform using the above modified values.yaml

    helm upgrade --install platform axual-stable/platform -f values.yaml --version=<helm-chart-version> -n kafka

Discovery API

SASL support is implemented in Discovery API and Schema Registry by means of basic authentication. The same SASL credentials configured for applications are used to communicating with every service in the platform. Per Basic Authentication, the /v2 endpoint can be accessed by providing an Authentication header (plugged through the Axual Client of your choice).

Make sure Discovery API client truststore has the CA certificate used by Instance API

Using Axual CLI

  1. Add or modify the following configuration in the Discovery API config file for the tenant instance.

platform-config/tenants/{tenant-name}/instances/{instance-name}/discovery-api.sh
# Enable Basic auth for cluster cluster1 and cluster2.
SECURITY_BASIC_AUTH_ENABLED=cluster1:true,cluster2:true
# The Instance Manager (Instance API) url against which authentication calls are made
SECURITY_BASIC_AUTH_AUTHENTICATION_URL="https://<hostname>:<port>/credentials/authorize"
# Set SSL_CLIENT_AUTH to 'want'. Means server request that the client provides a certificate, but will not fail if none is supplied. Often used with Basic Auth enabled as an alternative authentication mechanism
DISCOVERYAPI_SERVER_SSL_CLIENT_AUTH=cluster1:want,cluster2:want
The accepted values to the variable SERVER_SSL_CLIENT_AUTH have changed from true/false to need/none/want

  1. Restart the Discovery API after have changed the configuration to apply the changes.

Instance API

  1. Instance API configuration also need to be updated in order to authorize connections from Discovery API instances. Modify the instance-api.sh file as follows:

platform-config/tenants/{tenant-name}/instances/{instance-name}/instance-api.sh
INSTANCE_API_AUTHORIZED_CNS="'Old-existing-CN,NEW-Discovery-API-client-CN'"

  1. Restart the Instance API after have changed the configuration to apply the changes.

Using Axual Helm Charts

Open the values.yaml for your instance Discovery-API and append the following configurations into the security and tls properties segments:

  1. Enable Basic Authentication

    platform/charts/instance/charts/discoveryapi/values.yaml
    security:
  (...)
  basicAuth:
    # Enables/Disable basic authentication
    enabled: true # default false
    # Override Instance Manger URL if it runs outside the K8S cluster
    #authenticationUrlOverride: ""
tls:
  (...)
  # Client authentication options
  # need - Client authentication is needed and mandatory
  # want - Client authentication is wanted but not mandatory
  # none - Client authentication is not wanted
  clientAuth: want # default none
    From Discovery-API 2.4.0 the variable clientAuth has changed from true/false to need/none/want. Check clientAuth Mapping

  2. Upgrade Axual platform using the above modified values.yaml

    helm upgrade --install platform axual-stable/platform -f values.yaml --version=<helm-chart-version> -n kafka

Instance API

Instance API values also need to be updated, in order to authorize the CN of the DA-client-key. Append into the same values.yaml file:

instance:
  instanceapi:
    security:
      enabled: true
      authorizedDns: "EXISTING-CN:MGMT-API-client,NEW-CN:DA-client"

  1. Upgrade Axual platform using the above modified values.yaml

    helm upgrade --install platform axual-stable/platform -f values.yaml --version=<helm-chart-version> -n kafka

Schema Registry (slave)

SASL support in Schema Registry (SR) is implemented by means of Basic Authentication. The SR API can be accessed by providing an Authentication header (plugged in by the SR client). The following configuration changes are only effective for the SR slave. The SR master doesn’t need to support basic auth. The user credentials supplied by applications to the Schema-Registry are handed over to Instance-API to perform the authorization check. Since the Instance API endpoints require mTLS authentication, an additional SSL context needs to be created. You will need to supply this configuration, as well.

Make sure that Schema Registry Slave client truststore has the CA certificate used by Instance API

Using Axual CLI

  1. Add or modify the following configuration in the Schema Registry config file for the tenant instance.

platform-config/tenants/{tenant-name}/instances/{instance-name}/schema-registry.sh
SR_SLAVE_BASIC_AUTH_ENABLED="true"

# Create SSL client context for reaching Instance API
SR_SLAVE_CLIENT_AUTH_SERVICE_SECURITY_ENABLED='true'
SR_SLAVE_CLIENT_AUTH_SERVICE_SSL_KEYSTORE='/path/to/keystore'
SR_SLAVE_CLIENT_AUTH_SERVICE_SSL_KEYSTORE_PASSWORD='password'
SR_SLAVE_CLIENT_AUTH_SERVICE_SSL_KEY_PASSWORD='password'
SR_SLAVE_CLIENT_AUTH_SERVICE_SSL_TRUSTSTORE='/path/to/truststore'
SR_SLAVE_CLIENT_AUTH_SERVICE_SSL_TRUSTSTORE_PASSWORD='password'

  1. Restart the Schema Registry after have changed the configuration to apply the changes.

Instance API

  1. Instance API configuration also need to be updated in order to authorize connections from SR instances. Modify the instance-api.sh file as follows:

platform-config/tenants/{tenant-name}/instances/{instance-name}/instance-api.sh
INSTANCE_API_AUTHORIZED_CNS="'Old-existing-CN,NEW-Schema-Registry-client-CN'"

  1. Restart the Instance API after you have changed the configuration to apply the changes.

Using Axual Helm Charts

Open the values.yaml for the platform deployment and append the following configuration:

platform/values.yaml
instance:
  schemaregistry:
    tls:
      slave:
        clientAuthNeed: false # SR cannot support basic auth while enforcing mutual TLS
    security:
      slave:
        basicAuth:
          enabled: true
          ssl:
            enabled: true
            clientKeystore: 'base64 encoded keystore'
            clientKeyPassword: 'plaintext password'
            clientKeystorePassword: 'plaintext password'
            clientTruststore: 'base64 encoded truststore'
            clientTruststorePassword: 'plaintext password'
The instance.schemaregistry.security.slave.basicAuth.ssl block is not required when instance.schemaregistry.tls.slave.automatedKeystores is set to true.

Instance API

Instance API values also need to be updated, in order to authorize the CN of the SR-client-key. Append into the same values.yaml file:

instance:
  instanceapi:
    security:
      enabled: true
      authorizedDns: "EXISTING-CN:MGMT-API-client,NEW-CN:SR-client"
When the instance.schemaregistry.tls.slave.automatedKeystores=true config is set, use the CN of the SR kafka-client certificate, located at instance.schemaregistry.tls.slave.clientCertificatePem.

Upgrade Axual platform using the above modified values.yaml files

helm upgrade --install platform axual-stable/platform -f values.yaml --version=<helm-chart-version> -n kafka

Management API

After your cluster and instance services have been updated to support SASL, you need to allow Management API to use those.

Using Axual CLI

Add or modify the following configuration in the Management API config file.

platform-config/clusters/{cluster-name}/mgmt-api.sh
# Define which authentication methods available on the Self-Service portal
MGMT_API_AVAILABLE_AUTH_METHODS="'SSL, SCRAM_SHA_256, SCRAM_SHA_512'"

Using Axual Helm Charts

Open the values.yaml for the platform deployment and append the following configuration:

platform/values.yaml
mgmt:
  api:
    axual:
      availableAuthMethods: 'SSL, SCRAM_SHA_512'

Upgrade Axual platform using the above modified values.yaml files

helm upgrade --install platform axual-stable/platform -f values.yaml --version=<helm-chart-version> -n kafka

Now SASL is available, and you can enable SASL for your Tenant.