Merge pull request #607 from kinde-oss/tamal/feat/wf-custom-password-validation-logic

feat: tutorial - password validation check

Author: alex72508

src/content/docs/workflows/workflow-tutorials/custom-password-validation-check.mdx

@@ -0,0 +1,213 @@
+---
+page_id: 57fc3195-6437-4165-b618-d5cf524f1912
+title: Tutorial - Password validation check
+sidebar:
+  order: 20
+relatedArticles:
+  - 56db51a5-5542-4631-8bc6-36339a813a85
+  - f499ebb0-d7f5-4244-bf92-6bf0f6082b62
+description: Learn how to implement a custom password validation workflow in Kinde.
+topics:
+  - "workflows"
+  - "example-workflows"
+  - "authentication"
+sdk: "kinde infrastructure"
+languages:
+  - "TypeScript"
+  - "JavaScript"
+audience:
+  - "developers"
+complexity: "intermediate"
+keywords:
+  - "user registration"
+  - "authentication triggers"
+  - "custom password"
+  - "special characters"
+updated: "2025-11-05"
+featured: false
+deprecated: false
+ai_summary: "Learn how to implement a custom password validation workflow in Kinde."
+---
+
+
+Kinde enforces essential password safety rules out of the box, such as a minimum length and checks against the most common passwords. But what if your application requires more specific password policies, like enforcing uppercase letters, numbers, or special characters?
+
+In this guide, you’ll implement a **custom password validation workflow** in Kinde using its flexible workflow engine. This feature lets you define exactly how strict (or lenient) your password rules should be, and display custom error messages right on the Kinde sign-up or login widget.
+
+## What you need
+
+- A [Kinde account](https://kinde.com/) (Sign up for free)
+- A [GitHub account](https://github.com/) (Sign up for free)
+- A running Kinde project such as the [Kinde Next.js starter kit](https://github.com/kinde-starter-kits/kinde-nextjs-app-router-starter-kit)
+
+## Step 1: Create the workflow code
+
+1. Fork the [workflow base template](https://github.com/kinde-starter-kits/workflow-base-template) repo into your GitHub account by selecting **Use this template > Create a new repository**
+2. Clone the repo into your computer with the following Git command:
+    
+    ```bash
+    git clone https://github.com/your_github_username/workflow-base-template.git
+    ```
+    
+3. Change into the directory:
+    
+    ```bash
+    cd workflow-base-template
+    ```
+    
+4. Create a new workflow directory with the following command. 
+You can name it anything that resonates with your project structure; we are calling it `newPasswordValidation`
+    
+    ```bash
+    mkdir kindeSrc/environment/workflows/newPasswordValidation
+    ```
+    
+5. Create a new `Workflow.ts` file:
+    
+    ```bash
+    touch kindeSrc/environment/workflows/newPasswordValidation/Workflow.ts
+    ```
+    
+6. Open the new file with your favorite code editor (e.g., VS Code) and add the following workflow code into the file and save changes:
+    
+    ```tsx
+    import {
+      onNewPasswordProvidedEvent,
+      WorkflowSettings,
+      WorkflowTrigger,
+      invalidateFormField,
+    } from "@kinde/infrastructure"
+    
+    // The setting for this workflow
+    export const workflowSettings: WorkflowSettings = {
+      id: "onNewPasswordProvided",
+      name: "New Password Entered",
+      trigger: WorkflowTrigger.NewPasswordProvided,
+      failurePolicy: {
+        action: "stop",
+      },
+      bindings: {
+        "kinde.widget": {}, // Required for accessing the UI
+      },
+    }
+    
+    function customPasswordValidator(password: string) {
+      const hasUppercase = /[A-Z]/.test(password)
+      const hasLowercase = /[a-z]/.test(password)
+      const hasNumber = /[0-9]/.test(password)
+      const hasSpecialChar = /[!@#$%^&*(),.?":{}|<>]/.test(password)
+    
+      if (!hasUppercase) {
+        return "Password must include at least one uppercase letter."
+      }
+      if (!hasLowercase) {
+        return "Password must include at least one lowercase letter."
+      }
+      if (!hasNumber) {
+        return "Password must include at least one number."
+      }
+      if (!hasSpecialChar) {
+        return "Password must include at least one special character."
+      }
+      return null // valid password
+    }
+    
+    // The workflow code to be executed when the event is triggered
+    export default async function Workflow(event: onNewPasswordProvidedEvent) {
+      const { firstPassword } = event.context.auth
+      const invalidMessage = customPasswordValidator(firstPassword)
+    
+      if (invalidMessage) {
+        // Custom form validation
+        invalidateFormField("p_first_password", invalidMessage)
+      }
+    }
+    ```
+    
+    Optional: Install the Kinde infrastructure dependency with the following bash command for TypeScript intellisense.
+    
+    ```bash
+    npm install
+    ```
+    
+7. Run the following git commands in your terminal to push the changes to your GitHub repo:
+    
+    ```bash
+    git add .
+    git commit -m "add new password validation workflow"
+    git push
+    ```
+    
+
+### Code explanation
+
+Here’s a quick breakdown of what the code does.
+
+**Imports** 
+
+The top of the file brings in useful methods and types from the `@kinde/infrastructure` package, including `onNewPasswordProvidedEvent`, `WorkflowSettings`, and `invalidateFormField`.
+
+**Workflow settings**
+
+The `workflowSettings` object defines when and how the workflow runs.
+
+- It's triggered by the `NewPasswordProvided` event, meaning it runs whenever a user enters a new password.
+- The `name` field ("New Password Entered") helps you easily identify this workflow in the Kinde dashboard.
+- The `bindings` section (`"kinde.widget"`) gives the workflow access to the Kinde sign-in form UI.
+
+**Password validation logic**
+
+The `customPasswordValidator` function checks that the password meets all of your custom rules:
+
+- At least one **uppercase** letter
+- At least one **lowercase** letter
+- At least one **number**
+- At least one **special character**
+
+You can easily update this logic to match your app’s specific requirements.
+
+**Main workflow function**
+
+The default `Workflow` function runs each time the `NewPasswordProvided` event is triggered.
+
+It grabs the user's input, validates the password using your custom logic, and if it fails, calls `invalidateFormField()` to show an error message right in the Kinde UI.
+
+## Step 2: Deploy the workflow code
+
+1. Sign in to your [Kinde dashboard](https://kinde.com/) and select **Workflows** from the sidebar.
+2. If you already have your workflow repo connected, go straight to step 4.
+3. Select **Connect repo > Connect GitHub** and follow the onboarding flow to authorize Kinde to access your GitHub account.
+    
+    ![connect repo to kinde](https://imagedelivery.net/skPPZTHzSlcslvHjesZQcQ/c67bef10-5641-4b5a-87fe-46ff8d247f00/public)
+    
+4. From the dropdown, select your GitHub repository that contains the Kinde workflow code, choose the `main` branch, and click **Next**.
+    
+    If you already have a repo connected and want to change it, go to **Kinde > Settings > Git repo > Change repo.**
+    
+5. Select **Sync code** to pull your latest workflow code from GitHub into your Kinde project. 
+You’ll now see your workflow listed inside the dashboard. 
+    
+    ![list the workflow](https://imagedelivery.net/skPPZTHzSlcslvHjesZQcQ/22096715-7d1d-4e1e-630a-dbf0fef1a800/public)
+    
+
+## Step 3: Test the workflow
+
+1. Sign in to your [Kinde dashboard](https://kinde.com/) and select **View details** for the one you are testing.
+2. Go to **Authentication** and uncheck **Email + code** and check **Email + password** auth method, and select **Save**.
+    
+    By default, Kinde uses passwordless connection, so to test this workflow, we are enabling it.
+    
+    ![enable password connection on kinde](https://imagedelivery.net/skPPZTHzSlcslvHjesZQcQ/9102b724-a7a6-4412-f536-18ba82783d00/public)
+    
+3. Start your project and go through the sign-up flow. When you enter a weak or invalid password, your custom error messages will appear directly in the Kinde sign-up widget, giving users instant feedback based on your validation rules.
+    
+    ![display custom password validation error](https://imagedelivery.net/skPPZTHzSlcslvHjesZQcQ/20c15fcd-36be-4872-6f0e-c0157020ef00/public)
+    
+
+### Phew! All done.
+
+You’ve just built and deployed a custom password validation workflow in Kinde! 
+
+With this setup, you now have full control over the strength and structure of user passwords in your application. Whether you're enforcing security best practices or meeting specific compliance needs, Kinde workflows make it easy to extend the platform with custom logic, without compromising on developer experience.
+
+Check out additional workflow examples in the official [Kinde workflow base template repository](https://github.com/kinde-starter-kits/workflow-base-template).