2020-01-21 01:25:09 +01:00
<!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" >
2020-01-21 22:14:46 +01:00
< link rel = "stylesheet" href = "https://gancio.org/assets/css/premonition.css" >
< link rel = "stylesheet" href = "https://gancio.org/assets/css/fa.min.css" >
2020-01-21 01:25:09 +01:00
< 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" />
2020-01-21 22:14:46 +01:00
< link rel = "canonical" href = "https://gancio.org/dev/oauth" />
< meta property = "og:url" content = "https://gancio.org/dev/oauth" />
2020-01-21 01:25:09 +01:00
< meta property = "og:site_name" content = "Gancio" />
< script type = "application/ld+json" >
2020-01-21 22:14:46 +01:00
{ "@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 >
2020-01-21 01:25:09 +01:00
<!-- 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 >
2020-01-21 22:14:46 +01:00
2020-01-21 01:25:09 +01:00
< 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 >
2020-01-21 22:14:46 +01:00
2020-01-21 01:25:09 +01:00
</ ul >
</ li >
< li class = "navigation-list-item" >
< a href = "https://gancio.org/config" class = "navigation-list-link" > Configuration</ a >
</ li >
2020-01-21 22:14:46 +01:00
< li class = "navigation-list-item active" >
2020-01-21 01:25:09 +01:00
< a href = "https://gancio.org/dev" class = "navigation-list-link" > Hacking</ a >
< ul class = "navigation-list-child-list " >
2020-01-21 22:14:46 +01:00
2020-01-21 01:25:09 +01:00
< li class = "navigation-list-item " >
2020-01-21 22:14:46 +01:00
< a href = "https://gancio.org/dev/structure" class = "navigation-list-link" > Project Structure</ a >
2020-01-21 01:25:09 +01:00
</ li >
2020-01-21 22:14:46 +01:00
< li class = "navigation-list-item active" >
2020-01-21 01:25:09 +01:00
2020-01-21 22:14:46 +01:00
< a href = "https://gancio.org/dev/oauth" class = "navigation-list-link active" > OAuth</ a >
2020-01-21 01:25:09 +01:00
</ li >
2020-01-21 22:14:46 +01:00
< li class = "navigation-list-item " >
< a href = "https://gancio.org/dev/locales" class = "navigation-list-link" > Internationalization</ a >
</ li >
2020-01-21 01:25:09 +01:00
</ ul >
</ li >
< li class = "navigation-list-item" >
< a href = "https://gancio.org/instances" class = "navigation-list-link" > Instances</ a >
</ li >
2020-01-21 22:14:46 +01:00
2020-01-21 01:25:09 +01:00
< li class = "navigation-list-item" >
< a href = "https://gancio.org/about" class = "navigation-list-link" > About</ a >
</ li >
< li class = "navigation-list-item" >
2020-01-21 22:14:46 +01:00
< a href = "https://gancio.org/contacts" class = "navigation-list-link" > Contacts</ a >
2020-01-21 01:25:09 +01:00
</ li >
2020-01-21 22:14:46 +01:00
< li class = "navigation-list-item" >
2020-01-21 01:25:09 +01:00
2020-01-21 22:14:46 +01:00
< a href = "https://gancio.org/federation" class = "navigation-list-link" > Federation</ a >
2020-01-21 01:25:09 +01:00
</ 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 >
2020-01-21 22:14:46 +01:00
< 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 >
2020-01-21 01:25:09 +01:00
</ ul >
</ div >
</ div >
< div class = "main-content" >
2020-01-21 22:14:46 +01:00
< 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 >
2020-01-21 01:25:09 +01:00
< div id = "main-content" class = "page-content" role = "main" >
2020-01-21 22:14:46 +01:00
< 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 >
2020-01-21 01:25:09 +01:00
< 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 >
2020-01-21 22:14:46 +01:00
< hr />
2020-01-21 01:25:09 +01:00
< 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 >
2020-01-21 22:14:46 +01:00
< td > redirect_uris</ td >
2020-01-21 01:25:09 +01:00
< 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 >
2020-01-21 22:14:46 +01:00
< td > Space separated list of scopes. If none is provided, defaults to < code class = "highlighter-rouge" > event:write</ code > as it’ </ td >
2020-01-21 01:25:09 +01:00
</ 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 >
2020-01-21 22:14:46 +01:00
< span class = "nt" > -d</ span > < span class = "s1" > 'redirect_uris=https://noblogs.org/'</ span > < span class = "se" > \</ span >
2020-01-21 01:25:09 +01:00
< 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" >
2020-01-21 22:14:46 +01:00
</ 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" >
2020-01-21 01:25:09 +01:00
</ 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" >
2020-01-21 22:14:46 +01:00
</ 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" >
2020-01-21 01:25:09 +01:00
</ 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 >
2020-01-21 22:14:46 +01:00
< li >< code class = "highlighter-rouge" > event:write</ code >< br />
2020-01-21 01:25:09 +01:00
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 >
2020-01-21 22:36:32 +01:00
< 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 >
2020-01-21 22:14:46 +01:00
2020-01-21 01:25:09 +01:00
< 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 >
2020-01-21 22:14:46 +01:00
< td > Should be < code class = "highlighter-rouge" > event:write</ code ></ td >
2020-01-21 01:25:09 +01:00
</ tr >
< tr >
< td > client_id</ td >
< td >< code class = "highlighter-rouge" > string</ code ></ td >
2020-01-21 22:14:46 +01:00
< 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 >
2020-01-21 01:25:09 +01:00
</ tr >
</ tbody >
</ table >
</ div >
</ div >
</ div >
</ div >
</ body >
</ html >
