Building a dedicated JWT endpoint for the Support SDK

This article is for teams responsible for implementing JWT services in organizations. It describes how to build a JWT endpoint to work with the Support SDK for mobile applications.

When integrating the Support SDK in a mobile application, the SDK can be configured to use JWT to authenticate the application's users in Zendesk Support. If this option is chosen, the Zendesk Support service calls a JWT endpoint provided by your organization to authenticate the users.

A dedicated JWT endpoint must be built for the Support SDK. Libraries for implementing JWT services are available for most modern languages. Zendesk Support provides a number of JWT endpoint code examples for different stacks on Github. Though geared for SSO sign-ins, you can replace the sign-in redirect in the examples with an HTTP response.

Your organization must also have a user database and a way for the endpoint to query it. The Zendesk Support service will pass a unique identifier to the endpoint and wait for your system to look up the user in the database and confirm that the user is known and trusted.

If it's not already done, the developers of the mobile application must modify the application to get the unique identifier of the current user. The application can then pass the identifier to the Support SDK to authenticate the user in Zendesk Support.

The identifier can be whatever you want to use to look up users in your database.

Topics covered in this article:

Building the endpoint
Troubleshooting your JWT implemention

Building the endpoint

After getting a unique identifier from your organization's mobile application, the Zendesk Support service will send it in a request to your dedicated JWT endpoint. The Zendesk Support service will expect a response containing a JWT token confirming that the user is known and trusted. See the request and response formats below.

A Zendesk Support administrator in your organization should provide you with the shared secret to sign the JWT token. See JSON web token response below.

After building the endpoint, provide the endpoint URL to the Support administrator. The admin needs the URL to finish configuring the SDK in the Support account.

Here's the authentication flow (enlarge):

SDK authentication flow

Request format

The Zendesk Support service will make a POST request with the following format to the JWT endpoint:

POST {your_service_uri}
user_token={user_identifier_provided_by_the_app}

Response format

The Zendesk Support service expects the following response format:

200 OK
{
  "jwt": "{your_jwt_token_response}"
}

If the user identifier the Zendesk Support service sends to the JWT endpoint is not known or trusted, a HTTP 401 Unauthorized response should be returned to the Zendesk Support service.

JSON web token response

A Zendesk Support admin should provide you with the shared secret. If not, refer the admin to Setting up the SDK in the Zendesk Support Help Center. Use the secret to generate the encrypted string for the JWS signature.

Note: You must use the HMAC with SHA-256 (HS256) algorithm for signing. The RSA signature with SHA-256 (RS256) algorithm is not supported.

The following token properties are required:

name
email
jti
iat

Notes:

The JWT will be rejected if any of the properties is missing or empty
The keys must be lower case
The email and name values are case-sensitive in Zendesk Support
iat must be a whole number in seconds

Troubleshooting your JWT implementation

If your JWT implementation doesn't work as expected, try the following troubleshooting steps:

Make sure you're not using SSO JWT
Check the app settings in Zendesk Support
Check your initialization code
Test your JWT endpoint
Verify the JWT payload
Verify the shared secret
Check your SSL certificates

Make sure you're not using SSO JWT

The Support SDK JWT is not the same as Zendesk Support SSO JWT. You must build a dedicated JWT endpoint for the Support SDK, as described above. If you use a JWT library to generate your JWT tokens, make sure you replace the sign-in redirect with an HTTP response.

Check the app settings in Zendesk Support

You need to sign in as a Zendesk Support admin, or ask a Zendesk Support admin in your organization to check the app settings in Zendesk Support for you.

In the Zendesk Support agent interface, click the Admin icon in the sidebar, then select Channels > Mobile SDK.
Verify the following settings:

Notes:
- Authentication method must be JWT
- JWT URL is an endpoint that you must build specifically for the mobile SDK. It's not your Zendesk Support SSO JWT endpoint (if your organization has one)
- JWT Secret is a secret that your service uses to sign the JWT token that it sends to the Zendesk Support service. The secret is shown in its entirety only once, when the app is set up. Make sure you don't use the redacted version

Check your initialization code

In your app code, make sure the identity is set after the initialization code. Example:

Zendesk.initialize(appId: "1e41a02a5f85d58e009ed4fa",
                           clientId: "mobile_sdk_client_e1c4e6262f1d02f43496",
                           zendeskUrl: "https://omniwear.zendesk.com")

let identity = Identity.createJwt(token: "unique_db_user_identifier")
Zendesk.instance?.setIdentity(identity)

Test your JWT endpoint

Use cURL to make requests to the endpoint. You'll need a valid user identifier. For example, if your endpoint is https://example.com/services/jwt and the user identifier is BD2F35A7621, use the following cURL statement:

curl "https://example.com/services/jwt" -d "user_token=BD2F35A7621" -v -X POST

The Zendesk Support service expects a very specific response from your service and is strict about it. The response must:

Return a 200 response code for success, no exceptions. Redirects will not be followed
Return a JWT payload
Be signed with the shared key using the HS256 algorithm

Example response:

Formatted for clarity, the JWT token value should look as follows:

{
    "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6ImJ
            jYXJyb2xsQHplbmRlc2suY29tIiwibmFtZSI6ImJjYXJyb2xsIiw
            icGhvbmUiOiI5ODc2NTQzMjM0NTY3ODkiLCJ0YWdzIjpbImZyZWV
            fcGxheWVyIiwiYmlnX2Zpc2giXSwicm9sZSI6InVzZXIiLCJpYXQ
            iOjE0NDkzNTUxNjIsImp0aSI6IjIxMTUyMzc5MDcyMDg5MzEyMjc
            ifQ.b_0rr6_1MWrmKEzqMfvf_DI4dPPMSmDjKh_M6STIIas"
}

If your service returns something that looks like a JWT token and a 200 response code, then it's time to check the payload itself.

Verify the JWT payload

Paste the JWT token from your cURL request into the decoder at https://jwt.io. Make sure to select the HS256 algorithm for the decoder. The decoded data appears on the right side as soon as you paste the token.

The decoded payload data must contain the following properties:

name
email
jti
iat

The JWT will be rejected if any property is missing or empty.

The keys must be lower case.

iat must be a whole number in seconds.

Everything else is optional.

Example:

Verify the shared secret

JWT relies on a shared secret to verify the JWT payload. Make sure the secret in your JWT service is longer than nine characters.

A Zendesk Support admin in your organization might have provided you with a nine-character secret. This is a redacted version of the secret displayed in the Zendesk Support admin interface. Ask your Zendesk Support admin to regenerate the secret in the app's settings in Zendesk Support, and then update your JWT service with the new secret.

Check your SSL certificate

Zendesk won't connect to your JWT endpoint if there are issues with a SSL certificate. You can check this by running the following command, where example.com is the domain of your endpoint:

openssl s_client -connect example.com:443

If the output looks like the following, it means that some certificate in the chain has failed validation:

depth=0 /OU=Domain Control Validated/OU=Free SSL/CN=example.com
verify error:num=20:unable to get local issuer certificate
verify return:1
depth=0 /OU=Domain Control Validated/OU=Free SSL/CN=example.com
verify error:num=27:certificate not trusted
verify return:1
depth=0 /OU=Domain Control Validated/OU=Free SSL/CN=example.com
verify error:num=21:unable to verify the first certificate
verify return:1