Merge pull request #767 from Iterable/jwt/SDK-136-new-jwt-token-generator

[SDK-136] Add Jwt Generator to Example app

Author: lposen

.gitignore

@@ -85,6 +85,7 @@ ios/generated
 android/generated
 
 # Iterable
+.env.local
 .env
 .xcode.env.local
 coverage/

example/.env.example

@@ -9,11 +9,19 @@
 #  4. Fill in the following fields:
 #     - Name: A descriptive name for the API key
 #     - Type: Mobile
-#     - JWT authentication: Leave **unchecked** (IMPORTANT)
+#     - JWT authentication: Whether or not you want to use JWT
 #  5. Click "Create API Key"
-#  6. Copy the generated API key
-#  7. Replace the placeholder text next to `ITBL_API_KEY=` with the copied API key
+#  6. Copy the generated API key and replace the placeholder text next to
+#     `ITBL_API_KEY=` with the copied API key
+#  7. If you chose to enable JWT authentication, copy the JWT secret and and
+#     replace the placeholder text next to `ITBL_JWT_SECRET=` with the copied
+#     JWT secret
 ITBL_API_KEY=replace_this_with_your_iterable_api_key
+# Your JWT Secret, created when making your API key (see above)
+ITBL_JWT_SECRET=replace_this_with_your_jwt_secret
+# Is your api token JWT Enabled?
+# Must be set to 'true' to enable JWT authentication
+ITBL_IS_JWT_ENABLED=true
 
 # Your Iterable user ID or email address
-ITBL_ID=replace_this_with_your_user_id_or_email
+ITBL_ID=replace_this_with_your_user_id_or_email

example/README.md

@@ -23,7 +23,8 @@ _example app directory_.  To do so, run the following:
 
 ```bash
 cd ios
-pod install
+bundle install
+bundle exec pod install
 ```
 
 Once this is done, `cd` back into the _example app directory_:
@@ -40,12 +41,18 @@ In it, you will find:
 
 ```shell
 ITBL_API_KEY=replace_this_with_your_iterable_api_key
+ITBL_JWT_SECRET=replace_this_with_your_jwt_secret
+ITBL_IS_JWT_ENABLED=true
 ITBL_ID=replace_this_with_your_user_id_or_email
 ```
 
-Replace `replace_this_with_your_iterable_api_key` with your _mobile_ Iterable API key,
-and replace `replace_this_with_your_user_id_or_email` with the email or user id
-that you use to log into Iterable.
+- Replace `replace_this_with_your_iterable_api_key` with your **_mobile_
+Iterable API key**
+- Replace `replace_this_with_your_jwt_secret` with your **JWT Secret** (if you
+have a JWT-enabled API key)
+- Set `ITBL_IS_JWT_ENABLED` to true if you have a JWT-enabled key, and false if you do not.
+- Replace `replace_this_with_your_user_id_or_email` with the **email or user
+id** that you use to log into Iterable.
 
 Follow the steps below if you do not have a mobile Iterable API key.
 
