Merge pull request #112 from kinde-oss/feat/marketing-properties

Author: DanielRivers

lib/types.ts

@@ -11,9 +11,9 @@ export enum PromptTypes {
   login = "login",
 }
 
-export type LoginMethodParams = Partial<
+export type LoginMethodParams<T = Record<string, string>> = Partial<
   Pick<
-    LoginOptions,
+    LoginOptions<T>,
     | "audience"
     | "scope"
     | "isCreateOrg"
@@ -26,10 +26,49 @@ export type LoginMethodParams = Partial<
     | "redirectURL"
     | "hasSuccessPage"
     | "workflowDeploymentId"
+    | "properties"
   >
 >;
 
-export type LoginOptions = {
+export type KindeProperties = Partial<{
+  // UTM tags
+  utm_source: string;
+  utm_medium: string;
+  utm_campaign: string;
+  utm_content: string;
+  utm_term: string;
+
+  // Google Ads smart campaign tracking
+  gclid: string;
+  click_id: string;
+  hsa_acc: string;
+  hsa_cam: string;
+  hsa_grp: string;
+  hsa_ad: string;
+  hsa_src: string;
+  hsa_tgt: string;
+  hsa_kw: string;
+  hsa_mt: string;
+  hsa_net: string;
+  hsa_ver: string;
+
+  // Marketing category
+  match_type: string;
+  keyword: string;
+  device: string;
+  ad_group_id: string;
+  campaign_id: string;
+  creative: string;
+  network: string;
+  ad_position: string;
+  fbclid: string;
+  li_fat_id: string;
+  msclkid: string;
+  twclid: string;
+  ttclid: string;
+}>;
+
+export type LoginOptions<T = Record<string, string>> = {
   /** Audience to include in the token */
   audience?: string;
   /** Client ID of the application
@@ -122,6 +161,10 @@ export type LoginOptions = {
    * Workflow Deployment ID to trigger on authentication
    */
   workflowDeploymentId?: string;
+  /**
+   * Properties to be passed
+   */
+  properties?: T & KindeProperties;
 };
 
 export enum IssuerRouteTypes {

lib/utils/generateAuthUrl.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi } from "vitest";
 import { IssuerRouteTypes, LoginOptions, PromptTypes, Scopes } from "../types";
 import { generateAuthUrl } from "./generateAuthUrl";
 import { MemoryStorage, StorageKeys } from "../sessionManager";
@@ -228,4 +228,90 @@ describe("generateAuthUrl", () => {
     result.url.searchParams.delete("state");
     expect(result.url.toString()).toBe(expectedUrl);
   });
+
+  it("Properties are added when defined", async () => {
+    const domain = "https://auth.example.com";
+    const options: LoginOptions = {
+      clientId: "client123",
+      scope: [Scopes.openid, Scopes.profile, Scopes.offline_access],
+      redirectURL: "https://example2.com",
+      prompt: PromptTypes.create,
+      properties: {
+        utm_campaign: "test",
+      },
+    };
+    const expectedUrl =
+      "https://auth.example.com/oauth2/auth?client_id=client123&response_type=code&redirect_uri=https%3A%2F%2Fexample2.com&audience=&scope=openid+profile+offline&prompt=create&code_challenge_method=S256&utm_campaign=test";
+
+    const result = await generateAuthUrl(
+      domain,
+      IssuerRouteTypes.login,
+      options,
+    );
+    const nonce = result.url.searchParams.get("nonce");
+    expect(nonce).not.toBeNull();
+    expect(nonce!.length).toBe(16);
+    const state = result.url.searchParams.get("state");
+    expect(state).not.toBeNull();
+    expect(state!.length).toBe(32);
+    const codeChallenge = result.url.searchParams.get("code_challenge");
+    expect(codeChallenge!.length).toBeGreaterThanOrEqual(27);
+    result.url.searchParams.delete("code_challenge");
+    result.url.searchParams.delete("nonce");
+    result.url.searchParams.delete("state");
+    expect(result.url.toString()).toBe(expectedUrl);
+  });
+
+  it("When non whitelisted properties are added when defined, warn for each one do not add to the url", async () => {
+    const consoleWarnSpy = vi.spyOn(console, "warn");
+
+    const domain = "https://auth.example.com";
+    const options: LoginOptions<{
+      testProperty1: string;
+      testProperty2: string;
+    }> = {
+      clientId: "client123",
+      scope: [Scopes.openid, Scopes.profile, Scopes.offline_access],
+      redirectURL: "https://example2.com",
+      prompt: PromptTypes.create,
+      properties: {
+        utm_campaign: "test",
+        testProperty1: "testValue1",
+        testProperty2: "testValue2",
+      },
+    };
+    const expectedUrl =
+      "https://auth.example.com/oauth2/auth?client_id=client123&response_type=code&redirect_uri=https%3A%2F%2Fexample2.com&audience=&scope=openid+profile+offline&prompt=create&code_challenge_method=S256&utm_campaign=test";
+
+    const result = await generateAuthUrl(
+      domain,
+      IssuerRouteTypes.login,
+      options,
+    );
+    const nonce = result.url.searchParams.get("nonce");
+    expect(nonce).not.toBeNull();
+    expect(nonce!.length).toBe(16);
+    const state = result.url.searchParams.get("state");
+    expect(state).not.toBeNull();
+    expect(state!.length).toBe(32);
+    const codeChallenge = result.url.searchParams.get("code_challenge");
+    expect(codeChallenge!.length).toBeGreaterThanOrEqual(27);
+    result.url.searchParams.delete("code_challenge");
+    result.url.searchParams.delete("nonce");
+    result.url.searchParams.delete("state");
+    expect(result.url.toString()).toBe(expectedUrl);
+
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      "Unsupported Property for url generation: ",
+      "testProperty1",
+    );
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      "Unsupported Property for url generation: ",
+      "testProperty2",
+    );
+    expect(consoleWarnSpy).not.toHaveBeenCalledWith(
+      "Unsupported Property for url generation: ",
+      "utm_campaign",
+    );
+  });
 });

