Forem: Xkit

What domain do I use when setting up OAuth for Zendesk?

Trey Griffith — Thu, 28 Jan 2021 19:53:08 +0000

If you're building a Zendesk integration that allows your users to connect their Zendesk accounts to your app, you have probably noticed that all the Zendesk documentation for OAuth use the domain {subdomain}.zendesk.com, and you might be asking: whose subdomain is this? Is it the app developer's or the user's?

The subdomain you use when developing OAuth apps for Zendesk is the user's subdomain

The answer is that it's the user's subdomain, not you, the developer's subdomain. If you're building the integration only for internal use, that's the same subdomain so it won't matter, but if you intend for other Zendesk users to make use of it (what Zendesk calls a "global OAuth client"), you'll need to use their subdomain.

Why do I need the user's subdomain?

Why use the customer's subdomain? Zendesk's docs sum it up:

Zendesk maintains separate logins for each Zendesk account or subdomain. When a customer signs in, they're signing into a specific Zendesk subdomain which carries over to OAuth. When a Zendesk account owner uses OAuth to authorize your service, they're authorizing the service for their subdomain.

The documentation can be a little bit confusing at times, using "your" subdomain at times when they mean "the user's" subdomain. Just know whereever you see {subdomain}, they're referring to your user, not you.

How to get the user's subdomain

Now you might be wondering if Zendesk provides a sort of global subdomain that you can use where Zendesk either determines through cookies, or collects directly from the user, their Zendesk subdomain. The unfortunate answer here is no: you're left to your own devices to determine the user's subdomain before sending them through the OAuth flow. You'll also need to hang on to this subdomain: it's used not only for the initial authorization request, but also the token request and API calls afterward.

You'll probably want to model your own subdomain collection after Zendesk's login process pictured here:

Conclusion

So if you're building a Zendesk integration, don't forget to build in subdomain collection to make sure you're making requests to the right domain.

Of course, if you don't want to bother building an entire subdomain collection flow, you can use Xkit's Zendesk Connector. It has built-in subdomain collection through a popup window and it will surface the subdomain to you with every access token it provides.

With one API call you'll get everything you'll need to get access to your user's Zendesk account. And you can get started in 30 minutes, for free.

Why does my GitHub OAuth2 Token not have the scopes I requested?

Trey Griffith — Wed, 27 Jan 2021 18:18:06 +0000

Why doesn't my access token work?

If you're building a GitHub integration into your app that uses GitHub's OAuth authorization method (as opposed to their App authorization, which is similar but has important differences), you may have noticed that sometimes the scopes that your access token has been granted are different from what you requested. This can be a particularly difficult issue to debug since it usually rears its head when you're trying to use an API protected by one of the scopes you requested, but the API request fails for just one of your users. However, when you try to reproduce this issue, it seems to work just fine. What's going on here?

GitHub makes use of a little known part of the OAuth2 spec that allows the authorization server (in this case GitHub) to: "fully or partially ignore the scope requested by the client, based on the authorization server policy or the resource owner's instructions". The way GitHub does this is by allowing your user to pick and choose which of your requested scopes to actually grant to your application through a process we call "line item grants".

As you can see, this is a completely valid use of the OAuth2 spec, but since most providers don't use this, you may not have been ready for it. But not to worry, while the spec includes the ability for the authorization server (GitHub) to ignore your scope, it does provide you some recourse: "if the issued access token scope is different from the one requested by the client, the authorization server MUST include the scope response parameter to inform the client of the actual scope granted."

Verifying the Granted Scope

The scope parameter in the Access Token response (which you were probably ignoring until now) will contain the scope that your user actually granted you, and which you therefore actually have access to with your token. See GitHub's docs about this process here.

Unfortunately, here's where GitHub goes off the rails. While GitHub allows you to specify the scope you want in your request by space-delimiting each scope string (e.g. read:org read:user), which matches the OAuth2 Spec, it returns scope by comma-delimiting the scope strings (e.g. read:org,read:user) in violation of the specification. Which means you may have to serialize and parse your scope using different patterns.

Scope Normalization

In addition, GitHub transforms the scopes through a process called "scope normalization". Basically, they take your requested scopes and narrow them down to the smallest set of logical scopes that will be granted. So, for example, if you request the repo scope, but you also request public_repo and delete:repo, GitHub will return just repo, since the other requested scopes are already included in the repo scope.

