From 1e98384163bf415eee2ba15ac917b653b9389a95 Mon Sep 17 00:00:00 2001 From: vinckr Date: Mon, 30 Sep 2024 10:37:19 +0200 Subject: [PATCH] fix: simplify social signin docs --- docs/kratos/social-signin/01_overview.mdx | 150 +++++++++++++++++ docs/kratos/social-signin/96_native-apps.mdx | 162 ------------------- src/sidebar.ts | 6 +- 3 files changed, 154 insertions(+), 164 deletions(-) delete mode 100644 docs/kratos/social-signin/96_native-apps.mdx diff --git a/docs/kratos/social-signin/01_overview.mdx b/docs/kratos/social-signin/01_overview.mdx index 4bf6f180d..c498f69ef 100644 --- a/docs/kratos/social-signin/01_overview.mdx +++ b/docs/kratos/social-signin/01_overview.mdx @@ -361,6 +361,156 @@ metadata_public: github_username: foo-user ``` +## Social sign-in for native and mobile apps + +This section covers how to implement social sign-in for native applications via OIDC and OAuth 2.0. The user interaction looks +like this: + +- The user is presented with a login or registration screen that includes a social sign-in button. +- The user clicks the social sign-in button. A browser window opens (using + [ASWebAuthenticationSession](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession) on iOS + or [Custom Tabs](https://developer.chrome.com/docs/android/custom-tabs/) on Android). +- The user authenticates with the identity provider and grants the application access to profile information. +- The user is redirected back to the application and is logged in. + +:::note + +Apple and Google support a more tightly integrated login experience for native apps. See the documentation on +[Apple social sign-in](./apple#using-the-apple-sdk-on-native-apps) and +[Google social sign-in](./10_google.mdx#using-the-google-sdk-on-native-apps) for more information. + +::: + +### Native app social sign-in authentication flow + +From a high level, the native app initializes a login or registration flow and receives the first part of the session token +exchange code from the Ory Network. After the user performed the social sign-in, the user is redirected back to the native +application via an [iOS Universal Link](https://developer.apple.com/ios/universal-links/) or +[Android App Link](https://developer.android.com/training/app-links). The native application then exchanges the session token +exchange code for a session token. + +:::info + +As part of this flow, Ory will redirect the browser to a callback. In this demo, we use the redirect URL +`http://localhost:19006/Callback`. Please ensure that this redirect URL is allowed. Go +to  to allow it. + +::: + +The flow looks like this: + +```mdx-code-block +>+A: Open login screen + A->>+O: create API flow with return_session_token_exchange_code=true + O->>A: flow.session_token_exchange_code: ... + U->>A: choose SSO provider + A->>O: submit form with provider=... + O->>A: Status 422 with err.response.data.redirect_browser_to= + A->>+B: go to + B->>+I: open + U->>I: login, consent + I->>-B: redirect to + B->>O: open + O->>B: 302 Found + B->>A: redirect with App link to /?code=... + deactivate B + A->>O: exchange code for session token + O->>-A: session token +`}/> +``` + +The following sections describe how to implement the native app authentication flow. The code examples are written in TypeScript +for React Native. The steps refer to the steps in the flow diagram above. + +##### Steps 1-5: Create an API flow with return_session_token_exchange_code=true + +The user opens the login screen (1) and the native application initializes a login or registration flow through the Ory Network +APIs (2) with the following parameters: + +- The flow is of type `api`. +- The `return_to` parameter is set to the URL of the native application. This URL is used to redirect the user back to the app + after the social sign-in. +- The `return_session_token_exchange_code` parameter is set to `true` to receive the session token exchange code in the response + (3). + + + +Upon rendering the form, the user selects the specific social sign-in provider (4). The native application submits the form to the +Ory Network (5). + +##### Steps 6-12: Open the identity provider authentication URL in a browser + +Ory Network returns a `422` status code if the user needs to perform a social sign-in from a flow of type `api` (6). The response +contains the URL of the identity provider in the `redirect_browser_to` field. + + + +[WebBrowser.openAuthSessionAsync](https://docs.expo.dev/versions/latest/sdk/webbrowser/#webbrowseropenauthsessionasyncurl-redirecturl-options) +opens a browser tab for authentication for the specified `url` (7+8). Implementations in other languages and frameworks may vary. + + + +The user authenticates with the identity provider and grants the application access to profile information (9). The identity +provider then issues a redirect to the Ory Network callback URL (10), which the browser follows (11). + +##### Steps 12-14: Exchange the session token exchange code for a session token + +Finally, Ory Network issues a session for the user and redirects the browser to the application's `return_to` URL (12). The native +application receives the second part of the session token exchange code in the `code` URL query parameter. In the example below, +the call to +[WebBrowser.maybeCompleteAuthSession](https://docs.expo.dev/versions/latest/sdk/webbrowser/#webbrowsermaybecompleteauthsessionoptions) +is used to close the browser tab and return the control flow to the code that awaited the call to +`WebBrowser.openAuthSessionAsync`. + + + +The native application then exchanges the session token exchange code for a session token (13) using the first part of the code +returned from the flow initialization, and the second part of the code returned from the `return_to` query parameter. + + + +Finally, the native application stores the session token in the secure storage (14) and redirects the user to the home screen. + + + ## Get social sign-in provider tokens In this section you learn how to get OIDC/OAuth 2.0 access, refresh, and ID tokens issued for the identity by social sign-in diff --git a/docs/kratos/social-signin/96_native-apps.mdx b/docs/kratos/social-signin/96_native-apps.mdx deleted file mode 100644 index 2e9ef4a29..000000000 --- a/docs/kratos/social-signin/96_native-apps.mdx +++ /dev/null @@ -1,162 +0,0 @@ ---- -id: native-apps -title: Social sign-in for native and mobile apps -sidebar_label: Native apps ---- - -```mdx-code-block -import Mermaid from '@theme/Mermaid'; -import CodeFromRemote from "@theme/CodeFromRemote" -``` - -## Overview - -This page covers how to implement social sign-in for native applications via OIDC and OAuth 2.0. The user interaction looks like -this: - -- The user is presented with a login or registration screen that includes a social sign-in button. -- The user clicks the social sign-in button. A browser window opens (using - [ASWebAuthenticationSession](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession) on iOS - or [Custom Tabs](https://developer.chrome.com/docs/android/custom-tabs/) on Android). -- The user authenticates with the identity provider and grants the application access to profile information. -- The user is redirected back to the application and is logged in. - -:::note - -Apple and Google support a more tightly integrated login experience for native apps. See the documentation on -[Apple social sign-in](./apple#using-the-apple-sdk-on-native-apps) and -[Google social sign-in](./10_google.mdx#using-the-google-sdk-on-native-apps) for more information. - -::: - -## The native app authentication flow - -From a high level, the native app initializes a login or registration flow and receives the first part of the session token -exchange code from the Ory Network. After the user performed the social sign-in, the user is redirected back to the native -application via an [iOS Universal Link](https://developer.apple.com/ios/universal-links/) or -[Android App Link](https://developer.android.com/training/app-links). The native application then exchanges the session token -exchange code for a session token. - -:::info - -As part of this flow, Ory will redirect the browser to a callback. In this demo, we use the redirect URL -`http://localhost:19006/Callback`. Please ensure that this redirect URL is allowed. Go -to  to allow it. - -::: - -The flow looks like this: - -```mdx-code-block ->+A: Open login screen - A->>+O: create API flow with return_session_token_exchange_code=true - O->>A: flow.session_token_exchange_code: ... - U->>A: choose SSO provider - A->>O: submit form with provider=... - O->>A: Status 422 with err.response.data.redirect_browser_to= - A->>+B: go to - B->>+I: open - U->>I: login, consent - I->>-B: redirect to - B->>O: open - O->>B: 302 Found - B->>A: redirect with App link to /?code=... - deactivate B - A->>O: exchange code for session token - O->>-A: session token -`}/> -``` - -### Implementation - -The following sections describe how to implement the native app authentication flow. The code examples are written in TypeScript -for React Native. The steps refer to the steps in the flow diagram above. - -#### Steps 1-5: Create an API flow with return_session_token_exchange_code=true - -The user opens the login screen (1) and the native application initializes a login or registration flow through the Ory Network -APIs (2) with the following parameters: - -- The flow is of type `api`. -- The `return_to` parameter is set to the URL of the native application. This URL is used to redirect the user back to the app - after the social sign-in. -- The `return_session_token_exchange_code` parameter is set to `true` to receive the session token exchange code in the response - (3). - - - -Upon rendering the form, the user selects the specific social sign-in provider (4). The native application submits the form to the -Ory Network (5). - -#### Steps 6-12: Open the identity provider authentication URL in a browser - -Ory Network returns a `422` status code if the user needs to perform a social sign-in from a flow of type `api` (6). The response -contains the URL of the identity provider in the `redirect_browser_to` field. - - - -[WebBrowser.openAuthSessionAsync](https://docs.expo.dev/versions/latest/sdk/webbrowser/#webbrowseropenauthsessionasyncurl-redirecturl-options) -opens a browser tab for authentication for the specified `url` (7+8). Implementations in other languages and frameworks may vary. - - - -The user authenticates with the identity provider and grants the application access to profile information (9). The identity -provider then issues a redirect to the Ory Network callback URL (10), which the browser follows (11). - -#### Steps 12-14: Exchange the session token exchange code for a session token - -Finally, Ory Network issues a session for the user and redirects the browser to the application's `return_to` URL (12). The native -application receives the second part of the session token exchange code in the `code` URL query parameter. In the example below, -the call to -[WebBrowser.maybeCompleteAuthSession](https://docs.expo.dev/versions/latest/sdk/webbrowser/#webbrowsermaybecompleteauthsessionoptions) -is used to close the browser tab and return the control flow to the code that awaited the call to -`WebBrowser.openAuthSessionAsync`. - - - -The native application then exchanges the session token exchange code for a session token (13) using the first part of the code -returned from the flow initialization, and the second part of the code returned from the `return_to` query parameter. - - - -Finally, the native application stores the session token in the secure storage (14) and redirects the user to the home screen. - - diff --git a/src/sidebar.ts b/src/sidebar.ts index 14264993b..e35ef7379 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -188,8 +188,11 @@ const guidesSidebar = (flat: boolean): ExtendSidebar => { label: "OpenID Connect SSO", collapsed: false, collapsible: false, + link: { + type: "doc", + id: "kratos/social-signin/overview", + }, items: [ - "kratos/social-signin/overview", { type: "category", label: "Social Sign-in Providers", @@ -218,7 +221,6 @@ const guidesSidebar = (flat: boolean): ExtendSidebar => { "kratos/social-signin/x-twitter", ], }, - "kratos/social-signin/native-apps", ], }, {