Breaking Down OAuth with Spotify

Learn the basics of OAuth and how it works in the context of Spotify’s OAuth flow.

If you’re interested in working with the Spotify API, you’ll need an OAuth token in order to access most of its data. In this blog post, we’ll explain what OAuth is, how it works, and break down each step in the context of Spotify’s OAuth flow.

What is OAuth and why do we need it?#

OAuth (Open Authorization) is a secure, industry-standard protocol that allows you to approve one application interacting with another on your behalf without giving away your password. Instead of passing user credentials from app to app, OAuth lets you pass authorization between apps over HTTPS with access tokens (kind of like a special code).

OAuth lets you pass authorization between apps with access tokens instead of passing around sensitive information like your username and password.

For example, you can tell Facebook that it’s okay for Spotify to access your profile or post updates to your timeline without having to give Spotify your Facebook password. This way it's less risky for both you and Facebook — in the event Spotify suffers a breach, your Facebook password remains safe.

Similarly, when a user authorizes an app to access their Spotify account data, that app shouldn’t be storing their username or password anywhere. As developers, we don’t want to be responsible for sensitive information like this, so instead, we rely on the secure OAuth protocol to take care of the authorization flow with access tokens.

Authorization, not authentication#

When trying to understand OAuth, it's important to remember that it's about authorization, not authentication.

OAuth is about authorization, not authentication.

Authorization is asking for permission to do things. Authentication is about proving you are the correct person by providing credentials like a username or password.

OAuth scenarios almost always represent two unrelated sites or services trying to accomplish something on behalf of users or their software. All three have to work together, with multiple approvals, for the completed transaction to get authorized.

Roles#

Since OAuth is a way to authorize an app without giving away your username and password, you can picture it like a series of handshakes. If all handshakes are completed, then your reward is a unique access token that only your app can use to access resources from a service.


There are four main roles that need to "shake hands" to get that token.

  1. Resource Server: The API which stores data the application wants to access (e.g. the Spotify API)

  2. Resource Owner: Owns the data in the resource server (e.g. the user who wants to log into your app with Spotify is the owner of their Spotify account)

  3. Client: The application that wants to access your data (e.g. your app)

  4. Authorization Server: The server that receives requests from the client for access tokens and issues them upon successful authentication and consent by the resource owner (e.g. Spotify Accounts Service)

Scopes#

In addition to these four roles, there is also the concept of scopes in OAuth. Scopes are used to specify exactly which resources should be available to the client that is asking for authorization.

They provide users of third-party apps with the confidence that only the information they choose to share will be shared, and nothing more. The resource server (e.g. the Spotify API) is in charge of defining these scope values, and which resources they relate to.

The Spotify API has many scopes for many different purposes. For example, the user-read-private scope is for read access to a user's subscription details and is required if you want to access the https://api.spotify.com/v1/me endpoint to get the currently logged-in user's profile information. There is also a scope called playlist-modify-private that is required if you need write access to a user's private playlists. This scope allows you to do things like add items to a playlist or upload a custom playlist cover image.

Check out all of the available scopes for the Spotify API here.


Tokens#

As we mentioned before, all of the back and forth hand-shaking that OAuth requires us to do is for one thing: an access token

You can think of access tokens like the two-factor authentication codes that some services send you via text message for you to log in. Just like two-factor auth codes, OAuth tokens have a limited time in which they are valid. After a while, all tokens expire, and you'll need to request another one (or refresh it). In the end, this is all for security — in case someone gets hold of your unique access token, they can only access your private data for a limited amount of time before they're locked out.


The OAuth flow#

Now that we've gone over OAuth roles, scopes, and tokens, let's look at how they all tie together in the context of Spotify’s OAuth flow.

Step 0: Client obtains client ID and client secret#

Before any client or server requests are even made, there are two things the client (your app) needs in order to kick off the OAuth flow: the client ID and the client secret. These are two strings that are used to identify and authenticate your specific app when requesting an access token.

With Spotify, your app's unique client ID and client secret can be found in the developer dashboard.

Once we have these two values, we're ready to initiate the OAuth flow.

Step 1: Client requests authorization to access data from Spotify#

First, the client (your app) sends an authorization request containing the client ID and secret to the authorization server (the Spotify Accounts Service). This request also includes any scopes the client needs and a redirect URI which the authorization server should send the access token to.

Step 2: Spotify authorizes access to client#

Second, the authorization server (Spotify) authenticates the client (your app) using the client ID and secret, then verifies that the requested scopes are permitted.

Step 3: User grants app access to their Spotify data#

After step 2, the user is redirected to a page on the Spotify authorization server where they can grant the app access to their Spotify account. In our case, the user will have been sent to a page that belongs to the Spotify accounts service (note the accounts.spotify.com URL in the screenshot below), where they can log in to Spotify.

Step 4: Client receives access token from Spotify#

Once the user grants access by logging into Spotify, the authorization server redirects the user back to the client (your app) with an access token. Sometimes, a refresh token is also returned with the access token.

Step 5: Client uses access token to request data from Spotify#

Finally, the client can use the access token to access resources from the resource server (the Spotify API).


Summing It Up#

If all of this feels like a lot, don't worry, it's because it is! OAuth is super tricky, but for a good reason — security! All you really need to remember is this:

OAuth is an authorization protocol that lets you approve one application interacting with another on your behalf without giving away sensitive user credentials like your username and password. Instead, it uses access tokens to ensure an application is authorized.

The five basic steps of the Spotify OAuth flow:

  1. Client requests authorization to access data from Spotify

  2. Spotify authorizes access to client

  3. User grants app access their Spotify data

  4. Client receives access token from Spotify

  5. Client uses access token to request data from Spotify


Next Steps#

Try out implementing Spotify’s OAuth flow yourself! It’s not as daunting as you might think — the documentation describes everything you need to implement the flow.

Coming Soon!#

Be sure to check out our new course being released soon, Build a Spotify Connected App, where we apply these concepts to build a real-world, full stack web app!

Sources#