Authentication service

The authentication service is responsible for authenticating users and nodes. It uses the popular Keycloak service to handle authentication within the vantage6 infrastructure. Vantage6 uses Keycloak because it is a mature and well-supported authentication service that is easy to deploy, customize and integrate with existing authentication services.

Configure

The Keycloak operator requires a YAML file to configure the Keycloak instance. This file is generated by the v6 hub new command.

Below, we list all possible configuration options. You can download this file here: auth_config.yaml

keycloak:
  # Whether the Keycloak is deployed standalone or as part of a vantage6 hub.
  standalone: false

  # Specify the version of the Keycloak Operator to use.
  operatorVersion: "26.0.0"

  # Specify the number of Keycloak instances to deploy.
  instances: 1

  # Whether to use production settings. Note that this setting impacts many settings.
  # In case it is false, this causes users and secrets to be set to simple, non-secure
  # (initial) values. Always set this to true in production environments.
  production: true

  # TLS settings - should be enabled for production environments.
  tls:
    enabled: true
    autoGenerated: true

  # Set the username and password for the Keycloak admin. This user is created when
  # Keycloak is initialized and can be used to login to the Keycloak admin UI and
  # manage Keycloak settings.
  auth:
    # For production environments, we recommend storing the admin password in a secret
    # (which MUST contain the 'username' and 'password' keys).
    adminUserSecret: admin-user-secret
    # For development environments, you can set the username and password directly:
    # adminUser: admin
    # adminPassword: admin

  # Development settings - only needed for development environments.
  dev:
    # Whether to forward ports to the host machine. Necessary for sandbox environments.
    forward_ports: true
    # The port on the host machine to expose the Keycloak authentication service to
    # for sandbox environments.
    local_auth_port_to_expose: 30764

  # Ensure that the auth pod has enough resources to run. The default values are enough
  # in most cases, but for a larger environment, you might need to increase the limits.
  resources:
    limits:
      memory: 2Gi
      cpu: 1000m
    requests:
      memory: 1Gi
      cpu: 500m

  # The following configuration initializes the Keycloak realm upon startup. Doing so
  # ensures that Keycloak is ready to be used by vantage6 services.
  realmImport:
    enabled: true

    # Keycloak realm name. If used as not standalone, not that this overwrites the
    # global hub setting.
    realm: vantage6

    # access token lifespan in seconds
    accessTokenLifespan: 300

    # sso session idle timeout in seconds. This is the time before the refresh token
    # expires. With default settings, this value controls the time before the refresh
    # token expires. If set to a value greater than 3600 seconds, you should also set
    # ssoSessionMaxLifespan and/or clientSessionIdleTimeout and/or clientSessionMaxLifespan
    # to higher values to effectively lengthen the session.
    ssoSessionIdleTimeout: 1800

    # password policy configuration. If you prefer not to have a password policy,
    # you can set this to an empty string. In production we recommend a strong policy.
    passwordPolicy: "length(8) and upperCase(1) and lowerCase(1) and digits(1) and specialChars(1)"

    # Allow users to reset their password via email.
    resetPasswordAllowed: false

    # Brute force protection settings.
    # - bruteForceProtected: enable brute force protection
    # - permanentLockout: whether to lock out a user permanently after a certain number
    #   of failed login attempts.
    # - failureFactor: the number of failed login attempts before a user is locked out.
    bruteForceProtected: true
    permanentLockout: false
    failureFactor: 5

    # Define the vantage6 admin user. This user will be created in the realm.
    admin:
      username: admin
      # In production, use a strong password here.
      password: Admin123!

    # Whether to verify email on first login. This should only be enabled if an SMTP
    # server is configured to send emails.
    verifyEmail: true

    # Whether to require users to update their password on first login.
    passwordUpdateRequired: true

    # Public client configuration. The public client is used by users to authenticate
    # in the browser.
    publicClient:
      name: public_client
      # Redirect URIs are the URIs that Keycloak is allowed to redirect to after
      # authentication. This should normally be set to the UI URL. If you have
      # other applications that can use the vantage6 Keycloak instance, those should be
      # added as well.
      redirectUris:
        - "http://localhost:7600/*"

    # Secret used for the backend admin client. Note that if this is defined, it will
    # override the hub's global backend admin client secret.
    backend_client_secret: myadminclientsecret

    # SMTP server configuration. This is used to send emails to users.
    smtpServer:
      host: your-smtp-server-hostname.org
      port: 587                 # usually 587 for STARTTLS, 465 for SSL
      from: your-email-address@your-domain.com
      ssl: false                # true for SSL, false for STARTTLS
      starttls: true            # true for STARTTLS, false for SSL
      # Authentication settings - should usually be used, unless you are running tests
      # with a local SMTP server.
      auth: true
      authType: basic           # always use 'basic' for username and password
      user: your-username       # your username (often the same as the email address)
      password: your-password   # your password
      # Optional settings for the reply-to address.
      replyTo: reply-to-email-address@your-domain.com
      replyToDisplayName: display-name-for-reply-to

database:
  # For production environments, we recommend using an external database.
  external: true

  # Hostname and port of the external database, required if external is set to true.
  host: your-database-hostname.org
  port: 5432

  # Credentials and database name.
  username: keycloak
  password: keycloak
  name: keycloak

  # Development settings - only used if external is set to false.
  # Specify the image to use for the database.
  # image:
  #   repository: postgres
  #   tag: "13"
  # Specify the path to the volume where the database is stored.
  # volumePath: /mnt/data_auth
  # Specify the name of the k8s node where the database is running.
  # k8sNodeName: docker-desktop
  # Specify the storage class to use for the database.
  # storageClass: local-storage

Customize

The number of configuration options in Keycloak is enormous. The vantage6 helm chart intends to provide a way to deploy a Keycloak instance that is both adapted to the vantage6 infrastructure and secure by default. To support all the Keycloak configuration options is not in scope of this project. However, you can customize your Keycloak deployment further by logging in to the Keycloak admin console, or by using the Keycloak CLI or API.

You can login to the Keycloak admin console by opening a browser and navigating to the address where you deployed the Keycloak service. For sandbox environments, this will be http://localhost:30764. For production environments, this will be the address of the Keycloak service in your Kubernetes cluster. You can login with the Keycloak admin credentials - see where these are configured in the admin section of the configuration file above.

Once you are logged in, you customize your Keycloak deployment in any way you want. Take care that you don’t overwrite the vantage6-specific configuration, such as the backend client, as this may cause issues in communicating with vantage6 HQ and store.

Note

With keycloak, it is also possible to use another identity provider. For instance, you could configure a Microsoft or Google login page. It is also possible to configure your own Keycloak instance and link it to the vantage6 keycloak service.

Install and use

Once you have configured Keycloak, you can start it in a similar way to the other components. You can start it with the following command:

v6 auth start

Or you can start it as part of the hub:

v6 hub start

The Helm chart for the Keycloak authentication service is based on the Keycloak Operator, which is Keycloak’s recommended way to deploy Keycloak in a Kubernetes cluster. The first time you start the authentication service, it will install the Keycloak Operator automatically. The custom resource definitions (CRDs) for the Keycloak Operator are downloaded and installed in your Kubernetes cluster. These custom Kubernetes resources specify how your Kubernetes service should deploy Keycloak.

If you prefer to install the CRDs yourself (and not as part of the v6 auth start command), you can install them using the following command:

v6 auth install-keycloak