GitHub Project: PHP-StripeOAuth

This was a fun one. PHP-StripeOAuth, which I developed for the integration of Stripe into the payment system/flow at Skillshare, got me pretty intimately familiar with OAuth, which is something I've been meaning to better understand.

Quick note:
The Stripe: Integrating OAuth documentation, along with their amazing support, got me exceptionally far.

What is this?

PHP-StripeOAuth is an OAuth helper class. It is based off of quizlet's oauth2-php library, and meant to wrap most of the overhead logic required for an OAuth2 client connection.

Specifically, it works within the Stripe Application environment. Stripe has developed the ability for developers to create Stripe applications. People (teachers, in Skillshare's case) can then "grant" your application to act on their behalf.

Acting on behalf of a Stripe member allows you to accept payments for them. This library facilitates the connecting of a Stripe member's Stripe account through the OAuth2 framework.

Why did I develop it?

My experience with Stripe has arguably been the best experience I've had with a 3rd-party API. The only place I thought there was room for improvement was providing a library or set of helpers for going through the OAuth2 flow for connecting a person's Stripe Account with your platform. Well, to be specific, in PHP.

I didn't want to perform raw curl calls in PHP, as it didn't seem to be too scalable incase anything changed on Stripe's side.

What's included?

This library includes two classes. One (StripeOAuth2Client) which extends the open-source OAuth2Client library, to get access to the raw request response.
A second, StripeOAuth, which acts as a helper and wraps commonly used Stripe OAuth functionality.

StripeOAuth includes the following public methods:

• getAccessToken Returns an access token for the connection, which requires code (aka. request token), allowing access to data
• getAuthorizeUri Returns the URI to connect a person with your Stripe application
• getBody Returns the raw (json encoded) body for the last OAuth request to Stripe
• getPublishableKey Returns the publishable key for the connected Stripe account
• getRefreshToken Returns the refresh token for the connected Stripe account
• getScope Returns the scope of access (eg. read, write; aka. permissions)
• getTokens Returns both the access and refresh token for a connected Stripe account
• getTokenType Currently, only returns the string-value bearer
• getUserId Returns the user ID for the Stripe account
• isLive Returns whether the Stripe account was connected in live or testing mode

StripeOAuth2Client includes the following public method (but, generally, shouldn't need to be accessed):

• getLastResponse Returns the raw response (json encoded) for the last OAuth2 request

How do I use it?

This library assumes you're familiar with the Stripe API, and have a basic understanding of how OAuth (maybe specifically OAuth2) flow works. The article Introducing OAuth 2.0 includes more than you should need to know (better too much information than not enough :)

Other than that, check out the example above. A nicety of the flow, is that you don't need to develop on an internet-connected server. Stripe redirects browsers to endpoints, so you should be able to test your entire flow within your local machine development environment.

Why did I abstract it out?

I didn't want to do raw curl calls, as can be seen in this gist. Nothing against that snippet, but I wanted to use a trusted library (in this case, the OAuth2 client I'm using) to handle all that.

I figure this is clean, and can be modified properly for any changes Stripe makes to it's flow.

For example, when I wrote this library, I wrote it for Stripe's 1.7.2 PHP SDK. It's now up to 1.7.7, and already fixes a few things that were hiccups for me when writing this library.

Refresh Tokens

Refresh tokens were a little tough for me to wrap my head around.
When you get permissions to act on behalf of a Stripe account, you set the scope of those permissions (eg. read, write, etc.). A refresh token, which is received when requesting an access token, can be used to make subsequent requests under the same, or lesser, scope.

The logic of this seems to be that you can maintain multiple access tokens. For example, one for reading, and one for reading & writing. Your application could then choose which to use under which situation and keep them separate (for security reasons).

I'm sure there are more practical reasons for this that I can't think of, but luckily, I don't need this at the moment.

Gotchas

While the Stripe API itself has very few peculiarities to it, the OAuth flow only had one that I could think of. Specifically, the OAuth2 client library currently being used does not get you access to the body of the response.

Why is this needed? Because Stripe includes a bunch of important information in the initial connection response, such as:

• publishable key
• scope
• token type (well, not really that important)
• user ID
• whether the Stripe account is being connected in live or test mode

Shoutout

Eric Ma: Thanks for your help in guiding me through some of the intricacies of OAuth :)

Todo

• Create helper/wrapper method for accessing a Stripe accounts email address. This could be done under Stripe's 1.7.2 PHP SDK library, but required a really-high scope (admin). With 1.7.7, I believe it's fixed and returned in the initial connecting response.