### Install Pre-commit Hooks

Source: https://github.com/jupyterhub/oauthenticator/blob/main/CONTRIBUTING.md

Install pre-commit to automatically check code formatting before commits. Ensure pre-commit is installed first.

```bash
pip install pre-commit
pre-commit install --install-hooks
```

--------------------------------

### Development Install with Pip

Source: https://github.com/jupyterhub/oauthenticator/blob/main/CONTRIBUTING.md

Install the OAuthenticator package in editable mode with test dependencies. Navigate to the cloned repository directory first.

```bash
cd oauthenticator
pip install -e ".[test]"
```

--------------------------------

### Install oauthenticator with Azure AD support

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/provider-specific-setup/providers/azuread.md

Install the oauthenticator package with the optional azuread dependency. This is required for AzureAdOAuthenticator.

```bash
pip install "oauthenticator[azuread]"
```

--------------------------------

### Full JupyterHub Authenticator Configuration Example

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/general-setup.md

A comprehensive example demonstrating the configuration of both the authenticator class and base OAuthenticator settings, including user access controls and specific GitHub authenticator options.

```python
c.JupyterHub.authenticator_class = "github"

c.OAuthenticator.oauth_callback_url = "https://my-jupyterhub.prg/hub/oauth_callback"
c.OAuthenticator.client_id = "1234-5678-9012-3456"
c.OAuthenticator.client_secret = "abcd-edfg-ijkl-mnop"

c.OAuthenticator.allow_existing_users = True
c.OAuthenticator.allowed_users = {"github-user-1", "github-user-2"}
c.OAuthenticator.admin_users = {"github-user-3"}

c.GitHubOAuthenticator.allowed_organizations = {"github-organization-1"}
c.GitHubOAuthenticator.scope = ["user:email", "read:org"]
```

--------------------------------

### Install oauthenticator with pip

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/install.md

Use this command to install oauthenticator using pip. Ensure you are using a Python 3 environment.

```bash
python3 -m pip install oauthenticator
```

--------------------------------

### Install googlegroups extra_requires

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/topic/google.md

Install the necessary package for Google Groups integration. This should be done in your hub environment.

```shell
pip install oauthenticator[googlegroups]
```

--------------------------------

### Launch JupyterHub

Source: https://github.com/jupyterhub/oauthenticator/blob/main/examples/mock-provider/README.md

Start JupyterHub after the mock OAuth2 server is running. JupyterHub will then use the configured authenticator.

```bash
jupyterhub
```

--------------------------------

### Install tbump for Version Management

Source: https://github.com/jupyterhub/oauthenticator/blob/main/RELEASE.md

Install the tbump tool, which is used for managing package versions and creating git tags during the release process.

```shell
pip install tbump
```

--------------------------------

### Install oauthenticator with conda

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/install.md

Use this command to install oauthenticator from the conda-forge channel. This is recommended for users who manage their environments with conda.

```bash
conda install -c conda-forge oauthenticator
```

--------------------------------

### Moodle Provider Setup

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/provider-specific-setup/providers/generic.md

Configure GenericOAuthenticator for Moodle. Requires Moodle's OAuth2 Server Plugin. Specify client ID, secret, login service name, and the specific URLs for Moodle's OAuth endpoints.

```python
c.JupyterHub.authenticator_class = "generic-oauth"

c.GenericOAuthenticator.oauth_callback_url = 'https://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.authorize_url = 'https://YOUR-MOODLE-DOMAIN.com/local/oauth/login.php?client_id=MOODLE-CLIENT-ID&response_type=code'
c.GenericOAuthenticator.token_url = 'https://YOUR-MOODLE-DOMAIN.com/local/oauth/token.php'
c.GenericOAuthenticator.userdata_url = 'https://YOUR-MOODLE-DOMAIN.com/local/oauth/user_info.php'

c.GenericOAuthenticator.scope = ["user_info"]
```

--------------------------------

### Build Docker Image

Source: https://github.com/jupyterhub/oauthenticator/blob/main/examples/full/README.md

Build the Docker container for the JupyterHub OAuth setup. This command tags the image as 'jupyterhub-oauth'.

```bash
docker build -t jupyterhub-oauth .
```

--------------------------------

### Yandex Provider Setup

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/provider-specific-setup/providers/generic.md

Configure GenericOAuthenticator for Yandex. Requires app setup on Yandex OAuth and specifying the callback URI. Set client ID, secret, login service name, and Yandex's OAuth endpoints. Username is claimed by 'login'.

