OAuthenticator

OAuth + JupyterHub Authenticator = OAuthenticator

OAuthenticator currently supports the following authentication services:

Auth0
Azure AD
Azure AD B2C
Bitbucket
CILogon
GitHub
GitLab
Globus
Google
MediaWiki
Moodle
Okpy
OpenShift

A generic implementation, which you can use with any provider, is also available.

Examples

For an example docker image using OAuthenticator, see the examples directory.

Another example is using GitHub OAuth to spawn each user's server in a separate docker container.

Installation

Install with pip:

pip3 install oauthenticator

Or clone the repo and do a dev install:

git clone https://github.com/jupyterhub/oauthenticator.git
cd oauthenticator
pip3 install -e .

General setup

The first step is to tell JupyterHub to use your chosen OAuthenticator. Each authenticator is provided in a submodule of oauthenticator, and each authenticator has a variant with Local (e.g. LocalGitHubOAuthenticator), which will map OAuth usernames onto local system usernames.

Set chosen OAuthenticator

In jupyterhub_config.py, add:

from oauthenticator.github import GitHubOAuthenticator
c.JupyterHub.authenticator_class = GitHubOAuthenticator

Set callback URL, client ID, and client secret

All OAuthenticators require setting a callback URL, client ID, and client secret. You will generally get these when you register your OAuth application with your OAuth provider. Provider-specific details are available in sections below. When registering your oauth application with your provider, you will probably need to specify a callback URL. The callback URL should look like:

http[s]://[your-host]/hub/oauth_callback

where [your-host] is where your server will be running. Such as example.com:8000.

When JupyterHub runs, these values will be retrieved from the environment variables:

$OAUTH_CALLBACK_URL
$OAUTH_CLIENT_ID
$OAUTH_CLIENT_SECRET

You can also set these values in your configuration file, jupyterhub_config.py:

# Replace MyOAuthenticator with your selected OAuthenticator class (e.g. c.GithubOAuthenticator).

c.MyOAuthenticator.oauth_callback_url = 'http[s]://[your-host]/hub/oauth_callback'
c.MyOAuthenticator.client_id = 'your-client-id'
c.MyOAuthenticator.client_secret = 'your-client-secret'

Azure AD Setup

Prereqs:

Requires: PyJWT>=1.5.3

> pip3 install PyJWT

BE SURE TO SET THE AAD_TENANT_ID environment variable

> export AAD_TENANT_ID='{AAD-TENANT-ID}'

Sample code is provided for you in examples > azuread > sample_jupyter_config.py
Just add the code below to your jupyterhub_config.py file
Making sure to replace the values in '{}' with your APP, TENANT, DOMAIN, etc. values

Follow this link to create an AAD APP

CLIENT_ID === Azure Application ID - found in Azure portal --> AD --> App Registrations --> App

TENANT_ID === Azure Directory ID - found in Azure portal --> AD --> Properties

jupyterhub_config.py:

import os
from oauthenticator.azuread import AzureAdOAuthenticator
c.JupyterHub.authenticator_class = AzureAdOAuthenticator

c.Application.log_level = 'DEBUG'

c.AzureAdOAuthenticator.tenant_id = os.environ.get('AAD_TENANT_ID')

c.AzureAdOAuthenticator.oauth_callback_url = 'http://{your-domain}/hub/oauth_callback'
c.AzureAdOAuthenticator.client_id = '{AAD-APP-CLIENT-ID}'
c.AzureAdOAuthenticator.client_secret = '{AAD-APP-CLIENT-SECRET}'

Run via:

sudo jupyterhub -f ./path/to/jupyterhub_config.py

See run.sh for an example

Source Code

Azure AD B2C Setup

Prereqs:

Requires: PyJWT>=1.5.3

> pip3 install PyJWT

BE SURE TO SET THE OAUTH_ACCESS_TOKEN_URL, OAUTH_AUTHORIZE_URL and OAUTH_SCOPE environment variables

> export OAUTH_ACCESS_TOKEN_URL='https://login.microsoftonline.com/YOUR_TENANT.onmicrosoft.com/oauth2/v2.0/token?p=YOUR_POLICY_NAME'
> export OAUTH_AUTHORIZE_URL='https://login.microsoftonline.com/YOUR_TENANT.onmicrosoft.com/oauth2/v2.0/authorize?p=YOUR_POLICY_NAME'
> export OAUTH_SCOPE='openid YOUR_RESOURCE'

