Our mobile SDKs use JSON Web Tokens (JWT) to authenticate your app. These are a commonly used method for providing authentication and authorisation using one simple token.

In your code, you need to create a function that generates a valid JWT using the JWT authorisation details provided by Dotdigital in your push notification profile, and a cryptographic nonce which we pass. We refer to this as the challenge function.

Required JWT Claims

Whichever provider or method you use to create a JWT, the JWT's claims must include the following with values provided in the Authentication fields in your push notification profile you setup in Dotdigital:

JWT Claim	Value
`iss`	The Issuer value in your Dotdigital push notification profile e.g. https://api.comapi.com/defaultauth
`aud`	The Audience value in your Dotdigital push notification profile e.g. https://api.comapi.com
`sub`	A unique and consistent identifier for the user, such as a user id, email address
`nonce`	The nonce is used to randomise the ciphers for added security

The role of the sub claim

The sub claim in the JWT is used to identify the push profile that is later associated with your Dotdigital contact when you set the email address on the profile. It needs to be unique and preferably consistent per user, so that if a user uses your app on multiple devices all these devices are grouped under the same push profile id, and when you send a push to the contact it is sent to all their devices.

Using a unique and consistent value per user for the sub claim

If you cannot allocate a unique and consistent sub claim for a user, possibly because your app allows anonymous users, then you must use a unique and consistent identifier for the device, such as a GUID which you store in the app, then contacts are restricted to a single device for pushes.

Using a random, unique, consistent value for the sub claim per user

🚧
Ensure your sub claim is unique and consistent per user
The value you pass in the sub claim is the unique user id and cannot be changed later. It is really important that the values are unique per user, and ideally don't change between installs.

📘
Which push profile is associated with my contact?
A PUSHOPTIN_xxx field is automatically created for your Dotdigital contacts when you setup your push notification channel. This contains the push profile id that is associated with a contact.

Signing the JWT

JWTs are digitally signed to prove it was issued by a trusted party. You must sign the JWT with the value of the Shared secret field from your push notification profile and the nonce we pass your function to prove it was issued by you.

Nonces

A cryptographic nonce must also be used by your JWT provider when creating the token to ensure that tokens always appear different even if they contain the same claims; this is a common security practice with cryptography. The SDK passes this nonce as an argument to your challenge function during initialisation of the SDK where you create or retrieve a JWT for your app user.

❗️
Important security note
We recommend that you do not hard code your shared secret on the client side. Instead, this value should be stored on the server side.

Sample Code

The following example code demonstrates how to create a challenge function and a self issued JWT for both Android and iOS:

Android JWT code sample

JWT provider: Java JWT.

Any class that you create to generate a JWT token must extend the ComapiAuthenticator class.

Any logic that creates the JWT token must be inside the onAuthenticationChallenge() method.
This method takes two parameters: AuthClient and ChallengeOptions.

Get the value of the nonce by calling the ChallengeOptions.GetNonce() method

When your JWT token is returned, pass it to the authenticateWithToken() method of the AuthClient object.

package com.example.testapp;

import android.content.SharedPreferences;
import android.text.TextUtils;
import android.util.Base64;

import com.comapi.ComapiAuthenticator;
import com.comapi.internal.network.AuthClient;
import com.comapi.internal.network.ChallengeOptions;

import java.io.UnsupportedEncodingException;
import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.TimeUnit;

import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;

public class ChallengeHandler extends ComapiAuthenticator {


