Security configuration

The security section of the configuration file allows you to configure the authentication and authorization providers of your deployment. As well as customize the default configurations of the Keycloak User management system.

Keycloak

Keycloak is an open source identity and access management solution that provides authentication, authorization, and user management for web, mobile, IoT, and internal applications. This section outlines the configuration options for the Keycloak service that Nebari provides.

### Keycloak configuration ###
security:
  keycloak:
    initial_root_password: initpasswd
    overrides:
      image:
        repository: quansight/nebari-keycloak
  ...

The keycloak section allows you to specify an initial password for the root Administrative user to manage your Keycloak database which is responsible for managing users, clients, and other Keycloak related configurations. Note that the root user is not actually a Nebari user - you cannot access the main features of Nebari such as JupyterLab with this user - it is exclusively for Keycloak management.

The overrides section allows you to specify a custom image for the Keycloak service. This is useful if you want to customize themes or add additional plugins to Keycloak. The full extent of override options can be found in the Keycloak Helm deployment.

Authentication methods

Nebari supports multiple authentication methods by using Keycloak under the hood. To ease the configuration procedure of adding the most common authentication providers to Keycloak, Nebari already supports [Auth0, GitHub, password] automatically during deployment. You may also disable authentication by setting authentication to false in the nebari-config.yaml file.

The default authentication method is set to GitHub if no changes are specified in the configuration file or during initialization.

To use GitHub as your authentication method, you must first create a GitHub OAuth application and provide the client_id and client_secret to Nebari. By using the GitHub authentication method, users will then be able to log in to Nebari using their GitHub account registered within Keycloak database.

### Authentication configuration ###
security:
  ...
  authentication:
    type: GitHub
    config:
      client_id: ...
      client_secret: ...

Auth0 is a cloud-based identity management platform that provides authentication, authorization, and user management for web, mobile, IoT, and internal applications. This authentication method is useful for organizations that already have an Auth0 account and user database and want to seamlessly integrate it with Nebari.

To use Auth0 as your authentication method, you must have an Auth0 application and provide the client_id and client_secret to Nebari. Make sure that your Auth0 application is a Regular Web Application. By using the Auth0 authentication method, users will then be able to log in to Nebari using their Auth0 account registered within Keycloak database.

### Authentication configuration ###
security:
  ...
  authentication:
    type: Auth0
    config:
      client_id: ...
      client_secret: ...
      auth0_subdomain: ...

It's important to note is that the auth0_subdomain field in the YAML must be only the <auth0_subdomain>.auth0.com. For example, for nebari-dev.auth0.com the subdomain would be nebari-dev.

Username and Password is the simplest authentication method that Nebari supports. By using the Password authentication method, users will then be able to log in to Nebari using their username and password registered within Keycloak database.

### Authentication configuration ###
security:
  ...
  authentication:
    type: password