```python
c.JupyterHub.authenticator_class = "generic-oauth"
c.OAuthenticator.oauth_callback_url = "https://[your-host]/hub/oauth_callback"
c.OAuthenticator.client_id = "[your app ID]"
c.OAuthenticator.client_secret = "[your app Password]"

c.GenericOAuthenticator.login_service = "Yandex.Passport"
c.GenericOAuthenticator.username_claim = "login"

c.GenericOAuthenticator.authorize_url = "https://oauth.yandex.ru/authorize"
c.GenericOAuthenticator.token_url = "https://oauth.yandex.ru/token"
c.GenericOAuthenticator.userdata_url = "https://login.yandex.ru/info"
```

--------------------------------

### OpenID Connect (OIDC) Provider Setup

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/provider-specific-setup/providers/generic.md

Configure GenericOAuthenticator for an OIDC-based identity provider. Requires specifying client ID, secret, and URLs for authorization, token, and user data. Defines requested scopes and how to extract username and group information.

```python
c.JupyterHub.authenticator_class = "generic-oauth"

# OAuth2 application info
# -----------------------
c.GenericOAuthenticator.client_id = "some-client-id"
c.GenericOAuthenticator.client_secret = "some-often-long-client-secret"

# Identity provider info
# ----------------------
c.GenericOAuthenticator.authorize_url =
c.GenericOAuthenticator.token_url = "https://accounts.example.com/auth/realms/example/protocol/openid-connect/token"
c.GenericOAuthenticator.userdata_url = "https://accounts.example.com/auth/realms/example/protocol/openid-connect/userinfo"

# What we request about the user
# ------------------------------
# scope represents requested information about the user, and since we configure
# this against an OIDC based identity provider, we should request "openid" at
# least.
#
# In this example we include "email" and "groups" as well, and then declare that
# we should set the username based on the "email" key in the response, and read
# group membership from the "groups" key in the response.
#
c.GenericOAuthenticator.scope = ["openid", "email", "groups"]
c.GenericOAuthenticator.username_claim = "email"
c.GenericOAuthenticator.auth_state_groups_key = "oauth_user.groups"

# Authorization
# -------------
c.GenericOAuthenticator.allowed_users = {"user1@example.com"}
c.GenericOAuthenticator.allowed_groups = {"staff"}
c.GenericOAuthenticator.admin_users = {"user2@example.com"}
c.GenericOAuthenticator.admin_groups = {"administrator"}
```

--------------------------------

### Nextcloud Provider Setup

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/provider-specific-setup/providers/generic.md

Configure GenericOAuthenticator for Nextcloud. Requires setting up an OAuth2 Application in Nextcloud's admin settings. Specify client ID, secret, login service name, and Nextcloud's OAuth endpoints. Includes a custom lambda for username extraction.

```python
c.JupyterHub.authenticator_class = "generic-oauth"

c.GenericOAuthenticator.client_id = 'NEXTCLOUD-CLIENT-ID'
c.GenericOAuthenticator.client_secret = 'NEXTCLOUD-CLIENT-SECRET-KEY'
c.GenericOAuthenticator.login_service = 'NAME-OF-SERVICE'  # name to be displayed at login
c.GenericOAuthenticator.username_claim = lambda r: r.get('ocs', {}).get('data', {}).get('id')

c.GenericOAuthenticator.authorize_url = 'https://YOUR-NEXTCLOUD-DOMAIN.com/apps/oauth2/authorize'
c.GenericOAuthenticator.token_url = 'https://YOUR-NEXTCLOUD-DOMAIN.com/apps/oauth2/api/v1/token'
c.GenericOAuthenticator.userdata_url = 'https://YOUR-NEXTCLOUD-DOMAIN.com/ocs/v2.php/cloud/user?format=json'
```

--------------------------------

### Get GitHub User and Token from Environment Variables

Source: https://github.com/jupyterhub/oauthenticator/blob/main/examples/auth_state/gist-nb.ipynb

Retrieve GitHub username and token from environment variables. Ensure these variables are set before running the code.

```python
import os
gh_user = os.environ['GITHUB_USER']
gh_token = os.environ['GITHUB_TOKEN']
```

--------------------------------

### Example ORCID iD Userdata JSON Response

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/provider-specific-setup/providers/generic.md

An example of the JSON response from the ORCID userdata endpoint, illustrating the 'sub' field which is used as the username.

```json
{
  "sub": "0000-0002-2601-8132",
  "name": "Credit Name",
  "family_name": "Jones",
  "given_name": "Tom"
}
```

--------------------------------

### Configure JupyterHub Authenticator Class

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/general-setup.md

Set the JupyterHub authenticator class in your configuration file. This example uses 'github' as a placeholder for a specific authenticator.

