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 <[email protected]>

---------

Co-authored-by: Vincent <[email protected]>

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"
+
+<Mermaid
+  chart={`flowchart LR
+    A["Create account with [email protected]"]
+    B["Sign in with social provider"]
+    C["Retrieve [email protected] from OIDC"]
+    D{"Does [email protected] exist?"}
+    E["Prompt for password"]
+    F{"Is password correct?"}
+    G["Link social to account"]
+    H["Sign-in successful. Use password or social"]
+    I["Authentication failed"]
+    J["Sign-in successful with social"]
+
+    A --> 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 `[email protected]` 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 `[email protected]`.
-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 `[email protected]`.
+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 `[email protected]` 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.