Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: ssr #439

Merged
merged 17 commits into from
Feb 8, 2024
Merged

feat: ssr #439

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
0da264d
feat: ssr
loks0n Dec 20, 2023
d1ee6d7
chore: rfac
loks0n Dec 20, 2023
3ced54e
chore: typo
loks0n Dec 20, 2023
d49d316
feat: ssr oauth explainer
loks0n Dec 21, 2023
ab2ca0f
Update src/routes/docs/products/auth/ssr/+page.markdoc
loks0n Dec 22, 2023
24146e2
Some improvements on SSR docs
Jan 10, 2024
0293415
Some suggestions
Jan 10, 2024
4462ca5
Merge branch '1.5.x' of https://github.com/appwrite/website into feat…
loks0n Jan 13, 2024
0209dc8
Merge branch 'feat-ssr' of https://github.com/appwrite/website into f…
loks0n Jan 13, 2024
3a27c87
Update src/routes/docs/products/auth/ssr/+page.markdoc
loks0n Jan 31, 2024
f0d2879
Merge branch '1.5.x' of https://github.com/appwrite/website into feat…
loks0n Feb 6, 2024
9531dac
chore: ssr journeys update
loks0n Feb 6, 2024
0e034e9
feat: svelte ssr auth
loks0n Feb 6, 2024
a53d726
chore: OAuth 2 -> OAuth2
loks0n Feb 6, 2024
838204c
feat: tokens concept page
loks0n Feb 6, 2024
1917731
chore: vincent review
loks0n Feb 8, 2024
4bfcdc1
chore: vincent review
loks0n Feb 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
220 changes: 114 additions & 106 deletions src/routes/docs/products/auth/+layout.svelte
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,113 +1,121 @@
<script lang="ts">
import Docs from '$lib/layouts/Docs.svelte';
import Sidebar, { type NavParent, type NavTree } from '$lib/layouts/Sidebar.svelte';
import Docs from '$lib/layouts/Docs.svelte';
import Sidebar, { type NavParent, type NavTree } from '$lib/layouts/Sidebar.svelte';

const parent: NavParent = {
href: '/docs',
label: 'Auth'
};
const parent: NavParent = {
href: '/docs',
label: 'Auth'
};

const navigation: NavTree = [
{
label: 'Getting started',
items: [
{
label: 'Overview',
href: '/docs/products/auth'
},
{
label: 'Quick start',
href: '/docs/products/auth/quick-start'
}
]
},
{
label: 'Concepts',
items: [
{
label: 'Accounts',
href: '/docs/products/auth/accounts'
},
{
label: 'Users',
href: '/docs/products/auth/users'
},
{
label: 'Teams',
href: '/docs/products/auth/teams'
},
{
label: 'Labels',
href: '/docs/products/auth/labels'
},
{
label: 'Security',
href: '/docs/products/auth/security'
}
]
},
{
label: 'Journeys',
items: [
{
label: 'Email and password login',
href: '/docs/products/auth/email-password'
},
{
label: 'Phone (SMS) login',
href: '/docs/products/auth/phone-sms'
},
{
label: 'Magic URL login',
href: '/docs/products/auth/magic-url'
},
{
label: 'Email OTP login',
href: '/docs/products/auth/email-otp'
},
{
label: 'OAuth 2 login',
href: '/docs/products/auth/oauth2'
},
{
label: 'Anonymous login',
href: '/docs/products/auth/anonymous'
},
{
label: 'JWT login',
href: '/docs/products/auth/jwt'
},
{
label: 'Custom token login',
href: '/docs/products/auth/custom-token'
},
{
label: 'Multi-factor authentication',
href: '/docs/products/auth/mfa'
},
]
},
{
label: 'References',
items: [
{
label: 'Account API',
href: '/docs/references/cloud/client-web/account'
},
{
label: 'Users API',
href: '/docs/references/cloud/server-nodejs/users'
},
{
label: 'Teams API',
href: '/docs/references/cloud/client-web/teams'
}
]
},
];
const navigation: NavTree = [
{
label: 'Getting started',
items: [
{
label: 'Overview',
href: '/docs/products/auth'
},
{
label: 'Quick start',
href: '/docs/products/auth/quick-start'
}
]
},
{
label: 'Concepts',
items: [
{
label: 'Accounts',
href: '/docs/products/auth/accounts'
},
{
label: 'Users',
href: '/docs/products/auth/users'
},
{
label: 'Teams',
href: '/docs/products/auth/teams'
},
{
label: 'Labels',
href: '/docs/products/auth/labels'
},
{
label: 'Security',
href: '/docs/products/auth/security'
},
{
label: 'Tokens',
href: '/docs/products/auth/tokens'
}
]
},
{
label: 'Journeys',
items: [
{
label: 'Email and password login',
href: '/docs/products/auth/email-password'
},
{
label: 'Phone (SMS) login',
href: '/docs/products/auth/phone-sms'
},
{
label: 'Magic URL login',
href: '/docs/products/auth/magic-url'
},
{
label: 'Email OTP login',
href: '/docs/products/auth/email-otp'
},
{
label: 'OAuth2 login',
href: '/docs/products/auth/oauth2'
},
{
label: 'Anonymous login',
href: '/docs/products/auth/anonymous'
},
{
label: 'JWT login',
href: '/docs/products/auth/jwt'
},
{
label: 'SSR login',
href: '/docs/products/auth/server-side-rendering'
},
{
label: 'Custom token login',
href: '/docs/products/auth/custom-token'
},
{
label: 'Multi-factor authentication',
href: '/docs/products/auth/mfa'
}
]
},
{
label: 'References',
items: [
{
label: 'Account API',
href: '/docs/references/cloud/client-web/account'
},
{
label: 'Users API',
href: '/docs/references/cloud/server-nodejs/users'
},
{
label: 'Teams API',
href: '/docs/references/cloud/client-web/teams'
}
]
}
];
</script>

