Skip to content
This repository was archived by the owner on Sep 29, 2023. It is now read-only.

Commit 1b1b328

Browse files
eldadfuxeldadfux
authored
Merge pull request #258 from appwrite/fix-auth-list-font
Authentication Guide Improvements
2 parents 6b17f2f + ddf14fb commit 1b1b328

File tree

5 files changed

+84
-33
lines changed

5 files changed

+84
-33
lines changed

‎app/views/docs/authentication.phtml

Lines changed: 69 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
Accounts can be created in many different ways, such as through an anonymous session, email and password, OAuth authentication, magic URLs, and more.
55
</p>
66

7-
<h2><a href="/docs/authentication#account-vs-user-service" id="account-vs-user-service">Account vs User Service</a></h2>
7+
<h2><a href="/docs/authentication#account-vs-user-api" id="account-vs-user-api">Account vs Users API</a></h2>
88

99
<p>
1010
The Account API operates in the scope of the currently logged-in account and is usually used in a frontend or mobile app. The Users API is used in backend integrations and operates in an admin scope using an API key with access to all your project users.
@@ -92,6 +92,10 @@ promise.then(function (response) {
9292
OAuth is another way to authenticate a user using a multi-step process. When using OAuth to authenticate, the authentication request is initiated from the client application. The user is then redirected to an OAuth2 provider to complete the authentication step, and finally, the user is redirected back to the client application. This provides integration with many third-party services that provide their own OAuth integration as a more secure approach than providing a username/password directly.
9393
</p>
9494

95+
<p>
96+
In applications with first-party redirects, using OAuth2 for authentication is preferred.
97+
</p>
98+
9599
<p>
96100
The example below shows you how to authenticate with OAuth2 using the Web SDK and Amazon's OAuth system.
97101
</p>
@@ -251,34 +255,73 @@ promise.then(function (response) {
251255
Appwrite handles the persistence of the session in a consistent way across SDKs. After authenticating with an SDK, the SDK will persist the session so that the user will not need to log in again the next time they open the app. The mechanism for persistence depends on the SDK.
252256
</p>
253257

254-
<ul>
255-
<li class="margin-bottom-tiny">Web - Uses a session secure cookie and falls back to local storage when a session cookie is not available.</li>
256-
<li class="margin-bottom-tiny">Flutter - Uses a session cookie stored in Application Documents through the path_provider package.</li>
257-
<li class="margin-bottom-tiny">Apple - Uses a session cookie.</li>
258-
<li class="margin-bottom-tiny">Android - Uses a session cookie stored in SharedPreferences.</li>
259-
</ul>
258+
<div class="notice">
259+
<h2>Best Practice</h2>
260+
<p>Only keep user sessions active as long as needed and only maintain <b>one</b> instance of the Client SDK in your app to avoid conflicting session data.</p>
261+
</div>
262+
263+
<table cellspacing="0" cellpadding="0" border="0" class="full margin-bottom-large text-size-small vertical">
264+
<thead>
265+
<tr>
266+
<th style="width: 80px"></th>
267+
<th style="width: 120px">SDK</th>
268+
<th>Persistence Method</th>
269+
</tr>
270+
</thead>
271+
<tbody>
272+
<tr>
273+
<td>
274+
<img src="/images-ee/platforms/web.svg" alt="Logo" height="30" class="force-light sdk-logo margin-start margin-end" />
275+
<img src="/images-ee/platforms/dark/web.svg" alt="Logo" height="30" class="force-dark sdk-logo margin-start margin-end" />
276+
</td>
277+
<td>
278+
Web
279+
</td>
280+
<td>
281+
Uses a session secure cookie and falls back to local storage when a session cookie is not available.
282+
</td>
283+
</tr>
284+
<tr>
285+
<td>
286+
<img src="/images-ee/platforms/flutter.svg" alt="Logo" height="30" class="force-light sdk-logo margin-start margin-end" />
287+
<img src="/images-ee/platforms/dark/flutter.svg" alt="Logo" height="30" class="force-dark sdk-logo margin-start margin-end" />
288+
</td>
289+
<td>
290+
Flutter
291+
</td>
292+
<td>
293+
Uses a session cookie stored in Application Documents through the <b>path_provider</b> package.
294+
</td>
295+
</tr>
296+
<tr>
297+
<td>
298+
<img src="/images-ee/platforms/apple.svg" alt="Logo" height="30" class="force-light sdk-logo margin-start margin-end" />
299+
<img src="/images-ee/platforms/dark/apple.svg" alt="Logo" height="30" class="force-dark sdk-logo margin-start margin-end" />
300+
</td>
301+
<td>
302+
Apple
303+
</td>
304+
<td>
305+
Uses a session cookie stored in <b>UserDefaults</b>.
306+
</td>
307+
</tr>
308+
<tr>
309+
<td>
310+
<img src="/images-ee/platforms/android.svg" alt="Logo" height="30" class="force-light sdk-logo margin-start margin-end" />
311+
<img src="/images-ee/platforms/dark/android.svg" alt="Logo" height="30" class="force-dark sdk-logo margin-start margin-end" />
312+
</td>
313+
<td>
314+
Android
315+
</td>
316+
<td>
317+
Uses a session cookie stored in <b>SharedPreferences</b>.
318+
</td>
319+
</tr>
320+
</tbody>
321+
</table>
260322

261323
<h2><a href="/docs/authentication#security" id="security">Security</a></h2>
262324

263325
<p>
264326
Security is very important to protect users' data and privacy. Appwrite uses a <a href="/docs/permissions">permissions model</a> coupled with user sessions to ensure users only have access to certain information based on the permissions. With Appwrite services, including databases and storage, access is granted at the collection, bucket, document, or file level. This access is consistent across access to these items in relation to document access, file access, and real-time events.
265327
</p>
266-
267-
<h2><a href="/docs/authentication#best-practices" id="best-practices">Best Practices</a></h2>
268-
269-
<p>
270-
Here are some common best practices when handling sessions and keys used for authentication purposes.
271-
</p>
272-
273-
<ol>
274-
<li class="margin-bottom-tiny">Only keep user sessions active as long as needed.</li>
275-
<li class="margin-bottom-tiny">Only grant scopes required for your use case for your APIs keys, and nothing more.</li>
276-
<li class="margin-bottom-tiny">Access Appwrite via HTTPS to prevent any redirects from interfering with your requests.</li>
277-
<li class="margin-bottom-tiny">Prefer using OAuth2 for authentication with first-party redirects.</li>
278-
<li class="margin-bottom-tiny">Generate an SSL certification for the Appwrite instance.</li>
279-
<li class="margin-bottom-tiny">Keep API keys private and out of client-side code.</li>
280-
<li class="margin-bottom-tiny">Only maintain <b>1</b> instance of the Client SDK in your app to avoid conflicting session data.</li>
281-
<li class="margin-bottom-tiny">When using the realtime service to get users' documents, clean up and resubscribe to the correct resources to maintain the correct app state.</li>
282-
<li class="margin-bottom-tiny">Unsubscribing from old resources is also recommended to prevent possible race conditions.</li>
283-
</ol>
284-

‎app/views/docs/index.phtml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -71,20 +71,20 @@ $cols = [
7171
</div>
7272

7373
<ul class="margin-bottom">
74-
<li><a href="/docs/authentication">Authentication</a></li>
75-
<li><a href="/docs/realtime">Realtime</a></li>
7674
<li><a href="/docs/databases">Databases</a></li>
7775
<li><a href="/docs/storage">Storage</a></li>
76+
<li><a href="/docs/authentication">Authentication</a></li>
7877
<li><a href="/docs/functions">Functions</a></li>
79-
<li><a href="/docs/keys">API Keys</a></li>
80-
<li><a href="/docs/webhooks">Webhooks</a></li>
78+
<li><a href="/docs/realtime">Realtime</a></li>
8179
</ul>
8280

8381
<div class="margin-bottom-small">
8482
<b class="text-size-small">Advanced</b>
8583
</div>
8684

8785
<ul class="margin-bottom">
86+
<li><a href="/docs/keys">API Keys</a></li>
87+
<li><a href="/docs/webhooks">Webhooks</a></li>
8888
<li><a href="/docs/pagination">Pagination</a></li>
8989
<li><a href="/docs/custom-domains">Custom Domains</a></li>
9090
<li><a href="/docs/permissions">Permissions</a></li>

‎app/views/docs/keys.phtml

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,12 @@ $scopes = $this->getParam('scopes', );
44

55
<p>Using your API Keys, you can access Appwrite services using the SDK of your choice. To create a new API key, go to your API keys tab in your project setting using your Appwrite console and click the 'Add API Key' button.</p>
66

7-
<p>When adding a new API Key, you can choose which permission scope to grant your application. It is a best practice to allow only the permissions you need to meet your project goals.</p>
7+
<p>When adding a new API Key, you can choose which scope to grant your application. If you need to replace your API Key, create a new key, update your app credentials and, once ready, delete your old key.</p>
88

9-
<p>If you need to replace your API Key, create a new key, update your app credentials and, once ready, delete your old key.</p>
9+
<div class="notice">
10+
<h2>Best Practice</h2>
11+
<p>It is a best practice to grant only the scopes you need to meet your project's goals to an API key. API keys should be treated as a secret. Never share the API key and keep API keys out of client applications.</p>
12+
</div>
1013

1114
<h2 id="scopes">Scopes</h2>
1215

‎app/views/docs/production.phtml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,11 @@
66

77
<p>Make sure to keep this key in a safe place and never make it publicly accessible. There are many online resources with methods of keeping your secret keys safe in your servers.</p>
88

9+
<div class="notice">
10+
<h2>Best Practice</h2>
11+
<p>You should always prefer <b>https</b> over http in production environments. This keeps your APIs secure and prevents any redirects from interfering with your requests.</p>
12+
</div>
13+
914
<h2><a href="/docs/production#limitConsoleAccess" id="limitConsoleAccess">Limit Console Access</a></h2>
1015

1116
<p>By default, anyone can signup for your Appwrite server, create projects, and use your computing power. While this is great for testing around or running your Appwrite service in a network isolated environment, it is highly not recommended for public production use.</p>

‎app/views/docs/realtime.phtml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -282,7 +282,7 @@ realtime.subscribe(channels: ["databases.A.collections.A.documents.A", "files"])
282282

283283
<h3><a href="/docs/realtime#unsubscribe" id="unsubscribe">Unsubscribe</a></h3>
284284

285-
<p>If you no longer want to receive updates from a subscription, you can unsubscribe so that your callbacks are no longer called.</p>
285+
<p>If you no longer want to receive updates from a subscription, you can unsubscribe so that your callbacks are no longer called. Leaving old subscriptions alive and resubscribing can result in duplicate subscriptions and cause race conditions.</p>
286286

287287
<ul class="phases clear" data-ui-phases>
288288
<li>

0 commit comments

Comments
 (0)