Shameless Plug: The following steps were used in the creation of FitRPG, a fitness gamification mobile app. Download it in the Play Store now!
During a 24 hour Hackathon, I was able to fairly efficiently allow users to authenticate through Fitbit login via a web browser. I primarily used OAuth and passport. However, when I decided to create an Ionic mobile app that allowed users to authenticate client-side through Fitbit/Jawbone (and really any external API that does authentication through OAuth 1.0/2.0), I ran through several issues and could find very little online support. In the end, it’s really not all that complicated–the key is we have to use our server-side to authenticate users, and we need an in app browser client-side. It’s important to note that every API is a little bit different, and while I cover only Fitbit authentication in this post, the same general concepts can be used for other APIs as well. This post covers the setting up of the back-end, my next post covers the setting up of the friend end. You must do both for this to work as they depend on each other. Make sure you get your consumer key and secret from Fitbit upon registering your app.
Server-Side (Requirements: node.js and express 4.0)
Step 1: Set up Passport First, we set up Passport, authentication middleware for node. Passport authenticates requests through ‘strategies’ you provide. In other words, we tell Passport what requests to authenticate, and it provides hooks for controlling what happens when authentication succeeds or fails. To do this, we jus require and then initialize it.
Step 2: Set Up Your Strategy with Passport Strategies are what Passport uses to authenticate requests. You can use them to verify a username/password combination, for instance, or to delegate authentication to OAuth, which is what we are doing in this situation. Before passport can ‘use’ a strategy, we have to configure it. Usually you do not have to create the strategy yourself–Passport has a pretty comprehensive set of over 140 authentication strategies that cover social networking, API services, and so on. I used the fitbit-passport strategy. On web, the fitbit-passport works fine as is, but on mobile, there is a tweak we want to make so that the login page shows up as mobile-friendly. I ended up having to make a copy of the node module and storing it in the body of my app files. Change the line that assigns options.userAuthorizationURL to:
Step 3: Configure Your Strategy with Passport To configure the strategy, you must create a new strategy and pass in a) an object with your Fitbit consumerKey, consumerSecret, and callbackURL (more on that later), and b) a callback function that occurs once authentication is successful–this function will receive the token, tokenSecret, and profile from passport. Finally, you tell passport that it needs to ‘use’ that strategy.
Step 4: Create Your Routes I used Express 4.2, and express.Router() to handle my routes. When my site goes to ‘/’ it uses the FitbitRouter. I could have also done “app.use(‘/fitbit’, FitbitRouter)” and that would have handled all of the routes on my site that start with ‘/fitbit’. In this particular case, my authentication page is just at mywebsite.com/auth, so that is where I will direct my mobile app to when I want to authenticate the user (more on that later). Step 5 covers the logic behind lines 4 and 5, but if you just want the code, skip to step 6 for the function in line 6.
Step 5.1: Get the Temporary Access Token The only endpoint we need to write is for that last route, as the first two just use the passport middleware. However, it is important and useful to understand what is going on. First, when we have a route that uses ‘/auth’, which is the route we direct users to when we want them to authenticate via Fitbit. On our client side, we will be opening an in-app browser that goes to this url (see Pt 2). When we go to this page, we use passport.authenticate(‘fitbit’) as middleware, with ‘fitbit’ referring to the strategy we’ve declared earlier. Passport does work in the background to do the first step of the authentication process. What’s basically happening is passport then sends a post request to Fitbit (taken directly from Fitbit API documentation):
Fitbit then sends back a response with a temporary OAuth token, which Passport receives and then uses to recreate a redirect url with, which looks like this: https://www.fitbit.com/oauth/authorize?display=touch&oauth_token=47617140d6906e7db65ac71df26290c0. The temporary oauth_token expires upon usage or within a few minutes. So to summarize, the middleware works to create that token and redirects users to a Fitbit login page where they can fill in their username and password.
Step 5.2: Get the OAuth Verifier Once the user is successfully signed in, Fitbit will redirect the user to the callback that you have provided, which in this example is the route to ‘authcallback’ (see step 3 above). The callback URL also includes Fitbit’s response, with the temporary OAuth token and a token verifier, which looks like this: http://example.fitbit.com/app/completeAuthorization?oauth_token=c5a8b2ff2a20524381083b1fe172fdc1&oauth_verifier=car3fbtjvralpv4kvba65arls2 With this verifier, passport (which is again included as middleware for that callback route) does another POST request to Fitbit, which looks like this.
Step 6: Save the OAuth token and OAuth token Secret Fitbit’s request comes back with the OAuth token and OAuth token secret, both of which you will need to access the user’s data in the future. Passport sends the token and tokensecret to the callback function shown in step 3. Passport also does additional work of getting the user’s profile for you. From this point, it’s up to you what you do with that information, but I recommend saving the token and tokensecret, and then using fitbit-node‘s requestResource function to retrieve data for that user. Once you have the token/tokenSecert, it’s pretty straightforward from there.
Step 7: Respond to the Client At this point, our client is waiting for a response from our server, which is the responsibility of our function ‘getOuthToken.’ All that function needs to do is redirect to a url that will basically notify the client that the process has completed, and the in-app browser can be closed. In my example below, we use JSON web tokens, which are tokens generated to ensure the security of our app (the user must make resource calls with this JSON web token). Your app can capture the ‘oauth_token’ in the request, and send that back to the client to save, or your app can merely redirect to any link, as long as you check for that in the client side. My app sends the JSON web token back in the url for the client to capture.
That’s it! You’re done (sorta – you need to implement the client side on ionic – see next blog). Once you complete these steps, your user has signed in via Fitbit! As I said before, if you want to make resource requests on behalf of the user, I’d recommend using fitbit-node. Good luck, and please comment if you have any questions.