<Docs variant="two-side-navs">
<Sidebar {navigation} {parent} />
<slot />
<Sidebar {navigation} {parent} />
<slot />
</Docs>
2 changes: 1 addition & 1 deletion src/routes/docs/products/auth/accounts/+page.markdoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Each user's account can also have their own preference object, which you can use

You can signup and login a user with an account created through
[Email and password](/docs/products/auth/email-password),
[OAuth 2](/docs/products/auth/oauth2),
[OAuth2](/docs/products/auth/oauth2),
[Magic URL](/docs/products/auth/magic-url),
[Email OTP](/docs/products/auth/email-otp),
[Phone (SMS)](/docs/products/auth/phone-sms),
Expand Down
46 changes: 23 additions & 23 deletions src/routes/docs/products/auth/oauth2/+page.markdoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,28 +1,28 @@
---
layout: article
title: OAuth 2 login
title: OAuth2 login
description: Integrate OAuth2 authentication seamlessly with Appwrite. Learn how to connect your application with third-party OAuth2 providers for secure user login and access.
---

OAuth authentication allows users to log in using accounts from other popular services. This can be convenient for users because they can start using your app without creating a new account. It can also be more secure, because the user has one less password that could become vulnerable.

When using OAuth to authenticate, the authentication request is initiated from the client application. The user is then redirected to an OAuth 2 provider to complete the authentication step, and finally, the user is redirected back to your application.
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 your application.

# Configure OAuth 2 login {% #configure %}
# Configure OAuth2 login {% #configure %}

Before using OAuth 2 login, you need to enable and configure an OAuth 2 provider.
Before using OAuth2 login, you need to enable and configure an OAuth2 provider.

1. Navigate to your Appwrite project.
2. Navigate to **Auth** > **Settings**.
3. Find and open the OAuth provider.
4. In the OAuth 2 settings modal, use the toggle to enable the provider.
5. Create and OAuth 2 app on the provider's developer platform.
4. In the OAuth2 settings modal, use the toggle to enable the provider.
5. Create and OAuth2 app on the provider's developer platform.
6. Copy information from your OAuth2 provider's developer platform to fill the **OAuth2 Settings** modal in the Appwrite Console.
7. Configure redirect URL in your OAuth 2 provider's developer platform. Set it to URL provided to you by **OAuth2 Settings** modal in Appwrite Console.
7. Configure redirect URL in your OAuth2 provider's developer platform. Set it to URL provided to you by **OAuth2 Settings** modal in Appwrite Console.

# Initialize OAuth 2 login {% #init %}
# Initialize OAuth2 login {% #init %}

