Alexander/FitTrackee
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update documentation

Browse Source
This commit is contained in:
Sam 2022-10-02 09:43:44 +02:00
parent 2f579318be
commit e070d7a4e8
6 changed files with 167 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/_images/fittrackee_screenshot-08.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 81 KiB

54
docs/_sources/apps.rst.txt
View File

@ -3,7 +3,7 @@ Third-party applications
(*new in 0.7.0*) (*new in 0.7.0*)
FitTrackee provides a REST API (see `documentation <api/index.html>`__) whose FitTrackee provides a REST API (see `documentation <api/index.html>`__) whose
most endpoints require authorization/authentication. most endpoints require authentication/authorization.
To allow a third-party application to interact with API endpoints, an To allow a third-party application to interact with API endpoints, an
`OAuth2 <https://datatracker.ietf.org/doc/html/rfc6749>`_ client can be created `OAuth2 <https://datatracker.ietf.org/doc/html/rfc6749>`_ client can be created
@ -15,11 +15,13 @@ in user settings ('apps' tab).
client (first-party application). client (first-party application).
FitTrackee supports only `Authorization Code <https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1>`_ FitTrackee supports only `Authorization Code <https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1>`_
flow (with PKCE support). flow (with `PKCE <https://datatracker.ietf.org/doc/html/rfc7636>`_ support).
It allows to exchange an authorization code for an access token. It allows to exchange an authorization code for an access token.
The client ID and secret must be sent in the POST body. The client ID and secret must be sent in the POST body.
It is recommended to use `PKCE <https://datatracker.ietf.org/doc/html/rfc7636>`_ It is recommended to use PKCE to provide a better security.
to provide a better security.
Scopes
~~~~~~
The following scopes are available: The following scopes are available:
@ -31,9 +33,48 @@ The following scopes are available:
- ``workouts:read``: grants read access to workouts-related endpoints, - ``workouts:read``: grants read access to workouts-related endpoints,
- ``workouts:write``: grants write access to workouts-related endpoints. - ``workouts:write``: grants write access to workouts-related endpoints.
Flow
~~~~
- The user creates an App (client) on FitTrackee for a third-party application.
.. figure:: _images/fittrackee_screenshot-07.png .. figure:: _images/fittrackee_screenshot-07.png
:alt: OAuth2 client creation on FitTrackee :alt: OAuth2 client creation on FitTrackee
| After registration, the client id and secret are shown.
| They must be stored in the 3rd-party application by the user.
- | 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.
.. figure:: _images/fittrackee_screenshot-08.png
:alt: App authorization on FitTrackee
| The authorization URL is ``https://<FITTRACKEE_HOST>/profile/apps/authorize``.
| The required parameters are:
- ``client_id``: the client id displayed after registration
- ``response_type``: ``code``, since FitTrackee only supports Authorization Code flow.
- ``scope``: scopes separated with space.
| and optional parameters:
- ``state``: unique value to prevent cross-site request forgery
| For PKCE, the following parameters are mandatory:
- ``code_challenge``: string generated from a code verifier
- ``code_challenge_method``: method used to create challenge, for instance "S256"
| Example for PKCE:
| `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`
- | 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 `/api/oauth/token <https://samr1.github.io/FitTrackee/api/oauth2.html#post--api-oauth-token>`_).
| Example of a redirect URL:
| `https://example.com/callback?code=<AUTHORIZATION_CODE>&state=<STATE>`
.. note:: .. note::
OAuth2 support is implemented with `Authlib <https://docs.authlib.org/en/latest/>`_ library. OAuth2 support is implemented with `Authlib <https://docs.authlib.org/en/latest/>`_ library.
@ -45,9 +86,12 @@ The following scopes are available:
proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Proto $scheme;
Resources
~~~~~~~~~
Some resources about OAuth 2.0: Some resources about OAuth 2.0:
- `OAuth 2.0 Simplified <https://www.oauth.com>`_ by `Aaron Parecki <https://aaronparecki.com>`_ - `OAuth 2.0 Simplified <https://www.oauth.com>`_ by `Aaron Parecki <https://aaronparecki.com>`_ (example for `authorization code flow with PKCE <https://www.oauth.com/oauth2-servers/server-side-apps/example-flow/>`_)
- `Web App Example of OAuth 2 web application flow <https://requests-oauthlib.readthedocs.io/en/latest/examples/real_world_example.html>`_ with Requests-OAuthlib (python) - `Web App Example of OAuth 2 web application flow <https://requests-oauthlib.readthedocs.io/en/latest/examples/real_world_example.html>`_ with Requests-OAuthlib (python)
- `OAuth 2 Session <https://docs.authlib.org/en/latest/client/oauth2.html#oauth-2-session>`_ with Authlib (python) - `OAuth 2 Session <https://docs.authlib.org/en/latest/client/oauth2.html#oauth-2-session>`_ with Authlib (python)
- `Minimal example of an application interacting with FitTrackee <https://codeberg.org/SamR1/ft-oauth-client>`_ (python) - `Minimal example of an application interacting with FitTrackee <https://codeberg.org/SamR1/ft-oauth-client>`_ (python)

