Authentication Workflow

Tout uses OAuth2.0 for authentication.

At first glance, it would be easy to assume that OAuth2.0 is a complicated, scary workflow with seemingly identical concepts like client_credentials and access_tokens. But OAuth2.0 is a really easy concept, and you'll think so as well in no time.

Premise of OAuth

The idea behind OAuth is to remove the need for users to share their username/password combinations with multiple providers. The reason for this is because:

  1. Users typically use the same user name and password for multiple services, so a breach in one compromises the others
  2. You, as the app developer, don't want to have to store user credentials and provide assurances that they won't be compromised

Workflows

  1. Client Credentials Workflow

    This is for you if:

    • You don't have a concept of Tout users on your page
    • You want to simply put Tout content on your page but not allow users to perform user-specific actions (reply, like, retout, share, follow)

  2. User Authentication Workflow

    This is for you if:

    • You want to enable a user to perform user-specific actions such as liking, sharing, replying to or retouting a Tout. You will also need a user context if you wish to perform follow or blocking actions as well as the creation of new videos
    • You wish to pull a user's private Touts

  3. Mixed Authentication Workflow

    This is the most real-world authentication workflow. It assumes you want to be able to:

    • Make API calls before the user has authenticated (say to display touts that are associated with a given hashtag)
    • And then enable a user to authenticate in order to take some user-specific actions, such as like those touts that have a hashtag.

Client Credentials Workflow

In OAuth, the client credentials refer to access granted to the application. This can sometimes be confusing because the word client can mean user to many people, but it is referring to the application that is acting on behalf of the user.

To successfully execute this type of authentication, you'll need both the application id (also known as a key) and secret you received when you registered your application.

I have registered an app called 'Tout IO Docs' and it has the following id and secret:

  • id - 2dde4b38e02a8182988d3a7cd0e53ebaf10336dc98f2c1fb3e25289ee61980e0
  • secret - 8796767f4a508dd778ae8fe034f7f88970efab0421d9485e38f94a26909ef689

It may go without saying, but NEVER share your application id/secret pair in full with anybody. I did so because I'm foolish and trying to illustrate this flow as fully as possible :)

The next step is to make an actual request. You'll want to make a POST request to https://www.tout.com/oauth/token and make sure to include the following URL query parameters:

  • client_id - this should match your application id from when you registered the application
  • client_secret - likewise, this should match your application's secret
  • grant_type - set this to client_credentials (hence this workflow's name).

Now when you put that all together, using the example app from above we get something like the following:

https://www.tout.com/oauth/authorize?

client_id=2dde4b38e02a8182988d3a7cd0e53ebaf10336dc98f2c1fb3e25289ee61980e0

&client_secret=8796767f4a508dd778ae8fe034f7f88970efab0421d9485e38f94a26909ef689

&grant_type=client_credentials

When you make the request, assuming you did it correctly you'll get a response that contains a few attributes:

  • access_token
  • expires_in
  • scope
  • token_type

While they're all important, the only thing we actually care about is the access_token. You might say, "but won't I have to keep track the expiration date so I don't use an invalid token?". Of course, you're more than welcome to keep track of the token. However, the access_token will last for 2 years so its not really a pressing concern.

Fantastic! So now we have an access token we can make successful API read-only requests. Go ahead and try the difference:

Here's some copy-paste ready cURL commands to help you understand the requests you have to make.

curl https://www.tout.com/oauth/token

-d client_id=2dde4b38e02a8182988d3a7cd0e53ebaf10336dc98f2c1fb3e25289ee61980e0

-d client_secret=8796767f4a508dd778ae8fe034f7f88970efab0421d9485e38f94a26909ef689

-d grant_type=client_credentials

User Authentication Workflow

The client_credentials is all well and good for getting read-only access, but that's not all that fun. We want to be able to enable users to perform Tout actions such as follow other users, or like and share Touts.

I suppose we'll need to get access on behalf of a user in that situation. There is more than one way to do this, but let's started with the easiest. The easiest is to use the URL redirection technique. We will give the user a link to authorize against Tout's API, and then they will be redirected to a URL of your choosing (remember that redirect_uri when you registered an app) with an access_token.

Enough talk, let's a build a URL. First, let's examine the base URL.

https://www.tout.com/oauth/authorize

Next, we are going to need three pieces of data this time around:

  1. response_type=token

  2. client_id - this is the same as the application_id.

  3. redirect_uri

  4. scope

Very important notice: Make sure your redirect_uri matches exactly with the one you registered.

Exactly.

There are four potential options for the scope parameter, and if you include more than one you'll want to separate them with a +

  • read
  • write
  • share
  • update_auth

So for my application that we leveraged in the first example, the authentication URL will be

https://www.tout.com/oauth/authorize?response_type=token

&client_id=2dde4b38e02a8182988d3a7cd0e53ebaf10336dc98f2c1fb3e25289ee61980e0

&redirect_uri=http://developer.tout.com/docs

&scope=read+write+share

Try it here

When you authenticate, notice that you'll be redirected to the interactive documentation, and in the URL will be a fragment (#) followed by access_token=SOMEREALLYLONGSTRING

You'll want to pull out that fragment (likely using some simple JavaScript on the page) and you'll have a glorious access_token that represents your Tout account (or whichever user was logged in and authorized the app to act on their behalf.

Mixed Authentication Workflow

© Tout
documentation made with I/O Docs