You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

529 lines
20 KiB

<!doctype html>
<html lang="en" class="no-js">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="description" content="A Text Annotation tool for Humans">
<link rel="canonical" href="https://doccano.github.io/doccano/advanced/oauth2_settings/">
<meta name="author" content="Hiroki Nakayama">
<link rel="shortcut icon" href="../../assets/images/favicon.png">
<meta name="generator" content="mkdocs-1.1.2, mkdocs-material-6.1.0">
<title>OAuth2 settings - doccano</title>
<link rel="stylesheet" href="../../assets/stylesheets/main.bc7e593a.min.css">
<link rel="stylesheet" href="../../assets/stylesheets/palette.ab28b872.min.css">
<meta name="theme-color" content="#00bdd6">
<link href="https://fonts.gstatic.com" rel="preconnect" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,400i,700%7CRoboto+Mono&display=fallback">
<style>body,input{font-family:"Roboto",-apple-system,BlinkMacSystemFont,Helvetica,Arial,sans-serif}code,kbd,pre{font-family:"Roboto Mono",SFMono-Regular,Consolas,Menlo,monospace}</style>
</head>
<body dir="ltr" data-md-color-scheme="" data-md-color-primary="cyan" data-md-color-accent="cyan">
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
<label class="md-overlay" for="__drawer"></label>
<div data-md-component="skip">
<a href="#how-to-use-oauth" class="md-skip">
Skip to content
</a>
</div>
<div data-md-component="announce">
</div>
<header class="md-header" data-md-component="header">
<nav class="md-header-nav md-grid" aria-label="Header">
<a href="https://doccano.github.io/doccano/" title="doccano" class="md-header-nav__button md-logo" aria-label="doccano">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 003-3 3 3 0 00-3-3 3 3 0 00-3 3 3 3 0 003 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54z"/></svg>
</a>
<label class="md-header-nav__button md-icon" for="__drawer">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2z"/></svg>
</label>
<div class="md-header-nav__title" data-md-component="header-title">
<div class="md-header-nav__ellipsis">
<span class="md-header-nav__topic md-ellipsis">
doccano
</span>
<span class="md-header-nav__topic md-ellipsis">
OAuth2 settings
</span>
</div>
</div>
<div class="md-header-nav__source">
<a href="https://github.com/doccano/doccano/" title="Go to repository" class="md-source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><path d="M439.55 236.05L244 40.45a28.87 28.87 0 00-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 01-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 000 40.81l195.61 195.6a28.86 28.86 0 0040.8 0l194.69-194.69a28.86 28.86 0 000-40.81z"/></svg>
</div>
<div class="md-source__repository">
doccano/doccano
</div>
</a>
</div>
</nav>
</header>
<div class="md-container" data-md-component="container">
<main class="md-main" data-md-component="main">
<div class="md-main__inner md-grid">
<div class="md-sidebar md-sidebar--primary" data-md-component="navigation">
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
<label class="md-nav__title" for="__drawer">
<a href="https://doccano.github.io/doccano/" title="doccano" class="md-nav__button md-logo" aria-label="doccano">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 003-3 3 3 0 00-3-3 3 3 0 00-3 3 3 3 0 003 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54z"/></svg>
</a>
doccano
</label>
<div class="md-nav__source">
<a href="https://github.com/doccano/doccano/" title="Go to repository" class="md-source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><path d="M439.55 236.05L244 40.45a28.87 28.87 0 00-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 01-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 000 40.81l195.61 195.6a28.86 28.86 0 0040.8 0l194.69-194.69a28.86 28.86 0 000-40.81z"/></svg>
</div>
<div class="md-source__repository">
doccano/doccano
</div>
</a>
</div>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../.." class="md-nav__link">
Get started
</a>
</li>
<li class="md-nav__item">
<a href="../../install_and_upgrade_doccano/" class="md-nav__link">
Install and upgrade doccano
</a>
</li>
<li class="md-nav__item">
<a href="../../tutorial/" class="md-nav__link">
Tutorial
</a>
</li>
<li class="md-nav__item">
<a href="../../setup_cloud_storage/" class="md-nav__link">
Setup cloud storage
</a>
</li>
<li class="md-nav__item md-nav__item--active md-nav__item--nested">
<input class="md-nav__toggle md-toggle" data-md-toggle="nav-5" type="checkbox" id="nav-5" checked>
<label class="md-nav__link" for="nav-5">
Advanced
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" aria-label="Advanced" data-md-level="1">
<label class="md-nav__title" for="nav-5">
<span class="md-nav__icon md-icon"></span>
Advanced
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../aws_https_settings/" class="md-nav__link">
AWS HTTPS settings
</a>
</li>
<li class="md-nav__item md-nav__item--active">
<input class="md-nav__toggle md-toggle" data-md-toggle="toc" type="checkbox" id="__toc">
<a href="./" class="md-nav__link md-nav__link--active">
OAuth2 settings
</a>
</li>
<li class="md-nav__item">
<a href="../auto_labelling_config/" class="md-nav__link">
Auto labeling settings
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../../developer_guide/" class="md-nav__link">
Developer guide
</a>
</li>
<li class="md-nav__item">
<a href="../../faq/" class="md-nav__link">
FAQ
</a>
</li>
<li class="md-nav__item">
<a href="../../CODE_OF_CONDUCT/" class="md-nav__link">
Code of conduct
</a>
</li>
<li class="md-nav__item">
<a href="../../roadmap/" class="md-nav__link">
Roadmap
</a>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-sidebar md-sidebar--secondary" data-md-component="toc">
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
</nav>
</div>
</div>
</div>
<div class="md-content">
<article class="md-content__inner md-typeset">
<a href="https://github.com/doccano/doccano/edit/master/docs/advanced/oauth2_settings.md" title="Edit this page" class="md-content__button md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20.71 7.04c.39-.39.39-1.04 0-1.41l-2.34-2.34c-.37-.39-1.02-.39-1.41 0l-1.84 1.83 3.75 3.75M3 17.25V21h3.75L17.81 9.93l-3.75-3.75L3 17.25z"/></svg>
</a>
<h1 id="how-to-use-oauth">How to use OAuth</h1>
<p>This document aims to instruct how to setup OAuth for doccano. doccano now supports social login via GitHub and Active Directory by <a href="https://github.com/doccano/doccano/pull/75">#75</a>. In this document, we show GitHub OAuth as an example.</p>
<h1 id="github">GitHub</h1>
<h2 id="create-oauth-app">Create OAuth App</h2>
<ol>
<li>In the upper-right corner of GitHub, click your profile photo, then click <strong>Settings</strong>.</li>
<li>In the left sidebar, click <strong>Developer settings</strong>.</li>
<li>In the left sidebar, click <strong>OAuth Apps</strong>.</li>
<li>Click <strong>New OAuth App</strong>.</li>
<li>In "Application name", type the name of your app.</li>
<li>In "Homepage URL", type the full URL to your app's website.</li>
<li>In "Authorization callback URL", type the callback URL(e.g. <a href="https://example.com/social/complete/github/">https://example.com/social/complete/github/</a>) of your app.</li>
<li>Click Register application.</li>
</ol>
<h2 id="set-enviromental-variables">Set enviromental variables</h2>
<p>Once the application is registered, your app's <code>Client ID</code> and <code>Client Secret</code> will be displayed on the following page:
<img alt="image" src="../../images/oauth/oauth_apps.png" /></p>
<ol>
<li>Copy the <code>Client ID</code> and <code>Client Secret</code> from the Developer Applications of your app on GitHub.</li>
<li>Set the <code>Client ID</code> and <code>Client Secret</code> to enviromental variables:</li>
</ol>
<pre><code class="language-bash">export OAUTH_GITHUB_KEY=YOUR_CLIENT_ID
export OAUTH_GITHUB_SECRET=YOUR_CLIENT_SECRET
</code></pre>
<h2 id="run-server">Run server</h2>
<pre><code class="language-bash">python manage.py runserver
</code></pre>
<p>Go to login page:</p>
<p><img alt="image" src="../../images/oauth/login_page.png" /></p>
<h1 id="okta">Okta</h1>
<p>Create an Okta web app in the Okta developer portal and get the key and secret from the app details.</p>
<h2 id="oauth2">OAuth2</h2>
<p>If you want to use OAuth2, set these environment variables.</p>
<pre><code class="language-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
</code></pre>
<p>In the app settings, please set the redirect URI to <code>{DOCCANO_URL}/social/complete/okta-oauth2/</code>. For example, if you are serving Doccano at <code>https://example.com</code>, the redirect URI should be <code>https://example.com/social/complete/okta-oauth2/</code>. If using a local installation being served at port 8000, set the redirect URI to <code>http://127.0.0.1:8000/social/complete/okta-oauth2/</code>.</p>
<p>Okta Application setup:
<img alt="image" src="../../images/oauth/okta_oauth_app.png" /></p>
<p>Optionally, if you want to assign Doccano super users from Okta users, you can use Okta groups to assign them the policy. This will also assign the users the staff role, allowing them to access the Django admin page and app. Ensure your Okta <a href="https://developer.okta.com/docs/guides/customize-tokens-returned-from-okta/add-groups-claim-org-as/">authorization server can serve <code>groups</code> claims</a> and set the environment variable <code>OKTA_OAUTH2_ADMIN_GROUP_NAME</code>.</p>
<pre><code class="language-bash">export OKTA_OAUTH2_ADMIN_GROUP_NAME=SUPERUSER_OKTA_GROUP_NAME
</code></pre>
<h2 id="openidconnect">OpenIDConnect</h2>
<p>If you want to use OpenIDConnect, set these environment variables.</p>
<pre><code class="language-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
</code></pre>
<p>In the app settings, please set the redirect URI to your app domain <code>/social/complete/okta-openidconnect/</code>. For example, if you are serving Doccano at <code>https://example.com</code>, the redirect URI should be <code>https://example.com/social/complete/okta-openidconnect/</code>. If using a local installation being served at port 8000, set the redirect URI to <code>http://127.0.0.1:8000/social/complete/okta-openidconnect/</code>.</p>
<p>Optionally, if you want to assign Doccano super users from Okta users, you can use Okta groups to assign them the policy. This will also assign the users the staff role, allowing them to access the Django admin page and app. Ensure your Okta <a href="https://developer.okta.com/docs/guides/customize-tokens-returned-from-okta/add-groups-claim-org-as/">authorization server can serve <code>groups</code> claims</a> and set the environment variable <code>OKTA_OPENIDCONNECT_ADMIN_GROUP_NAME</code>.</p>
<pre><code class="language-bash">export OKTA_OPENIDCONNECT_ADMIN_GROUP_NAME=SUPERUSER_OKTA_GROUP_NAME
</code></pre>
<h2 id="run-server_1">Run Server</h2>
<pre><code class="language-bash">python manage.py runserver
</code></pre>
<p>If everything has been setup correctly, you should see a login page like the one below with an option to login using Okta.
<img alt="image" src="../../images/oauth/okta_oauth_login_page.png" /></p>
</article>
</div>
</div>
</main>
<footer class="md-footer">
<div class="md-footer-nav">
<nav class="md-footer-nav__inner md-grid" aria-label="Footer">
<a href="../aws_https_settings/" class="md-footer-nav__link md-footer-nav__link--prev" rel="prev">
<div class="md-footer-nav__button md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12z"/></svg>
</div>
<div class="md-footer-nav__title">
<div class="md-ellipsis">
<span class="md-footer-nav__direction">
Previous
</span>
AWS HTTPS settings
</div>
</div>
</a>
<a href="../auto_labelling_config/" class="md-footer-nav__link md-footer-nav__link--next" rel="next">
<div class="md-footer-nav__title">
<div class="md-ellipsis">
<span class="md-footer-nav__direction">
Next
</span>
Auto labeling settings
</div>
</div>
<div class="md-footer-nav__button md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11H4z"/></svg>
</div>
</a>
</nav>
</div>
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
<div class="md-footer-copyright">
<div class="md-footer-copyright__highlight">
Copyright &copy; 2018 - 2019 Hiroki Nakayama
</div>
Made with
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
Material for MkDocs
</a>
</div>
<div class="md-footer-social">
<a href="https://github.com/Hironsan" target="_blank" rel="noopener" title="github.com" class="md-footer-social__link">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 496 512"><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg>
</a>
<a href="https://twitter.com/Hironsan13" target="_blank" rel="noopener" title="twitter.com" class="md-footer-social__link">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path d="M459.37 151.716c.325 4.548.325 9.097.325 13.645 0 138.72-105.583 298.558-298.558 298.558-59.452 0-114.68-17.219-161.137-47.106 8.447.974 16.568 1.299 25.34 1.299 49.055 0 94.213-16.568 130.274-44.832-46.132-.975-84.792-31.188-98.112-72.772 6.498.974 12.995 1.624 19.818 1.624 9.421 0 18.843-1.3 27.614-3.573-48.081-9.747-84.143-51.98-84.143-102.985v-1.299c13.969 7.797 30.214 12.67 47.431 13.319-28.264-18.843-46.781-51.005-46.781-87.391 0-19.492 5.197-37.36 14.294-52.954 51.655 63.675 129.3 105.258 216.365 109.807-1.624-7.797-2.599-15.918-2.599-24.04 0-57.828 46.782-104.934 104.934-104.934 30.213 0 57.502 12.67 76.67 33.137 23.715-4.548 46.456-13.32 66.599-25.34-7.798 24.366-24.366 44.833-46.132 57.827 21.117-2.273 41.584-8.122 60.426-16.243-14.292 20.791-32.161 39.308-52.628 54.253z"/></svg>
</a>
</div>
</div>
</div>
</footer>
</div>
<script src="../../assets/javascripts/vendor.6a3d08fc.min.js"></script>
<script src="../../assets/javascripts/bundle.71201edf.min.js"></script><script id="__lang" type="application/json">{"clipboard.copy": "Copy to clipboard", "clipboard.copied": "Copied to clipboard", "search.config.lang": "en", "search.config.pipeline": "trimmer, stopWordFilter", "search.config.separator": "[\\s\\-]+", "search.placeholder": "Search", "search.result.placeholder": "Type to start searching", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.term.missing": "Missing"}</script>
<script>
app = initialize({
base: "../..",
features: [],
search: Object.assign({
worker: "../../assets/javascripts/worker/search.4ac00218.min.js"
}, typeof search !== "undefined" && search)
})
</script>
</body>
</html>