Split auth guide, add label, team, and password security to docs. #412

gewenyu99 · 2023-08-11T18:50:02Z

What does this PR do?

(Provide a description of what this PR does.)

Test Plan

(Write your test plan here. If you changed any code, please provide us with clear instructions on how you verified your changes work.)

Related PRs and Issues

(If this PR is related to any other PR or resolves any issue or related to any issue link all related PR and issues here.)

Have you read the Contributing Guidelines on issues?

(Write your answer here.)

stnguyen90 · 2023-08-17T21:37:09Z

app/views/docs/authentication-management.phtml

+
+[TODO @steven: TEAMS docs]
+
+[TODO @steven: Labels docs]


Labels are a good way to flag a user to grant them access to resources. For example, a subscriber label can be added to a user once they've purchased a subscription:

const sdk = require('node-appwrite'); const client = new sdk.Client(); const users = new sdk.Users(client); users.updateLabels( '[USER_ID]', [ sdk.Role.label('subscriber'), ] );

And a collection can be be given read access to users with that label:

const sdk = require('node-appwrite'); const client = new sdk.Client(); const databases = new sdk.Databases(client); databases.updateCollection( '[DATABASE_ID]', '[COLLECTION_ID]', '[NAME]', [ sdk.Permissions.read(sdk.Role.label('subscriber')), ] );

stnguyen90

I added some notes. Let me know if you need any additional clarification.

stnguyen90 · 2023-08-17T21:44:48Z

app/views/docs/authentication-management.phtml

+    Each user can also have their own preference object, which you can use to save preferences such as theme, language, and notification settings.
+</p>
+
+[TODO @steven: TEAMS docs]


Teams are a good way to allow users to collaborate and share access to resources. For example, in a todo app, a user can create a team for one of their todo lists and invite another user to the team to grant the other user access. The invited user can accept the invitation to gain access or ignore it if they don't want to gain access.

If you'd like for users to collaborate without requiring users to accept the invitation, use an Appwrite Function and server SDK to add a user to a team.

stnguyen90 · 2023-08-17T21:53:04Z

app/views/docs/authentication-oauth.phtml

+
+<h2><a href="#profile" id="profile">OAuth 2 Profile</a></h2>
+<p>
+    [TODO: @steven fill the docs to access oauth account profile information]


It's common to fetch information from an OAuth2 provider such as an avatar image. To do this you can use the access token from the OAuth2 provider and make API calls to the provider.

After creating an OAuth2 session, you can fetch the session with:

import { Client, Account } from "appwrite"; const client = new Client(); const account = new Account(client); account.getSession('current');

An OAuth2 session will have the following attributes set:

provider: The OAuth2 Provider

providerUid: User ID from the OAuth2 Provider

provderAccessToken: Access token from the OAuth2 provider that can be used to make API calls to the OAuth2 Provider

Refer to the docs for the OAuth2 provider for how to make an API call with the access token.

…docs into feat-auth-improvements

gewenyu99 · 2023-08-18T20:30:22Z

gewenyu99 · 2023-08-18T20:30:36Z

gewenyu99 · 2023-08-18T20:30:47Z

gewenyu99 · 2023-08-18T20:31:01Z

gewenyu99 · 2023-08-18T20:31:12Z

gewenyu99 · 2023-08-18T20:31:24Z

gewenyu99 · 2023-08-18T20:31:35Z

gewenyu99 · 2023-08-18T20:31:45Z

gewenyu99 · 2023-08-18T20:32:04Z

eldadfux · 2023-08-22T05:18:39Z

In the console, we call personal information -> personal data, let's be consistent.
We should probably mention that for non-web platforms success and failure URLs are optional and Appwrite will handle the redirect. They also need some additional settings to allow the redirect to their apps to work.
Is magic URL working on mobile? I think we also need some additional settings there

gewenyu99 · 2023-08-23T00:31:35Z

In the console, we call personal information -> personal data, let's be consistent.

We should probably mention that for non-web platforms success and failure URLs are optional and Appwrite will handle the redirect. They also need some additional settings to allow the redirect to their apps to work.

Is magic URL working on mobile? I think we also need some additional settings there

I was considering just dropping magic URL in the docs... I don't think it works.

Meldiron · 2023-08-27T07:52:45Z

app/views/docs/authentication-anonymous.phtml

+<h2><a href="#attach-account" id="attach-account">Attaching an Account</a></h2>
+<p>
+    Anonymous users cannot sign back in. 
+    If they close their browser, or go to another computer, they won't be able to log in again.


Step of closing browser here sounds irelevant. Also would be good to mention here that we store session information in cookies, so clearing browser might also cause sign out.

app/views/docs/authentication-magic.phtml

Meldiron · 2023-08-27T07:55:22Z

app/views/docs/authentication-magic.phtml

+
+<p>
+    Initialize the log in process with the <a href="/docs/client/account#accountCreateMagicURLSession">Create Magic URL Session</a> route.
+    If the email has never been used, a <b>new user ID is generated</b>, then the user will receive an email. 