Sample code

The sample code can be found at examples folder

See run.sh for setting up environment variables.
See config.py for setting up such as client id/secret and add_user_cmd.

Source code

The source code can be found at here.

GitHub Setup

First, you'll need to create a GitHub OAuth application.

Then, add the following to your jupyterhub_config.py file:

from oauthenticator.github import GitHubOAuthenticator
c.JupyterHub.authenticator_class = GitHubOAuthenticator

You can also use LocalGitHubOAuthenticator to map GitHub accounts onto local users.

You can use your own Github Enterprise instance by setting the GITHUB_HOST environment variable.

You can set GITHUB_HTTP environment variable to true or anything if your GitHub Enterprise supports http only.

GitHub allows expanded capabilities by adding GitHub-Specific Scopes to the requested token.

GitLab Setup

First, you'll need to create a GitLab OAuth application.

Then, add the following to your jupyterhub_config.py file:

from oauthenticator.gitlab import GitLabOAuthenticator
c.JupyterHub.authenticator_class = GitLabOAuthenticator

You can also use LocalGitLabOAuthenticator to map GitLab accounts onto local users.

You can use your own GitLab CE/EE instance by setting the GITLAB_HOST environment flag.

You can restrict access to only accept members of certain projects or groups by setting

c.GitLabOAuthenticator.gitlab_project_id_whitelist = [ ... ]

and

c.GitLabOAuthenticator.gitlab_group_whitelist = [ ... ]

but be aware that each entry incurs a separate API call, increasing the risk of rate limiting and timeouts.

Google Setup

Visit https://console.developers.google.com to set up an OAuth client ID and secret. See Google's documentation on how to create OAUth 2.0 client credentials. The Authorized JavaScript origins should be set to to your hub's public address while Authorized redirect URIs should be set to the same but followed by /hub/oauth_callback.

Then, add the following to your jupyterhub_config.py file:

from oauthenticator.google import GoogleOAuthenticator
c.JupyterHub.authenticator_class = GoogleOAuthenticator

By default, any domain is allowed to login but you can restrict authorized domains with a list (recommended):

c.GoogleOAuthenticator.hosted_domain = ['mycollege.edu', 'mycompany.com']

You can customize the sign in button text (optional):

c.GoogleOAuthenticator.login_service = 'My College'

OpenShift Setup

In case you have an OpenShift deployment with OAuth properly configured (see the following sections for a quick reference), you should set the client ID and secret by the environment variables OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET and OAUTH_CALLBACK_URL.

Prior to OpenShift 4.0, the OAuth provider and REST API URL endpoints can be specified by setting the single environment variable OPENSHIFT_URL. From OpenShift 4.0 onwards, these two endpoints are on different hosts. You need to set OPENSHIFT_AUTH_API_URL to the OAuth provider URL, and OPENSHIFT_REST_API_URL to the REST API URL endpoint.

The OAUTH_CALLBACK_URL should match http[s]://[your-app-route]/hub/oauth_callback

Global OAuth (admin)

As a cluster admin, you can create a global OAuth client in your OpenShift cluster creating a new OAuthClient object using the API:

$ oc create -f - <<EOF
apiVersion: v1
kind: OAuthClient
metadata:
  name: <OAUTH_CLIENT_ID>
redirectURIs:
- <OUAUTH_CALLBACK_URL>
secret: <OAUTH_SECRET>
EOF

Service Accounts as OAuth Clients

As a project member, you can use the Service Accounts as OAuth Clients scenario. This gives you the possibility of defining clients associated with service accounts. You just need to create the service account with the proper annotations:

$ oc create -f - <<EOF
apiVersion: v1
kind: ServiceAccount
metadata:
  name: <name>
  annotations:
    serviceaccounts.openshift.io/oauth-redirecturi.1: '<OUAUTH_CALLBACK_URL>'
EOF

In this scenario your OAUTH_CLIENT_ID will be system:serviceaccount:<serviceaccount_namespace>:<serviceaccount_name>, the OAUTH_CLIENT_SECRET is the API token of the service account (oc sa get-token <serviceaccount_name>) and the OAUTH_CALLBACK_URL is the value of the annotation serviceaccounts.openshift.io/oauth-redirecturi.1. More details can be found in the upstream documentation.

