269 lines
14 KiB
HTML
269 lines
14 KiB
HTML
<!DOCTYPE html>
|
||
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
|
||
|
||
<title>Third-party applications — FitTrackee 0.7.8
|
||
documentation</title>
|
||
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
|
||
<link rel="stylesheet" type="text/css" href="_static/bootstrap-sphinx.css" />
|
||
<link rel="stylesheet" type="text/css" href="_static/css/fork-awesome.min.css" />
|
||
<link rel="stylesheet" type="text/css" href="_static/css/custom.css" />
|
||
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
|
||
<script src="_static/jquery.js"></script>
|
||
<script src="_static/underscore.js"></script>
|
||
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
|
||
<script src="_static/doctools.js"></script>
|
||
<script src="_static/sphinx_highlight.js"></script>
|
||
<link rel="index" title="Index" href="genindex.html" />
|
||
<link rel="search" title="Search" href="search.html" />
|
||
<link rel="next" title="Installation" href="installation.html" />
|
||
<link rel="prev" title="Features" href="features.html" />
|
||
<meta charset='utf-8'>
|
||
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
|
||
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
|
||
<meta name="apple-mobile-web-app-capable" content="yes">
|
||
<script type="text/javascript" src="_static/js/jquery-1.12.4.min.js"></script>
|
||
<script type="text/javascript" src="_static/js/jquery-fix.js"></script>
|
||
<script type="text/javascript" src="_static/bootstrap-3.4.1/js/bootstrap.min.js"></script>
|
||
<script type="text/javascript" src="_static/bootstrap-sphinx.js"></script>
|
||
|
||
</head><body>
|
||
|
||
<div id="navbar" class="navbar navbar-default navbar-fixed-top">
|
||
<div class="container">
|
||
<div class="navbar-header">
|
||
<!-- .btn-navbar is used as the toggle for collapsed navbar content -->
|
||
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
|
||
<span class="icon-bar"></span>
|
||
<span class="icon-bar"></span>
|
||
<span class="icon-bar"></span>
|
||
</button>
|
||
<a class="navbar-brand" href="index.html">
|
||
FitTrackee</a>
|
||
<span class="navbar-text navbar-version pull-left"><b>0.7.8
|
||
</b></span>
|
||
</div>
|
||
|
||
<div class="collapse navbar-collapse nav-collapse">
|
||
<ul class="nav navbar-nav">
|
||
|
||
<li><a href="https://github.com/SamR1/FitTrackee">GitHub</a></li>
|
||
|
||
|
||
<li class="dropdown globaltoc-container">
|
||
<a role="button"
|
||
id="dLabelGlobalToc"
|
||
data-toggle="dropdown"
|
||
data-target="#"
|
||
href="index.html">Docs <b class="caret"></b></a>
|
||
<ul class="dropdown-menu globaltoc"
|
||
role="menu"
|
||
aria-labelledby="dLabelGlobalToc"><ul class="current">
|
||
<li class="toctree-l1"><a class="reference internal" href="features.html">Features</a></li>
|
||
<li class="toctree-l1 current"><a class="current reference internal" href="#">Third-party applications</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="cli.html">Command line interface</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="api/index.html">API documentation</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="troubleshooting/index.html">Troubleshooting</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Change log</a></li>
|
||
</ul>
|
||
</ul>
|
||
</li>
|
||
|
||
<li class="dropdown">
|
||
<a role="button"
|
||
id="dLabelLocalToc"
|
||
data-toggle="dropdown"
|
||
data-target="#"
|
||
href="#">Page <b class="caret"></b></a>
|
||
<ul class="dropdown-menu localtoc"
|
||
role="menu"
|
||
aria-labelledby="dLabelLocalToc"><ul>
|
||
<li><a class="reference internal" href="#">Third-party applications</a><ul>
|
||
<li><a class="reference internal" href="#scopes">Scopes</a></li>
|
||
<li><a class="reference internal" href="#flow">Flow</a></li>
|
||
<li><a class="reference internal" href="#resources">Resources</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</ul>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
<li>
|
||
<a href="features.html" title="Previous Chapter: Features"><span class="glyphicon glyphicon-chevron-left visible-sm"></span><span class="hidden-sm hidden-tablet">« Features</span>
|
||
</a>
|
||
</li>
|
||
<li>
|
||
<a href="installation.html" title="Next Chapter: Installation"><span class="glyphicon glyphicon-chevron-right visible-sm"></span><span class="hidden-sm hidden-tablet">Installation »</span>
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
<li class="hidden-sm">
|
||
<div id="sourcelink">
|
||
<a href="_sources/apps.rst.txt"
|
||
rel="nofollow">Source</a>
|
||
</div></li>
|
||
|
||
</ul>
|
||
|
||
|
||
|
||
<form class="navbar-form navbar-right" action="search.html" method="get">
|
||
<div class="form-group">
|
||
<input type="text" name="q" class="form-control" placeholder="Search" />
|
||
</div>
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="container">
|
||
<div class="row">
|
||
<div class="body col-md-12 content" role="main">
|
||
|
||
<section id="third-party-applications">
|
||
<h1>Third-party applications<a class="headerlink" href="#third-party-applications" title="Permalink to this heading">¶</a></h1>
|
||
<p>(<em>new in 0.7.0</em>)</p>
|
||
<p>FitTrackee provides a REST API (see <a class="reference external" href="api/index.html">documentation</a>) whose
|
||
most endpoints require authentication/authorization.</p>
|
||
<p>To allow a third-party application to interact with API endpoints, an
|
||
<a class="reference external" href="https://datatracker.ietf.org/doc/html/rfc6749">OAuth2</a> client can be created
|
||
in user settings (‘apps’ tab).</p>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p>OAuth2 endpoints requiring authentication are not accessible by third-party
|
||
applications (<a class="reference external" href="api/oauth2.html">documentation</a>), only by FitTrackee
|
||
client (first-party application).</p>
|
||
</div>
|
||
<p>FitTrackee supports only <a class="reference external" href="https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1">Authorization Code</a>
|
||
flow (with <a class="reference external" href="https://datatracker.ietf.org/doc/html/rfc7636">PKCE</a> support).
|
||
It allows to exchange an authorization code for an access token.
|
||
The client ID and secret must be sent in the POST body.
|
||
It is recommended to use PKCE to provide a better security.</p>
|
||
<section id="scopes">
|
||
<h2>Scopes<a class="headerlink" href="#scopes" title="Permalink to this heading">¶</a></h2>
|
||
<p>The following scopes are available:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">application:write</span></code>: grants write access to application configuration (only for users with administration rights),</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">profile:read</span></code>: grants read access to auth endpoints,</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">profile:write</span></code>: grants write access to auth endpoints,</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">users:read</span></code>: grants read access to users endpoints,</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">users:write</span></code>: grants write access to users endpoints,</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">workouts:read</span></code>: grants read access to workouts-related endpoints,</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">workouts:write</span></code>: grants write access to workouts-related endpoints.</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="flow">
|
||
<h2>Flow<a class="headerlink" href="#flow" title="Permalink to this heading">¶</a></h2>
|
||
<ul>
|
||
<li><p>The user creates an App (client) on FitTrackee for a third-party application.</p>
|
||
<figure class="align-default">
|
||
<img alt="OAuth2 client creation on FitTrackee" src="_images/fittrackee_screenshot-07.png" />
|
||
</figure>
|
||
<div class="line-block">
|
||
<div class="line">After registration, the client id and secret are shown.</div>
|
||
<div class="line">They must be stored in the 3rd-party application by the user.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">The 3rd-party app needs to redirect to FitTrackee, in order for the user to authorize the 3rd-party app to access user data on FitTrackee.</div>
|
||
</div>
|
||
<figure class="align-default">
|
||
<img alt="App authorization on FitTrackee" src="_images/fittrackee_screenshot-08.png" />
|
||
</figure>
|
||
<div class="line-block">
|
||
<div class="line">The authorization URL is <code class="docutils literal notranslate"><span class="pre">https://<FITTRACKEE_HOST>/profile/apps/authorize</span></code>.</div>
|
||
<div class="line">The required parameters are:</div>
|
||
</div>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">client_id</span></code>: the client id displayed after registration</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">response_type</span></code>: <code class="docutils literal notranslate"><span class="pre">code</span></code>, since FitTrackee only supports Authorization Code flow.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">scope</span></code>: scopes separated with space.</p></li>
|
||
</ul>
|
||
<div class="line-block">
|
||
<div class="line">and optional parameters:</div>
|
||
</div>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">state</span></code>: unique value to prevent cross-site request forgery</p></li>
|
||
</ul>
|
||
<div class="line-block">
|
||
<div class="line">For PKCE, the following parameters are mandatory:</div>
|
||
</div>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">code_challenge</span></code>: string generated from a code verifier</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">code_challenge_method</span></code>: method used to create challenge, for instance “S256”</p></li>
|
||
</ul>
|
||
<div class="line-block">
|
||
<div class="line">Example for PKCE:</div>
|
||
<div class="line"><cite>https://<FITTRACKEE_HOST>/profile/apps/authorize?response_type=code&client_id=<CLIENT_ID>&scope=profile%3Aread+workouts%3Awrite&state=<STATE>&code_challenge=<CODE_CHALLENGE>&code_challenge_method=S256</cite></div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">After the authorization, FitTrackee redirects to the 3rd-party app, so the 3rd-party app can get the authorization code from the redirect URL and then fetches an access token with the client id and secret (endpoint <a class="reference external" href="https://samr1.github.io/FitTrackee/api/oauth2.html#post--api-oauth-token">/api/oauth/token</a>).</div>
|
||
<div class="line">Example of a redirect URL:</div>
|
||
<div class="line"><cite>https://example.com/callback?code=<AUTHORIZATION_CODE>&state=<STATE></cite></div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>OAuth2 support is implemented with <a class="reference external" href="https://docs.authlib.org/en/latest/">Authlib</a> library.</p>
|
||
</div>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<div class="line-block">
|
||
<div class="line">If FitTrackee is running behind a proxy, the <code class="docutils literal notranslate"><span class="pre">X-Forwarded-Proto</span></code> header must be set.</div>
|
||
<div class="line">For instance for <cite>nginx</cite>:</div>
|
||
</div>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>proxy_set_header X-Forwarded-Proto $scheme;
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
</section>
|
||
<section id="resources">
|
||
<h2>Resources<a class="headerlink" href="#resources" title="Permalink to this heading">¶</a></h2>
|
||
<p>Some resources about OAuth 2.0:</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference external" href="https://www.oauth.com">OAuth 2.0 Simplified</a> by <a class="reference external" href="https://aaronparecki.com">Aaron Parecki</a> (example for <a class="reference external" href="https://www.oauth.com/oauth2-servers/server-side-apps/example-flow/">authorization code flow with PKCE</a>)</p></li>
|
||
<li><p><a class="reference external" href="https://requests-oauthlib.readthedocs.io/en/latest/examples/real_world_example.html">Web App Example of OAuth 2 web application flow</a> with Requests-OAuthlib (python)</p></li>
|
||
<li><p><a class="reference external" href="https://docs.authlib.org/en/latest/client/oauth2.html#oauth-2-session">OAuth 2 Session</a> with Authlib (python)</p></li>
|
||
<li><p><a class="reference external" href="https://codeberg.org/SamR1/ft-oauth-client">Minimal example of an application interacting with FitTrackee</a> (python)</p></li>
|
||
</ul>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
</div>
|
||
|
||
</div>
|
||
</div>
|
||
<footer class="footer">
|
||
<div class="container">
|
||
<p class="pull-right">
|
||
<a href="#">Back to top</a>
|
||
|
||
</p>
|
||
<p>
|
||
© Copyright 2018 - 2022, SamR1 <a rel="me" href="https://fosstodon.org/@FitTrackee"><i class="fa fa-mastodon" aria-hidden="true"></i></a>.
|
||
Last updated on Nov 30, 2022.<br/>
|
||
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 5.3.0.<br/>
|
||
</p>
|
||
</div>
|
||
</footer>
|
||
|
||
</body>
|
||
</html> |