From 6b3dce7f2750cce0ba03ad5d1b8be783d4a61bd5 Mon Sep 17 00:00:00 2001 From: Jonas Hungershausen Date: Tue, 24 Sep 2024 14:43:07 +0000 Subject: [PATCH] feat: add docs for improved account linking (#1859) * feat: add docs for improved account linking * Update docs/kratos/social-signin/95_account-linking.mdx Co-authored-by: Vincent --------- Co-authored-by: Vincent --- .../social-signin/95_account-linking.mdx | 49 ++++++++++++++++--- 1 file changed, 42 insertions(+), 7 deletions(-) diff --git a/docs/kratos/social-signin/95_account-linking.mdx b/docs/kratos/social-signin/95_account-linking.mdx index d652d584e..410a4e4d2 100644 --- a/docs/kratos/social-signin/95_account-linking.mdx +++ b/docs/kratos/social-signin/95_account-linking.mdx @@ -7,7 +7,7 @@ slug: link-multiple-provider-account # User account linking -Ory allows users to link their accounts to social sign-in providers after they sign up, as well as un-link social sign-in +Ory allows users to link their accounts to social sign-in providers after they signed up, as well as un-link social sign-in providers they previously added. :::info @@ -46,13 +46,39 @@ To try out account un-linking, use the Ory Account Experience. Follow these step ## Automatic account linking -Users can link social sign-in accounts on login automatically using a secure flow. This is how it works: +Users can link social sign-in accounts on login without interaction using a secure flow. This is how it works: + +```mdx-code-block +import Mermaid from "@theme/Mermaid" + + B --> C --> D + D -->|Yes| E --> F + D -->|No| J + F -->|Yes| G --> H + F -->|No| I + +`} +/> +``` 1. The user creates an account with the identifier `alice@example.com` and a password. -1. When signing in later the user clicks to sign in with a social sign-in provider. That social sign-in account (through the OIDC - userinfo endpoint or the identity token) contains the same identifier `alice@example.com`. -1. Since the identifier is registered already, the user cannot be logged in directly. Instead the user will be prompted to enter - the password chosen in step 1. +1. When signing in later, the user signs in with a social sign-in provider. That social sign-in account (through the OIDC userinfo + endpoint or the identity token) contains the same identifier `alice@example.com`. +1. Since the identifier already exists, the user can't be logged in directly. Instead, the user will be prompted to enter the + password chosen in step 1. 1. After entering the correct password, the social sign-in is linked to the user's account. Now they can sign in with either password or social sign-in provider. @@ -67,5 +93,14 @@ Automatic account linking can be a security risk. Consider this scenario: 1. Your system, detecting duplicate accounts, prompts for account linking. 1. Malicious actors link the accounts, gaining access to John's account. -To prevent this users need to verify an additional credential before the accounts can be linked. In the scenario above, the +To prevent this, users need to verify an additional credential before the accounts can be linked. In the scenario above, the malicious actors would be prompted to enter the password associated with the `jon@doe.com` identifier. + +### Hide irrelevant authentication methods + +Depending on the use case it might be required to show all configured authentication methods to the user. This can be confusing +for users who have accounts with different authentication methods. + +To prevent confusion and hide authentication methods that aren't configured for the user, enable +[login hints](../../identities/sign-in/login-hint.mdx). Login hints inform users about the authentication methods available for +the existing account.