```python
# code for a jupyterhub_config.py file...
c.JupyterHub.authenticator_class = "github"
```

--------------------------------

### JupyterHub Configuration for GitHub API Access

Source: https://github.com/jupyterhub/oauthenticator/blob/main/examples/auth_state/README.md

Configure JupyterHub to enable GitHub authentication, persist authentication state, request specific GitHub scopes (like gist write access), and pass GitHub API credentials as environment variables to user containers. This example also shows launching users with Docker.

```python
c.JupyterHub.authenticator_class = 'oauthenticator.github.GitHub'
c.GitHub.scope = ['gist']
c.GitHub.oauth_callback_url = '/hub/oauth_callback'

c.JupyterHub.spawner_class = 'dockerspawner.DockerSpawner'
c.DockerSpawner.image = 'jupyter/datascience-notebook'

c.Authenticator.auth_state_path = '/etc/jupyterhub/auth_state'
c.GitHub.enable_auth_state = True

c.GitHub.environment = {
    'GITHUB_TOKEN': '{{ github.token }}',
    'GITHUB_USER': '{{ github.user }}',
    'GITHUB_API_URL': 'https://api.github.com/'
}
```

--------------------------------

### Create Service Account as OAuth Client

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/provider-specific-setup/providers/openshift.md

As a project member, create a service account with annotations to use it as an OAuth client. The redirect URI annotation is crucial for callback handling.

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

--------------------------------

### Launch Mock OAuth2 Server

Source: https://github.com/jupyterhub/oauthenticator/blob/main/examples/mock-provider/README.md

Run the mock OAuth2 server in a Docker container. Ensure the port is accessible.

```bash
docker run --rm -it -p 127.0.0.1:8080:8080 ghcr.io/navikt/mock-oauth2-server:2.1.1
```

--------------------------------

### Enable Refresh Before Server Spawn

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/how-to/refresh.md

Enable this option to ensure user authentication is up-to-date before launching a server. This is particularly useful when servers receive access tokens, guaranteeing their validity at startup.

```python
c.Authenticator.refresh_pre_spawn = True
```

--------------------------------

### Create a Gist via GitHub API

Source: https://github.com/jupyterhub/oauthenticator/blob/main/examples/auth_state/gist-nb.ipynb

Post a new gist to GitHub using the authenticated requests session. The gist content and description are provided in JSON format. The output prints the URL of the created gist.

```python
import json
r = s.post('https://api.github.com/gists',
    data=json.dumps({
        'files': {
            'test.md': {
                'content': '# JupyterHub gist\n\nThis file was created from JupyterHub.',
            },
        },
        'description': 'test uploading a gist from JupyterHub',
    }),
)
r.raise_for_status()
print("Created gist: %s" % r.json()['html_url'])
```

--------------------------------

### Create OpenShift OAuthClient

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/provider-specific-setup/providers/openshift.md

Use this command to create a global OAuth client in your OpenShift cluster as a cluster admin. Ensure the metadata name and secret match your desired client ID and secret.

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

--------------------------------

### Clone the Repository

Source: https://github.com/jupyterhub/oauthenticator/blob/main/CONTRIBUTING.md

Use this command to clone the OAuthenticator repository to your local machine.

```bash
git clone https://github.com/jupyterhub/oauthenticator
```

--------------------------------

### Enable access for all authenticated users with allow_all

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/topic/allowing.md

Use this configuration to grant access to any user who can successfully authenticate. This is suitable for institutional SSO providers or temporary hubs where broad access is acceptable.

```python
c.OAuthenticator.allow_all = True
```

--------------------------------

### Run Tests with Pytest

Source: https://github.com/jupyterhub/oauthenticator/blob/main/CONTRIBUTING.md

Execute the project's test suite using pytest. This command should be run from the root of the cloned repository.

```bash
pytest
```

--------------------------------

### Run Specific OAuthenticator Test File

Source: https://github.com/jupyterhub/oauthenticator/blob/main/README.md

Execute tests from a specific file within the OAuthenticator test suite. Replace <test-file-name> with the actual file name.

```bash
pytest -v ./oauthenticator/tests/<test-file-name>
```

--------------------------------

### Run OAuthenticator Tests

Source: https://github.com/jupyterhub/oauthenticator/blob/main/README.md

Execute all OAuthenticator tests locally. Ensure your development environment is set up according to CONTRIBUTING.md before running.

```bash
pytest -v ./oauthenticator/tests/
```

--------------------------------

### Configure User List

Source: https://github.com/jupyterhub/oauthenticator/blob/main/examples/full/README.md

