Obtaining and using third-party OAuth tokens to access external resources is a key capability offered by ZIS. This tutorial shows you how to use the ZIS OAuth feature to interact with an external OAuth provider.

The tutorial uses Slack as an OAuth provider and Postman as an API client. By the end of this tutorial, you should have a good understanding of how to obtain a Slack OAuth2 token with the ZIS OAuth feature.

Prerequisites

Before starting this tutorial, make sure you have performed the following tasks:

Configure your Slack OAuth client for ZIS

In Slack, navigate to the OAuth & Permissions page. Under Redirect URLs, add the following ZIS redirect URL:

https://zis.zendesk.com/api/services/zis/connections/oauth/callback

Store the Slack OAuth client details in ZIS

Along with the ZIS redirect URL, stored client details are used by ZIS to initiate OAuth flows for your users and manage the access token lifecycle.

Make an OAuth enabled request in Postman with the following details to create an OAuth client:

  • Method : POST

  • URL: https://{subdomain}.zendesk.com/api/services/zis/connections/oauth/clients/{integration_key}

  • Body:

    {  "name": "slack",  "client_id": "{slack_client_id}",  "client_secret": "{slack_client_secret}",  "default_scopes": "chat.postMessage",  "auth_url": "https://slack.com/oauth/v2/authorize",  "token_url": "https://slack.com/api/oauth.v2.access"}

Note: name is the human-friendly identifier for referencing the stored client in future API requests. For more details of this endpoint, see the ZIS Connections API reference.

Kick off a Slack OAuth flow

Once an OAuth client is stored, you can get ZIS to kick off an OAuth flow, then obtain and store the access token for later use.

Make an OAuth enabled request with the following details in Postman:

  • Method: POST
  • URL: https://{subdomain}.zendesk.com/api/services/zis/connections/oauth/start/{integration_key}
  • Body:
    {  "allow_offline_access": true,  "oauth_client_name": "slack",  "origin_oauth_redirect_url": "http://example.local",  "permission_scopes": "chat:write",  "name": "slack"}

Note: The origin_oauth_redirect_url property is used to redirect the user back to the original requester after ZIS completed the OAuth flow with the provider. You can ignore the redirection.

The name property is used to specify a user-friendly name for referencing the obtained access token. In a ZIS flow for example, you can refer to the token as "$.connections.slack".

For more details of this endpoint, refer to the ZIS Connections API docs.

ZIS returns a redirect_url in the response payload. Enter the URL in a browser and it will take you through the process to complete an OAuth flow.

Note: The final redirection to the non-existent example URL (http://example.local) fails in this scenario. You’ll see an error like this in your web browser:

This is expected. You can close your browser for now.

At this point, ZIS obtained a Slack OAuth access token and stored it with the name "slack". In a ZIS Flow, you can easily refer to the access token as "$.connections.slack" as demonstrated in Extending your first integration: Using ZIS Links. The token is also used for posting messages given the granted "chat:write" permission.

In an app, the last step Kick off a Slack OAuth flow is commonly initiated from a UI during the setup phase. The next tutorial will cover the implementation details.

Next: Part 3: Adding the configuration user interface