OAuth & MongoDB Realm Serverless Functions
Rate this tutorial
I recently had the opportunity to work with Lauren Schaefer and Maxime Beugnet on a stats tracker for some YouTube statistics that we were tracking manually at the time.
I knew that to access the YouTube API, we would need to authenticate using OAuth 2. I also knew that because we were building the app on MongoDB Realm Serverless functions, someone would probably need to write the implementation from scratch.
I've dealt with OAuth before, and I've even built client implementations before, so I thought I'd volunteer to take on the task of implementing this workflow. It turned out to be easier than I thought, and because it's such a common requirement, I'm documenting the process here, in case you need to do the same thing.
This post assumes that you've worked with MongoDB Realm Functions in the past, and that you're comfortable with the concepts around calling REST-ish APIs.
But first...
OAuth 2 is an authorization protocol which allows unrelated servers to allow authenticated access to their services, without sharing user credentials, such as your login password. What this means in this case is that YouTube will allow my Realm application to operate as if it was logged in as a MongoDB user.
There are some extra features for added control and security, like the ability to only allow access to certain functionality. In our case, the application will only need read-only access to the YouTube data, so there's no need to give it permission to delete MongoDB's YouTube videos!
Because OAuth 2 doesn't transmit the user's login credentials, there is some added complexity to make this work.
From the user's perspective, it looks like this:
- The user clicks on a button (or in my minimal implementation, they type in a specific URL), which redirects the browser to the authorizing service—in this case YouTube.
- The authorizing service asks the user to log in, if necessary.
- The authorizing service asks the user to approve the request to allow the Realm app to make requests to the YouTube API on their behalf.
- If the user approves, then the browser redirects back to the Realm application, but with an extra parameter added to the URL containing a code which can be used to obtain access tokens.
Behind the scenes, there's a Step 5, where the Realm service makes an extra HTTPS request to the YouTube API, using the code provided in Step 4, requesting an access token and a refresh token.
Access tokens are only valid for an hour. When they expire, a new access token can be requested from YouTube, using the refresh token, which only expires if it hasn't been used for six months!
If this sounds complicated, that's because it is! If you look more closely at the diagram above, though, you can see that there are only actually two requests being made by the browser to the Realm app, and only one request being made by the Realm app directly to Google. As long as you implement those three things, you'll have implemented the OAuth's full authorization flow.
Once the authorization flow has been completed by the appropriate user (a user who has permission to log in as the MongoDB organization), as long as the access token is refreshed using the refresh token, API calls can be made to the YouTube API indefinitely.
You'll need to create a Realm app and an associated Google project, and link the two together. There are quite a few steps, so make sure you don't miss any!
Go to https://cloud.mongodb.com/ and log in if necessary. I'm going to assume that you have already created a MongoDB Atlas cluster, and an associated Realm App. If not, follow the steps described in the MongoDB documentation.
This flow is loosely applicable to any OAuth service, but I'll be working with Google's YouTube API. The first thing to do is to create a project in the Google API Console that is analogous to your Realm app.
Go to https://console.developers.google.com/apis/dashboard. Click the projects list (at the top-left of the screen), then click the "Create Project" button, and enter a name. I entered "DREAM" because that's the funky acronym we came up with for the analytics monitor project my team was working on. Select the project, then click the radio button that says "External" to make the app available to anyone with a Google account, and click "Create" to finish creating your project.
Ignore the form that you're presented with for now. On the left-hand side of the screen, click "Library" and in the search box, enter "YouTube" to filter Google's enormous API list.
Select each of the APIs you wish to use—I selected the YouTube Data API and the YouTube Analytics API—and click the "Enable" button to allow your app to make calls to these APIs.
Now, select "OAuth consent screen" from the left-hand side of the window. Next to the name of your app, click "Edit App."
You'll be taken to a form that will allow you to specify how your OAuth consent screens will look. Enter a sensible app name, your email address, and if you want to, upload a logo for your project. You can ignore the "App domain" fields for now. You'll need to enter an Authorized domain by clicking "Add Domain" and enter "mongodb-realm.com" (without the quotes!). Enter your email address under "Developer contact information" and click "Save and Continue."
In the table of scopes, check the boxes next to the scopes that end with "youtube.readonly" and "yt-analytics.readonly." Then click "Update." On the next screen, click "Save and Continue" to go to the "Test users" page. Because your app will be in "testing" mode while you're developing it, you'll need to add the email addresses of each account that will be allowed to authenticate with it, so I added my email address along with those of my team.
Click "Save and Continue" for a final time and you're done configuring the OAuth consent screen!
A final step is to generate some credentials your Realm app can use to prove to the Google API that the requests come from where they say they do. Click on "Credentials" on the left-hand side of the screen, click "Create Credentials" at the top, and select "OAuth Client ID."
The "Application Type" is "Web application." Enter a "Name" of "Realm App" (or another useful identifier, if you prefer), and then click "Create." You'll be shown your client ID and secret values. Leave them up on the screen, and in a different tab, go to your Realm app and select "Values" from the left side. Click the "Create New Value" button, give it a name of "GOOGLE_CLIENT_ID," select "Value," and paste the client ID into the content text box.
Repeat with the client secret, but select "Secret," and give it the name "GOOGLE_CLIENT_SECRET." You'll then be able to access these values with code like context.values.get("GOOGLE_CLIENT_ID") in your Realm function.
Once you've got the values safely stored in your Realm App, you've now got everything you need to authorize a user with the YouTube Analytics API.
To create an HTTP endpoint, you'll need to create an HTTP service in your Realm App. Go to your Realm App, select "3rd Party Services" on the left side, and then click the "Add a Service" button. Select HTTP and give it a "Service Name." I chose "google_oauth."
A webhook function is automatically created for you, and you'll be taken to its settings page.
Give the webhook a name, like "authorizor," and set the "HTTP Method" to "GET." While you're here, you should copy the "Webhook URL." Go back to your Google API project, "Credentials," and then click on the Edit (pencil) button next to your Realm app OAuth client ID.
Under "Authorized redirect URIs," click "Add URI," paste the URI into the text box, and click "Save."
Go back to your Realm Webhook settings, and click "Save" at the bottom of the page. You'll be taken to the function editor, and you'll see that some sample code has been inserted for you. Replace it with the following skeleton:
Because the function will be making outgoing HTTP calls that will need to be awaited, I've made it an async function. Inside the function, I've required the querystring library because the function will also need to generate query strings for redirecting to Google.
After the require line, paste in the following constants, which will be required for authorizing users with Google:
Add the following lines, which will obtain values for the Google credentials client ID and secret, and also obtain the URL for the current webhook call:
Once this is done, the code should check to see if it's being called via a Google redirect due to an error. This is the case if it's called with an
error parameter. If that's the case, a good option is to log the error and display it to the user. Add the following code which does this:Now to implement Step 1 of the authorization flow illustrated at the start of this post! When the user requests this webhook URL, they won't provide any parameters, whereas when Google redirects to it, the URL will include a
code parameter. So, by checking if the code parameter is absent, you can ensure that we're this is the Step 1 call. Add the following code:The code above adds the appropriate parameters to the Google OAuth endpoint described in their OAuth flow documentation, and then redirects the browser to this endpoint, which will display a consent page to the user. When Steps 2 and 3 are complete, the browser will be redirected to this webhook (because that's the URL contained in
OAUTH2_CALLBACK) with an added code parameter.Add the following code inside the empty
else block you added above, to handle the case where a code parameter is provided:There's quite a lot of code here to implement Step 5, but it's not too complicated. It makes a request to the Google token endpoint, providing the code from the URL, to obtain both an access token and a refresh token for when the access token expires (which it does after an hour). It then checks for errors, modifies the JavaScript object a little to make it suitable for storing in MongoDB, and then it saves it to the
tokens_collection. You can find all the code for this webhook function on GitHub.Go to the webhook's "Settings" tab, copy the webhook's URL, and paste it into a new browser tab. You should see the following scary warning page! This is because the app has not been checked out by Google, which would be the case if it was fully published. You can ignore it for now—it's safe because it's your app. Click "Continue" to progress to the consent page.
The consent page should look something like the screenshot below. Click "Allow" and you should be presented with a very plain page that says
{"status": "okay" }, which means that you've completed all of the authorization steps!
If you load up the
auth_tokens collection in MongoDB Atlas, you should see that it contains a single document containing the access and refresh tokens provided by Google.
To make a test call, create a new HTTP service webhook, and paste in the following code:
The summary of this code is that it looks up an access token in the
auth_tokens collection, and then makes an authenticated request to YouTube's playlists endpoint. Authentication is proven by providing the access token as a bearer token in the 'Authorization' header.Test out this function by calling the webhook in a browser tab. It should display some JSON, listing details about your YouTube playlists. The problem with this code is that if you run it over an hour after authorizing with YouTube, then the access token will have expired, and you'll get an error message! To account for this, I created a function called
get_token, which will refresh the access token if it's expired.The
get_token function is a standard MongoDB Realm serverless function, not a webhook. Click "Functions" on the left side of the page in MongoDB Realm, click "Create New Function," and name your function "get_token." In the function editor, paste in the following code:The start of this function does the same thing as the temporary block in the webhook—it looks up the currently stored access token in MongoDB Atlas. It then checks to see if the token has expired, and if it has, it makes a call to Google with the
refresh_token, requesting a new access token, which it then uses to update the MongoDB document.Save this function and then return to your test webhook. You can replace the code between the TEMPORARY BLOCK comments with the following line of code:
From now on, this should be all you need to do to make an authorized request against the Google API—obtain the access token with
get_token and add it to your HTTP request as a bearer token in the Authorization header.I hope you found this useful! The OAuth 2 protocol can seem a little overwhelming, and the incompatibility of various client libraries, such as Google's, with MongoDB Realm can make life a bit more difficult, but this post should demonstrate how, with a webhook and a utility function, much of OAuth's complexity can be hidden away in a well designed MongoDB app.
If you have questions, please head to our developer community website where the MongoDB engineers and the MongoDB community will help you build your next big idea with MongoDB.
Rate this tutorial