Edit the 'userlist' file to specify GitHub users and their admin status. Each line should contain a GitHub username, optionally followed by 'admin' if the user should be an administrator.

```text
mal admin
zoe admin
wash
inara admin
kaylee
jayne
simon
river
```

--------------------------------

### Run JupyterHub with OAuth

Source: https://github.com/jupyterhub/oauthenticator/blob/main/examples/full/README.md

Run the JupyterHub Docker container, mapping port 8000 and using an environment file for configuration. Ensure your OAuth client ID, secret, and callback URL are set in the 'env' file.

```bash
docker run -it -p 8000:8000 --env-file=env jupyterhub-oauth
```

--------------------------------

### Basic Azure AD Configuration

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/provider-specific-setup/providers/azuread.md

Configure JupyterHub to use AzureAdOAuthenticator and provide your Azure OAuth application credentials. Ensure the oauth_callback_url matches your JupyterHub deployment.

```python
c.JupyterHub.authenticator_class = "azuread"

c.OAuthenticator.oauth_callback_url = "https://[your-host]/hub/oauth_callback"
c.OAuthenticator.client_id = "[your oauth2 application id]"
c.OAuthenticator.client_secret = "[your oauth2 application secret]"

c.AzureAdOAuthenticator.tenant_id = "[your azure tenant id]"
c.AzureAdOAuthenticator.scope = ["openid", "email"]
```

--------------------------------

### Update CILogonOAuthenticator strip_idp_domain configuration

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/how-to/migrations/upgrade-to-15.md

The `strip_idp_domain` configuration option has been removed. Domain stripping behavior is now handled within the `allowed_idps` dictionary using the `username_derivation` configuration.

```python
c.CILogonOAuthenticator.username_claim = "email"
c.CILogonOAuthenticator.allowed_idps = ["uni.edu"]
c.CILogonOAuthenticator.strip_idp_domain = True
```

```python
c.CILogonOAuthenticator.allowed_idps = {
    'https://uni-idp.com/login/oauth/authorize': {
        'username_derivation': {
            'username_claim': 'email',
            'action': 'strip_idp_domain',
            'domain': 'uni.edu',
        }
    },
}
```

--------------------------------

### Tag and Release with tbump

Source: https://github.com/jupyterhub/oauthenticator/blob/main/RELEASE.md

Use tbump to set the new version number and create a git tag. The CI system will then build and publish the release.

```shell
# Example versions to set: 1.0.0, 1.0.0b1
VERSION=
tbump ${VERSION}
```

--------------------------------

### Create Requests Session with GitHub Token

Source: https://github.com/jupyterhub/oauthenticator/blob/main/examples/auth_state/gist-nb.ipynb

Initialize a requests session and set the Authorization header with the GitHub token for API authentication. This session can be reused for subsequent API calls.

```python
import requests
s = requests.session()
s.headers['Authorization'] = 'token ' + gh_token
```

--------------------------------

### Update CILogonOAuthenticator allowed_idps configuration

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/how-to/migrations/upgrade-to-15.md

The `allowed_idps` configuration now requires a dictionary structure to define username derivation rules for each identity provider. This allows for more granular control over username generation, including stripping domains, adding prefixes, or leaving usernames unchanged.

```python
c.CILogonOAuthenticator.allowed_idps = {
    'https://some-idp.com/login/oauth/authorize': {
        'username_derivation': {
            'username_claim': 'email',
            'action': 'strip_idp_domain',
            'domain': 'uni.edu',
        }
    },
    'https://another-idp.com/login/oauth/authorize': {
        'username_derivation': {
            'username_claim': 'nickname',
            'action': 'prefix',
            'prefix': 'idp',
        }
    },
    'https://yet-another-idp.com/login/oauth/authorize': {
        'username_derivation': {
            'username_claim': 'nickname',
        }
    },
}
```

--------------------------------

### Checkout and Update Main Branch

Source: https://github.com/jupyterhub/oauthenticator/blob/main/RELEASE.md

Ensure your local main branch is up-to-date with the remote repository before proceeding with release steps.

```shell
git checkout main
git fetch origin main
git reset --hard origin/main
```

--------------------------------

### Allow specific users by username with allowed_users

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/topic/allowing.md

This configuration specifies a list of users by their usernames who are permitted to log in. If this is the only authorization rule, only these users will be allowed.

```python
c.OAuthenticator.allowed_users = {"mensah", "ratthi"}
```

--------------------------------

### Update CILogonOAuthenticator idp to shown_idps

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/how-to/migrations/upgrade-to-15.md

