Cloudera Docs

Authentication in Cloudera Surveyor for Apache Kafka

Get started with authentication in Cloudera Surveyor. Cloudera Surveyor supports LDAP authentication as the only authentication mechanism.

Cloudera Surveyor supports authentication of its end users. It supports a single authentication method, which is LDAP. While configuring authentication is optional, it is enabled by default. As a result, you must configure LDAP authentication properties during or after installation.

LDAP properties define the LDAP server Cloudera Surveyor uses to authenticate users. The LDAP server you configure must contain entries with valid usernames and passwords. When LDAP authentication is configured, users must provide valid credentials to access the Cloudera Surveyor UI.

Authentication keys and tokens

Cloudera Surveyor uses an authentication key to securely generate authentication tokens. These tokens are sent to clients and are required for subsequent access requests.

The authentication key is a sequence of at least 32 random bytes that you must manually generate, save as a file, and configure using a configuration property. You can use any tool or method to generate the authentication key.

The authentication key is sensitive data. Once configured, it is stored in a Kubernetes Secret and mounted to all Cloudera Surveyor Pods. Because of this, Cloudera recommends following the security guidelines of your organization and restricting access to Cloudera Surveyor for Apache Kafka Secrets and Pods. Use standard Kubernetes access control mechanisms, such as Role-Based Access Control (RBAC), to ensure proper security.

In addition, Cloudera recommends the following:
  • Delete the file containing the authentication after configuration is complete.
  • Update the authentication key on a regular basis. You can update the authentication key at any time through configuration.

Configuring LDAP authentication

Learn how to configure LDAP authentication in Cloudera Surveyor.

  • TLS is enabled and configured for Cloudera Surveyor. See Channel encryption (TLS).
  • An LDAP server is available that meets the following requirements:
    • The server has TLS enabled.
    • The server is accessible from the Kubernetes cluster where Cloudera Surveyor for Apache Kafka is deployed.
    • Entries containing usernames and passwords are located under a common base in the directory information tree. Passwords must be stored in the userPassword attribute in the user entries.
  1. Generate an authentication key and save it as a file.
    The authentication key is a random sequence of at least 32 bytes that is saved to a file. To generate it, use any tool or method that is available to you. Take note of the location and name of the file that you create. You will need to specify the file in a later step.
  2. Generate a Java truststore (PKCS12 or JKS) containing the TLS certificate of the root Certificate Authority (CA) of the LDAP certificate chain. 
    keytool -import -trustcacerts -file [***LDAP ROOT CA***] \
  -keystore [***TRUSTSTORE NAME***] \
  -storepass [***TRUSTSTORE PASSWORD***] \
  -storetype PKCS12
  3. Create a Secret containing the truststore and the truststore password. 
    kubectl create secret generic [***LDAP TRUSTSTORE SECRET***] \
  --namespace [***NAMESPACE***] \
  --from-file=[***TRUSTSTORE SECRET KEY***]=[***TRUSTSTORE NAME***] \
  --from-file=[***TRUSTSTORE PW SECRET KEY***]=[***PATH TO TRUSTSTORE PW FILE***]
    Take note of [***LDAP TRUSTSTORE SECRET***], [***TRUSTSTORE SECRET KEY***], and [***TRUSTSTORE PW SECRET KEY***]. You will need to specify these names in a custom values file you create in a later step.
  4. Configure LDAP properties in a custom values file (values.yml).

    The following configuration snippet is an example containing LDAP properties for a typical setup.

    #...
surveyorConfig:
  surveyor:
    authentication:
      enabled: true
      userSessionTimeout: P1D
      inactivityTimeout: PT1H
      tokenRenewalInterval: PT10M
  quarkus:
    security:
      ldap:
        dir-context:
          url: ldaps://openldap-chart.ldap:1390
          principal: cn=admin,dc=openldap-chart,dc=ldap
          password: adminpassword
        identity-mapping:
          rdn-identifier: uid
          search-base-dn: ou=users,dc=openldap-chart,dc=ldap
          attribute-mappings:
            "0": 
              from: uid
              filter: (uid={0})
              filter-base-dn: ou=users,dc=openldap-chart,dc=ldap
