From 99d72dfccfff79c4a5ee9f7449e12d7ecfe585b7 Mon Sep 17 00:00:00 2001 From: Simon Li Date: Thu, 16 Nov 2023 19:16:54 +0000 Subject: [PATCH] authenticator reference doc: update authenticate return --- docs/source/reference/authenticators.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/source/reference/authenticators.md b/docs/source/reference/authenticators.md index 65980560..5fde46d6 100644 --- a/docs/source/reference/authenticators.md +++ b/docs/source/reference/authenticators.md @@ -65,11 +65,15 @@ from JupyterHub's login form. Unless the login form has been customized, - `username` - `password` -The `authenticate` method's job is simple: +If authentication is successful the `authenticate` method must return either: -- return the username (non-empty str) of the authenticated user if - authentication is successful -- return `None` otherwise +- the username (non-empty str) of the authenticated user +- or a dictionary with fields: + - `name`: the username + - `auth_state`: optional, a dictionary of of [auth state that will be persisted](authenticator-auth-state) + - `groups`: optional, a list of JupyterHub [group memberships](authenticator-groups) + +Otherwise, it must return `None`. Writing an Authenticator that looks up passwords in a dictionary requires only overriding this one method: @@ -182,6 +186,8 @@ Additionally, configurable attributes for your authenticator will appear in jupyterhub help output and auto-generated configuration files via `jupyterhub --generate-config`. +(authenticator-auth-state)= + ### Authentication state JupyterHub 0.8 adds the ability to persist state related to authentication,