    @Override
    public void onAuthenticationChallenge(AuthClient authClient, ChallengeOptions challengeOptions) {

      try {

        byte[] data;
        //<Shared secret> string must be the same as the value of the 'Shared secret' field in your push notification profile in Dotdigital. 
        data = "<Shared secret>".getBytes("UTF-8");

        String base64Secret = Base64.encodeToString(data, Base64.DEFAULT);

        Map<String, Object> header = new HashMap<>();
        header.put("typ", "JWT");

        Map<String, Object> claims = new HashMap<>();
        claims.put("nonce", challengeOptions.getNonce());
        // ID claim, this claim name must be the same as the value of the 'ID claim' field in your push notification profile in Dotdigital,
        // the default value is 'sub', and the value of the claim must be a consitent unique value for the app user.
        claims.put("sub", "<Unique consitent app user id>");
        //<Audience> string must be the same as the value of the 'Audience' field in your push notification profile in Dotdigital.
        claims.put("aud", "<Audience>");
        //<Issuer> string must be the same as the value of the 'Issuer' field in your push notification profile in Dotdigital.
        claims.put("iss", "<Issuer>");
        claims.put("iat", System.currentTimeMillis());
        claims.put("exp", System.currentTimeMillis() + TimeUnit.DAYS.toMillis(30));

        final String token = Jwts.builder()
          .setHeader(header)
          .setClaims(claims)
          .signWith(SignatureAlgorithm.HS256, base64Secret)
          .compact();

        //Pass the JWT token to the SDK.
        authClient.authenticateWithToken(token);

      } catch (UnsupportedEncodingException e) {
        e.printStackTrace();
        //Authorisation failed.
        authClient.authenticateWithToken(null);
      }
    }
}

iOS JWT code sample

Here's an example implementation of a token generator in Objective-C and Swift using JWT

#import "CMPAuthenticationManager.h"
#import <JWT/JWT.h>

@implementation CMPAuthenticationManager

+ (NSString *)generateTokenForNonce:(NSString *)nonce profileID:(NSString *)profileID issuer:(NSString *)issuer audience:(NSString *)audience secret:(NSString *)secret {
    NSDate *now = [NSDate date];
    NSDate *exp = [NSCalendar.currentCalendar dateByAddingUnit:NSCalendarUnitDay value:30 toDate:now options:0];
    
    NSDictionary *headers = @{@"typ" : @"JWT"};
    /* Claims notes:
       ID claim, this claim name must be the same as the value of the 'ID claim' field in your push notification profile in Dotdigital,
       the default value is 'sub', and the value of the claim must be a consitent unique value for the app user. 
       
       'aud' audience claim must be the same as the value of the 'Audience' field in your push notification profile in Dotdigital.
       
       'iss' audience claim must be the same as the value of the 'Issuer' field in your push notification profile in Dotdigital.
    */
    NSDictionary *payload = @{@"nonce" : nonce,
                               @"sub" : profileID,
                               @"iss" : issuer,
                               @"aud" : audience,
                               @"iat" : [NSNumber numberWithDouble:now.timeIntervalSince1970],
                               @"exp" : [NSNumber numberWithDouble:exp.timeIntervalSince1970]};
    
    NSData *secretData = [secret dataUsingEncoding:NSUTF8StringEncoding];
    id<JWTAlgorithm> algorithm = [JWTAlgorithmFactory algorithmByName:@"HS256"];
    
    NSString *token = [JWTBuilder encodePayload:payload].headers(headers).secretData(secretData).algorithm(algorithm).encode;
    return token;
}

@end
  
/* Note that this should preferably be generated by your backend, the app should only retreive the token through an HTTP call */

import JWT

class JWTokenGenerator {
    
    struct AuthHeaders {
        static let HeaderType = "JWT"
    }
    
