496 lines
17 KiB
HTML
496 lines
17 KiB
HTML
<!DOCTYPE html>
|
||
|
||
<html lang="en-US">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta http-equiv="X-UA-Compatible" content="IE=Edge">
|
||
|
||
<title>OAuth - Gancio</title>
|
||
|
||
|
||
|
||
<link rel="shortcut icon" href="https://gancio.org/favicon.ico" type="image/x-icon">
|
||
<link rel="stylesheet" href="https://gancio.org/assets/css/just-the-docs.css">
|
||
<link rel="stylesheet" href="https://gancio.org/assets/css/style.css">
|
||
<link rel="stylesheet" href="https://gancio.org/assets/css/premonition.css">
|
||
<link rel="stylesheet" href="https://gancio.org/assets/css/fa.min.css">
|
||
|
||
|
||
<script type="text/javascript" src="https://gancio.org/assets/js/vendor/lunr.min.js"></script>
|
||
|
||
|
||
<script type="text/javascript" src="https://gancio.org/assets/js/just-the-docs.js"></script>
|
||
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
|
||
<script src="https://gancio.org/assets/js/jquery-3.3.1.min.js"></script>
|
||
<link rel="stylesheet" href="https://gancio.org/assets/css/jquery.fancybox.min.css"/>
|
||
<script src="https://gancio.org/assets/js/jquery.fancybox.min.js"></script>
|
||
|
||
<!-- Begin Jekyll SEO tag v2.6.1 -->
|
||
<title>OAuth | Gancio</title>
|
||
<meta name="generator" content="Jekyll v3.8.6" />
|
||
<meta property="og:title" content="OAuth" />
|
||
<meta property="og:locale" content="en_US" />
|
||
<meta name="description" content="A shared agenda for local communities with AP support" />
|
||
<meta property="og:description" content="A shared agenda for local communities with AP support" />
|
||
<link rel="canonical" href="https://gancio.org/dev/oauth" />
|
||
<meta property="og:url" content="https://gancio.org/dev/oauth" />
|
||
<meta property="og:site_name" content="Gancio" />
|
||
<script type="application/ld+json">
|
||
{"@type":"WebPage","headline":"OAuth","url":"https://gancio.org/dev/oauth","description":"A shared agenda for local communities with AP support","@context":"https://schema.org"}</script>
|
||
<!-- End Jekyll SEO tag -->
|
||
|
||
</head>
|
||
|
||
<body>
|
||
|
||
<div class="page-wrap">
|
||
<div class="side-bar">
|
||
<a href="https://gancio.org/" class="site-title fs-6 lh-tight">Gancio</a>
|
||
<span class="fs-3"><button class="js-main-nav-trigger navigation-list-toggle btn btn-outline" type="button" data-text-toggle="Hide">Menu</button></span>
|
||
<div class="navigation main-nav js-main-nav">
|
||
<nav role="navigation" aria-label="Main navigation">
|
||
<ul class="navigation-list">
|
||
|
||
|
||
|
||
|
||
<li class="navigation-list-item active">
|
||
|
||
<a href="https://gancio.org/404.html" class="navigation-list-link"></a>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="navigation-list-item">
|
||
|
||
<a href="https://gancio.org/" class="navigation-list-link">Home</a>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="navigation-list-item">
|
||
|
||
<a href="https://gancio.org/install" class="navigation-list-link">Install</a>
|
||
|
||
|
||
<ul class="navigation-list-child-list ">
|
||
|
||
|
||
|
||
|
||
<li class="navigation-list-item ">
|
||
|
||
<a href="https://gancio.org/install/debian" class="navigation-list-link">Debian</a>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
<li class="navigation-list-item ">
|
||
|
||
<a href="https://gancio.org/install/docker" class="navigation-list-link">Docker</a>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
<li class="navigation-list-item ">
|
||
|
||
<a href="https://gancio.org/install/nginx" class="navigation-list-link">Nginx</a>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
</ul>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
<li class="navigation-list-item">
|
||
|
||
<a href="https://gancio.org/config" class="navigation-list-link">Configuration</a>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="navigation-list-item active">
|
||
|
||
<a href="https://gancio.org/dev" class="navigation-list-link">Hacking</a>
|
||
|
||
|
||
<ul class="navigation-list-child-list ">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="navigation-list-item ">
|
||
|
||
<a href="https://gancio.org/dev/structure" class="navigation-list-link">Project Structure</a>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="navigation-list-item active">
|
||
|
||
<a href="https://gancio.org/dev/oauth" class="navigation-list-link active">OAuth</a>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="navigation-list-item ">
|
||
|
||
<a href="https://gancio.org/dev/locales" class="navigation-list-link">Internationalization</a>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
</ul>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
<li class="navigation-list-item">
|
||
|
||
<a href="https://gancio.org/instances" class="navigation-list-link">Instances</a>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="navigation-list-item">
|
||
|
||
<a href="https://gancio.org/about" class="navigation-list-link">About</a>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
<li class="navigation-list-item">
|
||
|
||
<a href="https://gancio.org/contacts" class="navigation-list-link">Contacts</a>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
<li class="navigation-list-item">
|
||
|
||
<a href="https://gancio.org/federation" class="navigation-list-link">Federation</a>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
<li class="navigation-list-item">
|
||
|
||
<a href="https://gancio.org/changelog" class="navigation-list-link">Changelog</a>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</div>
|
||
<footer role="contentinfo" class="site-footer">
|
||
<p class="text-small text-grey-dk-000 mb-0">This site uses <a href="https://github.com/pmarsceill/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll.</p>
|
||
</footer>
|
||
</div>
|
||
<div class="main-content-wrap js-main-content" tabindex="0">
|
||
<div class="page-header">
|
||
<div class="main-content">
|
||
|
||
<div class="search js-search">
|
||
<div class="search-input-wrap">
|
||
<input type="text" class="js-search-input search-input" tabindex="0" placeholder="Search Gancio" aria-label="Search Gancio" autocomplete="off">
|
||
<svg width="14" height="14" viewBox="0 0 28 28" xmlns="http://www.w3.org/2000/svg" class="search-icon"><title>Search</title><g fill-rule="nonzero"><path d="M17.332 20.735c-5.537 0-10-4.6-10-10.247 0-5.646 4.463-10.247 10-10.247 5.536 0 10 4.601 10 10.247s-4.464 10.247-10 10.247zm0-4c3.3 0 6-2.783 6-6.247 0-3.463-2.7-6.247-6-6.247s-6 2.784-6 6.247c0 3.464 2.7 6.247 6 6.247z"/><path d="M11.672 13.791L.192 25.271 3.02 28.1 14.5 16.62z"/></g></svg>
|
||
</div>
|
||
<div class="js-search-results search-results-wrap"></div>
|
||
</div>
|
||
|
||
|
||
<ul class="list-style-none text-small mt-md-1 mb-md-1 pb-4 pb-md-0 js-aux-nav aux-nav">
|
||
|
||
<li class="d-inline-block my-0 mr-2"><a href="https://blog.gancio.org">Blog</a></li>
|
||
|
||
<li class="d-inline-block my-0 mr-2"><a href="https://framagit.org/les/gancio">Source</a></li>
|
||
|
||
<li class="d-inline-block my-0 mr-2"><a href="https://socialhub.activitypub.rocks/c/software/gancio">Forum</a></li>
|
||
|
||
<li class="d-inline-block my-0"><a href="https://mastodon.cisti.org/@gancio">Mastodon</a></li>
|
||
|
||
</ul>
|
||
|
||
</div>
|
||
</div>
|
||
<div class="main-content">
|
||
|
||
|
||
<nav class="breadcrumb-nav">
|
||
<ol class="breadcrumb-nav-list">
|
||
|
||
<li class="breadcrumb-nav-list-item"><a href="https://gancio.org/dev">Hacking</a></li>
|
||
|
||
<li class="breadcrumb-nav-list-item"><span>OAuth</span></li>
|
||
</ol>
|
||
</nav>
|
||
|
||
|
||
<div id="main-content" class="page-content" role="main">
|
||
<div class="premonition error"><div class="fa fa-exclamation-triangle"></div><div class="content"><p class="header">BETA FEATURE</p><p>Expect bad behavior and open <a href="https://framagit.org/les/gancio/issues">issues</a></p>
|
||
|
||
|
||
</div></div>
|
||
<h2 class="no_toc" id="oauth">OAuth</h2>
|
||
<p>An open standard for token-based authentication and authorization on the Internet.</p>
|
||
|
||
<p>Gancio supports OAuth 2.0, an authorization framework described in <a href="https://tools.ietf.org/html/rfc6749">RFC 6749</a> that allows third-party applications to obtain limited access to an HTTP service on behalf of a resource owner, through the use of a standardized authorization flow that generates a client access token to be used with HTTP requests.</p>
|
||
|
||
<p>To obtain an OAuth token for a Gancio instance, make sure that you allow your users to specify the domain they want to connect to before login. Use that domain to <a href="#create-client">acquire a client id/secret</a> and then proceed with normal OAuth 2.</p>
|
||
|
||
<hr />
|
||
|
||
<h2 id="create-client">Create client</h2>
|
||
<p>Create a new application to obtain OAuth2 credentials.</p>
|
||
|
||
<p class="label label-yellow">POST</p>
|
||
<p><code class="highlighter-rouge">/api/client</code></p>
|
||
|
||
<h4 id="request-parameters">Request parameters</h4>
|
||
|
||
<table>
|
||
<tbody>
|
||
<tr>
|
||
<td>client_name</td>
|
||
<td><code class="highlighter-rouge">string</code></td>
|
||
<td>A name for your application</td>
|
||
</tr>
|
||
<tr>
|
||
<td>redirect_uris</td>
|
||
<td><code class="highlighter-rouge">string</code></td>
|
||
<td>Where the user should be redirected after authorization</td>
|
||
</tr>
|
||
<tr>
|
||
<td>scopes</td>
|
||
<td><code class="highlighter-rouge">string</code></td>
|
||
<td>Space separated list of scopes. If none is provided, defaults to <code class="highlighter-rouge">event:write</code> as it’s the only supported scope!</td>
|
||
</tr>
|
||
<tr>
|
||
<td>website</td>
|
||
<td><code class="highlighter-rouge">string</code></td>
|
||
<td>A URL to the homepage of your app</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h4 id="example">Example</h4>
|
||
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>curl <span class="nt">-X</span> POST <span class="se">\</span>
|
||
<span class="nt">-d</span> <span class="s1">'client_name=Wordpress Event Manager'</span> <span class="se">\</span>
|
||
<span class="nt">-d</span> <span class="s1">'redirect_uris=https://noblogs.org/'</span> <span class="se">\</span>
|
||
<span class="nt">-d</span> <span class="s1">'website=https://myapp.example'</span> <span class="se">\</span>
|
||
http://localhost:13120/api/client
|
||
</code></pre></div></div>
|
||
|
||
<h4 id="returns">Returns</h4>
|
||
<p>Application, with <code class="highlighter-rouge">client_id</code> and <code class="highlighter-rouge">client_secret</code></p>
|
||
|
||
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
|
||
</span><span class="s2">"name"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"Wordpress Event Manager"</span><span class="p">,</span><span class="w">
|
||
</span><span class="s2">"scopes"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"event:write"</span><span class="p">,</span><span class="w">
|
||
</span><span class="s2">"website"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"https://myapp.example"</span><span class="p">,</span><span class="w">
|
||
</span><span class="s2">"client_secret"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"909029fa12797e6bdfb5baf5e379675dfa4e3ad4"</span><span class="p">,</span><span class="w">
|
||
</span><span class="s2">"redirect_uris"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"https://noblogs.org"</span><span class="p">,</span><span class="w">
|
||
</span><span class="s2">"client_id"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"0f377e34b2aaf517f7db534f32d26b0dd938fb6d"</span><span class="w">
|
||
</span><span class="p">}</span><span class="w">
|
||
</span></code></pre></div></div>
|
||
|
||
<h4 id="list-of-scopes">List of scopes</h4>
|
||
<ul>
|
||
<li><code class="highlighter-rouge">event:write</code><br />
|
||
Grant access to add/update events.</li>
|
||
</ul>
|
||
|
||
<h2 id="authorize-a-user">Authorize a user</h2>
|
||
<p>Displays an authorization form to the user. If approved, it will create and return an authorization code, then redirect to the desired <code class="highlighter-rouge">redirect_uri</code>.
|
||
The authorization code can be used while requesting a token to obtain access to user-level methods.</p>
|
||
|
||
<p><a href="/assets/oauth_auth.png" data-fancybox="group" data-caption="OAuth authorization form"><img src="/assets/thumbs/oauth_auth.png" alt="/assets/thumbs/oauth_auth.png" /></a></p>
|
||
|
||
<p class="label label-green">GET</p>
|
||
<p><code class="highlighter-rouge">/authorize</code></p>
|
||
|
||
<h4 id="request-parameters-1">Request parameters</h4>
|
||
|
||
<table>
|
||
<tbody>
|
||
<tr>
|
||
<td>response_type</td>
|
||
<td><code class="highlighter-rouge">string</code></td>
|
||
<td>Should be set equal to <code class="highlighter-rouge">code</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td>redirect_uri</td>
|
||
<td><code class="highlighter-rouge">string</code></td>
|
||
<td>Where the user should be redirected after authorization</td>
|
||
</tr>
|
||
<tr>
|
||
<td>scope</td>
|
||
<td><code class="highlighter-rouge">string</code></td>
|
||
<td>Should be <code class="highlighter-rouge">event:write</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td>client_id</td>
|
||
<td><code class="highlighter-rouge">string</code></td>
|
||
<td><code class="highlighter-rouge">client_id</code>, obtained during app registration.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h2 id="obtain-a-token">Obtain a token</h2>
|
||
|
||
<p class="label label-yellow">POST</p>
|
||
<p><code class="highlighter-rouge">/oauth/token</code></p>
|
||
|
||
<h4 id="request-parameters-2">Request parameters</h4>
|
||
|
||
<table>
|
||
<tbody>
|
||
<tr>
|
||
<td>client_id</td>
|
||
<td><code class="highlighter-rouge">string</code></td>
|
||
<td><code class="highlighter-rouge">client_id</code> obtained during <a href="#create-client">client registration</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td>client_secret</td>
|
||
<td><code class="highlighter-rouge">string</code></td>
|
||
<td><code class="highlighter-rouge">client_secret</code> obtained during <a href="#create-client">client registration</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td>scope</td>
|
||
<td><code class="highlighter-rouge">string</code></td>
|
||
<td>Should be <code class="highlighter-rouge">event:write</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td>grant_type</td>
|
||
<td><code class="highlighter-rouge">string</code></td>
|
||
<td>Set equal to <code class="highlighter-rouge">authorization_code</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td>code</td>
|
||
<td><code class="highlighter-rouge">string</code></td>
|
||
<td>A user authorization code, obtained via <a href="#authorize-a-user">/authorize</a></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
</body>
|
||
</html>
|