Welcome to Native Authenticator’s documentation!

A simple authenticator for small-medium size JupyterHub applications.

Native Authenticator provides the following features:

• New users can signup on the system;
• New users can be blocked of accessing the system and need an admin authorization;
• Option of increase password security by avoiding common passwords or minimum password length;
• Option to block users after a number attempts of login;
• Option of open signup and no need for initial authorization;
• Option of adding more information about users on signup.

Indices and tables

Quickstart

Installation

Native Authenticator is a plugin Authenticator for the JupyterHub.

You must install this authenticator throught the project’s repository. This is a temporary solution until we have the package on the Pypi:

$ git clone https://github.com/jupyterhub/nativeauthenticator.git
$ pip install -e .

Then, you must create the configuration file for JupyterHub:

$ jupyterhub --generate-config -f /etc/jupyterhub/jupyterhub_config.py

And change the default Authenticator class for the Native Authenticator class:

c.JupyterHub.authenticator_class = 'nativeauthenticator.NativeAuthenticator'

You can then run JupyterHub using the config file and the NativeAuthenticator will be running the system:

$ jupyterhub -f /etc/jupyterhub/jupyterhub_config.py

Default workflow

A new user that wants access to a system running the Native Authenticator must enter the SignUp page and create a new username and password. By default, this user will not have access to the system, they will the authorization of an admin to actually be able to login the system. Thus, when making the signup the user will receive a message letting them know that their information was sent to an admin.

The admin must acces the authorization panel and authorize the user so they be able to login:

Adding new users

To create a new user one must fo to /hub/signup and create a username and a password. The information on the signup can change depending on admin configuration and are all obligatory. By default, when a new user is created on the system it will need an Admin authorization to access the system.

It is important to notice that admin must also create a new user through signup. However, usernames list in the config file as admins will automatically have authorization to enter the system.

c.Authenticator.admin_users = {'username'}

Usernames restrictions

Usernames can’t contain commas, whitespaces, slashes or be empty. If any of these are in the username on signup, the user won’t be able to do the signup.

Authorize or unauthorize users

To authorize new users to enter the system or to manage those that already have access to the system you can go to /hub/authorize. Authorized users will have a green background with a button for unauthorize them while unauthorized users will have a white background and an authorization button.

Change password

Users that are logged in the system can easily change their password by going to: /hub/change-password.

Optional Configuration

Password Strength

By default, when a user signs up through Native Authenticator there is no password strength verification, so any type of password is valid. There are two methods that you can add to increase password strength: a verification for commmon passowords and a minimum length of password.

To verify if the password is not common (such as ‘qwerty’ or ‘1234’), you can add the following line to your config file:

c.Authenticator.check_common_password = True

The Authenticator will verify if the password is a common password and the user won’t be able to sign up if it is. The list of the common passwords that are in our verification is available on this link >._

You can also add a minimum password length that the user must have. To do this add the following line on the config file with an integer as a value:

c.Authenticator.minimum_password_length = 10

If any of this configuration is available, the user will receive this message on SignUp:

Block users after failed logins

One thing that can make systems more safe is to block users after a number of failed logins. With Native Authenticator you can add this feature by adding allowed_failed_logins on the config file. The default is 0, which means that the system will not block users ever.

c.Authenticator.allowed_failed_logins = 3

You can also define the number of seconds a user must wait before trying again. The default value is 600 seconds.

c.Authenticator.seconds_before_next_try = 1200

Disable SignUp

By default Native Authenticator allows everyone to register user accounts. But you can add a option to disable signup. To do so, just add the following line to the config file:

c.Authenticator.enable_signup = False

Open SignUp

By default all users that make sign up on Native Authenticator need an admin approval so they can actually log in the system. You can change this behavior by adding an option of open signup, where all users that do sign up can already log in the system. To do so, just add this line to the config file:

c.Authenticator.open_signup = True

Ask for extra information on SignUp

Native Authenticator is based on username and password only. But if you need extra information about the users, you can add them on the sign up. For now, the only extra information you can ask is email. To do so, you can add the following line on the config file:

c.Authenticator.ask_email_on_signup = True

Import users from FirstUse Authenticator

If you are using FirstUse Authenticator <https://github.com/jupyterhub/firstuseauthenticator> and wish to change to Native Authenticator, you can import users from that authenticator to Native authenticator with minimum work!

To do so, you have to add the following line on the configuration file:

c.Authenticator.import_from_firstuse = True

Remark: unless you have configured the open signup configuration, the users will be created but they will not be able to login, because they don’t have authorization by default.

By default, Native Authenticator assumes that the path for the database is the same directory. If that’s not the case, you can change the path the file through this variables:

c.Authenticator.firstuse_dbm_path = '/home/user/passwords.dbm'

Native Authenticator ensures that usernames are sanitized, so they won’t have commas or white spaces. Additionaly, you can add password verification such as avoiding common passwords. If usernames or passwords imported from the FirstUse Authenticator don’t comply with these verifications, the importating will raise an error.

You can also remove FirstUse’s database file after the importation to Native Authenticator, to avoid leaving unused files on the system. To do so, you must add the following line to the configuration file:

c.Authenticator.delete_firstuse_db_after_import = True

Add two factor authentication obligatory for users

You can increase security making two factor authentication obligatory for all users. To do so, add the following line on the config file:

c.Authenticator.allow_2fa = True

Users will receive a message after signup with the two factor authentication code:

And login will now require the two factor authentication code as well: