Alexander/FitTrackee
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
a5ab419ba7
FitTrackee/docs/apps.html

266 lines
13 KiB
HTML
Raw Normal View History

update documentation
2022-08-27 16:50:29 +02:00
<!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/" />
bump version to 0.7.4
2022-11-05 10:10:25 +01:00
<title>Third-party applications &#8212; FitTrackee 0.7.4
update documentation
2022-08-27 16:50:29 +02:00
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/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>
bump version to 0.7.3
2022-11-01 19:58:12 +01:00
<script src="_static/sphinx_highlight.js"></script>
update documentation
2022-08-27 16:50:29 +02:00
<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>
bump version to 0.7.4
2022-11-05 10:10:25 +01:00
<span class="navbar-text navbar-version pull-left"><b>0.7.4
update documentation
2022-08-27 16:50:29 +02:00
</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>
update documentation
2022-10-02 09:43:44 +02:00
<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>
update documentation
2022-08-27 16:50:29 +02:00
</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">&laquo; 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 &raquo;</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
update documentation
2022-10-02 09:43:44 +02:00
most endpoints require authentication/authorization.</p>
update documentation
2022-08-27 16:50:29 +02:00
<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>
update documentation
2022-10-02 09:43:44 +02:00
flow (with <a class="reference external" href="https://datatracker.ietf.org/doc/html/rfc7636">PKCE</a> support).
update documentation
2022-08-27 16:50:29 +02:00
It allows to exchange an authorization code for an access token.
bump version to 0.7.0
2022-09-19 18:49:25 +02:00
The client ID and secret must be sent in the POST body.
update documentation
2022-10-02 09:43:44 +02:00
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>
update documentation
2022-08-27 16:50:29 +02:00
<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>
update documentation
2022-10-02 09:43:44 +02:00
</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>
update documentation
2022-08-27 16:50:29 +02:00
<figure class="align-default">
<img alt="OAuth2 client creation on FitTrackee" src="_images/fittrackee_screenshot-07.png" />
</figure>
update documentation
2022-10-02 09:43:44 +02:00
<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://&lt;FITTRACKEE_HOST&gt;/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://&lt;FITTRACKEE_HOST&gt;/profile/apps/authorize?response_type=code&amp;client_id=&lt;CLIENT_ID&gt;&amp;scope=profile%3Aread+workouts%3Awrite&amp;state=&lt;STATE&gt;&amp;code_challenge=&lt;CODE_CHALLENGE&gt;&amp;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=&lt;AUTHORIZATION_CODE&gt;&amp;state=&lt;STATE&gt;</cite></div>
</div>
</li>
</ul>
bump version to 0.7.0
2022-09-19 18:49:25 +02:00
<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>
update documentation
2022-10-02 09:43:44 +02:00
</section>
<section id="resources">
<h2>Resources<a class="headerlink" href="#resources" title="Permalink to this heading"></a></h2>
update documentation
2022-08-27 16:50:29 +02:00
<p>Some resources about OAuth 2.0:</p>
<ul class="simple">
update documentation
2022-10-02 09:43:44 +02:00
<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>
bump version to 0.7.0
2022-09-19 18:49:25 +02:00
<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>
update documentation
2022-08-27 16:50:29 +02:00
</ul>
update documentation
2022-10-02 09:43:44 +02:00
</section>
update documentation
2022-08-27 16:50:29 +02:00
</section>
</div>
</div>
</div>
<footer class="footer">
<div class="container">
<p class="pull-right">
<a href="#">Back to top</a>
</p>
<p>
&copy; Copyright 2018 - 2022, SamR1.<br/>
bump version to 0.7.3
2022-11-01 19:58:12 +01:00
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 5.3.0.<br/>
update documentation
2022-08-27 16:50:29 +02:00
</p>
</div>
</footer>
</body>
</html>
Reference in New Issue Copy Permalink