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 to authenticate users in Zendesk Support.

When integrating the Support SDK in a mobile application, the SDK can be configured to authenticate an application user in Zendesk Support. If this option is chosen, Zendesk needs to call a custom endpoint provided by your organization to authenticate the user.

Your dedicated custom endpoint must accept a unique secure token and return a JWT. Zendesk will send a unique secure token supplied by the mobile app to the endpoint. In turn, your service should look up the token, confirm that the user is known and trusted, and respond with a JWT payload. Basically, we're exchanging a JWT that your backend server understands with a JWT that Zendesk understands.

Note: The client supplies the token, but the actual JWT challenge and response occurs between the backend servers. Do not place a JWT into the client-side SDK code. That is not supported and you may encounter unexpected results.

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 and refactor the sign-in redirect in the examples with an HTTP response containing a JWT payload.

The secure token is supplied to Zendesk by the mobile application. The developers of the mobile app are responsible for providing identifier values that are supported by your custom endpoint. The secure token is a string and has no format restrictions.

Building the endpoint

After getting a unique token 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.

If the administrator is unsure where to add the URL, it should be entered in the JWT URL field on the Setup page at Channels > Classic > Mobile SDK in Admin Center. JWT should be selected as the authentication method to view the field.

Here's the authentication flow (enlarge):

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={secure_token_provided_by_the_app}

Response format

The Zendesk Support service expects the following response format:

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

If the secure token 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 Zendesk help. 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 Admin Center for you.

1. In Admin Center, click the Channels icon () in the sidebar, then select Classic > Mobile SDK.

2. 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 token = Identity.createJwt(token: "unique_db_user_identifier")
Zendesk.instance?.setIdentity(token)

Test your JWT endpoint

Use curl to make requests to the endpoint. You'll need a valid token. For example, if your endpoint is https://example.com/services/jwt and the token 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.

Note: curl recognizes certain certificates chains to be available to make secure connections. If a curl request to your remote test server returns an error such as "SSL certificate problem: Invalid certificate chain" or "no alternative certificate subject name matches target host name", try adding the --insecure option to your curl command. This option allows curl to proceed and operate even for server connections otherwise considered insecure. You are responsible for making sure any production environment SSL configurations are correct. Use this option only in trusted test environments.

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