new user ID is generated
Buuut only if they pass unique(). If they provide custom ID, user with that ID will try to be created (unless its already used by other user)

app/views/docs/authentication-magic.phtml

Meldiron · 2023-08-27T07:57:43Z

app/views/docs/authentication-magic.phtml

+    userId: 'email@example.com',
+    secret: '[SECRET]',


Suggested change

userId: 'email@example.com',

secret: '[SECRET]',

userId: '[ID_FROM_EMAL_PARAMS]',

secret: '[SECRET_FROM_EMAIL_PARAMS]',

Let's do something like that here, and in other exmapes where we don't provide example of parsing URL

We just removed mobile platform... MagicURL doesn't work with out some voodoo magic. I saw Damodar's attempt of explaining it. It's a little much.

Meldiron · 2023-08-27T07:58:57Z

app/views/docs/authentication-management.phtml

+
+const account = new Account(client);
+
+const user = await account.updatePrefs({darkTheme: true, language: 'en'});</code></pre>


Lets use typical promise.then() syntax

Please check the whole PR. This should be done in ~dozen palces.

Some places, we can't use promise.then(), basically when ever we have a 2 part example where you need to save something from the returned object.

But this should indeed be .then

Fixed here. There are some palces where this is used on purpose, because we're saving the objects returned.

Meldiron · 2023-08-27T07:59:53Z

app/views/docs/authentication-management.phtml

