This is a bit of a long read but I sure hope it would be worth it.
One thing common with OAuth is a requirement of a
redirect_uri also known as a callback url - a url that will catch the initial authorization
code which in turn would be used to acquire the
access_token. Inspired by @mark’s OAuth 2.0 in Shortcuts, I came up with an idea that maybe, I can create an proxy
redirect_uri where I can use for both Shortcuts and Scriptable or any other app that has a url-scheme.
The very basic requirement is that is should be able to forward all the companion data to a url-scheme call to the app.
Here is how I expect the authorization endpoint to call the proxy:
And here’s what I expect the proxy to do:
- Translate the rest of the query data (
&data1=value1&data2=value2&...) to an input the receiving app should understand
- Redirect to the app through the
Scriptable and Shortcuts’ url-schemes accept input differently. Shortcuts only accept one input, Scriptable can have more.
To work around Shortcuts limitation, instead of passing a simple text on the
input parameter, it’s possible to pass a url-encoded JSON string.
This means we need to know how the app accepts arguments – as regular query variables or JSON strings.
So, let’s list down the ingredients of our solution.
- accept a url-scheme as a query parameter -
- a flag to indicate what how it will pass the arguments to the receiving app -
- a way to translate query variables to the format required by the receiving app
You can deploy this to your own server if you have one but if not, you can use heroku for free as what I did for this demo.
Follow this steps to deploy our proxy to heroku.
- Sign-up for a Github account if you don’t have one, otherwise Login.
- Navigate to the oauth-proxy repo and fork it. It should create a repo under your account. Example:
- Sign-up if you don’t have an account, otherwise Login.
- Create a new app
- Give your app a name, I used
my-oauth-proxy. Choose a region closest to you. Note that you can’t use the same as mine. App names on heroku are globally unique.
- Once your app is created, you should be on heroku’s Deploy page. Under Deployment method, choose Github.
- Connect your Github account and your repo.
- In the Manual Deploy section, choose which branch to deploy. There’s only one branch at the moment which is
- Click Deploy Branch and wait for the build to complete.
You now have your own OAuth proxy.
To use your proxy, we first need a way to build the
redirect_uri and use it with the website providing the API.
We need a few more ingredients:
URL Encode: the built-in
URL Encodeaction only encodes values that are meant to be passed as query values. But if the value itself is a URL or a URL scheme, it doesn’t encode properly. This shortcut does a proper url encode.
Build OAuth Redirect URI: a helper shortcut to generate the
- Save OAuth Client Info Shortcut: a helper shortcut to save an OAuth client’s credentials in the Shortcuts directory
- json-util.js - utility module for JSON
- basic-ui.js - utility module for common UI elements
- Save OAuth Client Info.js: a script to save OAuth client credentials in the Scriptable directory
Below are the steps on how the whole thing will flow. Mainly focused on Shortcuts
- Create a client/app with your target API. This is usually found in your target API’s website.
- Once you created an app, you should get a
- Think of the shortcut name you will use to authenticate.
- Run the Build OAuth Redirect URI shortcut. Assign the resulting
redirect_uriin your target API’s website.
- Run the Save OAuth Client Info shortcut/script to save the
redirect_urias a JSON file in your iCloud drive.
- Start creating a shortcut with the name specified on 3.
- This shortcut should expect input. Receiving an input means it was ran via the
redirect_uri, otherwise it’s starting an authentication.
- To start an authentication, open the url target API’s authentication endpoint.
- When the input is received from the
redirect_uri, use the data receive to retrieve an
- Store the details of the
access_codeinto a file on your iCloud drive. This
access_codewill eventually used to call the authentication endpoints of the API.
Check out these samples to tie the whole thing together. I chose Spotify as the first example because you can configure it to have more than one
- Spotify Dashboard - create your client here
- Use the steps 1-5 above to save the necessary information on your iCloud drive.
- Spotify Get Client - read the client information from your iCloud drive
- Spotify Auth - performs the actual authentication
- Spotify Refresh Token - refresh the user token, if needed
- Spotify Recently Played - sample use of the token
- spotify-api.js - module to interface with Spotify’s api
- spotify-auth.js - script to demo authentication with Spotify
- spotify-app.js - script to demo pulling date from Spotify’s API
I’m not much of a writer but I hope you’ve enjoyed this article.