globalTruststore:
  secretRef:
    name: [***LDAP TRUSTSTORE SECRET***]
    key: [***TRUSTSTORE SECRET KEY***]
  type: PKCS12
  password:
    secretRef:
      name: [***LDAP TRUSTSTORE SECRET***]
      key: [***TRUSTSTORE PW SECRET KEY***]

    • surveyorConfig.surveyor.authentication.enabled - Enables or disables authentication. Set to true by default. Included in the example as a reference, you do not need to set the property explicitly to enable authentication.

    • surveyorconfig.surveyor.authentication.* - These properties control user session behavior and authentication token management. They define the session timeout, inactivity timeout, and the interval for renewing authentication tokens. All time intervals are specified in ISO 8601 format. For optimal security, Cloudera recommends that token renewal is shorter than or equal to half of the inactivity timeout.

    • surveyorconfig.quarkus.security.ldap.dircontext.* - These properties configure the LDAP server that Cloudera Surveyor connects to. They specify the server URL, the distinguished name (DN) of the bind user, and the password of the bind user. These are required for establishing a secure connection with the LDAP directory.

    • surveyorconfig.quarkus.security.ldap.identity-mapping.* - These properties configure how Cloudera Surveyor interacts with the LDAP directory to identify users and map their group memberships. They define the attributes and base DNs used to locate user entries and groups in the directory, as well as the filters applied to verify group membership.

    • globalTruststore.secretRef.name - The name of the Kubernetes Secret containing the truststore of the LDAP server.

    • globalTruststore.secretRef.key - The key in the Kubernetes Secret that contains the truststore.

    • globalTruststore.password.name - The name of the Kubernetes Secret containing the truststore password.

    • globalTruststore.password.key - The key in the Kubernetes Secret that contains the truststore password.

  5. Apply your configuration and activate the authentication key. 
    helm upgrade cloudera-surveyor [***CHART***] \
  --namespace [***NAMESPACE***] \
  --values [***VALUES.YML***] \
  --set-file surveyorConfig.surveyor.authentication.keys.active=[***PATH TO AUTHENTICATION KEY FILE***]
LDAP authentication is enabled. Users are required to authenticate to access the Cloudera Surveyor UI.

Updating the authentication key

Learn how to update an authentication key that Cloudera Surveyor uses to generate authentication tokens. Cloudera recommends you update the key regularly. Alternatively, you might need to update the key as a security measure to log out all users.

You update the authentication key by updating surveyorConfig.surveyor.authentication.keys.active with a new key that you generate. Additionally, you temporarily set surveyorConfig.surveyor.authentication.keys.passive to the old key. Having both keys active at the same time is required to ensure a rolling transition of keys and prevents users from being forced to relogin multiple times. After the new key is added and active, you remove the old key to deactivate it.

A complete Cloudera Surveyor configuration (a full values.yaml file with all configured properties) is required to complete this task. Ensure you have the values file ready. You can retrieve all values for your installation using the `helm get values command.

helm get values cloudera-surveyor \
  --namespace [***NAMESPACE***] \
  --all
  1. Generate a new authentication key and save it as a file.
    The authentication key is a random sequence of at least 32 bytes that is saved to a file. To generate it, use any tool or method that is available to you.

    Take note of the location and name of the file that you create. You will need to specify the file in a later step.

  2. Activate your new key.
    1. Extract your old key. 
      kubectl get secret cloudera-surveyor-auth-keys \
  --namespace [***NAMESPACE***] \
  -ojsonpath='{.data.key-active}' \
| base64 --decode > old-key
    2. Activate the new key. 
      helm upgrade cloudera-surveyor [***CHART***] \
  --namespace [***NAMESPACE***] \
  --values [***VALUES.YAML***] \
  --set-file surveyorConfig.surveyor.authentication.keys.active=[***PATH TO NEW KEY FILE***] \
  --set-file surveyorConfig.surveyor.authentication.keys.passive=old-key
    3. Rolling restart Cloudera Surveyor. 
      kubectl rollout restart deployment/cloudera-surveyor \
--namespace [***NAMESPACE***]
    4. Wait until the deployment is successfully restarted.

      Monitor the restart with the kubectl rollout.

      kubectl rollout status deployment/cloudera-surveyor \
  --namespace [***NAMESPACE***] \
  --watch
      The restart is successful once you see the following message.
      deployment "cloudera-surveyor" successfully rolled out
    5. Delete the old key file you created in a previous step. 
      rm old key
  3. Deactivate your old key by removing it from configuration. 
    helm upgrade cloudera-surveyor [***CHART***] \
  --namespace [***NAMESPACE***]  
  --values [***VALUES.YAML***] \
  --set-file surveyorConfig.surveyor.authentication.keys.active=[***NEW KEY FILE***]

    Notice that surveyorConfig.surveyor.authentication.keys.passive (the old key) is not provided. This removes and deactivates the old key.

  4. Rolling restart Cloudera Surveyor. 
    kubectl rollout restart deployment/cloudera-surveyor \
  --namespace [***NAMESPACE***]
  5. Wait until the deployment is successfully restarted.

    Monitor the restart with the kubectl rollout.

    kubectl rollout status deployment/cloudera-surveyor \
  --namespace [***NAMESPACE***] \
  --watch
    The restart is successful once you see the following message.
    deployment "cloudera-surveyor" successfully rolled out

The new authentication key is added. Authentication tokens are now signed with the new key. The old key is no longer accepted. All users are required to relogin.

The new authentication key is sensitive data. Cloudera recommends that you delete the new key file you generated.