Skip to main content

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.

warning

We strongly recommend changing the initial_root_password after your initial deployment and deleting this value from your nebari-config.yaml. Any changes to this value in the nebari-config.yaml after the initial deployment will have no effect.

For more information on how to do this, see the Change Keycloak root password section.

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: ...
warning

The options for type, which are Auth0, GitHub, and password, are case sensitive.

note

Even if you formally select password/GitHub/Auth0 authentication in the nebari-config.yaml file, it's still possible to add other authentication methods alongside them to Keycloak manually. For more information on how to do this, please refer to the Keycloak documentation.