diff --git a/docs/advanced/oauth2_settings.md b/docs/advanced/oauth2_settings.md index 73e506ce..9f6f8b2d 100644 --- a/docs/advanced/oauth2_settings.md +++ b/docs/advanced/oauth2_settings.md @@ -1,6 +1,8 @@ # How to use OAuth -This document aims to instruct how to setup OAuth for doccano. doccano now supports social login via GitHub and Active Directory by [#75](https://github.com/doccano/doccano/pull/75). In this document, we show GitHub OAuth as an example. +This document aims to instruct how to setup OAuth for doccano. doccano now supports social login via GitHub and Active Directory by [#75](https://github.com/doccano/doccano/pull/75). In this document, we show GitHub OAuth as an example. + +# GitHub ## Create OAuth App @@ -35,3 +37,55 @@ python manage.py runserver Go to login page: ![image](../images/oauth/login_page.png) + +# Okta + +Create an Okta web app in the Okta developer portal and get the key and secret from the app details. + +## OAuth2 + +If you want to use OAuth2, set these environment variables. + +```bash +export OAUTH_OKTA_OAUTH2_KEY=YOUR_CLIENT_ID +export OAUTH_OKTA_OAUTH2_SECRET=YOUR_CLIENT_SECRET +export OAUTH_OKTA_OAUTH2_API_URL=YOUR_BASE_URL +``` + +In the app settings, please set the redirect URI to `{DOCCANO_URL}/social/complete/okta-oauth2/`. For example, if you are serving Doccano at `https://example.com`, the redirect URI should be `https://example.com/social/complete/okta-oauth2/`. If using a local installation being served at port 8000, set the redirect URI to `http://127.0.0.1:8000/social/complete/okta-oauth2/`. + +Okta Application setup: +![image](../images/oauth/okta_oauth_app.png) + +Optionally, if you want to assign Doccano super users from Okta users, you can use Okta groups to assign them the policy. Ensure your Okta [authorization server can serve `groups` claims](https://developer.okta.com/docs/guides/customize-tokens-returned-from-okta/add-groups-claim-org-as/) and set the environment variable `OKTA_OAUTH2_ADMIN_GROUP_NAME`. + +```bash +export OKTA_OAUTH2_ADMIN_GROUP_NAME=SUPERUSER_OKTA_GROUP_NAME +``` + +## OpenIDConnect + +If you want to use OpenIDConnect, set these environment variables. + +```bash +export OAUTH_OKTA_OPENIDCONNECT_KEY=YOUR_CLIENT_ID +export OAUTH_OKTA_OPENIDCONNECT_SECRET=YOUR_CLIENT_SECRET +export OAUTH_OKTA_OPENIDCONNECT_API_URL=YOUR_BASE_URL +``` + +In the app settings, please set the redirect URI to your app domain `/social/complete/okta-openidconnect/`. For example, if you are serving Doccano at `https://example.com`, the redirect URI should be `https://example.com/social/complete/okta-openidconnect/`. If using a local installation being served at port 8000, set the redirect URI to `http://127.0.0.1:8000/social/complete/okta-openidconnect/`. + +Optionally, if you want to assign Doccano super users from Okta users, you can use Okta groups to assign them the policy. Ensure your Okta [authorization server can serve `groups` claims](https://developer.okta.com/docs/guides/customize-tokens-returned-from-okta/add-groups-claim-org-as/) and set the environment variable `OKTA_OPENIDCONNECT_ADMIN_GROUP_NAME`. + +```bash +export OKTA_OPENIDCONNECT_ADMIN_GROUP_NAME=SUPERUSER_OKTA_GROUP_NAME +``` + +## Run Server + +```bash +python manage.py runserver +``` + +If everything has been setup correctly, you should see a login page like the one below with an option to login using Okta. +![image](../images/oauth/okta_oauth_login_page.png) diff --git a/docs/images/oauth/okta_oauth_app.png b/docs/images/oauth/okta_oauth_app.png new file mode 100644 index 00000000..55a4198e Binary files /dev/null and b/docs/images/oauth/okta_oauth_app.png differ diff --git a/docs/images/oauth/okta_oauth_login_page.png b/docs/images/oauth/okta_oauth_login_page.png new file mode 100644 index 00000000..fbf4f8ec Binary files /dev/null and b/docs/images/oauth/okta_oauth_login_page.png differ