The `idp` configuration, used to specify a single SAML Entity ID for CILogon, has been renamed to `shown_idps` and now expects a list of SAML Entity IDs. The first ID in the list becomes the default.

```python
c.CILogonOAuthenticator.idp = "https://accounts.google.com/o/oauth2/auth"
```

```python
c.CILogonOAuthenticator.shown_idps = ["https://accounts.google.com/o/oauth2/auth"]
```

--------------------------------

### Configure GenericOAuthenticator

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/how-to/writing-an-oauthenticator.md

Use this configuration when your OAuth provider is compatible with GenericOAuthenticator. Set the necessary OAuth parameters and URLs.

```python
c.JupyterHub.authenticator_class = "generic-oauth"

c.GenericOAuthenticator.oauth_callback_url = 'https://{host}/hub/oauth_callback'
c.GenericOAuthenticator.client_id = 'OAUTH-CLIENT-ID'
c.GenericOAuthenticator.client_secret = 'OAUTH-CLIENT-SECRET-KEY'
c.GenericOAuthenticator.login_service = 'name-of-service-provider'
c.GenericOAuthenticator.userdata_url = 'url-retrieving-user-data-with-access-token'
c.GenericOAuthenticator.token_url = 'url-retrieving-access-token-oauth-completion'
c.GenericOAuthenticator.username_claim = 'username-key-for-USERDATA-URL'
```

--------------------------------

### Configure Extra Authorize Parameters for Tokens

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/topic/google.md

Configure JupyterHub to request offline access and force approval when authorizing with Google. This allows retrieval of both access and refresh tokens.

```python
c.OAuthenticator.extra_authorize_params = {'access_type': 'offline', 'approval_prompt': 'force'}
```

--------------------------------

### JupyterHub CILogon Configuration

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/provider-specific-setup/providers/cilogon.md

Configure JupyterHub to use CILogon as the authenticator class and set OAuth callback URL, client ID, and client secret.

```python
c.JupyterHub.authenticator_class = "cilogon"
c.OAuthenticator.oauth_callback_url = "https://[your-domain]/hub/oauth_callback"
c.OAuthenticator.client_id = "[your oauth2 application id]"
c.OAuthenticator.client_secret = "[your oauth2 application secret]"
```

--------------------------------

### Enable user management via admin panel with allow_existing_users

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/topic/allowing.md

Set this to True to allow users to be managed (added/removed) through the JupyterHub admin page. Users added this way can log in if they are also granted access via an 'allow' rule.

```python
c.OAuthenticator.allow_existing_users = True
```

--------------------------------

### Reset Version to Development State

Source: https://github.com/jupyterhub/oauthenticator/blob/main/RELEASE.md

After a successful release, reset the version to a development state using tbump with the --no-tag option.

```shell
# Example version to set: 1.0.1.dev
NEXT_VERSION=
tbump --no-tag ${NEXT_VERSION}.dev
```

--------------------------------

### JupyterHub Configuration for OpenShift

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/provider-specific-setup/providers/openshift.md

Configure your `jupyterhub_config.py` to use the OpenShift authenticator and set the necessary OAuth callback URL, client ID, and client secret.

```python
c.JupyterHub.authenticator_class = "openshift"
c.OAuthenticator.oauth_callback_url = "https://[your-domain]/hub/oauth_callback"
c.OAuthenticator.client_id = "[your oauth2 application id]"
c.OAuthenticator.client_secret = "[your oauth2 application secret]"
```

--------------------------------

### JupyterHub Bitbucket Configuration

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/provider-specific-setup/providers/bitbucket.md

Configure JupyterHub to use Bitbucket as the authenticator and set the OAuth callback URL, client ID, and client secret. Ensure these values match your Bitbucket OAuth application settings.

```python
c.JupyterHub.authenticator_class = "bitbucket"
c.OAuthenticator.oauth_callback_url = "https://[your-domain]/hub/oauth_callback"
c.OAuthenticator.client_id = "[your oauth2 application id]"
c.OAuthenticator.client_secret = "[your oauth2 application secret]"
```

--------------------------------

### Basic JupyterHub Globus Configuration

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/provider-specific-setup/providers/globus.md

Configure JupyterHub to use Globus as the authentication backend and set the OAuth callback URL, client ID, and client secret.

```python
c.JupyterHub.authenticator_class = "globus"
c.OAuthenticator.oauth_callback_url = "https://[your-domain]/hub/oauth_callback"
c.OAuthenticator.client_id = "[your oauth2 application id]"
c.OAuthenticator.client_secret = "[your oauth2 application secret]"
```

--------------------------------

### Configure Username from Email Address

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/provider-specific-setup/providers/globus.md

