<commit_before># OAuthenticator

OAuth + JupyterHub Authenticator = OAuthenticator

OAuthenticator currently supports the following authentication services:

- [Auth0](oauthenticator/auth0.py)
- [Bitbucket](oauthenticator/bitbucket.py)
- [CILogon](oauthenticator/cilogon.py)
- [GitHub](#github-setup)
- [GitLab](#gitlab-setup)
- [Globus](#globus-setup)
- [Google](#google-setup)
- [MediaWiki](oauthenticator/mediawiki.py)
- [Okpy](#okpyauthenticator)
- [OpenShift](#openshift-setup)

A [generic implementation](oauthenticator/generic.py), which you can use with
any provider, is also available.

## Examples

For an example docker image using OAuthenticator, see the [example](example)
directory.

[Another example](https://github.com/jupyterhub/dockerspawner/tree/master/examples/oauth)
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:

```python
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**:

```bash
$OAUTH_CALLBACK_URL
$OAUTH_CLIENT_ID
$OAUTH_CLIENT_SECRET
```

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

```python
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'
```


## GitHub Setup

First, you'll need to create a [GitHub OAuth
application](https://github.com/settings/applications/new).

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.

GitHub allows expanded capabilities by
adding [GitHub-Specific Scopes](github_scope.md) to the requested token.

## GitLab Setup

First, you'll need to create a [GitLab OAuth
application](http://docs.gitlab.com/ce/integration/oauth_provider.html).


Then, add the following to your `jupyterhub_config.py` file:<commit_msg>added GITHUB_HTTP<commit_after># OAuthenticator

OAuth + JupyterHub Authenticator = OAuthenticator

OAuthenticator currently supports the following authentication services:

- [Auth0](oauthenticator/auth0.py)
- [Bitbucket](oauthenticator/bitbucket.py)
- [CILogon](oauthenticator/cilogon.py)
- [GitHub](#github-setup)
- [GitLab](#gitlab-setup)
- [Globus](#globus-setup)
- [Google](#google-setup)
- [MediaWiki](oauthenticator/mediawiki.py)
- [Okpy](#okpyauthenticator)
- [OpenShift](#openshift-setup)

A [generic implementation](oauthenticator/generic.py), which you can use with
any provider, is also available.

## Examples

For an example docker image using OAuthenticator, see the [example](example)
directory.

[Another example](https://github.com/jupyterhub/dockerspawner/tree/master/examples/oauth)
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:

```python
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**:

```bash
$OAUTH_CALLBACK_URL
$OAUTH_CLIENT_ID
$OAUTH_CLIENT_SECRET
```

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

```python
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'
```


## GitHub Setup

First, you'll need to create a [GitHub OAuth
application](https://github.com/settings/applications/new).

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](github_scope.md) to the requested token.

## GitLab Setup

First, you'll need to create a [GitLab OAuth
application](http://docs.gitlab.com/ce/integration/oauth_provider.html).


Then, add the following to your `jupyterhub_config.py` file:
{'fraction_non_alphanumeric': 0.08992805755395683, 'fraction_numerical': 0.002302158273381295, 'mean_word_length': 5.33637192342753, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3033151', 'n_tokens_mistral': 2227, 'n_tokens_neox': 2085, 'n_words': 691}