lib/utils/generateAuthUrl.ts

@@ -3,6 +3,44 @@ import { IssuerRouteTypes, LoginOptions, PromptTypes } from "../types";
 import { generateRandomString } from "./generateRandomString";
 import { mapLoginMethodParamsForUrl } from "./mapLoginMethodParamsForUrl";
 
+const whiteListedProperties = [
+  // UTM tags
+  "utm_source",
+  "utm_medium",
+  "utm_campaign",
+  "utm_content",
+  "utm_term",
+
+  // Google Ads smart campaign tracking
+  "gclid",
+  "click_id",
+  "hsa_acc",
+  "hsa_cam",
+  "hsa_grp",
+  "hsa_ad",
+  "hsa_src",
+  "hsa_tgt",
+  "hsa_kw",
+  "hsa_mt",
+  "hsa_net",
+  "hsa_ver",
+
+  // Marketing category
+  "match_type",
+  "keyword",
+  "device",
+  "ad_group_id",
+  "campaign_id",
+  "creative",
+  "network",
+  "ad_position",
+  "fbclid",
+  "li_fat_id",
+  "msclkid",
+  "twclid",
+  "ttclid",
+];
+
 interface generateAuthUrlConfig {
   disableUrlSanitization: boolean;
 }
@@ -70,6 +108,19 @@ export const generateAuthUrl = async (
     searchParams["prompt"] = PromptTypes.create;
   }
 
+  if (loginOptions.properties) {
+    Object.keys(loginOptions.properties).forEach((key) => {
+      if (!whiteListedProperties.includes(key)) {
+        console.warn("Unsupported Property for url generation: ", key);
+        return;
+      }
+      const value = loginOptions.properties?.[key];
+      if (value !== undefined) {
+        searchParams[key] = value;
+      }
+    });
+  }
+
   const queryString = new URLSearchParams(searchParams).toString();
 
   return {