Enable extracting the username from the user's email address. This automatically adds the 'email' scope.

```python
username_from_email = True
```

--------------------------------

### Configure Globus Scopes and Transfer Settings

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/provider-specific-setup/providers/globus.md

Configure GlobusOAuthenticator settings for enabling authentication state, defining scopes for Globus services, excluding specific tokens, setting a local endpoint ID, and managing token revocation on logout.

```python
# Allow saving user tokens to the database
# - requires JUPYTERHUB_CRYPT_KEY to be set, see
#   https://jupyterhub.readthedocs.io/en/stable/reference/authenticators.html#authentication-state
c.GlobusOAuthenticator.enable_auth_state = True

# Default scopes are below if unspecified. Add a custom transfer server if you have one.
c.GlobusOAuthenticator.scope = ['openid', 'profile', 'urn:globus:auth:scope:transfer.api.globus.org:all']
# Default tokens excluded from being passed into the spawner environment
c.GlobusOAuthenticator.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.GlobusOAuthenticator.globus_local_endpoint = '<Your Local JupyterHub UUID>'
# Set a custom logout URL for your identity provider
c.GlobusOAuthenticator.logout_redirect_url = 'https://globus.org/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.GlobusOAuthenticator.revoke_tokens_on_logout = False
```

--------------------------------

### JupyterHub Auth0 Configuration

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/provider-specific-setup/providers/auth0.md

Set the authenticator class and provide Auth0 OAuth credentials in your `jupyterhub_config.py` file. Ensure the `oauth_callback_url` matches your Auth0 application settings.

```python
c.JupyterHub.authenticator_class = "auth0"
c.OAuthenticator.oauth_callback_url = "https://[your-domain]/hub/oauth_callback"
c.OAuthenticator.client_id = "[your oauth2 application id]"
c.OAuthenticator.client_secret = "[your oauth2 application secret]"
```

--------------------------------

### JupyterHub Configuration for Google OAuth

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/provider-specific-setup/providers/google.md

Configure your `jupyterhub_config.py` to use Google as the authenticator and provide your OAuth application credentials.

```python
c.JupyterHub.authenticator_class = "google"
c.OAuthenticator.oauth_callback_url = "https://[your-domain]/hub/oauth_callback"
c.OAuthenticator.client_id = "[your oauth2 application id]"
c.OAuthenticator.client_secret = "[your oauth2 application secret]"
```

--------------------------------

### Azure AD Group Management Configuration

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/provider-specific-setup/providers/azuread.md

Enable and configure group management for AzureAdOAuthenticator to load user groups from the access token. This requires Azure AD to be set up to include group memberships in the token.

```python
c.JupyterHub.authenticator_class = "azuread"

# {...} other settings (see above)

c.AzureAdOAuthenticator.manage_groups = True
c.AzureAdOAuthenticator.auth_state_groups_key = "user.groups"  # this is the default
```

--------------------------------

### Configure OAuthenticator Base Class

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/general-setup.md

Configure the base OAuthenticator class with your OAuth2 application's redirect URL, client ID, and client secret. Ensure the redirect URL matches the one registered with your identity provider.

```python
# code for a jupyterhub_config.py file...
c.OAuthenticator.oauth_callback_url = "https://[your-domain]/hub/oauth_callback"
c.OAuthenticator.client_id = "[your oauth2 application id]"
c.OAuthenticator.client_secret = "[your oauth2 application secret]"
```

--------------------------------

### Configure Google Workspace Admin Impersonation

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/topic/google.md

Configure JupyterHub to impersonate a Google Workspace admin for retrieving group membership. Ensure the specified admin user has read-only access to users and groups.

```python
c.GoogleOAuthenticator.gsuite_administrator = {'example.com': 'admin-for-jupyter@example.com'}
```

```python
c.GoogleOAuthenticator.google_service_account_keys = {'example.com': '/etc/jupyterhub/service_account.json'}
```

```python
c.GoogleOAuthenticator.admin_google_groups = {'example.com': ['jupyterhub-admins']}
```

```python
c.GoogleOAuthenticator.allowed_google_groups = {'example.com': ['jupyterhub-users']}
```

--------------------------------

### Verify GitHub API Scopes

Source: https://github.com/jupyterhub/oauthenticator/blob/main/examples/auth_state/gist-nb.ipynb

Make a request to the GitHub API to verify the authenticated user and check the granted OAuth scopes. This helps ensure the token has the necessary permissions.

```python
r = s.get('https://api.github.com/user')
r.raise_for_status()
r.headers['X-OAuth-Scopes']
```

--------------------------------

