Feat/params to idp

src/content/docs/authenticate/auth-guides/pass-params-idp.mdx

@@ -0,0 +1,152 @@
+---
+page_id: 64079be6-be72-4b63-a9d1-4466af4d49be
+title: Pass parameters to identity providers
+sidebar:
+  order: 2
+relatedArticles:
+  - fcf28a71-c3a8-4474-9564-ad089d3f2105
+  - b663dbde-2045-4f51-bab4-84d0c9fbe15b
+  - 50284476-2442-414c-af20-01ed3ef4ca4e
+---
+
+You can pass provider-specific parameters to an Identity Provider (IdP) during authentication. These are also known as 'upstream params'. The values your pass can either be static per connection or dynamic per user.
+
+There's a number of reason why you might want to use upstream params:
+- to create a smoother sign in experience - by passing the email through
+- to offer an account switcher (such as the Google account switcher) during sign in
+
+## Limitations
+
+- Each IDP has their own set of supported parameters and values, so you'll need to check their documentation to determine which URL parameters are supported.
+- Applies only to OAuth 2.0 connections, e.g. [social connections](/authenticate/social-sign-in/add-social-sign-in/) and [Entra ID OAuth 2.0 enterprise connection](/authenticate/enterprise-connections/azure/).
+- SAML IdPs do not support upstream parameters.
+
+## Static parameters
+
+Static parameters can be useful when you have specific values you always want to pass on to the IDP. These are set in the connecction configuration screen.
+
+![Screen shot of google connection screen and upstream params field](https://imagedelivery.net/skPPZTHzSlcslvHjesZQcQ/3fa86bd8-9005-4022-7118-fc93ce4f4a00/public)
+
+The Upstream parameter field accepts JSON and the structure is as follows:
+
+```json
+{
+ "<param_name_to_pass>": {
+    "value": "<your_hardcoded_value>"
+  }
+}
+
+```
+
+Replace `<param_name_to_pass>` with the name of the parameter you wish to pass upstream to the IDP.
+Replace `<your_hardcoded_value>` with the value of the parameter you wish to pass upstream.
+
+### Example: Force the google account selector to display on sign in
+
+If you want Google to always show the account selector even if the user is already logged in with a Google account, pass the `prompt=select_account` parameter from Kinde. 
+This is how that would look:
+
+```json
+{
+ "prompt": {
+    "value": "select_account"
+  }
+}
+
+```
+
+Now, when your user clicks on the Google button and Kinde creates the URL to redirect to Google, it will append`&prompt=select_account`.
+
+## Dynamic parameters
+
+Dynamic parameters cover the case where you don't know the value of the parameter ahead of time, and it needs to be populated on the fly during the auth flow. For example, if you need to pass on a parameter that was provided to Kinde in the auth URL.
+
+This is the structure.
+
+```json
+{
+ "<param_name_to_pass>": {
+    "alias": "<dynamic_param_name>"
+  }
+}
+
+```
+
+The `alias` keyword tells Kinde which parameter from your auth url to use, and the value to pass upstream to the IDP.
+
+Here is an example where we provide `login_hint` as part of the auth URL, where the email [`&login_hint=hello@example.com`](mailto:&login_hint=hello@example.com) is included on the URL.
+
+```html
+https://<your_kinde_sudomain>.kinde.com/oauth2/auth
+	?response_type=code
+	&client_id=<your_kinde_client_id>
+	&redirect_uri=<your_app_redirect_url>
+	&scope=openid%20profile%20email
+	&state=abc
+	&login_hint=hello@example.com
+```
+
+In this case both Kinde and the IDP use the parameter name `login_hint` so the configuration is the same on both sides:
+Add this to the connection configuration:
+
+  }
+}
+
+```
+
+In this case we are saying pass the `login_hint` parameter upstream to the IDP with the value Kinde received in the `login_hint` auth url param. So `&login_hint=hello@example.com` would be passed on to the provider.
+
+Where the `alias` becomes especially powerful is when you want to re-map a parameter name to match the one an IDP expects. For example, let’s say that our IDP expects `username`  instead of `login_hint` for the same value, in this case our JSON would look like this:
+
+```json
+{
+	"username": {
+		"alias": "login_hint"
+	}
+}
+```
+
+In this case we are saying pass the `username` parameter upstream to the IDP with the value Kinde received in the `login_hint` auth url param. We remap the email value from `login_hint` to `username` and the parameter `&username=hello@example.com` would be passed on to the IDP.
+
+## Kinde-provided aliases
+
+When an email address is populated during the auth flow, we make this available via the `login_hint` alias.
+
+You might use this if you are using Home realm discovery with an Entra ID OAuth2.0 connection, and you want to pass the URL that the user entered on Kinde as the `login_hint`, upstream to Entra, to prevent the user having to enter their email twice.
+
+If the user enters `hello@example.com` in the Kinde email field with the following configuration active, we set the `login_hint` parameter to `hello@example.com` via the Kinde provided alias.
+
+```json
+{
+	"login_hint": {
+			"alias": "login_hint"
+	}
+}
+```
+
+## Multiple parameters
+
+You can send multple parameters this way and mix-and-match between dynamic and static in the same configuration. For example if the user entered `hello@example.com` and the following was configured:
+
+```json
+{
+	"prompt": {
+		"value": "login"
+	},
+	"username": {
+		"alias": "login_hint"
+	}
+}
+
+```
+
+This would result in `&prompt=login&username=hello@example.com`
+
+## Supported aliases
+
+The values which can be used as an `alias` are:
+
+- `prompt`
+- `login_hint`
+
+If you need other aliases added, let us know via a [feedback form](https://updates.kinde.com/).

src/content/docs/authenticate/enterprise-connections/azure.mdx

@@ -17,6 +17,8 @@ Kinde supports the use of Microsoft Entra ID as an authentication method. We sup
 
 If you [import users into Kinde](/manage-users/add-and-edit/import-users-in-bulk/), their Entra ID will be picked up and matched to the relevant connection based on their email address, for a seamless transition to Kinde.
 
+You can also pass [upstream params](/authenticate/auth-guides/pass-params-idp/) to the IdP as part of this procedure.
+
 <Aside>
 
 **Microsoft Entra ID** used to be known as **Microsoft Azure AD**. [More information](https://learn.microsoft.com/en-gb/azure/active-directory/fundamentals/new-name).
@@ -50,8 +52,7 @@ You can make a connection available only to a specific organization, or you can
 1. Go to **Settings > Environment > Authentication**.
 2. Scroll to the **Enterprise connection** section and select **Add connection**. The **Add connection** window opens.
 3. Select the Microsoft connection type you want (WS Federated or OAuth2.0) and then select **Save**.
-4. On the tile for the new connection, select **Configure**.
-5. Next: 'Step 2: Configure the connection'.
+4. Next: 'Step 2: Configure the connection'.
 
 ## Step 2: Configure the connection
 
@@ -80,8 +81,9 @@ You can make a connection available only to a specific organization, or you can
 9. Select if you want to treat this connection as a trusted provider. A [trusted provider](/authenticate/about-auth/identity-and-verification/) is one that guarantees the email they issue is verified. We recommend leaving this off for maximum security.
 10. If you want, select **Sync user profiles and attributes on sign in**. Recommended to keep Kinde user profile data in sync with user profile data from Microsoft. If you choose this option, ensure that the global profile sync preference is also switched on in **Settings > Environment > Policies**.
 11. If you want to enable just-in-time (JIT) provisioning, select the **Create a user record in Kinde** option. This saves time adding users manually or via API later.
-12. Copy the **Callback URL**. You’ll need to enter this in your Entra ID app.
-13. Select **Save**.
+12. Add any [upstream params](/authenticate/auth-guides/pass-params-idp/) that you want to pass to the IdP.
+13. Copy the **Callback URL**. You’ll need to enter this in your Entra ID app.
+14. Select **Save**.
 
 ## Step 3: Add the callback URL to your Entra ID app
 

src/content/docs/authenticate/social-sign-in/apple.mdx

@@ -24,12 +24,12 @@ It's also important to note that Apple limits the information it passes when use
 ## **Copy the callback URL from Kinde**
 
 1. In Kinde, go to **Settings** > **Authentication**.
-2. If you have not yet added the Apple connection, select **Add connection**, select **Apple**, then **Save**.
-3. On the **Apple auth** tile in the **Social authentication** section, select **Configure**.
-4. In the **Callback URL** section:
+2. If you have not yet added the Apple connection, select **Add connection**, select **Apple**, then **Next**.
+3. In the **Callback URL** section:
    1. If you use Kinde’s domain as your default, copy the **Kinde domain** URL.
    2. If you use custom domains, select the **Use custom domain instead** switch. 
    3. If you have only one custom domain, copy the **Custom domain** URL. If you have custom domains for multiple organizations, select each one from the list and copy the callbacks for each. You need to enter all custom domain callbacks in the provider app.
+4. Select **Save**.
 5. Use the copied Callback URLs to set up the app, see below.
 
 ## **Configure sign in for your app**
@@ -127,8 +127,9 @@ You can use open source libraries for creating and signing JWT tokens for your c
 2. On the Apple tile, select **Configure**.
 3. Paste the **Client ID** (Service ID) and **Client secret** (Private key) into the relevant fields.
 4. Select if you want to treat this connection as a trusted provider. A [trusted provider](/authenticate/about-auth/identity-and-verification/) is one that guarantees the email they issue is verified. We recommend leaving this off for maximum security.
-5. Select which apps will use Apple sign in.
-6. Select **Save**. Users will now see Apple as an option to sign up and sign in to your product.
+5. Add any [upstream params](/authenticate/auth-guides/pass-params-idp/) that you want to pass to the IdP.
+6. Select which apps will use Apple sign in.
+7. Select **Save**. Users will now see Apple as an option to sign up and sign in to your product.
 
 ## **Renew Apple token periodically**
 

src/content/docs/authenticate/social-sign-in/bitbucket-sso.mdx

@@ -21,12 +21,12 @@ Before you make your production environment live, you must add your own social a
 
 1. In Kinde, go to **Settings** > **Authentication**.
 2. In the **Social connections** section, select **Add connection.**
-3. In the window that appears, select **Bitbucket,** then select **Save**. Bitbucket now appears in the **Social connections** list.
-4. On the **Bitbucket** tile, select **Configure**.
-5. In the **Callback URL** section:
+3. In the window that appears, select **Bitbucket,** then select **Next**. 
+4. In the **Callback URL** section:
    1. If you use Kinde’s domain as your default, copy the **Kinde domain** URL.
    2. If you use custom domains, select the Use custom domain instead switch.
    3. If you have only one custom domain, copy the Custom domain URL. If you have custom domains for multiple organizations, select each one from the list and copy the callbacks for each. You need to enter all custom domain callbacks in the Bitbucket app.
+5. Select **Save**.
 6. Use the copied Callback URL to set up the app, see below.
 
 ## **Create and configure a Bitbucket app**
@@ -49,7 +49,8 @@ Before you make your production environment live, you must add your own social a
 2. On the **Bitbucket** tile, select **Configure**.
 3. Paste the **Client ID** (key) and **Client secret** (secret) into the relevant fields.
 4. Select if you want to treat this connection as a trusted provider. A [trusted provider](/authenticate/about-auth/identity-and-verification/) is one that guarantees the email they issue is verified. We recommend leaving this off for maximum security.
-5. Select which applications will allow Bitbucket social sign in.
-6. Select **Save**.
+5. Add any [upstream params](/authenticate/auth-guides/pass-params-idp/) that you want to pass to the IdP.
+6. Select which applications will allow Bitbucket social sign in.
+7. Select **Save**.
 
 Users will now see Bitbucket as an option to sign up and sign in to the selected applications.

src/content/docs/authenticate/social-sign-in/discord.mdx

@@ -17,15 +17,15 @@ Before you make your production environment live, you must add your own social a
 
 1. In Kinde, go to **Settings** > **Authentication**.
 2. In the **Social connections** section, select **Add connection.**
-3. In the window that appears, select **Discord,** then select **Save**. Discord now appears in the **Social connections** list.
-4. On the **Discord** tile, select **Configure**.
-5. In the **Callback URL** section:
+3. In the window that appears, select **Discord,** then select **Next**.
+4. In the **Callback URL** section:
    1. If you use Kinde’s domain as your default, copy the **Kinde domain** URL.
    2. If you use custom domains, select the Use custom domain instead switch.
    3. If you have only one custom domain, copy the Custom domain URL. If you have custom domains for multiple organizations, select each one from the list and copy the callbacks for each. You need to enter all custom domain callbacks in the Discord app.
+5. Select **Save**.
 6. Use the copied Callback URL to set up the app, see below.
 
-## **Create and configure a Discord app**
+## Create and configure a Discord app
 
 1. Log in to the [Discord developer site](https://discord.com/developers/applications/) and create a new app.
 2. Give it a name and then go to **OAuth2** in the side menu.
@@ -39,7 +39,8 @@ Before you make your production environment live, you must add your own social a
 2. On the **Discord** tile, select **Configure**.
 3. Paste the **Client ID** and **Client secret** from the Discord app into the relevant fields.
 4. Select if you want to treat this connection as a trusted provider. A [trusted provider](/authenticate/about-auth/identity-and-verification/) is one that guarantees the email they issue is verified. We recommend leaving this off for maximum security.
-5. Select which applications will allow Discord social sign in.
-6. Select **Save**.
+5. Add any [upstream params](/authenticate/auth-guides/pass-params-idp/) that you want to pass to the IdP.
+6. Select which applications will allow Discord social sign in.
+7. Select **Save**.
 
 Users will now see Discord as an option to sign up and sign in to the selected applications.

src/content/docs/authenticate/social-sign-in/facebook.mdx

@@ -17,12 +17,12 @@ Before you make your production environment live, you must add your own social a
 
 1. In Kinde, go to **Settings** > **Authentication**.
 2. If you have not yet added the Facebook social connection, select **Add connection** in the **Social authentication** section.
-3. Select **Facebook**, then **Save**.
-4. On the **Facebook** tile, select **Configure**.
-5. In the **Callback URL** section:
+3. Select **Facebook**, then **Next**.
+4. In the **Callback URL** section:
    1. If you use Kinde’s domain as your default, copy the **Kinde domain** URL.
    2. If you use custom domains, select the **Use custom domain instead** switch.
    3. If you have only one custom domain, copy the Custom domain URL. If you have custom domains for multiple organizations, select each one from the list and copy the callbacks for each. You need to enter all custom domain callbacks in the Meta app.
+5. Select **Save**.
 6. Use the copied Callback URLs to set up the app, see below.
 
 <Aside>
@@ -94,8 +94,9 @@ The following steps were correct when we published this, but third party provide
 2. On the **Facebook** tile, select **Configure**.
 3. Paste the **Client ID** and **Client secret** from the Facebook app into the relevant fields.
 4. Select if you want to treat this connection as a trusted provider. A [trusted provider](/authenticate/about-auth/identity-and-verification/) is one that guarantees the email they issue is verified. We recommend leaving this off for maximum security.
-5. Select which applications will allow Facebook SSO.
-6. Select **Save**.
+5. Add any [upstream params](/authenticate/auth-guides/pass-params-idp/) that you want to pass to the IdP.
+6. Select which applications will allow Facebook SSO.
+7. Select **Save**.
 
 Users will now see Facebook as an option to sign up and sign in to the selected applications.
 

src/content/docs/authenticate/social-sign-in/github.mdx

@@ -17,12 +17,12 @@ Before you make your production environment live, you must add your own social a
 
 1. In Kinde, go to **Settings** > **Authentication**.
 2. In the **Social Connections** section, select **Add connection**.
-3. In the window that appears, select **GitHub**, then select **Save**.
-4. On the **GitHub** tile, select **Configure**.
-5. In the **Callback URL** section:
+3. In the window that appears, select **GitHub**, then select **Next**.
+4. In the **Callback URL** section:
    1. If you use Kinde’s domain as your default, copy the **Kinde domain** URL.
    2. If you use custom domains, select the **Use custom domain instead** switch.
    3. If you have only one custom domain, copy the Custom domain URL. If you have custom domains for multiple organizations, select each one from the list and copy the callbacks for each. You need to enter all custom domain callbacks in the provider app.
+5. Select **Save**.
 6. Use the copied Callback URL to set up the app, see below.
 
 ## **Create GitHub app**
@@ -62,5 +62,6 @@ Before you make your production environment live, you must add your own social a
 2. On the GitHub tile, select **Configure**.
 3. Paste the **Client ID** and **Client secret** into the relevant fields.
 4. Select if you want to treat this connection as a trusted provider. A [trusted provider](/authenticate/about-auth/identity-and-verification/) is one that guarantees the email they issue is verified. We recommend leaving this off for maximum security.
-5. Select which applications will use GitHub sign in.
-6. Select **Save**. Users will now see GitHub as an option to sign up and sign in to your product.
+5. Add any [upstream params](/authenticate/auth-guides/pass-params-idp/) that you want to pass to the IdP.
+6. Select which applications will use GitHub sign in.
+7. Select **Save**. Users will now see GitHub as an option to sign up and sign in to your product.

src/content/docs/authenticate/social-sign-in/gitlab.mdx

@@ -17,12 +17,12 @@ Before you make your production environment live, you must add your own social a
 
 1. In Kinde, go to **Settings** > **Authentication**.
 2. In the **Social Connections** section, select **Add connection**.
-3. In the window that appears, select **GitLab**, then select **Save**.
-4. On the **GitLab** tile, select **Configure**.
-5. In the **Callback URL** section:
+3. In the window that appears, select **GitLab**, then select **Next**.
+4. In the **Callback URL** section:
    1. If you use Kinde’s domain as your default, copy the **Kinde domain** URL.
    2. If you use custom domains, select the **Use custom domain instead** switch.
    3. If you have only one custom domain, copy the Custom domain URL. If you have custom domains for multiple organizations, select each one from the list and copy the callbacks for each. You need to enter all custom domain callbacks in the GitLab app.
+5. Select **Save**.
 6. Use the copied Callback URL to set up the app, see below.
 
 ## **Create GitLab app**
@@ -39,5 +39,6 @@ Before you make your production environment live, you must add your own social a
 2. On the GitLab tile, select **Configure**.
 3. Paste the **Client ID** (**Application ID**) and **Client secret** (**Secret**) into the relevant fields.
 4. Select if you want to treat this connection as a trusted provider. A [trusted provider](/authenticate/about-auth/identity-and-verification/) is one that guarantees the email they issue is verified. We recommend leaving this off for maximum security.
-5. Select which applications will have a GitLab sign in option.
-6. Select **Save**. Users will now see GitLab as an option to sign up and sign in to your product.
+5. Add any [upstream params](/authenticate/auth-guides/pass-params-idp/) that you want to pass to the IdP.
+6. Select which applications will have a GitLab sign in option.
+7. Select **Save**. Users will now see GitLab as an option to sign up and sign in to your product.