github/endurain
1
1
Fork 0
mirror of https://github.com/joaovitoriasilva/endurain.git synced 2026-01-09 15:57:59 -05:00
Code Issues 45 Packages Projects Releases Wiki Activity

Deployed 39a01eca with MkDocs version: 1.6.1

Browse Source
This commit is contained in:
João Vitória Silva
2025-12-16 11:56:21 +00:00
parent 22f84b4d47
commit 53c9b76594
2 changed files with 300 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

300
developer-guide/authentication/index.html
View File

@@ -976,6 +976,108 @@
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#mobile-sso-implementation-guide" class="md-nav__link">
<span class="md-ellipsis">
Mobile SSO Implementation Guide
</span>
</a>
<nav class="md-nav" aria-label="Mobile SSO Implementation Guide">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#overview" class="md-nav__link">
<span class="md-ellipsis">
Overview
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#prerequisites" class="md-nav__link">
<span class="md-ellipsis">
Prerequisites
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#step-by-step-implementation" class="md-nav__link">
<span class="md-ellipsis">
Step-by-Step Implementation
</span>
</a>
<nav class="md-nav" aria-label="Step-by-Step Implementation">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#step-1-fetch-available-identity-providers" class="md-nav__link">
<span class="md-ellipsis">
Step 1: Fetch Available Identity Providers
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#step-2-initialize-webview-and-load-sso-url" class="md-nav__link">
<span class="md-ellipsis">
Step 2: Initialize WebView and Load SSO URL
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#step-3-monitor-webview-url-changes" class="md-nav__link">
<span class="md-ellipsis">
Step 3: Monitor WebView URL Changes
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#step-4-extract-tokens-from-webview-cookies-store-tokens-securely-and-clean-up-the-webview" class="md-nav__link">
<span class="md-ellipsis">
Step 4: Extract tokens from WebView Cookies, store tokens securely and clean up the WebView
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#step-5-make-authenticated-api-requests" class="md-nav__link">
<span class="md-ellipsis">
Step 5: Make Authenticated API Requests
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#step-6-implement-token-refresh" class="md-nav__link">
<span class="md-ellipsis">
Step 6: Implement Token Refresh
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
@@ -1432,6 +1534,108 @@
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#mobile-sso-implementation-guide" class="md-nav__link">
<span class="md-ellipsis">
Mobile SSO Implementation Guide
</span>
</a>
<nav class="md-nav" aria-label="Mobile SSO Implementation Guide">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#overview" class="md-nav__link">
<span class="md-ellipsis">
Overview
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#prerequisites" class="md-nav__link">
<span class="md-ellipsis">
Prerequisites
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#step-by-step-implementation" class="md-nav__link">
<span class="md-ellipsis">
Step-by-Step Implementation
</span>
</a>
<nav class="md-nav" aria-label="Step-by-Step Implementation">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#step-1-fetch-available-identity-providers" class="md-nav__link">
<span class="md-ellipsis">
Step 1: Fetch Available Identity Providers
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#step-2-initialize-webview-and-load-sso-url" class="md-nav__link">
<span class="md-ellipsis">
Step 2: Initialize WebView and Load SSO URL
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#step-3-monitor-webview-url-changes" class="md-nav__link">
<span class="md-ellipsis">
Step 3: Monitor WebView URL Changes
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#step-4-extract-tokens-from-webview-cookies-store-tokens-securely-and-clean-up-the-webview" class="md-nav__link">
<span class="md-ellipsis">
Step 4: Extract tokens from WebView Cookies, store tokens securely and clean up the WebView
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#step-5-make-authenticated-api-requests" class="md-nav__link">
<span class="md-ellipsis">
Step 5: Make Authenticated API Requests
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#step-6-implement-token-refresh" class="md-nav__link">
<span class="md-ellipsis">
Step 6: Implement Token Refresh
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
@@ -1862,8 +2066,102 @@
<p>When authenticating via OAuth, the response format matches the standard authentication:</p>
<ul>
<li><strong>Web clients</strong>: Tokens set as HTTP-only cookies, redirected to app</li>
<li><strong>Mobile clients</strong>: Tokens returned in JSON format</li>
<li><strong>Mobile clients using WebView</strong>: Tokens set as HTTP-only cookies in WebView, redirected to app</li>
</ul>
<div class="admonition warning">
<p class="admonition-title">Mobile clients using WebView</p>
<p>Mobile apps must use WebView for OAuth/SSO flows to properly handle redirects and cookies. Tokens returned in JSON format is not currently supported for SSO.</p>
</div>
<h2 id="mobile-sso-implementation-guide">Mobile SSO Implementation Guide</h2>
<h3 id="overview">Overview</h3>
<p>Mobile applications must use an embedded WebView (or in-app browser) to handle OAuth/SSO authentication. The flow leverages browser-based redirects and cookie storage that are part of the OAuth 2.0 standard.</p>
<h3 id="prerequisites">Prerequisites</h3>
<ul>
<li>WebView component that supports:<ul>
<li>Cookie storage and management</li>
<li>JavaScript execution</li>
<li>URL interception/monitoring</li>
<li>Custom headers (for subsequent API calls)</li>
</ul>
</li>
<li>Secure storage for tokens (Keychain on iOS, KeyStore on Android)</li>
</ul>
<h3 id="step-by-step-implementation">Step-by-Step Implementation</h3>
<h4 id="step-1-fetch-available-identity-providers">Step 1: Fetch Available Identity Providers</h4>
<p>Before presenting SSO options to users, fetch the list of enabled providers:</p>
<p><strong>Request:</strong></p>
<div class="highlight"><pre><span></span><code><span class="err">GET /api/v1/public/idp</span>
</code></pre></div>
<p><strong>Response:</strong></p>
<div class="highlight"><pre><span></span><code><span class="p">[</span>
<span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="nt">&quot;id&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
<span class="w"> </span><span class="nt">&quot;name&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Keycloak&quot;</span><span class="p">,</span>
<span class="w"> </span><span class="nt">&quot;slug&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;keycloak&quot;</span><span class="p">,</span>
<span class="w"> </span><span class="nt">&quot;icon&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;keycloak&quot;</span>
<span class="w"> </span><span class="p">},</span>
<span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="nt">&quot;id&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span>
<span class="w"> </span><span class="nt">&quot;name&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Pocket ID&quot;</span><span class="p">,</span>
<span class="w"> </span><span class="nt">&quot;slug&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;pocket-id&quot;</span><span class="p">,</span>
<span class="w"> </span><span class="nt">&quot;icon&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;pocketid&quot;</span>
<span class="w"> </span><span class="p">}</span>
<span class="p">]</span>
</code></pre></div>
<h4 id="step-2-initialize-webview-and-load-sso-url">Step 2: Initialize WebView and Load SSO URL</h4>
<p>When user selects an SSO provider, open a WebView with the SSO initiation URL:</p>
<p><strong>URL to Load:</strong></p>
<div class="highlight"><pre><span></span><code>https://your-endurain-instance.com/api/v1/public/idp/login/{idp_slug}?redirect=/dashboard
</code></pre></div>
<p><strong>Parameters:</strong></p>
<ul>
<li><code>{idp_slug}</code>: The provider slug from Step 1 (e.g., "google", "keycloak")</li>
<li><code>redirect</code> (optional): Frontend path to navigate to after successful login</li>
</ul>
<p><strong>What Happens:</strong></p>
<ol>
<li>Backend generates OAuth state and authorization URL</li>
<li>WebView redirects to the identity provider's login page</li>
<li>User authenticates with the provider (enters credentials, 2FA, etc.)</li>
</ol>
<h4 id="step-3-monitor-webview-url-changes">Step 3: Monitor WebView URL Changes</h4>
<p>Set up URL interception to detect when the OAuth callback completes:</p>
<p><strong>URLs to Monitor:</strong></p>
<ul>
<li>Success: <code>https://your-endurain-instance.com/login?sso=success&amp;session_id={uuid}</code></li>
<li>Success with redirect: <code>https://your-endurain-instance.com/login?sso=success&amp;session_id={uuid}&amp;redirect=/dashboard</code></li>
<li>Error: <code>https://your-endurain-instance.com/login?error=sso_failed</code></li>
</ul>
<h4 id="step-4-extract-tokens-from-webview-cookies-store-tokens-securely-and-clean-up-the-webview">Step 4: Extract tokens from WebView Cookies, store tokens securely and clean up the WebView</h4>
<p>When SSO succeeds, extract authentication tokens from the WebView's cookie store and store them securely:</p>
<p><strong>Cookies to Extract:</strong></p>
<ul>
<li><code>endurain_access_token</code>: JWT access token (15 min expiry)</li>
<li><code>endurain_refresh_token</code>: JWT refresh token (7 day expiry)</li>
</ul>
<h4 id="step-5-make-authenticated-api-requests">Step 5: Make Authenticated API Requests</h4>
<p>Use extracted tokens for subsequent API calls with the required headers:</p>
<p><strong>Required Headers:</strong></p>
<ul>
<li><code>Authorization: Bearer {access_token}</code></li>
<li><code>X-Client-Type: mobile</code></li>
</ul>
<h4 id="step-6-implement-token-refresh">Step 6: Implement Token Refresh</h4>
<p>Access tokens expire after 15 minutes. Implement automatic refresh logic:</p>
<p><strong>Refresh Request:</strong></p>
<div class="highlight"><pre><span></span><code><span class="err">POST /api/v1/refresh</span>
<span class="err">Authorization: Bearer {refresh_token}</span>
<span class="err">X-Client-Type: mobile</span>
</code></pre></div>
<p><strong>Response:</strong></p>
<div class="highlight"><pre><span></span><code><span class="p">{</span>
<span class="w"> </span><span class="nt">&quot;access_token&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;eyJ...&quot;</span><span class="p">,</span>
<span class="w"> </span><span class="nt">&quot;refresh_token&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;eyJ...&quot;</span><span class="p">,</span>
<span class="w"> </span><span class="nt">&quot;session_id&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;uuid&quot;</span><span class="p">,</span>
<span class="w"> </span><span class="nt">&quot;token_type&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Bearer&quot;</span><span class="p">,</span>
<span class="w"> </span><span class="nt">&quot;expires_in&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">900</span>
<span class="p">}</span>
</code></pre></div>
<h2 id="configuration">Configuration</h2>
<h3 id="environment-variables">Environment Variables</h3>
<p>The following environment variables control authentication behavior:</p>

2
search/search_index.json
View File

File diff suppressed because one or more lines are too long