### JupyterHub GitLab Authenticator Configuration

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/provider-specific-setup/providers/gitlab.md

Configure your `jupyterhub_config.py` to use GitLab as the authenticator and set the OAuth callback URL, client ID, and client secret.

```python
c.JupyterHub.authenticator_class = "gitlab"
c.OAuthenticator.oauth_callback_url = "https://[your-domain]/hub/oauth_callback"
c.OAuthenticator.client_id = "[your oauth2 application id]"
c.OAuthenticator.client_secret = "[your oauth2 application secret]"
```

--------------------------------

### Allow specific users and organizations with GitHubOAuthenticator

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/topic/allowing.md

This configuration allows specific users by username and any member of a specified organization. Users must meet at least one of these criteria to be granted access.

```python
c.GitHubOAuthenticator.allowed_users = {"mensah", "art"}
c.GitHubOAuthenticator.allowed_organizations = {"preservation"}
```

--------------------------------

### JupyterHub GitHub Configuration

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/provider-specific-setup/providers/github.md

Set the authenticator class and provide GitHub OAuth application credentials in your jupyterhub_config.py. Ensure the oauth_callback_url matches your GitHub application's settings.

```python
c.JupyterHub.authenticator_class = "github"
c.OAuthenticator.oauth_callback_url = "https://[your-domain]/hub/oauth_callback"
c.OAuthenticator.client_id = "[your oauth2 application id]"
c.OAuthenticator.client_secret = "[your oauth2 application secret]"
```

--------------------------------

### Skeleton of a Custom OAuthenticator Class

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/how-to/writing-an-oauthenticator.md

This is a basic template for creating a custom OAuthenticator subclass. You will need to implement the logic for handling OAuth requests and responses specific to your provider.

```python
from oauthenticator.generic import GenericOAuthenticator

class MyOAuthenticator(GenericOAuthenticator):
    async def authenticate(self, handler, data=None):
        # Your custom authentication logic here
        # This method is called when the user is redirected back to JupyterHub
        # after authenticating with the OAuth provider.
        # You will typically need to exchange the authorization code for an access token
        # and then fetch user information from the provider.
        pass

    async def pre_login_hook(self, handler, data):
        # Optional: Code to run before the user is redirected to the OAuth provider.
        pass

    async def post_login_hook(self, handler, data):
        # Optional: Code to run after the user has been authenticated by the OAuth provider
        # but before they are logged into JupyterHub.
        pass

    async def logout_hook(self, handler, completer):
        # Optional: Code to run when a user logs out of JupyterHub.
        pass

```

--------------------------------

### Configure Custom 403 HTML Template Path

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/how-to/custom-403.md

Specify the directory where JupyterHub should look for custom HTML templates, including a custom 403 error page. Ensure the specified path contains your custom template files.

```python
c.JupyterHub.template_paths = ["examples/templates"]
```

--------------------------------

### Set Custom 403 Message

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/how-to/custom-403.md

Configure a custom string message to display to unauthorized users. This message replaces the default error message.

```python
c.OAuthenticator.custom_403_message = "Your message for the user"
```

--------------------------------

### Configure JupyterHub for AWS Cognito

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/provider-specific-setup/providers/generic.md

Set up JupyterHub to use AWS Cognito as the authentication provider. Ensure your AWS Cognito user pool and OAuth2 application are configured.

```python
c.JupyterHub.authenticator_class = "generic-oauth"
c.OAuthenticator.oauth_callback_url = "https://[your-host]/hub/oauth_callback"
c.OAuthenticator.client_id = "[your oauth2 application id]"
c.OAuthenticator.client_secret = "[your oauth2 application secret]"

c.GenericOAuthenticator.login_service = "AWS Cognito"
c.GenericOAuthenticator.username_claim = "login"

c.GenericOAuthenticator.authorize_url = "https://your-AWSCognito-domain/oauth2/authorize"
c.GenericOAuthenticator.token_url = "https://your-AWSCognito-domain/oauth2/token"
c.GenericOAuthenticator.userdata_url = "https://your-AWSCognito-domain/oauth2/userInfo"
```

--------------------------------

### Enable Auth State

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/how-to/refresh.md

Enable the 'auth state' feature in your Authenticator configuration. This is typically enabled by default in the JupyterHub Helm chart. Remember to also set the $JUPYTERHUB_CRYPT_KEY environment variable to a 32-byte string.

```python
c.Authenticator.enable_auth_state = True
# also set $JUPYTERHUB_CRYPT_KEY env to 32-byte string
```

--------------------------------

### Retrieve Fresh Access Token from JupyterHub API

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/how-to/refresh.md