    static func generate(tokenFor nonce: String, profileId: String, issuer: String, audience: String, secret: String) -> String {
        let now = Date()
        let exp = Calendar.current.date(byAdding: .day, value: 30, to: now)!
        
        let base64SecretKey = secret.data(using: .utf8)!
        
        let headers = ["typ" : NSString.init(string: AuthHeaders.HeaderType)] as [AnyHashable : Any]
        
        /* Claims notes:
        ID claim, this claim name must be the same as the value of the 'ID claim' field in your push notification profile in Dotdigital,
        the default value is 'sub', and the value of the claim must be a consitent unique value for the app user. 

        'aud' audience claim must be the same as the value of the 'Audience' field in your push notification profile in Dotdigital.

        'iss' audience claim must be the same as the value of the 'Issuer' field in your push notification profile in Dotdigital.
        */
        let claims = ["nonce" : NSString.init(string: nonce),
                      "sub" : NSString.init(string: profileId),
                      "iss" : NSString.init(string: issuer),
                      "aud" : NSString.init(string: audience),
                      "iat" : NSNumber(value: now.timeIntervalSince1970),
                      "exp" : NSNumber(value: exp.timeIntervalSince1970)] as [AnyHashable : Any]
        
        let algorithm = JWTAlgorithmFactory.algorithm(byName: "HS256")
        
        let e = JWTBuilder.encodePayload(claims)!
        
        let h = e.headers(headers)!
        let s = h.secretData(base64SecretKey)!
        let b = s.algorithm(algorithm)!
        let token = b.encode

        return token!
    }
}

/* Note that this should preferably be generated by your backend, the app should only retreive the token through an HTTP call */

JavaScript JWT code sample

JWT provider: jsrassign library.

Get the value of the nonce by using the nonce property of the first parameter.

When your JWT token is returned, pass it to the answerAuthenticationChallenge() function (second parameter of your challengeHandler() function).

function challengeHandler (options, answerAuthenticationChallenge) {
    // Header
    var oHeader = { alg: 'HS256', typ: 'JWT' };
    // Payload
    var tNow = KJUR.jws.IntDate.get('now');
    var tEnd = KJUR.jws.IntDate.get('now + 1day');

    var oPayload = {
      	// ID claim, this claim name must be the same as the value of the 'ID claim' field in your push notification profile in Dotdigital,
        // the default value is 'sub', and the value of the claim must be a consitent unique value for the app user. 
        sub: "<Unique consitent app user id>",
        nonce: options.nonce,
      	// 'aud' audience claim must be the same as the value of the 'Audience' field in your push notification profile in Dotdigital.
        aud: "<Audience>",
        // 'iss' audience claim must be the same as the value of the 'Issuer' field in your push notification profile in Dotdigital.
        iss: "<Issuer>",
        iat: tNow,
        exp: tEnd,
    };
    var sHeader = JSON.stringify(oHeader);
    var sPayload = JSON.stringify(oPayload);
  	//<Shared secret> string must be the same as the value of the 'Shared secret' field in your push notification profile in Dotdigital. 
    var sJWT = KJUR.jws.JWS.sign("HS256", sHeader, sPayload, {utf8: "<Shared secret>"});
    answerAuthenticationChallenge(sJWT);
}

🚧
Be careful with the secret value being automatically cast to hex
The jsrassign library automatically checks the secret field to see if it is a hexadecimal number being passed. We always use string based secrets, so to stop this unwanted automatic cast please ensure that the secret value is always cast to an UTF8 string by using the following cast operation {utf8: <Your secret value>}
Common indications of this issue are 403 - Invalid JWT errors when trying to start a session with the SDK.

Create a JWT

Required JWT Claims

The role of the sub claim

🚧
Ensure your `sub` claim is unique and consistent per user

📘
Which push profile is associated with my contact?

Signing the JWT

Nonces

❗️
Important security note

Sample Code

Android JWT code sample

iOS JWT code sample

JavaScript JWT code sample

🚧
Be careful with the secret value being automatically cast to hex

Required JWT Claims

The role of the sub claim

🚧Ensure your sub claim is unique and consistent per user

📘Which push profile is associated with my contact?

Signing the JWT

Nonces

❗️Important security note

Sample Code

Android JWT code sample

iOS JWT code sample

JavaScript JWT code sample

🚧Be careful with the secret value being automatically cast to hex

🚧
Ensure your `sub` claim is unique and consistent per user

📘
Which push profile is associated with my contact?

❗️
Important security note

🚧
Be careful with the secret value being automatically cast to hex