Merge pull request #402 from kinde-oss/Feat/workflow-docs

Big update to workflow docs by @DaveOrDead. 
New topics, updated section, more examples, generally awesome.

Author: clairekinde11

package-lock.json

@@ -12,10 +12,11 @@ relatedArticles:
 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
 
-Upstream params are available for OAuth 2.0 connections, e.g. [social connections](/authenticate/social-sign-in/add-social-sign-in/), [Entra ID OAuth 2.0 enterprise connection](/authenticate/enterprise-connections/azure/), and as part of [advanced configurations](/authenticate/enterprise-connections/advanced-saml-configurations/) in SAML connections. 
+Upstream params are available for OAuth 2.0 connections, e.g. [social connections](/authenticate/social-sign-in/add-social-sign-in/), [Entra ID OAuth 2.0 enterprise connection](/authenticate/enterprise-connections/azure/), and as part of [advanced configurations](/authenticate/enterprise-connections/advanced-saml-configurations/) in SAML connections.
 
 ## Limitations
 
@@ -31,28 +32,26 @@ The Upstream parameter field accepts JSON and the structure is as follows:
 
 ```json
 {
- "<param_name_to_pass>": {
+  "<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. 
+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": {
+  "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`.
@@ -65,34 +64,34 @@ This is the structure.
 
 ```json
 {
- "<param_name_to_pass>": {
+  "<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 [`&[email protected]`](mailto:&[email protected]) 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
-	&[email protected]
+https://<your_kinde_subdomain
+  >.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
+      &[email protected]</your_app_redirect_url
+    ></your_kinde_client_id
+  ></your_kinde_subdomain
+>
 ```
 
 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 `&[email protected]` would be passed on to the provider.
 
@@ -104,7 +103,7 @@ Where the `alias` becomes especially powerful is when you want to re-map a param
 		"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 `&[email protected]` would be passed on to the IDP.
 
@@ -118,9 +117,9 @@ If the user enters `[email protected]` in the Kinde email field with the followi
 
 ```json
 {
-	"login_hint": {
-			"alias": "login_hint"
-	}
+  "login_hint": {
+    "alias": "login_hint"
+  }
 }
 ```
 
@@ -130,14 +129,13 @@ You can send multple parameters this way and mix-and-match between dynamic and s
 
 ```json
 {
-	"prompt": {
-		"value": "login"
-	},
-	"username": {
-		"alias": "login_hint"
-	}
+  "prompt": {
+    "value": "login"
+  },
+  "username": {
+    "alias": "login_hint"
+  }
 }
-
 ```
 
 This would result in `&prompt=login&[email protected]`

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

@@ -64,7 +64,7 @@ Because it is just a string, you can leverage it to store additional information
 3. When you redirect your user to Kinde to complete the authentication flow, include the random string as the `state` param:
 
    ```jsx
-   https://<your_kinde_sudomain>.kinde.com/oauth2/auth
+   https://<your_kinde_subdomain>.kinde.com/oauth2/auth
    	?response_type=code
    	&client_id=<your_kinde_client_id>
    	&redirect_uri=<your_app_redirect_url>

src/content/docs/authenticate/custom-configurations/redirect-users.mdx

@@ -12,7 +12,7 @@ To use workflows and other BYO code features, you need to sync your git-stored c
 
 ## Change the git repo
 
-If you are connecting your repo to Kinde for the first time, see [Connect your workflows repo and branch](/workflows/about-workflows/connect-repo-for-workflows/)
+If you are connecting your repo to Kinde for the first time, see [Connect your workflows repo and branch](/workflows/getting-started/connect-repo-for-workflows/)
 
 1. Go to **Settings > Git repo**.
 2. Select **Change repo**
@@ -22,7 +22,7 @@ If you are connecting your repo to Kinde for the first time, see [Connect your w
 
 ## Preview workflow code
 
-If you are on an eligible plan, we recommend enabling code preview for your workflow. This lets you [test deployed code](/workflows/manage-workflows/preview-workflows/) before you make it live for customers.
+If you are on an eligible plan, we recommend enabling code preview for your workflow. This lets you [test deployed code](/workflows/testing/preview-workflows/) before you make it live for customers.
 
 1. Go to **Settings > Git repo**.
 2. Select the **Enable preview mode** option.

src/content/docs/build/set-up-options/sync-git-code.mdx

@@ -46,7 +46,7 @@ You will need to use this redirect URL in the following step.
 Your users must be redirected from your product to Kinde to sign up or sign in securely. The redirect URL on your product side would look like the following:
 
 ```markdown
