Merge pull request #657 from matthewwiese/main

Add ORCID iD example configuration

docs/source/how-to/writing-an-oauthenticator.md

@@ -4,6 +4,10 @@ There are two ways to write your own OAuthenticator.
 
 ## Using GenericOAuthenticator
 
+```{note}
+Before writing your own config, [](tutorials:provider-specific:generic) may already have an example for your service.
+```
+
 The first and simplest is to use the `oauthenticator.generic.GenericOAuthenticator` class
 and configuration to set the necessary configuration variables.
 
@@ -28,9 +32,6 @@ c.GenericOAuthenticator.token_url = 'url-retrieving-access-token-oauth-completio
 c.GenericOAuthenticator.username_claim = 'username-key-for-USERDATA-URL'
 ```
 
-Checkout [](tutorials:provider-specific:generic:moodle) and [](tutorials:provider-specific:generic:yandex) for how to configure
-GenericOAuthenticator for Moodle and Yandex.
-
 ## Writing your own OAuthenticator class
 
 If you want more advanced features and customization beyond the basics of OAuth,

docs/source/tutorials/provider-specific-setup/providers/generic.md

@@ -147,3 +147,42 @@ c.GenericOAuthenticator.authorize_url = "https://your-AWSCognito-domain/oauth2/a
 c.GenericOAuthenticator.token_url = "https://your-AWSCognito-domain/oauth2/token"
 c.GenericOAuthenticator.userdata_url = "https://your-AWSCognito-domain/oauth2/userInfo"
 ```
+
+## Setup for ORCID iD
+
+```{note}
+The `GenericOAuthenticator` will by default lowercase your username. For example, an ORCID iD of `0000-0002-9079-593X` will produce a JupyterHub username of `0000-0002-9079-593x`.
+```
+
+Follow the ORCID [API Tutorial](https://info.orcid.org/documentation/api-tutorials/api-tutorial-get-and-authenticated-orcid-id/) to create an application via the Developer Tools submenu after clicking on your name in the top right of the page.
+
+Edit your `jupyterhub_config.py` with the following:
+
+```python
+c.JupyterHub.authenticator_class = "generic"
+
+# 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"
+```
+
+The above `username_claim` value selects the ORCID iD from the JSON response as the individual's JupyterHub username. An example response is below:
+
+```json
+{
+  "sub": "0000-0002-2601-8132",
+  "name": "Credit Name",
+  "family_name": "Jones",
+  "given_name": "Tom"
+}
+```
+
+Please refer to the [Authorization Code Flow](https://github.com/ORCID/ORCID-Source/blob/main/orcid-web/ORCID_AUTH_WITH_OPENID_CONNECT.md#authorization-code-flow) section of the ORCID documentation for more information.