@@ -54,12 +61,12 @@ To add an API key, do the following:
  1. Sign into your Iterable account
  2. Go to [Integrations > API Keys](https://app.iterable.com/settings/apiKeys)
  3. Click "New API Key" in the top right corner
- 4. Fill in the followsing fields:
+ 4. Fill in the following fields:
     - Name: A descriptive name for the API key
     - Type: Mobile
-    - JWT authentication: Leave **unchecked** (IMPORTANT)
+    - JWT authentication: Check to enable JWT authentication. If enabled, will need to create a [JWT generator](https://support.iterable.com/hc/en-us/articles/360050801231-JWT-Enabled-API-Keys#sample-python-code-for-jwt-generation) to generate the JWT token.
  5. Click "Create API Key"
- 6. Copy the generated API key
+ 6. Copy the generated API key and JWT secret into your _.env_ file
 
 
 ## Step 3: Start the Metro Server

example/android/app/src/main/java/iterable/reactnativesdk/example/IterableJwtGenerator.java

@@ -0,0 +1,106 @@
+package com.iterable;
+
+import javax.crypto.Mac;
+import javax.crypto.spec.SecretKeySpec;
+import java.nio.charset.StandardCharsets;
+import java.time.Duration;
+import java.util.Base64;
+import java.util.Base64.Encoder;
+
+/**
+* Utility class to generate JWTs for use with the Iterable API
+*
+* @author engineering@iterable.com
+*/
+public class IterableJwtGenerator {
+   static Encoder encoder = Base64.getUrlEncoder().withoutPadding();
+
+   private static final String algorithm = "HmacSHA256";
+
+   // Iterable enforces a 1-year maximum token lifetime
+   private static final Duration maxTokenLifetime = Duration.ofDays(365);
+
+   private static long millisToSeconds(long millis) {
+       return millis / 1000;
+   }
+
+   private static final String encodedHeader = encoder.encodeToString(
+       "{\"alg\":\"HS256\",\"typ\":\"JWT\"}".getBytes(StandardCharsets.UTF_8)
+   );
+
+   /**
+    * Generates a JWT from the provided secret, header, and payload. Does not
+    * validate the header or payload.
+    *
+    * @param secret  Your organization's shared secret with Iterable
+    * @param payload The JSON payload
+    *
+    * @return a signed JWT
+    */
+   public static String generateToken(String secret, String payload) {
+       try {
+           String encodedPayload = encoder.encodeToString(
+               payload.getBytes(StandardCharsets.UTF_8)
+           );
+           String encodedHeaderAndPayload = encodedHeader + "." + encodedPayload;
+
+           // HMAC setup
+           Mac hmac = Mac.getInstance(algorithm);
+           SecretKeySpec keySpec = new SecretKeySpec(
+               secret.getBytes(StandardCharsets.UTF_8), algorithm
+           );
+           hmac.init(keySpec);
+
+           String signature = encoder.encodeToString(
+               hmac.doFinal(
+                   encodedHeaderAndPayload.getBytes(StandardCharsets.UTF_8)
+               )
+           );
+
+           return encodedHeaderAndPayload + "." + signature;
+
+       } catch (Exception e) {
+           throw new RuntimeException(e.getMessage());
+       }
+   }
+
+   /**
+    * Generates a JWT (issued now, expires after the provided duration).
+    *
+    * @param secret   Your organization's shared secret with Iterable.
+    * @param duration The token's expiration time. Up to one year.
+    * @param email    The email to included in the token, or null.
+    * @param userId   The userId to include in the token, or null.
+    *
+    * @return A JWT string
+    */
+   public static String generateToken(
+       String secret, Duration duration, String email, String userId) {
+
+       if (duration.compareTo(maxTokenLifetime) > 0)
+           throw new IllegalArgumentException(
+               "Duration must be one year or less."
+           );
+
+       if ((userId != null && email != null) || (userId == null && email == null))
+           throw new IllegalArgumentException(
+               "The token must include a userId or email, but not both."
+           );
+
+       long now = millisToSeconds(System.currentTimeMillis());
+
+       String payload;
+       if (userId != null)
+           payload = String.format(
+               "{ \"userId\": \"%s\", \"iat\": %d, \"exp\": %d }",
+               userId, now, now + millisToSeconds(duration.toMillis())
+           );
+       else
+           payload = String.format(
+               "{ \"email\": \"%s\", \"iat\": %d, \"exp\": %d }",
+               email, now, now + millisToSeconds(duration.toMillis())
+           );
+
+       return generateToken(secret, payload);
+   }
+}

example/android/app/src/main/java/iterable/reactnativesdk/example/JwtTokenModule.kt

@@ -0,0 +1,37 @@
+package iterable.reactnativesdk.example
+
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.Promise
+import com.iterable.IterableJwtGenerator
+import java.time.Duration
+
+class JwtTokenModule(reactContext: ReactApplicationContext) : ReactContextBaseJavaModule(reactContext) {
+
+    override fun getName(): String {
+        return NAME
+    }
+
+    @ReactMethod
+    fun generateJwtToken(
+        secret: String,
+        durationMs: Double,
+        email: String?,
+        userId: String?,
+        promise: Promise
+    ) {
+        try {
+            val duration = Duration.ofMillis(durationMs.toLong())
+            val token = IterableJwtGenerator.generateToken(secret, duration, email, userId)
+            promise.resolve(token)
+        } catch (e: Exception) {
+            promise.reject("JWT_GENERATION_ERROR", e.message, e)
+        }
+    }
+
+    companion object {
+        const val NAME = "JwtTokenModule"
+    }
+}
+

example/android/app/src/main/java/iterable/reactnativesdk/example/JwtTokenPackage.kt

@@ -0,0 +1,34 @@
+package iterable.reactnativesdk.example
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+
+class JwtTokenPackage : BaseReactPackage() {
+
+    override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
+        return if (name == JwtTokenModule.NAME) {
+            JwtTokenModule(reactContext)
+        } else {
+            null
+        }
+    }
+
+    override fun getReactModuleInfoProvider(): ReactModuleInfoProvider {
+        return ReactModuleInfoProvider {
+            val moduleInfos: MutableMap<String, ReactModuleInfo> = HashMap()
+            moduleInfos[JwtTokenModule.NAME] = ReactModuleInfo(
+                JwtTokenModule.NAME,
+                JwtTokenModule.NAME,
+                false,  // canOverrideExistingModule
+                false,  // needsEagerInit
+                true,   // hasConstants
+                false   // isCxxModule
+            )
+            moduleInfos
+        }
+    }
+}
+

example/android/app/src/main/java/iterable/reactnativesdk/example/MainApplication.kt

@@ -20,6 +20,7 @@ class MainApplication : Application(), ReactApplication {
             PackageList(this).packages.apply {
               // Packages that cannot be autolinked yet can be added manually here, for example:
               // add(MyReactNativePackage())
+              add(JwtTokenPackage())
             }
 
         override fun getJSMainModuleName(): String = "index"

example/ios/IterableJwtGenerator.swift

@@ -0,0 +1,95 @@
+//
+//  IterableJwtGenerator.swift
+//  ReactNativeSdkExample
+//
+//  Utility class to generate JWTs for use with the Iterable API
+//
+
+import CryptoKit
+import Foundation
+
+@objcMembers public final class IterableJwtGenerator: NSObject {
+
+  private struct Header: Encodable {
+    let alg = "HS256"
+    let typ = "JWT"
+  }
+
+  /// Base64 URL encode without padding (URL-safe base64 encoding for JWT)
+  private static func urlEncodedBase64(_ data: Data) -> String {
+    let base64 = data.base64EncodedString()
+    return
+      base64
+      .replacingOccurrences(of: "+", with: "-")
+      .replacingOccurrences(of: "/", with: "_")
+      .replacingOccurrences(of: "=", with: "")
+  }
+
+  /// Generic JWT generation helper that works with any Encodable payload
+  private static func generateJwt<T: Encodable>(secret: String, payload: T) -> String {
+    let headerJsonData = try! JSONEncoder().encode(Header())
+    let headerBase64 = urlEncodedBase64(headerJsonData)
+
+    let payloadJsonData = try! JSONEncoder().encode(payload)
+    let payloadBase64 = urlEncodedBase64(payloadJsonData)
+
+    let toSign = Data((headerBase64 + "." + payloadBase64).utf8)
+
+    if #available(iOS 13.0, *) {
+      let privateKey = SymmetricKey(data: Data(secret.utf8))
+      let signature = HMAC<SHA256>.authenticationCode(for: toSign, using: privateKey)
+      let signatureBase64 = urlEncodedBase64(Data(signature))
+
+      let token = [headerBase64, payloadBase64, signatureBase64].joined(separator: ".")
+
+      return token
+    }
+    return ""
+  }
+
+  public static func generateJwtForEmail(secret: String, iat: Int, exp: Int, email: String)
+    -> String
+  {
+    struct Payload: Encodable {
+      var email: String
+      var iat: Int
+      var exp: Int
+    }
+
+    return generateJwt(secret: secret, payload: Payload(email: email, iat: iat, exp: exp))
+  }
+
+  public static func generateJwtForUserId(secret: String, iat: Int, exp: Int, userId: String)
+    -> String
+  {
+    struct Payload: Encodable {
+      var userId: String
+      var iat: Int
+      var exp: Int
+    }
+
+    return generateJwt(secret: secret, payload: Payload(userId: userId, iat: iat, exp: exp))
+  }
+
+  public static func generateToken(
+    secret: String, durationMs: Int64, email: String?, userId: String?
+  ) throws -> String {
+    // Convert durationMs from milliseconds to seconds
+    let durationSeconds = Double(durationMs) / 1000.0
+    let currentTime = Date().timeIntervalSince1970
+
+    if userId != nil {
+      return generateJwtForUserId(
+        secret: secret, iat: Int(currentTime),
+        exp: Int(currentTime + durationSeconds), userId: userId!)
+    } else if email != nil {
+      return generateJwtForEmail(
+        secret: secret, iat: Int(currentTime),
+        exp: Int(currentTime + durationSeconds), email: email!)
+    } else {
+      throw NSError(
+        domain: "JWTGenerator", code: 6,
+        userInfo: [NSLocalizedDescriptionKey: "No email or userId provided"])
+    }
+  }
+}

example/ios/JwtTokenModule.mm

@@ -0,0 +1,25 @@
+//
+//  JwtTokenModule.m
+//  ReactNativeSdkExample
+//
+//  React Native module bridge for JWT token generation
+//
+
+#import <React/RCTBridgeModule.h>
+
+@interface RCT_EXTERN_MODULE(JwtTokenModule, NSObject)
+
+RCT_EXTERN_METHOD(generateJwtToken:(NSString *)secret
+                  durationMs:(double)durationMs
+                  email:(NSString *)email
+                  userId:(NSString *)userId
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
++ (BOOL)requiresMainQueueSetup
+{
+    return NO;
+}
+
+@end
+