Use this Python code to fetch the user model from the JupyterHub API, which includes a fresh access token in the `auth_state` field. This is useful when you need an up-to-date token for user-specific operations.

```python
import os
import requests

hub_token = os.environ["JUPYTERHUB_API_TOKEN"]
hub_api_url = os.environ["JUPYTERHUB_API_URL"]
user_url = hub_api_url + "/user"

r = requests.get(user_url, headers={"Authorization": f"Bearer {hub_token}"})
user = r.json()
access_token = user["auth_state"]["access_token"]
```

--------------------------------

### Configure JupyterHub for ORCID iD

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/provider-specific-setup/providers/generic.md

Set up JupyterHub to use ORCID iD for authentication. The `username_claim` is set to 'sub' to use the ORCID iD as the JupyterHub username. Note that the authenticator will lowercase the username by default.

```python
c.JupyterHub.authenticator_class = "generic-oauth"

# Fill these in with your values
c.GenericOAuthenticator.oauth_callback_url = "YOUR CALLBACK URL"
c.GenericOAuthenticator.client_id = "YOUR CLIENT ID"
c.GenericOAuthenticator.client_secret = "YOUR CLIENT SECRET"

c.GenericOAuthenticator.login_service = "ORCID iD" # Text of login button
c.GenericOAuthenticator.authorize_url = "https://orcid.org/oauth/authorize"
c.GenericOAuthenticator.token_url = "https://orcid.org/oauth/token"
c.GenericOAuthenticator.scope = ["/authenticate", "openid"]
c.GenericOAuthenticator.userdata_url = "https://orcid.org/oauth/userinfo"
c.GenericOAuthenticator.username_claim = "sub"
```

--------------------------------

### Configure Allowed and Admin Globus Groups

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/provider-specific-setup/providers/globus.md

Specify UUIDs for Globus Groups to define allowed users and administrators. When these settings are active, the Globus Groups API scope is automatically included.

```python
# Groups of allowed users
c.GlobusOAuthenticator.allowed_globus_groups = {
    'd11abe71-5132-4c04-a4ad-50926885dc8c',
    '21c6bc5d-fc12-4f60-b999-76766cd596c2',
}
# Admin users
c.GlobusOAuthenticator.admin_globus_groups = {'3f1f85c4-f084-4173-9efb-7c7e0b44291a'}
```

--------------------------------

### Override GitLab Scope List

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/topic/gitlab.md

Use this configuration to specify custom scopes for GitLab authentication. Ensure the scopes you request are implemented in your GitLab version.

```python
c.GitLabOAuthenticator.scope = ['read_user']
```

--------------------------------

### Customize User Refresh Behavior with a Hook

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/how-to/refresh.md

Implement a custom `refresh_user_hook` in JupyterHub to control how user authentication states are refreshed. This hook allows you to define specific logic for different user types, such as treating infrastructure users as always fresh.

```python
infrastructure_users = {"health-check-user"}

def refresh_user_hook(authenticator, user, auth_state):
    if user.name in infrastructure_users:
        # if this is an infrastructure user,
        # refresh_user doesn't make sense
        # consider it always fresh
        return True
    # for all other users, refresh as usual
    return None

c.OAuthenticator.refresh_user_hook = refresh_user_hook
```

--------------------------------

### Restrict Users to a Specific Identity Provider

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/tutorials/provider-specific-setup/providers/globus.md

Configure GlobusOAuthenticator to restrict user logins to a specific identity provider domain.

```python
c.GlobusOAuthenticator.identity_provider = "uchicago.edu"
```

--------------------------------

### Grant Auth State Read Access for Roles

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/how-to/refresh.md

Configure JupyterHub roles to grant the server token access to read user authentication state. This is necessary for refreshing access tokens, as `auth_state` stores this information. Ensure the `admin:auth_state!user` scope is added to both 'user' and 'server' roles.

```python
c.JupyterHub.load_roles = [
    {
        "name": "user",
        "scopes": [
            "self",
            "admin:auth_state!user",
        ],
    },
    {
        "name": "server",
        "scopes": [
            "users:activity!user",
            "access:servers!server",
            "admin:auth_state!user",
        ],
    },
]
```

--------------------------------

### Disable Automatic User Refresh in JupyterHub

Source: https://github.com/jupyterhub/oauthenticator/blob/main/docs/source/how-to/refresh.md

Set `c.Authenticator.auth_refresh_age = 0` in your JupyterHub configuration to disable the automatic refresh of user authentication state. This reverts to the behavior of older OAuthenticator versions where `refresh_user` was called but did nothing.

```python
c.Authenticator.auth_refresh_age = 0
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.