-https://<your_kinde_sudomain>.kinde.com/oauth2/auth
+https://<your_kinde_subdomain>.kinde.com/oauth2/auth
 ?response_type=code
 &client_id=<your_kinde_client_id>
 &redirect_uri=<your_app_redirect_url>
@@ -61,6 +61,7 @@ Kinde supports all the standard OAuth 2 request parameters as well as a few addi
 Kinde also supports the PKCE extension, in which case the `code_challenge` and `code_challenge_method` parameters are also required. This is recommended for mobile apps and single page applications (SPAs).
 
 ## Handling successful auth for desktop and mobile apps
+
 If you offer mobile and desktop apps, as well as access through a browser, you'll need to handle the post-authentication browser state. Rather than leaving a hanging screen, you can show users a success page. To do this, add the `is_use_auth_success_page` parameter to the authorization URL. See the [Request prameters](/developer-tools/about/using-kinde-without-an-sdk/#request-parameters) section below.
 
 ## Handling the callback
@@ -84,7 +85,7 @@ client_id=<your_kinde_client_id>
 &client_secret=<your_kinde_client_secret>
 &grant_type=authorization_code
 &redirect_uri=<your_app_redirect_url>
-&code=<CALLBACK_AUTHORIZATION_CODE> 
+&code=<CALLBACK_AUTHORIZATION_CODE>
 ```
 
 Make sure you replace the `<values>` with your own credentials.

src/content/docs/developer-tools/about/using-kinde-without-an-sdk.mdx

@@ -1,6 +1,6 @@
 ---
 page_id: 5c7de06d-f065-4a8a-81cb-f6914ee374f7
-title: Bring your own project and code to Kinde
+title: Connect existing code base to Kinde
 sidebar:
   order: 3
 relatedArticles:

src/content/docs/get-started/guides/byo-code.mdx

@@ -4,23 +4,23 @@ title: About workflows
 sidebar:
   order: 1
 relatedArticles:
-  - d672fca7-6c6a-49f8-85c9-6e86ce99f440
-  - 8554d648-fc2f-4ef9-aaa9-4f27b3c05205
+  - b5a147ac-c189-40b5-8300-b518dd353f91
+  - a49abb3b-467f-4b4c-aba2-07ec360b3f19
   - d360c480-49a8-47d3-b178-1abd34ae669f
 ---
 
-In Kinde, workflows exist to give you (almost) unlimited power over how Kinde works for you. 
+In Kinde, workflows exist to give you (almost) unlimited power over how Kinde works for you.
 
-Develop code in your own repo, and push it to a Kinde workflow, where we execute it in ways that you define, triggered by Kinde events. 
+Develop code in your own repo, and push it to a Kinde workflow, where we execute it in ways that you define, triggered by Kinde events.
 
 Currently, you can use the following triggers:
 
-- `user:post_authentication` fires after the user has completed single factor authentication (e.g. email + password or Google), and before authorization.
-- `m2m:token_generation` - when a request to the token endpoint is made with an M2M application.
-- `user:new_password_provided` - when a user requests to create or reset a password.
-- `user:existing_password_provided` - when a user hasn’t signed in, but they have requested to sign in and given their current password.
-- `user:tokens_generation` - An ID or access token is generated after authentication or refresh token request.
-- `user:pre_mfa` - where the user has completed single factor authentication (e.g. email + password or Google) and determined which organization (if any) they are trying to access. This trigger is only available to customers on a Kinde Scale plan.
+- [user:post_authentication](/workflows/example-workflows/workflow-user-post-auth/) fires after the user has completed single factor authentication (e.g. email + password or Google), and before authorization.
+- [m2m:token_generation](/workflows/example-workflows/m2m-token-generation-workflow/) - when a request to the token endpoint is made with an M2M application.
+- [user:new_password_provided](/workflows/example-workflows/new-password-provided-workflow/) - when a user requests to create or reset a password.
+- [user:existing_password_provided](/workflows/example-workflows/existing-password-provided-workflow/) - when a user hasn’t signed in, but they have requested to sign in and given their current password.
+- [user:token_generation](/workflows/example-workflows/user-token-generation/) - An ID or access token is generated after authentication or refresh token request.
+- [user:pre_mfa](/workflows/example-workflows/pre-mfa-workflow/) - where the user has completed single factor authentication (e.g. email + password or Google) and determined which organization (if any) they are trying to access. This trigger is only available to customers on a Kinde Scale plan.
 
 We will add more triggers (and allow you to create your own) as we develop the feature.
 

src/content/docs/workflows/about-workflows/index.mdx

@@ -0,0 +1,59 @@
+---
+page_id: a5c850c0-0251-44ea-adef-73606694ace3
+title: kinde.accessToken
+sidebar:
+  order: 2
+relatedArticles:
+  - d170e5f0-c6c0-4323-90c9-1d722c837384
+  - 5917da0f-24f0-48df-a387-aca03ce1fe7a
+---
+
+The `kinde.accessToken` binding lets you modify access tokens for the current user. When you add custom claims, they are included in the access token returned to the client.
+
+## Methods
+
+### `setCustomClaim(name: string, value: any): void`
+
+Adds a custom claim to the access token. The claim will be available when the token is returned to the client.
+
+## Available in workflows
+
+- [user:tokens_generation](/workflows/example-workflows/user-token-generation/)
+
+## Configuration
+
+```js
+export const workflowSettings = {
+  // ...other settings
+  bindings: {"kinde.accessToken": {}}
+};
+```
+
+## Usage
+
+### Using the Kinde infrastructure library (recommended)
+
+The [Kinde infrastructure library](https://github.com/kinde-oss/infrastructure) provides type-safe access token modification:
+
+```js
+import { accessTokenCustomClaims } from "@kinde/infrastructure";
+
+export default async function (event: onUserTokenGeneratedEvent) {
+  const accessToken = accessTokenCustomClaims<{
+    hello: string;
+    ipAddress: string;
+  }>();
+
+  accessToken.hello = "Hello there!";
+  accessToken.ipAddress = event.request.ip;
+};
+```
+
+### Using the low-level API
+
+If you're not using the infrastructure library, you can modify the access token directly:
+
+```js
+kinde.accessToken.setCustomClaim("hello", "Hello there!");
+kinde.accessToken.setCustomClaim("ipAddress", event.request.ip);
+```

src/content/docs/workflows/bindings/access-token-binding.mdx

@@ -0,0 +1,58 @@
+---
+page_id: 2b401ba2-b802-4939-b86f-d5e28eb4559b
+title: kinde.auth
+sidebar:
+  order: 3
+relatedArticles:
+  - d170e5f0-c6c0-4323-90c9-1d722c837384
+  - 5917da0f-24f0-48df-a387-aca03ce1fe7a
+---
+
+The `kinde.auth` binding affects the auth flow.
+
+## Methods
+
+### `denyAccess(reason: string): void`
+
+Prevent the user from accessing the application.
+
+## Available in workflows
+
+- [user:post_authentication](/workflows/example-workflows/workflow-user-post-auth/)
+- [user:new_password_provided](/workflows/example-workflows/new-password-provided-workflow/)
+- [user:existing_password_provided](/workflows/example-workflows/existing-password-provided-workflow/)
+- [user:tokens_generation](/workflows/example-workflows/user-token-generation/)
+- [user:pre_mfa](/workflows/example-workflows/pre-mfa-workflow/)
+
+## Configuration
+
+```js
+export const workflowSettings = {
+  // ...other settings
+  bindings: {"kinde.auth": {}}
+};
+```
+
+## Usage
+
+### Using the Kinde infrastructure library (recommended)
+
+The [Kinde infrastructure library](https://github.com/kinde-oss/infrastructure) provides a type-safe helper:
+
+```js
+import { denyAccess } from "@kinde/infrastructure";
+
+export default async function (event: onUserTokenGeneratedEvent) {
+  if (event.request.ip.startsWith("192")) {
+    denyAccess("You are not allowed to access this resource");
+  }
+}
+```
+
+### Using the low-level API
+
+If you're not using the infrastructure library, you can call the underlying API directly:
+
+```js
+kinde.auth.denyAccess("You are not allowed to access this resource");
+```