Merge branch 'master' into dev
This commit is contained in:
commit
d57720f02d
BIN
docs/_images/fittrackee_screenshot-08.png
Normal file
BIN
docs/_images/fittrackee_screenshot-08.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 81 KiB |
@ -3,7 +3,7 @@ Third-party applications
|
||||
(*new in 0.7.0*)
|
||||
|
||||
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
|
||||
`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).
|
||||
|
||||
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.
|
||||
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>`_
|
||||
to provide a better security.
|
||||
It is recommended to use PKCE to provide a better security.
|
||||
|
||||
Scopes
|
||||
~~~~~~
|
||||
|
||||
The following scopes are available:
|
||||
|
||||
@ -31,9 +33,48 @@ The following scopes are available:
|
||||
- ``workouts:read``: grants read access to workouts-related endpoints,
|
||||
- ``workouts:write``: grants write access to workouts-related endpoints.
|
||||
|
||||
.. figure:: _images/fittrackee_screenshot-07.png
|
||||
|
||||
Flow
|
||||
~~~~
|
||||
|
||||
- The user creates an App (client) on FitTrackee for a third-party application.
|
||||
|
||||
.. figure:: _images/fittrackee_screenshot-07.png
|
||||
: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::
|
||||
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;
|
||||
|
||||
Resources
|
||||
~~~~~~~~~
|
||||
|
||||
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)
|
||||
- `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)
|
@ -80,7 +80,12 @@
|
||||
<ul class="dropdown-menu localtoc"
|
||||
role="menu"
|
||||
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>
|
||||
</li>
|
||||
@ -132,7 +137,7 @@
|
||||
<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 authorization/authentication.</p>
|
||||
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>
|
||||
@ -143,11 +148,12 @@ applications (<a class="reference external" href="api/oauth2.html">documentation
|
||||
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 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.
|
||||
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>
|
||||
to provide a better security.</p>
|
||||
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>
|
||||
@ -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: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>
|
||||
@ -175,13 +231,17 @@ to provide a better security.</p>
|
||||
</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></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://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>
|
||||
|
||||
|
||||
|
File diff suppressed because one or more lines are too long
BIN
docsrc/source/_images/fittrackee_screenshot-08.png
Normal file
BIN
docsrc/source/_images/fittrackee_screenshot-08.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 81 KiB |
@ -3,7 +3,7 @@ Third-party applications
|
||||
(*new in 0.7.0*)
|
||||
|
||||
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
|
||||
`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).
|
||||
|
||||
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.
|
||||
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>`_
|
||||
to provide a better security.
|
||||
It is recommended to use PKCE to provide a better security.
|
||||
|
||||
Scopes
|
||||
~~~~~~
|
||||
|
||||
The following scopes are available:
|
||||
|
||||
@ -31,9 +33,48 @@ The following scopes are available:
|
||||
- ``workouts:read``: grants read access to workouts-related endpoints,
|
||||
- ``workouts:write``: grants write access to workouts-related endpoints.
|
||||
|
||||
.. figure:: _images/fittrackee_screenshot-07.png
|
||||
|
||||
Flow
|
||||
~~~~
|
||||
|
||||
- The user creates an App (client) on FitTrackee for a third-party application.
|
||||
|
||||
.. figure:: _images/fittrackee_screenshot-07.png
|
||||
: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::
|
||||
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;
|
||||
|
||||
Resources
|
||||
~~~~~~~~~
|
||||
|
||||
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)
|
||||
- `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)
|
Loading…
Reference in New Issue
Block a user