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 theSupport SDK for mobile applicationsto authenticate users in Zendesk Support.

Whenintegrating the Support SDKin 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 ofJWT endpoint code examplesfor 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. SeeJSON web token responsebelow.

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 theJWT URLfield on the Setup page atChannels>Classic>Mobile SDKin Admin Center.JWTshould be selected as the authentication method to view the field.

Here's the authentication flow (enlarge):

Request format

The Zendesk Support service will make aPOSTrequest 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:

             

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

If the secure token the Zendesk Support service sends to the JWT endpoint is not known or trusted, aHTTP 401 Unauthorizedresponse 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 toSetting up the SDKin the Zendesk Support Help Center. Use the secret to generate the encrypted string for the JWS signature.

Note: You must use theHMACwithSHA-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
• Theemailandname值是case-sensitive in Zendesk Support
• iatmust 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 aJWT libraryto 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. InAdmin Center, click theChannelsicon () in the sidebar, then selectClassic>Mobile SDK.

2. Verify the following settings:

   Notes:

   • Authentication methodmust be JWT
   • JWT URLis 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 Secretis 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 setafterthe initialization code. Example:

             

              
亚博.initialize(appId:"1e41a02a5f85d58e009ed4fa",clientId:"mobile_sdk_client_e1c4e6262f1d02f43496",zendeskUrl:"https://omniwear.zendesk.com");lettoken=Identity.createJwt(token:"unique_db_user_identifier")亚博.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 ishttps://example.com/services/jwtand the token isBD2F35A7621, use the following curl statement:

             

              
旋度"https://example.com/services/jwt"-d"user_token=BD2F35A7621"-v-XPOST
             

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:

格式清晰,JWT令牌值应该look as follows:

             

              
{"jwt":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6ImJjYXJyb2xsQHplbmRlc2suY29tIiwibmFtZSI6ImJjYXJyb2xsIiwicGhvbmUiOiI5ODc2NTQzMjM0NTY3ODkiLCJ0YWdzIjpbImZyZWVfcGxheWVyIiwiYmlnX2Zpc2giXSwicm9sZSI6InVzZXIiLCJpYXQiOjE0NDkzNTUxNjIsImp0aSI6IjIxMTUyMzc5MDcyMDg5MzEyMjcifQ.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--insecureoption 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 athttps://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.

iatmust 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=DomainControlValidated/OU=FreeSSL/CN=example.comverify error:num=20:unable togetlocal issuer certificateverifyreturn:1depth=0/OU=DomainControlValidated/OU=FreeSSL/CN=example.comverify error:num=27:certificate not trustedverifyreturn:1depth=0/OU=DomainControlValidated/OU=FreeSSL/CN=example.comverify error:num=21:unable to verify the first certificateverifyreturn:1