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 >
