Forem: Trey Griffith

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.

How I learned a language and launched a product in 60 days

Trey Griffith — Tue, 12 Jan 2021 00:25:23 +0000

Background: Why I had to pivot

Almost 3 years ago I incorporated Kinesis Inc, the corporate entity behind Xkit. But at the time I was building a non-custodial cryptocurrency exchange. After going through Y Combinator and raising $3.5M from some great investors and building a product I was really proud of, I made the hard decision to shut it down nearly a year ago. We hadn't found an audience that would provide venture scale growth, so it was back to the drawing board.

I started working on an idea in FinTech, trying to help a friend's company solve a problem with SMB customers not paying on time (or at all) for their services. As I talked to prospective customers about the problem, one thing became abundantly clear: in the time that I had spent away from the SaaS world toiling in the Bitcoin mines, expectations around how SaaS tools work together had radically shifted. It was no longer a "bonus" that you worked with some of their other tools, it was an outright necessity. For the product I was exploring I would be building integrations with Quickbooks, Xero, Stripe, and a few others.

I asked around if anyone had any good tools to accelerate this process, but the responses I got back were pretty disappointing. Nearly every tool was focused on consumers of SaaS software plugging together the services that they used. Not nearly as much was out there for producers of SaaS software trying to build native integrations to the other tools their customers use. Not only that, but the ones that did exist tried to pretend that we live in a world where powerful integrations are easy to design and maintain with a GUI. While I'm a fan of no-code and low-code solutions, the fact remains that for some tasks, leaning on a software development lifecycle is still the most effective and efficient way to build it.

In the meantime, the US blew up with COVID, throwing the financial markets (which my new FinTech project was heavily dependent on) into turmoil. So like any good (read: desperate) startup founder, I scrapped the FinTech project and started building the tool that I wish had existed to help me build integrations to my prospective customers' other SaaS apps. And despite never having touched the language, I decided to build it in Elixir.

Choosing Elixir

I've spent most of my career as a software engineer writing in Javascript and Ruby. I've long been intrigued by the concepts behind functional programming (years ago I wrote a small toy to try to achieve immutability on the web, like a centralized IPFS), and a friend introduced me to Elixir, which incorporated some Ruby syntax, making it a bit friendlier to get started with.

The concepts behind Erlang/OTP/Elixir make it a great fit for a tool like the one I was building. I knew it would be heavily dependent on outside services, meaning it had to be robust to crashes and other unforeseen events. And I knew high concurrency and low latency would be important features as a piece of developer infrastructure. I also wanted to test out Paul Graham's theory of hiring programmers: choose a good language and great programmers will always want to work for you. And finally, I'd be lying if I said there wasn't a part of me that just wanted to try something new. I had spent the past two years working an idea I had to shut down, my "big pivot" was a non-starter, I had laid off nearly the entire team, and for product development it was just me in my bedroom. So I liked the idea of learning something new while working on my second pivot in 3 months.

Learning Elixir

I read through Elixir's fabulous language guide. I mean I really read it, cover to cover, and did pretty much all the examples as they came up. Then I read through a handful of pages in the Phoenix (the most popular web framework for Elixir) guides before I said "f*** it" and started building what became Xkit. My first commit was on May 14, 2020. Commit message: "Initial install with platforms".

The first week was rough. I wasn't used to moving this slowly, but not only was a learning a new language with features pretty unfamiliar to me like pattern-matching, I was learning a new paradigm. Javascript is whatever you want it to be, which means I had some exposure to FP incidentally, but almost everything I've spent significant time on has had a pretty object-oriented flavor to it, even dating back to when I first got started with PHP. Not to mention the entire ethos of OTP to "fail fast and noisily" which ran counter to so many experiences which focused on avoiding failure at all costs (yes, I've seen some pretty large try/catch blocks in my day). I got pretty discouraged at the pace I was moving, and somewhere about 10 days in I was really regretting not just using Node/Express, a stack I was so familiar with it felt like I could write the app in my sleep.

But I kept at it (probably more out of pride than anything else) and a few days later I felt things start to shift. I still wasn't moving fast, but I could tell I was improving. Things that only a few days ago had felt foreign and impossible to grasp started to make sense. From that point on I started accelerating, and on June 1st, I sent one of my investors this video showing the first version of what became Xkit.

Shortcomings of Elixir and Phoenix

I started off trying to use a pure Phoenix stack including their new real-time front-end, LiveView. I'll be honest, although I really like Elixir and Phoenix, using Phoenix for the front-end brought me back a bit to my Rails days, and not in a good way. Building a modern web application with those tools felt like I'd be working against the tide. I also am pretty partial to Evergreen, the React UI kit by Segment, and I was bearing down on the 6 week timeline I'd set for myself to launch this product. So I ripped out the Phoenix front-end and converted it to be a back-end only application and built a new front-end in React and Evergreen. I did end up using Phoenix's websocket implementation which was a big help integrating the two, although some pieces are not very well documented.

When I finally getting close to launching, I ran up against the greatest weakness of my choice to use Elixir: deployment. While the world has moved towards a serverless paradigm, Elixir/Erlang/OTP thrive by handling a lot of the same things that "serverless" promises. That means that to really take advantage of all it has to offer, you're better off deploying it on as close to bare metal as you can. That, in addition to some of the architecture choices I made with Xkit (specifically to provision a custom subdomain for every user), made deployment quite a challenge. Failing to find any good documentation about how to deploy a Phoenix application on AWS, I ended up writing a blog post about our process.

You might think it's overkill for a one-person development team to have a one-command deploy process, but I assure you, based on my past experience, it's well worth the effort. You don't want critical DevOps knowledge in one person's head, or worse, on some inscrutable AWS GUI. I want it all in code. Even today, you can take the entire Xkit stack, move it to a new AWS account and have it up and running with a single command in around 30 minutes.

Launching Xkit

The delays I hit caused me to miss my six week launch goal by two weeks: I launched to some fellow YC founders on July 12 with ~15 connectors and this video.

Two weeks after that I launched on Product Hunt and shortly after that on Hacker News with over 25 connectors. Since then we've worked with some really great early customers who have helped us refine the product, and I've been able to hire a few friends to help grow the business.

We're well over 50 connectors at this point (almost entirely driven by customer requests) and we add so many that we no longer track it as a metric. And while I'm still contributing code, I can safely say that the majority of the coding that I will do for Xkit is now likely behind me. But the process of building Xkit (and learning Elixir in the process) has been incredibly rewarding, and hopefully we're just getting started.

PS - In case you're wondering about the answer to PG's theory about language being a good hiring tool - my early results indicate that it is. From a single post on Elixir Forum I met one of the best engineers I've seen, and a few weeks later he recruited one of the best engineers he'd worked with to join the team.