72
docs/apps.html
View File

@ -80,7 +80,12 @@
<ul class="dropdown-menu localtoc" <ul class="dropdown-menu localtoc"
role="menu" role="menu"
aria-labelledby="dLabelLocalToc"><ul> aria-labelledby="dLabelLocalToc"><ul>
<li><a class="reference internal" href="#">Third-party applications</a></li> <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>
</ul> </ul>
</li> </li>
@ -132,7 +137,7 @@
<h1>Third-party applications<a class="headerlink" href="#third-party-applications" title="Permalink to this heading"></a></h1> <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>(<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 <p>FitTrackee provides a REST API (see <a class="reference external" href="api/index.html">documentation</a>) whose
most endpoints require authorization/authentication.</p> most endpoints require authentication/authorization.</p>
<p>To allow a third-party application to interact with API endpoints, an <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 <a class="reference external" href="https://datatracker.ietf.org/doc/html/rfc6749">OAuth2</a> client can be created
in user settings (‘apps’ tab).</p> in user settings (‘apps’ tab).</p>
@ -143,11 +148,12 @@ applications (<a class="reference external" href="api/oauth2.html">documentation
client (first-party application).</p> client (first-party application).</p>
</div> </div>
<p>FitTrackee supports only <a class="reference external" href="https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1">Authorization Code</a> <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 PKCE support). 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. It allows to exchange an authorization code for an access token.
The client ID and secret must be sent in the POST body. The client ID and secret must be sent in the POST body.
It is recommended to use <a class="reference external" href="https://datatracker.ietf.org/doc/html/rfc7636">PKCE</a> It is recommended to use PKCE to provide a better security.</p>
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> <p>The following scopes are available:</p>
<ul class="simple"> <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">application:write</span></code>: grants write access to application configuration (only for users with administration rights),</p></li>
@ -158,9 +164,59 @@ to provide a better security.</p>
<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: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> <li><p><code class="docutils literal notranslate"><span class="pre">workouts:write</span></code>: grants write access to workouts-related endpoints.</p></li>
</ul> </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"> <figure class="align-default">
<img alt="OAuth2 client creation on FitTrackee" src="_images/fittrackee_screenshot-07.png" /> <img alt="OAuth2 client creation on FitTrackee" src="_images/fittrackee_screenshot-07.png" />
</figure> </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://&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>
<div class="admonition note"> <div class="admonition note">
<p class="admonition-title">Note</p> <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> <p>OAuth2 support is implemented with <a class="reference external" href="https://docs.authlib.org/en/latest/">Authlib</a> library.</p>
@ -175,13 +231,17 @@ to provide a better security.</p>
</pre></div> </pre></div>
</div> </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> <p>Some resources about OAuth 2.0:</p>
<ul class="simple"> <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></p></li> <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://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://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> <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> </ul>
</section>
</section> </section>

2
docs/searchindex.js
View File

File diff suppressed because one or more lines are too long

BIN
docsrc/source/_images/fittrackee_screenshot-08.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 81 KiB

54
docsrc/source/apps.rst
View File

@ -3,7 +3,7 @@ Third-party applications
(*new in 0.7.0*) (*new in 0.7.0*)
FitTrackee provides a REST API (see `documentation <api/index.html>`__) whose FitTrackee provides a REST API (see `documentation <api/index.html>`__) whose
most endpoints require authorization/authentication. most endpoints require authentication/authorization.
To allow a third-party application to interact with API endpoints, an To allow a third-party application to interact with API endpoints, an
`OAuth2 <https://datatracker.ietf.org/doc/html/rfc6749>`_ client can be created `OAuth2 <https://datatracker.ietf.org/doc/html/rfc6749>`_ client can be created
@ -15,11 +15,13 @@ in user settings ('apps' tab).
client (first-party application). client (first-party application).
FitTrackee supports only `Authorization Code <https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1>`_ FitTrackee supports only `Authorization Code <https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1>`_
flow (with PKCE support). flow (with `PKCE <https://datatracker.ietf.org/doc/html/rfc7636>`_ support).
It allows to exchange an authorization code for an access token. It allows to exchange an authorization code for an access token.
The client ID and secret must be sent in the POST body. The client ID and secret must be sent in the POST body.
It is recommended to use `PKCE <https://datatracker.ietf.org/doc/html/rfc7636>`_ It is recommended to use PKCE to provide a better security.
to provide a better security.
Scopes
~~~~~~
The following scopes are available: The following scopes are available:
@ -31,9 +33,48 @@ The following scopes are available:
- ``workouts:read``: grants read access to workouts-related endpoints, - ``workouts:read``: grants read access to workouts-related endpoints,
- ``workouts:write``: grants write access to workouts-related endpoints. - ``workouts:write``: grants write access to workouts-related endpoints.
Flow
~~~~
- The user creates an App (client) on FitTrackee for a third-party application.
.. figure:: _images/fittrackee_screenshot-07.png .. figure:: _images/fittrackee_screenshot-07.png
:alt: OAuth2 client creation on FitTrackee :alt: OAuth2 client creation on FitTrackee
| After registration, the client id and secret are shown.
| They must be stored in the 3rd-party application by the user.
- | 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.
.. figure:: _images/fittrackee_screenshot-08.png
:alt: App authorization on FitTrackee
| The authorization URL is ``https://<FITTRACKEE_HOST>/profile/apps/authorize``.
| The required parameters are:
- ``client_id``: the client id displayed after registration
- ``response_type``: ``code``, since FitTrackee only supports Authorization Code flow.
- ``scope``: scopes separated with space.
| and optional parameters:
- ``state``: unique value to prevent cross-site request forgery
| For PKCE, the following parameters are mandatory:
- ``code_challenge``: string generated from a code verifier
- ``code_challenge_method``: method used to create challenge, for instance "S256"
| Example for PKCE:
| `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`
- | 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 `/api/oauth/token <https://samr1.github.io/FitTrackee/api/oauth2.html#post--api-oauth-token>`_).
| Example of a redirect URL:
| `https://example.com/callback?code=<AUTHORIZATION_CODE>&state=<STATE>`
.. note:: .. note::
OAuth2 support is implemented with `Authlib <https://docs.authlib.org/en/latest/>`_ library. OAuth2 support is implemented with `Authlib <https://docs.authlib.org/en/latest/>`_ library.
@ -45,9 +86,12 @@ The following scopes are available:
proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Proto $scheme;
Resources
~~~~~~~~~
Some resources about OAuth 2.0: Some resources about OAuth 2.0:
- `OAuth 2.0 Simplified <https://www.oauth.com>`_ by `Aaron Parecki <https://aaronparecki.com>`_ - `OAuth 2.0 Simplified <https://www.oauth.com>`_ by `Aaron Parecki <https://aaronparecki.com>`_ (example for `authorization code flow with PKCE <https://www.oauth.com/oauth2-servers/server-side-apps/example-flow/>`_)
- `Web App Example of OAuth 2 web application flow <https://requests-oauthlib.readthedocs.io/en/latest/examples/real_world_example.html>`_ with Requests-OAuthlib (python) - `Web App Example of OAuth 2 web application flow <https://requests-oauthlib.readthedocs.io/en/latest/examples/real_world_example.html>`_ with Requests-OAuthlib (python)
- `OAuth 2 Session <https://docs.authlib.org/en/latest/client/oauth2.html#oauth-2-session>`_ with Authlib (python) - `OAuth 2 Session <https://docs.authlib.org/en/latest/client/oauth2.html#oauth-2-session>`_ with Authlib (python)
- `Minimal example of an application interacting with FitTrackee <https://codeberg.org/SamR1/ft-oauth-client>`_ (python) - `Minimal example of an application interacting with FitTrackee <https://codeberg.org/SamR1/ft-oauth-client>`_ (python)