From d9d5f6951689bb58beaedc11e469624540c73d46 Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Thu, 8 Jun 2023 19:16:33 +0000 Subject: [PATCH 1/8] Init github oauth provider guide --- app/views/docs/oauth-providers/github.md | 86 ++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 app/views/docs/oauth-providers/github.md diff --git a/app/views/docs/oauth-providers/github.md b/app/views/docs/oauth-providers/github.md new file mode 100644 index 000000000..0a0dd26d9 --- /dev/null +++ b/app/views/docs/oauth-providers/github.md @@ -0,0 +1,86 @@ +# GitHub provider + +Appwrite allows you to authenticate users using their GitHub account through the GitHub OAuth2 provider. OAuth authentication is a great way to reduce friction for your users and increase user conversion by simplifying the signup process. You can learn more about Appwrite's other OAuth2 providers [here](placeholder link). + +## Enabling the GitHub provider +Before you can use GitHub to authenticate users, you need to enable the provider in your Appwrite console. +1. Navigate to your Appwrite project +2. Navigate to **Auth** > **Settings** +3. Find and open the OAuth provider +4. In the **Github OAuth2 Settings** modal, use the toggle to enable the provider + +Don't close this modal, we'll need to create a GitHub OAuth app to complete this form. + +## Creating a GitHub OAuth app +To use GitHub OAuth with Appwrite, you need to create an OAuth app on your GitHub account or in your Github organization. You can do this by following the [Creating an OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) guide from GitHub. When prompted to provide a **Authorization callback URL**, provide the **URI** found in the **Github OAuth2 Settings** modal from your Appwrite console. + +After you've created your GitHub OAuth app, you can head back to your Appwrite console to complete the form in the **Github OAuth2 Settings** modal. +- Find the **Client ID** in your GitHub OAuth app and provide this in the **App ID** field in the **Github OAuth2 Settings** modal from the Appwrite console. +- Navigate to the **Client secrets** section in your Github OAuth app and click **Generate a new client secret**. +- Copy your new client secret and provide this in the **App Secret** field in the **Github OAuth2 Settings** modal from the Appwrite console. + +## Authenticating +You can use any of the Appwrite Client SDKs to authenticate users with their GitHub account. + +### Web +When a user calls the [Create OAuth2 Session](https://appwrite.io/docs/client/account#accountCreateOAuth2Session) endpoint in your web app, they will be taken to GitHub's OAuth page to complete their login. + +After authenticating, they'll be redirected back to your app using either the `success` or `failure` URLs provided. To provide the best experience to your users, make sure to **implement and provide both routes** to prompt the user about successful and failed authentication attempts. + +```js +import { Client, Account } from "appwrite"; + +const client = new Client(); + +const account = new Account(client); + +client + .setEndpoint('https://cloud.appwrite.io/v1') // Your API Endpoint + .setProject('[PROJECT_ID]') // Your project ID +; + +// Go to OAuth provider login page +account.createOAuth2Session('github', '[LINK_ON_SUCCESS]', '[LINK_ON_FAILURE]'); +``` + +### Flutter + +### Android (Kotlin) + +### Android (Java) + +### iOS (Swift) + +## Refreshing the OAuth2 session +OAuth2 sessions expire to protect from security risks. This means, OAuth2 sessions should be refreshed to keep the user authenticated. You can do this by calling the [Update OAuth Session](https://appwrite.io/docs/client/account#accountUpdateSession) endpoint when ever your user visits your app. + +### Web +```js +import { Client, Account } from "appwrite"; + +const client = new Client(); + +const account = new Account(client); + +client + .setEndpoint('https://cloud.appwrite.io/v1') // Your API Endpoint + .setProject('[PROJECT_ID]') // Your project ID +; + +// Updates current session +const promise = account.updateSession('current'); + +promise.then(function (response) { + console.log(response); // Success +}, function (error) { + console.log(error); // Failure +}); +``` + +### Flutter + +### Android (Kotlin) + +### Android (Java) + +### iOS (Swift) \ No newline at end of file From 6c06d64aafedb281e7e24e7957db2fd6074a00e7 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Sun, 11 Jun 2023 06:06:34 +0545 Subject: [PATCH 2/8] Update github.md --- app/views/docs/oauth-providers/github.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/app/views/docs/oauth-providers/github.md b/app/views/docs/oauth-providers/github.md index 0a0dd26d9..6458c7168 100644 --- a/app/views/docs/oauth-providers/github.md +++ b/app/views/docs/oauth-providers/github.md @@ -45,6 +45,27 @@ account.createOAuth2Session('github', '[LINK_ON_SUCCESS]', '[LINK_ON_FAILURE]'); ### Flutter +For Flutter make sure to follow [getting started for Flutter](https://appwrite.io/docs/getting-started-for-flutter) and setup configuration required for each platform to successfully authenticate user with OAuth2 providers. + +```dart +import 'package:appwrite/appwrite.dart'; + +void main() async { + final client = new Client(); + final account = new Account(client); + + client + .setEndpoint('https://cloud.appwrite.io/v1') // YOUR API Endpoint + .setProject('[PROJECT_ID]') // YOUR PROJECT ID + ; + + // OAuth Login, for simplest implementation you can leave both success and + // failure link empty so that Appwrite handles everything. + account.createOAuth2Session('github'); + +} +``` + ### Android (Kotlin) ### Android (Java) @@ -83,4 +104,4 @@ promise.then(function (response) { ### Android (Java) -### iOS (Swift) \ No newline at end of file +### iOS (Swift) From 1680f4398487bd6661f517b04cfebc86dd45f755 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Sun, 11 Jun 2023 06:09:59 +0545 Subject: [PATCH 3/8] Update github.md --- app/views/docs/oauth-providers/github.md | 25 +++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/app/views/docs/oauth-providers/github.md b/app/views/docs/oauth-providers/github.md index 6458c7168..674b576e5 100644 --- a/app/views/docs/oauth-providers/github.md +++ b/app/views/docs/oauth-providers/github.md @@ -61,7 +61,7 @@ void main() async { // OAuth Login, for simplest implementation you can leave both success and // failure link empty so that Appwrite handles everything. - account.createOAuth2Session('github'); + await account.createOAuth2Session('github'); } ``` @@ -100,6 +100,29 @@ promise.then(function (response) { ### Flutter +```dart +import 'package:appwrite/appwrite.dart'; + +void main() async { + final client = new Client(); + final account = new Account(client); + + client + .setEndpoint('https://cloud.appwrite.io/v1') // YOUR API Endpoint + .setProject('[PROJECT_ID]') // YOUR PROJECT ID + ; + + // OAuth Login, for simplest implementation you can leave both success and + // failure link empty so that Appwrite handles everything. + final future = account.updateSession('current'); + future.then(function (response) { + console.log(response); // Success + }, function (error) { + console.log(error); // Failure + }); +} +``` + ### Android (Kotlin) ### Android (Java) From eb5a98e3499275a307a85dd8140c2266628c34ed Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Mon, 12 Jun 2023 13:11:58 -0400 Subject: [PATCH 4/8] Update github.md --- app/views/docs/oauth-providers/github.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/views/docs/oauth-providers/github.md b/app/views/docs/oauth-providers/github.md index 674b576e5..e2f395f3b 100644 --- a/app/views/docs/oauth-providers/github.md +++ b/app/views/docs/oauth-providers/github.md @@ -45,7 +45,7 @@ account.createOAuth2Session('github', '[LINK_ON_SUCCESS]', '[LINK_ON_FAILURE]'); ### Flutter -For Flutter make sure to follow [getting started for Flutter](https://appwrite.io/docs/getting-started-for-flutter) and setup configuration required for each platform to successfully authenticate user with OAuth2 providers. +For Flutter make sure to follow [getting started for Flutter](https://appwrite.io/docs/getting-started-for-flutter#addYourPlatform) and setup configuration required for each platform to successfully authenticate user with OAuth2 providers. ```dart import 'package:appwrite/appwrite.dart'; From cc3f9be51b64c5723606293952a42d384975588c Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Tue, 13 Jun 2023 21:28:48 +0000 Subject: [PATCH 5/8] complete the example GitHub guide --- app/views/docs/oauth-providers/github.md | 223 ++++++++++++++++++++++- 1 file changed, 221 insertions(+), 2 deletions(-) diff --git a/app/views/docs/oauth-providers/github.md b/app/views/docs/oauth-providers/github.md index e2f395f3b..cd4764173 100644 --- a/app/views/docs/oauth-providers/github.md +++ b/app/views/docs/oauth-providers/github.md @@ -44,8 +44,49 @@ account.createOAuth2Session('github', '[LINK_ON_SUCCESS]', '[LINK_ON_FAILURE]'); ``` ### Flutter +You can use OAuth in your Flutter application, but some platforms like Android and Apple requires additional configuration to enable the OAuth callback, so the your users can be redirected back to your app.. + +#### Android OAuth callback + +In order to capture the Appwrite OAuth callback url, the following activity needs to be added inside the `` tag, along side the existing `` tags in your `AndroidManifest.xml`. Be sure to replace the `[PROJECT_ID]` string with your actual Appwrite project ID. You can find your Appwrite project ID in your project settings screen in your Appwrite console. + +```xml + + ... + + ... + + + + + + + + + + + +``` + +#### Apple +In order to capture the Appwrite OAuth callback url, the following URL scheme needs to added to your `Info.plist` +```xml +CFBundleURLTypes + + + CFBundleTypeRole + Editor + CFBundleURLName + io.appwrite + CFBundleURLSchemes + + appwrite-callback-[PROJECT_ID] + + + +``` -For Flutter make sure to follow [getting started for Flutter](https://appwrite.io/docs/getting-started-for-flutter#addYourPlatform) and setup configuration required for each platform to successfully authenticate user with OAuth2 providers. +To authenticate a user in your Flutter application, use the [Create OAuth2 Session](https://appwrite.io/docs/client/account?sdk=flutter-default#accountCreateOAuth2Session) endpoint. ```dart import 'package:appwrite/appwrite.dart'; @@ -67,11 +108,141 @@ void main() async { ``` ### Android (Kotlin) +Before you can add OAuth to your Android app, you need to setup a callback for your OAuth flow. + +In order to capture the Appwrite OAuth callback url, the following activity needs to be added inside the `` tag, along side the existing `` tags in your `AndroidManifest.xml`. Be sure to replace the `[PROJECT_ID]` string with your actual Appwrite project ID. You can find your Appwrite project ID in your project settings screen in your Appwrite console. + +```xml + + ... + + ... + + + + + + + + + + + +``` + +To authenticate a user in your Android application, use the [Create OAuth2 Session](https://appwrite.io/docs/client/account?sdk=android-kotlin#accountCreateOAuth2Session) endpoint. + +```kotlin +import io.appwrite.Client +import io.appwrite.services.Account + +val client = Client(context) + .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint + .setProject("[PROJECT_ID]") // Your project ID + +val account = Account(client) + +account.createOAuth2Session( + provider = "github", +) +``` ### Android (Java) +Before you can add OAuth to your Android app, you need to setup a callback for your OAuth flow. + +In order to capture the Appwrite OAuth callback url, the following activity needs to be added inside the `` tag, along side the existing `` tags in your `AndroidManifest.xml`. Be sure to replace the `[PROJECT_ID]` string with your actual Appwrite project ID. You can find your Appwrite project ID in your project settings screen in your Appwrite console. + +```xml + + ... + + ... + + + + + + + + + + + +``` + +To authenticate a user in your Android application, use the [Create OAuth2 Session](https://appwrite.io/docs/client/account?sdk=android-java#accountCreateOAuth2Session) endpoint. + +```java +import io.appwrite.Client; +import io.appwrite.coroutines.CoroutineCallback; +import io.appwrite.services.Account; + +Client client = new Client(context) + .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint + .setProject("[PROJECT_ID]"); // Your project ID + +Account account = new Account(client); + +account.createOAuth2Session( + "github", + new CoroutineCallback<>((result, error) -> { + if (error != null) { + error.printStackTrace(); + return; + } + + Log.d("Appwrite", result.toString()); + }) +); +``` ### iOS (Swift) +In order to capture the Appwrite OAuth callback url, the following URL scheme needs to added to your `Info.plist` +```xml +CFBundleURLTypes + + + CFBundleTypeRole + Editor + CFBundleURLName + io.appwrite + CFBundleURLSchemes + + appwrite-callback-[PROJECT_ID] + + + +``` + +If you're using UIKit, you'll also need to add a hook to your `SceneDelegate.swift` file to ensure cookies work correctly. +```swift +func scene(_ scene: UIScene, openURLContexts URLContexts: Set) { + guard let url = URLContexts.first?.url, + url.absoluteString.contains("appwrite-callback") else { + return + } + WebAuthComponent.handleIncomingCookie(from: url) +} +``` + +To authenticate a user in your Android application, use the [Create OAuth2 Session](https://appwrite.io/docs/client/account?sdk=apple-default#accountCreateOAuth2Session) endpoint. + +```swift +import Appwrite + +let client = Client() + .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint + .setProject("[PROJECT_ID]") // Your project ID + +let account = Account(client) + +let success = try await account.createOAuth2Session( + provider: "github" +) + +``` + ## Refreshing the OAuth2 session OAuth2 sessions expire to protect from security risks. This means, OAuth2 sessions should be refreshed to keep the user authenticated. You can do this by calling the [Update OAuth Session](https://appwrite.io/docs/client/account#accountUpdateSession) endpoint when ever your user visits your app. @@ -124,7 +295,55 @@ void main() async { ``` ### Android (Kotlin) +```kotlin +import io.appwrite.Client +import io.appwrite.services.Account -### Android (Java) +val client = Client(context) + .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint + .setProject("[PROJECT_ID]") // Your project ID + +val account = Account(client) +val response = account.updateSession( + sessionId = "current" +) +``` +### Android (Java) +```java +import io.appwrite.Client; +import io.appwrite.coroutines.CoroutineCallback; +import io.appwrite.services.Account; + +Client client = new Client(context) + .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint + .setProject("[PROJECT_ID]"); // Your project ID + +Account account = new Account(client); + +account.updateSession( + "current" + new CoroutineCallback<>((result, error) -> { + if (error != null) { + error.printStackTrace(); + return; + } + + Log.d("Appwrite", result.toString()); + }) +); +``` ### iOS (Swift) +``` swift +import Appwrite + +let client = Client() + .setEndpoint("https://cloud.appwrite.io/v1") // Your API Endpoint + .setProject("[PROJECT_ID]") // Your project ID + +let account = Account(client) + +let session = try await account.updateSession( + sessionId: "current" +) +``` \ No newline at end of file From dd9c0f0c7cfba9b4a634a8669d17fe801639a761 Mon Sep 17 00:00:00 2001 From: Asutosh Ranjan Date: Wed, 12 Jul 2023 22:24:48 +0530 Subject: [PATCH 6/8] refreshing OAuth2 session dart code fix --- app/views/docs/oauth-providers/github.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/app/views/docs/oauth-providers/github.md b/app/views/docs/oauth-providers/github.md index cd4764173..b73b32202 100644 --- a/app/views/docs/oauth-providers/github.md +++ b/app/views/docs/oauth-providers/github.md @@ -280,17 +280,15 @@ void main() async { client .setEndpoint('https://cloud.appwrite.io/v1') // YOUR API Endpoint - .setProject('[PROJECT_ID]') // YOUR PROJECT ID - ; + .setProject('[PROJECT_ID]'); // YOUR PROJECT ID - // OAuth Login, for simplest implementation you can leave both success and - // failure link empty so that Appwrite handles everything. - final future = account.updateSession('current'); - future.then(function (response) { - console.log(response); // Success - }, function (error) { - console.log(error); // Failure - }); + + try { + final future = await account.updateSession(sessionId: 'current'); + print(future.toMap()); // Success + } on AppwriteException catch(e){ + print(e.message); // Failure + } } ``` From 8f28820b68c47a6faea6ca3c1e21f15609d9b8a1 Mon Sep 17 00:00:00 2001 From: Asutosh Ranjan Date: Thu, 13 Jul 2023 23:39:36 +0530 Subject: [PATCH 7/8] added comments back --- app/views/docs/oauth-providers/github.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/app/views/docs/oauth-providers/github.md b/app/views/docs/oauth-providers/github.md index b73b32202..6d908e4d6 100644 --- a/app/views/docs/oauth-providers/github.md +++ b/app/views/docs/oauth-providers/github.md @@ -282,7 +282,8 @@ void main() async { .setEndpoint('https://cloud.appwrite.io/v1') // YOUR API Endpoint .setProject('[PROJECT_ID]'); // YOUR PROJECT ID - + // Simplest implementation of updating auth session + // prints Session Object value on success and error message on failure try { final future = await account.updateSession(sessionId: 'current'); print(future.toMap()); // Success From 8e43d65dc4cdf426f41e9e4d93f6b18cb804d3c5 Mon Sep 17 00:00:00 2001 From: Asutosh Ranjan Date: Thu, 13 Jul 2023 23:49:56 +0530 Subject: [PATCH 8/8] type error --- app/views/docs/oauth-providers/github.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/views/docs/oauth-providers/github.md b/app/views/docs/oauth-providers/github.md index 6d908e4d6..5993f7c36 100644 --- a/app/views/docs/oauth-providers/github.md +++ b/app/views/docs/oauth-providers/github.md @@ -282,7 +282,7 @@ void main() async { .setEndpoint('https://cloud.appwrite.io/v1') // YOUR API Endpoint .setProject('[PROJECT_ID]'); // YOUR PROJECT ID - // Simplest implementation of updating auth session + // Simplest implementation of updating an OAuth2 session // prints Session Object value on success and error message on failure try { final future = await account.updateSession(sessionId: 'current');