The actual normalization process (which scopes are removed when requesting two or more) is only partially documented, but based on our reading of the documentation and subsequent testing, here's the normalization tree:

repo
┣ delete:repo
┣ repo:status
┣ repo:invite
┣ repo_deployment
┣ public_repo
┃ ┗ admin:repo_hook
┃   ┗ write:repo_hook
┃     ┗ read:repo_hook
┗ security_events
admin:org
┗ write:org
  ┗ read:org
admin:public_key
┗ write:public_key
  ┗ read:public_key
user
┣ read:user
┣ user:email
┗ user:follow
write:discussion
┗ read:discussion
write:packages
┗ read:packages
admin:gpg_key
┗ write:gpg_key
  ┗ read:gpgp_key
workflow
gist
notifications
admin:org_hook

Conclusion

If you're building a GitHub integration, be sure to check the normalized, comma-delimited scopes that your user actually granted you via GitHub's API to make sure that your token has the scopes you expect it to.

Of course, if you want to avoid building (or heck, even learning) all that, you can use Xkit's GitHub OAuth Connector and be up and running with always-valid access tokens in a half hour. We have built-in checks to make sure that your tokens have the scopes you expect them to so you don't have to worry about it.

When do Salesforce access tokens expire?

Trey Griffith — Thu, 21 Jan 2021 23:09:20 +0000

If you're building a Salesforce integration into your app, particularly a "Connected App" style of integration, and your integration uses OAuth to get access to Salesforce's REST APIs, you may be wondering when the access tokens issued by Salesforce expire.

According to the OAuth 2.0 spec the expires_in parameter is included with the Access Token response and provides the lifetime of the returned token in seconds. And while this parameter is extremely common in OAuth implementations, it is merely recommended and not required. The Salesforce OAuth implementation does not use this parameter.

Typical Token Expiration

In our experience at Xkit, Salesforce Access Tokens typically expire in 2 hours (7,200 seconds), but this value is not guaranteed to be static—Salesforce could change it at any time with no warning.

Salesforce Access Tokens typically expire in 2 hours

How to determine token expiration

So what do you do? You have two options:

Use your access token until you receive a 401 HTTP status code, and only refresh it then
Use Salesforce's token introspection endpoint to determine when the token expires

Token Introspection

That's right! While Salesforce does not include an expires_in parameter, they do have a special token introspection endpoint as part of the extension to the OAuth 2.0 spec. This endpoint (Salesforce docs here) returns a JSON object that includes an exp property. This exp corresponds to the exp claim of the JWT spec. Unlike the expires_in parameter, exp is a Unix epoch timestamp.

Here's an example request from the Salesforce docs:

POST /services/oauth2/introspect HTTP/1.1
Host: https://mycompany.my.salesforce.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic M01WRzlsS2NQb05JTlZCSVBKamR3MUo5TExNODJIbkZWVlgxOUtZMQp1QTVtdTBRc
UVXaHFLcG9XM3N2RzNYSHJYRGlDUWpLMW1kZ0F2aENzY0E5R0U6MTk1NTI3OTkyNTY3NTI0MTU3MQ==

token=00DR00000009GVP!ARQAQE5XuPV7J4GoOu3wvLZjZI_TxoBpeZpRb6d8AVdII6cz
_BY_uu1PKxGeAjkSvO0LpWoL_qfbQWKlXoz1f2ICNiy.6Ndr&
token_type_hint=access_token

And an example response from our own experience:

HTTP/1.1 200 OK
Content-Type: application/json

{"active":true,"scope":"api refresh_token openid","client_id":"3MVG9lKcPoNINVBIPJjdw1J9LLM82HnFVVX19KY1uA5mu0QqEWhqKpoW3svG3XHrXDiCQjK1mdgAvhCscA9GE","username":"user@example.com\",\"sub\":\"https://login.salesforce.com/id/000000000000000000/000000000000000000\",\"token_type\":\"access_token\",\"exp\":1610509606,\"iat\":1610502406,\"nbf\":1610502406}

Conclusion

So if you need to know when your Salesforce Access Token expires, call the introspection endpoint and you can figure it out for yourself. And don't forget to add the special refresh_token scope so you can refresh your access when it does expire.

Of course, if you want to avoid building (or heck, even learning) all that, you can use Xkit's Salesforce Connector and be up and running with always-fresh access tokens in a half hour.