OkpyAuthenticator

Okpy is an auto-grading tool that is widely used in UC Berkeley EECS and Data Science courses. This authenticator enhances its support for Jupyter Notebook by enabling students to authenticate with the Hub first and saving relevant user states to the env (the feature is redacted until a secure state saving mechanism is developed).

Configuration

If you want to authenticate your Hub using OkpyAuthenticator, you need to specify the authenticator class in your jupyterhub_config.py file:

from oauthenticator.okpy import OkpyOAuthenticator
c.JupyterHub.authenticator_class = OkpyOAuthenticator

and set your OAUTH_ environment variables.

Globus Setup

Visit https://developers.globus.org/ to set up your app. Ensure Native App is unchecked and make sure the callback URL looks like:

https://[your-host]/hub/oauth_callback

Set scopes for authorization and transfer. The defaults include:

openid profile urn:globus:auth:scope:transfer.api.globus.org:all

Set the above settings in your jupyterhub_config:

# Tell JupyterHub to create system accounts
from oauthenticator.globus import LocalGlobusOAuthenticator
c.JupyterHub.authenticator_class = LocalGlobusOAuthenticator
c.LocalGlobusOAuthenticator.enable_auth_state = True
c.LocalGlobusOAuthenticator.oauth_callback_url = 'https://[your-host]/hub/oauth_callback'
c.LocalGlobusOAuthenticator.client_id = '[your app client id]'
c.LocalGlobusOAuthenticator.client_secret = '[your app client secret]'

Alternatively you can set env variables for the following: OAUTH_CALLBACK_URL, OAUTH_CLIENT_ID, and OAUTH_CLIENT_SECRET. Setting JUPYTERHUB_CRYPT_KEY is required, and can be generated with OpenSSL: openssl rand -hex 32

You are all set by this point! Be sure to check below for tweaking settings related to User Identity, Transfer, and additional security.

User Identity

By default, all users are restricted to their Globus IDs ([email protected]) with the default Jupyterhub config:

c.GlobusOAuthenticator.identity_provider = 'globusid.org'

If you want to use a Linked Identity such as [email protected], go to your App Developer page and set Required Identity Provider for your app to <Your University>, and set the following in the config:

c.GlobusOAuthenticator.identity_provider = 'universityofindependence.edu'

Globus Scopes and Transfer

The default configuration will automatically setup user environments with tokens, allowing them to start up python notebooks and initiate Globus Transfers. If you want to transfer data onto your JupyterHub server, it's suggested you install Globus Connect Server and add the globus_local_endpoint uuid below. If you want to change other behavior, you can modify the defaults below:

# Allow Refresh Tokens in user notebooks. Disallow these for increased security,
# allow them for better usability.
c.LocalGlobusOAuthenticator.allow_refresh_tokens = True
# Default scopes are below if unspecified. Add a custom transfer server if you have one.
c.LocalGlobusOAuthenticator.scope = ['openid', 'profile', 'urn:globus:auth:scope:transfer.api.globus.org:all']
# Default tokens excluded from being passed into the spawner environment
c.LocalGlobusOAuthenticator.exclude_tokens = ['auth.globus.org']
# If the JupyterHub server is an endpoint, for convenience the endpoint id can be
# set here. It will show up in the notebook kernel for all users as 'GLOBUS_LOCAL_ENDPOINT'.
c.LocalGlobusOAuthenticator.globus_local_endpoint = '<Your Local JupyterHub UUID>'
# Set a custom logout URL for your identity provider
c.LocalGlobusOAuthenticator.logout_redirect_url = 'https://auth.globus.org/v2/web/logout'
# For added security, revoke all service tokens when users logout. (Note: users must start
# a new server to get fresh tokens, logging out does not shut it down by default)
c.LocalGlobusOAuthenticator.revoke_tokens_on_logout = False

If you only want to authenticate users with their Globus IDs but don't want to allow them to do transfers, you can remove urn:globus:auth:scope:transfer.api.globus.org:all. Conversely, you can add an additional scope for another transfer server if you wish.