To initialize the OAuth 2 login process, use the [Create OAuth 2 Session](/docs/references/cloud/client-web/account#createOAuth2Session) endpoint.
To initialize the OAuth2 login process, use the [Create OAuth2 Session](/docs/references/cloud/client-web/account#createOAuth2Session) endpoint.

{% tabs %}
{% tabsitem #js title="Javascript" %}
Expand All @@ -39,7 +39,7 @@ const account = new Account(client);
account.createOAuth2Session('github', '[LINK_ON_SUCCESS]', '[LINK_ON_FAILURE]', true);
```

Users will be redirected to the OAuth 2 provider's login page to log in. Once complete, your user will be redirected back to your app.
Users will be redirected to the OAuth2 provider's login page to log in. Once complete, your user will be redirected back to your app.

In your web application, you need to finish OAuth authentication using [Create session](/docs/references/cloud/client-web/account#createSession) endpoint. Both user ID and token secret will be provided to you in the URL params.

Expand Down Expand Up @@ -67,7 +67,7 @@ final account = Account(client);
await account.createOAuth2Session(provider: 'github');
```

User will be redirected to the OAuth 2 provider's login page to log in. Once complete, your user will be redirected back to your app.
User will be redirected to the OAuth2 provider's login page to log in. Once complete, your user will be redirected back to your app.

You can optionally configure `success` or `failure` redirect links for having custom logic for handling those scenarios.
{% /tabsitem %}
Expand Down Expand Up @@ -100,7 +100,7 @@ val account = Account(client)
account.createOAuth2Session(provider = "github")
```

User will be redirected to the OAuth 2 provider's login page to log in. Once complete, your user will be redirected back to your app.
User will be redirected to the OAuth2 provider's login page to log in. Once complete, your user will be redirected back to your app.

You can optionally configure `success` or `failure` redirect links for having custom logic for handling those scenarios.

Expand Down Expand Up @@ -149,18 +149,18 @@ let account = Account(client)
try await account.createOAuth2Session(provider: "amazon")
```

User will be redirected to the OAuth 2 provider's login page to log in. Once complete, your user will be redirected back to your app.
User will be redirected to the OAuth2 provider's login page to log in. Once complete, your user will be redirected back to your app.

You can optionally configure `success` or `failure` redirect links for having custom logic for handling those scenarios.

{% /tabsitem %}
{% /tabs %}

# OAuth 2 profile {% #profile %}
# OAuth2 profile {% #profile %}

After authenticating a user through their OAuth 2 provider, you can fetch their profile information such as their avatar image or name. To do this you can use the access token from the OAuth 2 provider and make API calls to the provider.
After authenticating a user through their OAuth2 provider, you can fetch their profile information such as their avatar image or name. To do this you can use the access token from the OAuth2 provider and make API calls to the provider.

After creating an OAuth 2 session, you can fetch the session to get information about the provider.
After creating an OAuth2 session, you can fetch the session to get information about the provider.

{% multicode %}
```js
Expand Down Expand Up @@ -238,20 +238,20 @@ print(session.providerAccessToken);
{% /multicode %}


An OAuth 2 [session](/docs/references/cloud/models/session) will have the following attributes.
An OAuth2 [session](/docs/references/cloud/models/session) will have the following attributes.

| Property | Description |
| -------------------------- | --------------------------------------------------------------------------------------------------------- |
| provider | The OAuth2 Provider. |
| providerUid | User ID from the OAuth 2 Provider. |
| providerAccessToken | Access token from the OAuth 2 provider. Use this to **make requests to the OAuth 2 provider** to fetch personal data. |
| providerUid | User ID from the OAuth2 Provider. |
| providerAccessToken | Access token from the OAuth2 provider. Use this to **make requests to the OAuth2 provider** to fetch personal data. |
| providerAccessTokenExpiry | Check this value to know if an access token is about to expire. |

You can use the `providerAccessToken` to make requests to your OAuth 2 provider. Refer to the docs for the OAuth 2 provider you're using to learn about making API calls with the access token.
You can use the `providerAccessToken` to make requests to your OAuth2 provider. Refer to the docs for the OAuth2 provider you're using to learn about making API calls with the access token.

# Refreshing OAuth 2 tokens {% #refreshing-tokens %}
# Refreshing OAuth2 tokens {% #refreshing-tokens %}

OAuth 2 sessions expire to protect from security risks. OAuth 2 sessions should be refreshed periodically, so access tokens don't expire. Check value of `providerAccessTokenExpiry` to know if the token is expired or is about to expire. Refreshing before every request might cause rate limit problems. You can do this by calling the [Update session](/docs/references/cloud/client-web/account#updateSession) endpoint right before token expiry, or before first request after expiry.
OAuth2 sessions expire to protect from security risks. OAuth2 sessions should be refreshed periodically, so access tokens don't expire. Check value of `providerAccessTokenExpiry` to know if the token is expired or is about to expire. Refreshing before every request might cause rate limit problems. You can do this by calling the [Update session](/docs/references/cloud/client-web/account#updateSession) endpoint right before token expiry, or before first request after expiry.

{% multicode %}
```js
Expand Down Expand Up @@ -307,5 +307,5 @@ let session = try await account.updateSession(
{% /multicode %}

{% info title="GraphQL" %}
OAuth 2 is not available through the GraphQL API. You can use the REST API or any Client SDK instead.
OAuth2 is not available through the GraphQL API. You can use the REST API or any Client SDK instead.
{% /info %}
2 changes: 1 addition & 1 deletion src/routes/docs/products/auth/quick-start/+page.markdoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -171,7 +171,7 @@ mutation {
# More ways to authenticate {% #more-ways-to-authenticate %}
You can signup and login a user with an account created through
[Email and password](/docs/products/auth/email-password),
[OAuth 2](/docs/products/auth/oauth2),
[OAuth2](/docs/products/auth/oauth2),
[Magic URL](/docs/products/auth/magic-url),
[Email OTP](/docs/products/auth/email-otp),
[Phone (SMS)](/docs/products/auth/phone-sms),
Expand Down
Loading