+    accountUpdatePrefs(
+        prefs: "{\"darkTheme\": true, \"language\": \"en\"}"
+    ) {
+        _id
+        _createdAt
+        _updatedAt
+        name
+        registration
+        status
+        passwordUpdate
+        email
+        phone
+        emailVerification
+        phoneVerification
+        prefs {
+            data
+        }


I think we can remove most of this. getting just prefs back would be fine I think

Meldiron · 2023-08-27T08:01:17Z

app/views/docs/authentication-management.phtml

+        <div class="ide margin-top-small" data-lang="nodejs" data-lang-label="Node.js SDK">
+            <pre class="line-numbers"><code class="prism language-javascript" data-prism>const sdk = require('node-appwrite');
+
+const client = new sdk.Client();


Missing client initialization. setEndpoint, setPRoject, setApiKey..

Meldiron · 2023-08-27T08:01:26Z

app/views/docs/authentication-management.phtml

+    .setProject('5df5acd0d48c2') // Your project ID
+    .setKey('919c2d18fb5d4...a2ae413da83346ad2') // Your secret API key


I think we can use typical placeholders here

Let's check all places

We use '919c2d18fb5d4...a2ae413da83346ad2' all over the place, I think it's fine. We historically found that people didn't know that a key looks like a giant hash

app/views/docs/authentication-management.phtml

app/views/docs/authentication-oauth.phtml

Meldiron · 2023-08-27T08:09:06Z

app/views/docs/authentication-oauth.phtml

+
+<p>
+    You'll be redirected to the OAuth 2 provider's login page to log in. 
+    Once complete, you'll be redirected to the redirect URL configured in your OAuth 2 provider.


This is internal complexity (it redirect to appwrite API)
We could say:

Once complete, you will be redirected back to Appwrite API where user and session is created. User is next (almost instantly) redirected back to your application.

Meldiron · 2023-08-27T08:10:21Z

app/views/docs/authentication-oauth.phtml

+</p>
+
+<p>
+    You can optionally configure <code>success</code> or <code>failure</code> redirect links on web to handle success and failure scenarios.


For web, let's talk about 1st party cookies.

By default, OAuth flow on web won't work in some browsers (most mobile browsers, and Safari). Reason is they don't allow your web app (on your domain) to access cookies set on API cloud.appwrite.io domain.
To solve this, you need to setup custom domain that is subdomain of your app domain, for example appwrite.myapp.com

Yeah, this is just a "bug" we need to fix. I discuss this many times with Eldad, the consesus is we just need to fix this. This is way too much for someone to consider...

😆 Yeah... this will need to be covered in depth later but what's more likely is that we'll want to fix this behavior...

Gonna omit it this time round.

app/views/docs/authentication-oauth.phtml

Meldiron · 2023-08-27T08:12:33Z

app/views/docs/authentication-oauth.phtml

+<h2><a href="#refresh" id="refresh">Refresh Tokens</a></h2>
+<p>
+    OAuth 2 sessions expire to protect from security risks. 
+    OAuth 2 sessions should be periodically refreshed to keep the user authenticated. 


Suggested change

OAuth 2 sessions should be periodically refreshed to keep the user authenticated.

OAuth 2 sessions should be refreshed before using an access token that is expired. Check value of <code>providerAccessTokenExpiry</code> to know if the token is expired. Refreshing before every request might cause rate limit problems.

Added, but different from this.

Meldiron · 2023-08-27T08:12:46Z

app/views/docs/authentication-oauth.phtml

+        <td> User ID from the OAuth 2 Provider.</td>
+    </tr>
+    <tr>
+        <td>providerAccessToken</td>


Let's also mention providerAccessTokenExpiry

app/views/docs/authentication-security.phtml

Co-authored-by: Matej Bačo <matejbaco2000@gmail.com>

…docs into feat-auth-improvements

Vincent (Wen Yu) Ge added 4 commits August 11, 2023 01:32

Add some new pages for different auth methods.

459a5e2

Add auth method pages.

fce9b60

Add homepage list of auth methods

286867e

Add tags for engineers to add examples

c4e6f15

stnguyen90 self-requested a review August 14, 2023 18:10

Vincent (Wen Yu) Ge added 7 commits August 17, 2023 17:29

Fix web example format, add quickstart to auth

ff3c2b4

Fix auth index, add users api docs

21431cc

Fix auth index display names

672a6df

Maybe it should be user management vs just management

8050091

grammar check by GPT

e2f493e

Add info about personal information in auth docs

f1a41d2

Add more information about password security in Appwrite

61be417

gewenyu99 marked this pull request as ready for review August 17, 2023 20:37

stnguyen90 reviewed Aug 17, 2023

View reviewed changes

gewenyu99 changed the base branch from main to 1.4.x August 17, 2023 22:38

PineappleIOnic and others added 5 commits August 18, 2023 15:40

Improve Examples

e58af23

user management docs

9921120

OAuth docs additions with steven's comments

36a5b6b

Merge branch 'feat-auth-improvements' of https://github.com/appwrite/…

e52ae93

…docs into feat-auth-improvements

ChatGPT grammar check

a5b28d6

Where applicable, prefer promises because it's copyable.

47dd971

Vincent (Wen Yu) Ge added 3 commits August 23, 2023 00:34

Personal Information -> Data

7d01bd4

address OAuth2 issues like redirect

cda41f5

improve getting started guide because we should

a4eac31

Meldiron reviewed Aug 27, 2023

View reviewed changes

app/views/docs/authentication-magic.phtml Outdated Show resolved Hide resolved

Meldiron reviewed Aug 27, 2023

View reviewed changes

app/views/docs/authentication-magic.phtml Outdated Show resolved Hide resolved

Meldiron reviewed Aug 27, 2023

View reviewed changes

app/views/docs/authentication-magic.phtml Outdated Show resolved Hide resolved

Meldiron reviewed Aug 27, 2023

View reviewed changes

app/views/docs/authentication-management.phtml Show resolved Hide resolved

Meldiron reviewed Aug 27, 2023

View reviewed changes

app/views/docs/authentication-oauth.phtml Outdated Show resolved Hide resolved

Meldiron reviewed Aug 27, 2023

View reviewed changes

app/views/docs/authentication-oauth.phtml Show resolved Hide resolved

Meldiron reviewed Aug 27, 2023

View reviewed changes

app/views/docs/authentication-security.phtml Outdated Show resolved Hide resolved

Vincent (Wen Yu) Ge and others added 3 commits August 27, 2023 11:17

Apply suggestions from code review

3eaa246

Co-authored-by: Matej Bačo <matejbaco2000@gmail.com>

Fix code example errors and other items pointed out during review

56213ec

Merge branch 'feat-auth-improvements' of https://github.com/appwrite/…

f06a4b6

…docs into feat-auth-improvements

gewenyu99 merged commit 345c206 into 1.4.x Aug 27, 2023

This was referenced Sep 1, 2023

PRs Opened in August 2023 appwrite/.github#69

Closed

PRs Closed in August 2023 appwrite/.github#70

Closed


		const account = new Account(client);

		const user = await account.updatePrefs({darkTheme: true, language: 'en'});</code></pre>

		.setProject('5df5acd0d48c2') // Your project ID
		.setKey('919c2d18fb5d4...a2ae413da83346ad2') // Your secret API key

	OAuth 2 sessions should be periodically refreshed to keep the user authenticated.
	OAuth 2 sessions should be refreshed before using an access token that is expired. Check value of <code>providerAccessTokenExpiry</code> to know if the token is expired. Refreshing before every request might cause rate limit problems.

Split auth guide, add label, team, and password security to docs. #412

Split auth guide, add label, team, and password security to docs. #412

Conversation

gewenyu99 commented Aug 11, 2023

What does this PR do?

Test Plan

Related PRs and Issues

Have you read the Contributing Guidelines on issues?

stnguyen90 Aug 17, 2023 • edited Loading

Choose a reason for hiding this comment

stnguyen90 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gewenyu99 commented Aug 18, 2023

gewenyu99 commented Aug 18, 2023 • edited Loading

gewenyu99 commented Aug 18, 2023

gewenyu99 commented Aug 18, 2023

gewenyu99 commented Aug 18, 2023

gewenyu99 commented Aug 18, 2023

gewenyu99 commented Aug 18, 2023

gewenyu99 commented Aug 18, 2023

gewenyu99 commented Aug 18, 2023

eldadfux commented Aug 22, 2023

gewenyu99 commented Aug 23, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Meldiron Aug 27, 2023 • edited by gewenyu99 Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stnguyen90 Aug 17, 2023 •

edited

Loading

gewenyu99 commented Aug 18, 2023 •

edited

Loading

Meldiron Aug 27, 2023 •

edited by gewenyu99

Loading