Use c.GlobusOAuthenticator.exclude to prevent tokens from being passed into a users environment. By default, auth.globus.org is excluded but transfer.api.globus.org is allowed. If you want to disable transfers, modify c.GlobusOAuthenticator.scope instead of c.GlobusOAuthenticator.exclude to avoid procuring unnecessary tokens.

Moodle Setup

First install the OAuth2 Server Plugin for Moodle.

Use the GenericOAuthenticator for Jupyterhub by editing your jupyterhub_config.py accordingly:

from oauthenticator.generic import GenericOAuthenticator
c.JupyterHub.authenticator_class = GenericOAuthenticator

c.GenericOAuthenticator.oauth_callback_url = 'http://YOUR-JUPYTERHUB.com/hub/oauth_callback'
c.GenericOAuthenticator.client_id = 'MOODLE-CLIENT-ID'
c.GenericOAuthenticator.client_secret = 'MOODLE-CLIENT-SECRET-KEY'
c.GenericOAuthenticator.login_service = 'NAME-OF-SERVICE'
c.GenericOAuthenticator.userdata_url = 'http://YOUR-MOODLE-DOMAIN.com/local/oauth/user_info.php'
c.GenericOAuthenticator.token_url = 'http://YOUR-MOODLE-DOMAIN.com/local/oauth/token.php'
c.GenericOAuthenticator.userdata_method = 'POST'
c.GenericOAuthenticator.extra_params = {
    'scope': 'user_info',
    'client_id': 'MOODLE-CLIENT-ID',
    'client_secret': 'MOODLE-CLIENT-SECRET-KEY'}

And set your environmental variable OAUTH2_AUTHORIZE_URL to:

http://YOUR-MOODLE-DOMAIN.com/local/oauth/login.php?client_id=MOODLE-CLIENT-ID&response_type=code

Yandex Setup

First visit Yandex OAuth to setup your app. Ensure that Web services is checked (in the Platform section) and make sure the Callback URI #1 looks like:

https://[your-host]/hub/oauth_callback

Choose Yandex.Passport API in Permissions and check these options:

Access to email address
Access to username, first name and surname

Set the above settings in your jupyterhub_config.py:

c.JupyterHub.authenticator_class = 'oauthenticator.yandex.YandexPassportOAuthenticator'
c.YandexPassportOAuthenticator.oauth_callback_url = 'https://[your-host]/hub/oauth_callback'
c.YandexPassportOAuthenticator.client_id = '[your app ID]'
c.YandexPassportOAuthenticator.client_secret = '[your app Password]'

Name		Name	Last commit message	Last commit date
Latest commit History 608 Commits
examples		examples
oauthenticator		oauthenticator
.coveragerc		.coveragerc
.flake8		.flake8
.gitignore		.gitignore
.travis.yml		.travis.yml
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
RELEASE.md		RELEASE.md
cilogon_scope.md		cilogon_scope.md
github_scope.md		github_scope.md
gitlab_scope.md		gitlab_scope.md
globus-requirements.txt		globus-requirements.txt
requirements.txt		requirements.txt
setup.py		setup.py
test-requirements.txt		test-requirements.txt

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

OAuthenticator

Examples

Installation

General setup

Set chosen OAuthenticator

Set callback URL, client ID, and client secret

Azure AD Setup

Prereqs:

Run via:

Azure AD B2C Setup

Prereqs:

Sample code

Source code

GitHub Setup

GitLab Setup

Google Setup

OpenShift Setup

Global OAuth (admin)

Service Accounts as OAuth Clients

OkpyAuthenticator

Configuration

Globus Setup

User Identity

Globus Scopes and Transfer

Moodle Setup

Yandex Setup

About

Releases

Packages

Languages

License

InsightLab/oauthenticator

Folders and files

Latest commit

History

Repository files navigation

OAuthenticator

Examples

Installation

General setup

Set chosen OAuthenticator

Set callback URL, client ID, and client secret

Azure AD Setup

Prereqs:

Run via:

Azure AD B2C Setup

Prereqs:

Sample code

Source code

GitHub Setup

GitLab Setup

Google Setup

OpenShift Setup

Global OAuth (admin)

Service Accounts as OAuth Clients

OkpyAuthenticator

Configuration

Globus Setup

User Identity

Globus Scopes and Transfer

Moodle Setup

Yandex Setup

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages