Authenticate and Log In the End User

Learn about authentication and the login process on Android

After initialization has succeeded and the user has logged into your system of record, generate the JWT token in order to login to BrandMessenger.

There are various ways to generate the JWT token, using https://java.jsonwebtoken.io/jjwtdocs.html is one, but it is recommended that this logic is serverside, so that API_KEY_ID and API_KEY_SECRET are not present in the application code.

🚧

Both the API_KEY_ID and API_KEY_SECRET are obtained by contacting Khoros Support, if you do not already have them, and should be kept completely hidden from your users.

📘

We recommend reviewing your JWT generation method with your IT department to ensure that you are using the most secure option possible.

Generate the JWT

The following example snippet generates a JWT using an open source library where:

  • kid is your API Key ID
  • userId is the user's ID in your system of record

🚧

The token must be generated server-side! This should never be present in the browser because the key_id and secret are extremely sensitive information. In the event that a key_id and secret are exposed, you must contact Khoros Support to generate new ones, and update your backend systems to use the new credentials.

Here is an example:

final Map<String, Object> customProperties = new HashMap<>();
customProperties.put("userId", userID);
customProperties.put("scope", "appUser");
customProperties.put("platform", "android");
customProperties.put("givenName", loginName);

try {
    String jwtString =
    Jwts.builder()
        .addClaims(customProperties)
        .setHeaderParam("kid", API_KEY_ID)
        .setHeaderParam("typ", "JWT")
        .setIssuedAt(new Date(1420070400000l))
        .signWith(SignatureAlgorithm.HS256, API_KEY_SECRET.getBytes("UTF-8"))
        .compact();

    return jwtString;
} catch (UnsupportedEncodingException e) {
    return "There was an error while generating Smooch JSON Web Token";
}

Using an identity provider (IdP)

📘

The Brand Messenger Android SDK does not integrate directly with any external IDP, however, IDPs are supported as long as customers can generate the JWT as outlined in this section.

Oauth flow occurs outside of the SDK and is not restricted nor directly utilized by the Brand Messenger SDK for authentication.

Companies that opt to use an IdP should be aware of the general authentication flow and how the login process works for accounts using an IdP for authentication. Here is a quick walkthrough of the flow:

  • The user logs into the IdP.
  • Upon successful login to the IdP, the IdP returns the user's profile, which should contain the userId and name of the user. These two fields are required by Brand Messenger's JWT flow.
  • The app calls the company's own API getJWT using the userId and name.
  • The API generates the JWT in the server and returns it to the app.
  • The app logs into Brand Messenger using the generated JWT. Since the JWT includes the userId and name, the user can be identified between sessions/devices/etc.

🚧

Even with the use of an IdP, it's important that the JWT is generated at the server, rather than the app. This prevents any potential security risks that arise from storing the API_KEY_SECRET locally within the app's code.

During JWT token generation, include the following information in your claims:

  • 'userId' as the userId from your IdP
  • 'scope' as 'appUser'
  • 'platform' as 'android'
  • givenName' as user's name`

The header should include:

  • kid as your API Key ID
  • typ as JWT

The token should be signed with the HS256 algorithm using UTF-8 encoding of your API Key Secret.

Log the user into your app with the JWT

Here is an example login snippet:

BrandMessenger.login(
    userID,
    jwtString,
    new BrandMessengerCallback<LoginResult>() {
        @Override
        public void run(Response response) {
        }
    }
);

The example below shows how the login process works.

private void initSecureMessagingSdk() { 

// If a user is logged in, get user ID, username, first name, last name.
// If user is anonymous, generate an ID and username

// Log the author into Brand Mesenger. This supplies the JWT with
// credentials. 

    BrandMessenger.login(
            userId,
            generateJwt(this, userId, loginName, ""),
            new BrandMessengerCallback() {
                @Override
                public void run(Response response) {
                    User user = User.getCurrentUser();
                    // Set default properties on the user
                    // Or set all values if you have them
                    // At minimum, set first name, last name,
                    // and (epoch) date user started using Messaging.

                    user.setFirstName(loginName);
                    user.setLastName("");
                    user.setSignedUpAt(new Date(1420070400000l));
                }
            });
     }

Once successful, the SDK is ready to communicate.


Did this page help you?