Forem: Aaron Parecki

How to export your complete Foursquare checkin history

Aaron Parecki — Wed, 03 Nov 2021 15:22:31 +0000

Today I finished up a tool that you can use to export your complete history from Foursquare and publish the checkins to your website!

In 2017, I created OwnYourSwarm to export my future Swarm checkins to my website in real-time. It's been working great, and it's meant that I have had a complete archive of all my checkins on my website ever since then, so I don't have to worry if Foursquare disappears one day. However, I never got around to creating a way to export my past checkins, so I was always missing my checkin history from 2009-2016.

I had been considering building this as a feature of OwnYourSwarm, but realized that it would end up taking a lot of additional effort to make it work well as a web service, in addition to dealing with possible rate limit issues with the Foursquare API. So instead, this is published as a downloadable script you can run on your own computer. This also means you have a bit more flexibility in how you can use it, as well as being able to customize it more if you choose.

You can download the code from GitHub here:

https://github.com/aaronpk/Swarm-Checkins-Import

The readme has installation and usage instructions, so I'll refrain from repeating all that in this post. Make sure to check out the step by step tutorial in the readme if you want to use this with your own account.

The process is broken up into a couple steps.

First, it downloads your entire Foursquare checkin history to JSON files on your computer
Second, it downloads all the photos from your checkins
Third, it publishes each checkin to your website via Micropub

If your website doesn't support checkins via Micropub, or if you don't want your checkins on your website at all, you can just skip that step entirely, and instead you'll have a complete export of your data locally.

The JSON files contain the raw API response from Foursquare, so you can do what you want with that as well, such as turning it into your own HTML archive using your own custom tools if you want.

The one issue that I don't have a good solution for is handling renamed venues. Unfortunately the API returns the current name for old checkins, so if a venue is renamed, your old checkins will not reflect the name at the time of the checkin. This is particularly strange for businesses that have gone through an acquisition or rebranding, since for example all my old checkins in Green Dragon are now labeled as Rogue Eastside Brewery. As far as I can tell there isn't a good way to handle this, so I may have to go back and manually edit the posts on my website for the venues I know have been renamed.

I hope this is useful to people! I will be sleeping a little easier now knowing that my old checkin history is safely archived on my website now!

Is the OAuth 2.0 Implicit Flow Dead?

Aaron Parecki — Wed, 01 May 2019 05:00:00 +0000

You may have heard some buzz recently about the OAuth 2.0 Implicit flow. The OAuth Working Group has published some new guidance around the Implicit flow and JavaScript-based apps, specifically that the Implicit flow should no longer be used. In this post, we’ll look at what’s changing with the Implicit flow and why.

The Best Practice Around Implicit in OAuth 2.0 is Changing

The Implicit flow in OAuth 2.0 was created nearly ten years ago when browsers worked very differently than they do today. The primary reason the Implicit flow was created was because of an old limitation in browsers. It used to be the case that JavaScript could only make requests to the same server that the page was loaded from. However, the standard OAuth Authorization Code flow requires that a POST request is made to the OAuth server’s token endpoint, which is often on a different domain than the app. That meant there was previously no way to use this flow from JavaScript. The Implicit flow worked around this limitation by avoiding that POST request, and instead of returning the access token immediately in the redirect.

Today, Cross-Origin Resource Sharing (CORS) is universally adopted by browsers, removing the need for this compromise. CORS provides a way for JavaScript to make requests to servers on a different domain as long as the destination allows it. This opens up the possibility of using the Authorization Code flow in JavaScript.

It’s worth noting that the Implicit flow has always been seen as a compromise compared to the Authorization Code flow. For example, the spec provides no mechanism to return a refresh token in the Implicit flow, as it was seen as too insecure to allow that. The spec also recommends short lifetimes and limited scope for access tokens issued via the Implicit flow.

The OAuth Authorization Code Flow is Better

Now that it is possible to use the Authorization Code flow from a browser, we still have one more issue to deal with regarding JavaScript apps. Traditionally the Authorization Code flow uses a client secret when exchanging the authorization code for an access token, but there is no way to include a client secret in a JavaScript app and have it remain a secret. If you were to include a secret in the source code, anyone using the app could just “view source” in their browser and see it. So we need a solution.

Thankfully, this problem has already been solved, since the same issue applies to mobile apps as well. As we’ve seen in the past, native apps also can’t safely use a client secret. The OAuth working group solved this problem several years ago with the PKCE extension to the Authorization Code flow.

The Authorization Code flow with PKCE adds an additional step, which allows us to protect the authorization code so that even if it is stolen during the redirect, it will be useless by itself. You can read more about how PKCE works in our blog post, OAuth 2.0 for Native and Mobile Apps.

The OAuth 2.0 Implicit Flow for Existing Apps

The important thing to remember here is that there was no new vulnerability found in the Implicit flow. If you have an existing app that uses the Implicit flow, it’s not that your app is suddenly now insecure after this new guidance has been published.

That said, it is – and always has been – extremely challenging to implement the Implicit flow securely. If you have gone to the trouble of thoroughly auditing your source code, knowing exactly which third-party libraries you’re using in your application, have a strong Content Security Policy, and are confident in your ability to build a secure JavaScript application, then your application is probably fine.

So should you immediately switch all your apps to using PKCE instead of the Implicit flow? Probably not, it depends on your risk tolerance. But at this point, I would definitely not recommend creating new apps using the Implicit flow.

Does the Authorization Code Flow Make Browser-Based Apps Totally Secure?

Unfortunately, there is no such thing as perfect security. Especially in browsers, there are always many ways an application may be attacked. The best we can do is protect against common attacks, and reduce the overall attack surface of an application.

Specifically, the Authorization Code flow with PKCE does completely protect the application from the attack where an authorization code is stolen in transit back to the application. However, once the JavaScript app has obtained an access token, it will still have to store it somewhere in order to use it, and how it stores the access token will be the same whether the app used the Implicit flow or PKCE to obtain it. You’ll still need to ensure you have a good Content Security Policy and are aware of any third-party libraries you’re using in your application.

The best way to securely implement OAuth in a JavaScript app is to keep the token management outside of JavaScript entirely. If you’re building a JavaScript app that is served from a dynamic server, such as a Spring Boot backend with an Angular frontend, or an ASP.NET backend with a React front-end, then you can keep all of the OAuth exchange and token management inside the backend, never exposing it to the JavaScript front-end, and avoid all the risks inherent in managing tokens in JavaScript.

Start Using the Implicit Flow with PKCE in JavaScript Today

So you’re ready to start writing an app using PKCE in JavaScript? Let’s take a look at exactly what that entails.

For the purposes of this demonstration, let’s assume you want to implement this in pure JavaScript, with no additional libraries required. This will illustrate exactly how PKCE works, which you should then be able to translate into your particular framework of choice.

First, sign up for a free Okta Developer account. Once you’ve signed up, select Applications from the menu at the top of the page, and click Add Application.

Choose Single-Page App from the options, which will configure this application to enable the CORS headers on the token endpoint, and will not create a client secret.

Give your application a name, and then there are two settings you’ll need to change.

Change the Login redirect URI to match the base URI since we’ll be building a single-page app in just one HTML file.

Also, make sure to check the Authorization Code checkbox, and uncheck Implicit.

That will register the application and provide you with a client_id on the next screen. Make a note of this value since we’ll need it again later.

Create a new folder, and create an HTML file in it called index.html with the following contents. Fill in your Client ID in the config block below.

<html>
<title>OAuth Authorization Code + PKCE in Vanilla JS</title>
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">

<script>
// Configure your application and authorization server details
var config = {
    client_id: "",
    redirect_uri: "http://localhost:8080/",
    authorization_endpoint: "",
    token_endpoint: "",
    requested_scopes: "openid"
};
</script>

Next, we need to find the authorization endpoint and token endpoint for your OAuth server. Navigate to API in the main menu at the top, then choose Authorization Servers. You will probably have only one server in that list, “default”.

Copy the Issuer URI from that authorization server. Your authorization endpoint will be that URI with /v1/auth appended, and the token endpoint will end with /v1/token.

For example, if your Issuer URI is https://{yourOktaDomain}/oauth2/default, then your authorization endpoint will be https:/{yourOktaDomain}/oauth2/defalut/v1/auth and your token endpoint will be https://{yourOktaDomain}/oauth2/default/v1/token. Enter those two values in the JavaScript config object created in the previous step.

Set Up the HTML Structure

Next, let’s add some HTML to the page to create a couple of UI elements to help illustrate this flow.

<div class="flex-center full-height">
    <div class="content">
        <a href="#" id="start">Click to Sign In</a>
        <div id="token" class="hidden">
            <h2>Access Token</h2>
            <div id="access_token" class="code"></div>
        </div>
        <div id="error" class="hidden">
            <h2>Error</h2>
            <div id="error_details" class="code"></div>
        </div>
    </div>
</div>

And to make it look good, add the following CSS below.

<style>
body {
  padding: 0;
  margin: 0;
  min-height: 100vh;
  font-family: arial, sans-serif;
}
@media(max-width: 400px) {
  body {
    padding: 10px;
  }
}
.full-height {
  min-height: 100vh;
}
.flex-center {
  align-items: center;
  display: flex;
  justify-content: center;
}
.content {
  max-width: 400px;
}
h2 {
  text-align: center;
}
.code {
  font-family: "Courier New", "Courier", monospace;
  width: 100%;
  padding: 4px;
  border: 1px #ccc solid;
  border-radius: 4px;
  word-break: break-all;
}
.hidden {
  display: none;
}
</style>

Begin the PKCE Request

With that out of the way, we can get to the good stuff, actually starting the PKCE flow in JavaScript. First, add a new <script> tag so that we have a place to start writing JavaScript.

<script>
</script>

We’re first going to define a few helper functions that will take care of the tricky parts of PKCE: securely generating a random string, and generating the SHA256 hash of that string.

Add these functions into the <script> tag you just created.

// PKCE HELPER FUNCTIONS

// Generate a secure random string using the browser crypto functions
function generateRandomString() {
    var array = new Uint32Array(28);
    window.crypto.getRandomValues(array);
    return Array.from(array, dec => ('0' + dec.toString(16)).substr(-2)).join('');
}

// Calculate the SHA256 hash of the input text. 
// Returns a promise that resolves to an ArrayBuffer
function sha256(plain) {
    const encoder = new TextEncoder();
    const data = encoder.encode(plain);
    return window.crypto.subtle.digest('SHA-256', data);
}

// Base64-urlencodes the input string
function base64urlencode(str) {
    // Convert the ArrayBuffer to string using Uint8 array to convert to what btoa accepts.
    // btoa accepts chars only within ascii 0-255 and base64 encodes them.
    // Then convert the base64 encoded to base64url encoded
    // (replace + with -, replace / with _, trim trailing =)
    return btoa(String.fromCharCode.apply(null, new Uint8Array(str)))
        .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
}

// Return the base64-urlencoded sha256 hash for the PKCE challenge
async function pkceChallengeFromVerifier(v) {
    hashed = await sha256(v);
    return base64urlencode(hashed);
}

Now we’re ready to kick off the flow. The first step of the PKCE flow is to generate a secret, hash it, then redirect the user over to the authorization server with that hash in the URL.

We’ll add an onclick listener to the Click to Sign In link we created in the HTML.

// Initiate the PKCE Auth Code flow when the link is clicked
document.getElementById("start").addEventListener("click", async function(e){
    e.preventDefault();

    // Create and store a random "state" value
    var state = generateRandomString();
    localStorage.setItem("pkce_state", state);

    // Create and store a new PKCE code_verifier (the plaintext random secret)
    var code_verifier = generateRandomString();
    localStorage.setItem("pkce_code_verifier", code_verifier);

    // Hash and base64-urlencode the secret to use as the challenge
    var code_challenge = await pkceChallengeFromVerifier(code_verifier);

    // Build the authorization URL
    var url = config.authorization_endpoint 
        + "?response_type=code"
        + "&client_id="+encodeURIComponent(config.client_id)
        + "&state="+encodeURIComponent(state)
        + "&scope="+encodeURIComponent(config.requested_scopes)
        + "&redirect_uri="+encodeURIComponent(config.redirect_uri)
        + "&code_challenge="+encodeURIComponent(code_challenge)
        + "&code_challenge_method=S256"
        ;

    // Redirect to the authorization server
    window.location = url;
});

This function does a few things:

Creates a random string to use as the state value and stores it in LocalStorage
Creates a random string to use as the PKCE code_verifier value
Hashes and base64-urlencodes the code verifier
Builds the authorization URL with all the required parameters, using the config values you defined at the beginning
Redirects the browser to the authorization URL

At this point, the user is handed off to the authorization server to log in. The authorization server will then redirect the user back to the application, and there will be two parameters in the query string: code and state.

Get an Access Token using the Authorization Code

This application will need to verify the state value matches the one it generated at the beginning, then exchange the authorization code for an access token. To accomplish this, we’ll need to add a couple more helper functions.

Add the following function to the bottom of your JavaScript. This function will parse a query string into a JavaScript object.

// Parse a query string into an object
function parseQueryString(string) {
    if(string == "") { return {}; }
    var segments = string.split("&").map(s => s.split("=") );
    var queryString = {};
    segments.forEach(s => queryString[s[0]] = s[1]);
    return queryString;
}

Also, add the function below, which will give us an easy way to make a POST request and parse the JSON response.

// Make a POST request and parse the response as JSON
function sendPostRequest(url, params, success, error) {
    var request = new XMLHttpRequest();
    request.open('POST', url, true);
    request.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded; charset=UTF-8');
    request.onload = function() {
        var body = {};
        try {
            body = JSON.parse(request.response);
        } catch(e) {}

        if(request.status == 200) {
            success(request, body);
        } else {
            error(request, body);
        }
    }
    request.onerror = function() {
        error(request, {});
    }
    var body = Object.keys(params).map(key => key + '=' + params[key]).join('&');
    request.send(body);
}

Now you’re ready to exchange the authorization code for an access token. If you’re familiar with the traditional Authorization Code flow, you’ll remember that this step normally requires a client secret. But since we don’t have a client secret for this JavaScript application, instead we’ll send the PKCE code verifier when making this request, which ensures that only the application that requested a code can exchange it for an access token.

Add the following code to your JavaScript section.

// Handle the redirect back from the authorization server and
// get an access token from the token endpoint

var q = parseQueryString(window.location.search.substring(1));

// Check if the server returned an error string
if(q.error) {
    alert("Error returned from authorization server: "+q.error);
    document.getElementById("error_details").innerText = q.error+"\n\n"+q.error_description;
    document.getElementById("error").classList = "";
}

// If the server returned an authorization code, attempt to exchange it for an access token
if(q.code) {

    // Verify state matches what we set at the beginning
    if(localStorage.getItem("pkce_state") != q.state) {
        alert("Invalid state");
    } else {

        // Exchange the authorization code for an access token
        sendPostRequest(config.token_endpoint, {
            grant_type: "authorization_code",
            code: q.code,
            client_id: config.client_id,
            redirect_uri: config.redirect_uri,
            code_verifier: localStorage.getItem("pkce_code_verifier")
        }, function(request, body) {

            // Initialize your application now that you have an access token.
            // Here we just display it in the browser.
            document.getElementById("access_token").innerText = body.access_token;
            document.getElementById("start").classList = "hidden";
            document.getElementById("token").classList = "";

            // Replace the history entry to remove the auth code from the browser address bar
            window.history.replaceState({}, null, "/");

        }, function(request, error) {
            // This could be an error response from the OAuth server, or an error because the 
            // request failed such as if the OAuth server doesn't allow CORS requests
            document.getElementById("error_details").innerText = error.error+"\n\n"+error.error_description;
            document.getElementById("error").classList = "";
        });
    }

    // Clean these up since we don't need them anymore
    localStorage.removeItem("pkce_state");
    localStorage.removeItem("pkce_code_verifier");
}

This code does a few things:

Checks if the authorization server returned an error message and displays it to the user if so
Checks if the authorization server returned an authorization code, and exchanges it for an access token
Sends a POST request to the token endpoint which includes the code_verifier parameter that is made in the previous step
Updates the UI to indicate error messages or show the access token returned
Removes the authorization code from the address bar using the Session History Management API

At this point, you’re ready to try out the application! You’ll need to either run a local web server or host it on a test domain. In any case, just make sure that the Base URI and Redirect URI in your application settings are set to the URL that you’ll be visiting this application. (Also note that this will not work just opening the page from your filesystem due to cross-domain restrictions that browser have with file:// URIs).

You can use any webserver to serve the file, but I find that an easy way to launch this app is to use PHP’s built-in web server. You can run the command below to start a web server on port 8080:

php -S localhost:8080

You can now visit http://localhost:8080/ in your browser, and you’ll see the sign-in link.

Click on that link, and you’ll be redirected to Okta. If you’re already signed in, you’ll be immediately redirected, and the app will get an access token!

Congrats! You’ve successfully implemented PKCE in a browser with vanilla JavaScript!

You can find the completed sample code here: pkce-vanilla-js

Hopefully, this has been a helpful demonstration of what it takes to do PKCE in a browser! In practice, you’ll probably use a JavaScript library that handles this behind the scenes for you, but it can still be useful to know how this works under the hood!

Learn More about OAuth 2.0, the Implicit Flow, and Secure Authentication

If you’d like to dig deeper into these topics, here are a few resources:

Like what you learned today? Follow us on Twitter, and subscribe to our YouTube channel for more awesome content!

Use nginx to Add Authentication to Any Application

Aaron Parecki — Tue, 28 Aug 2018 05:00:00 +0000

Ever found yourself wanting to put an application behind a login form, but dreading writing all that code to deal with OAuth 2.0 or passwords? In this tutorial, I’ll show you how to use the nginx auth_request module to protect any application running behind your nginx server with OAuth 2.0, without writing any code! Lasso, a microservice written in Go, handles the OAuth dance to any number of different auth providers so you don’t have to.

Why Authenticate at the Web Server?

Imagine you use nginx to run a small private wiki for your team. At first, you probably start out with adding a wiki user account for each person. It’s not too bad, adding new accounts for new hires, and removing them when they leave.

A few months later, as your team and company start growing, you add some server monitoring software, and you want to put that behind a login so only your company can view it. Since it’s not very sophisticated software, the easiest way to do that is to create a single password for everyone in an .htpasswd file, and share that user with the office.

Another month goes by, and you add a continuous integration system, and that comes with GitHub authentication as an option, which seems reasonable since most of your team has GitHub accounts already.

At this point, when someone new joins, you have to create a wiki account for them, add them to the GitHub organization, and give them the shared password for the other system. When someone leaves, you can delete their wiki account and remove them from GitHub, but let’s face it, you probably won’t change the shared password for a while since it’s annoying having to distribute that to everyone again.

Surely there must be a better way to integrate all these systems to use a common shared login system! The problem is the wiki is written in PHP, the server monitoring system just ends up publishing a folder of static HTML, and the CI system is written in Ruby which only one person on your team feels comfortable writing.

If the web server could handle authenticating users, then each backend system wouldn’t need to worry about it, since the only requests that could make it through would already be authenticated!

Using the nginx auth_request Module

Enter the nginx auth_request module.

This module is shipped with nginx, but requires enabling when you compile nginx. When you download the nginx source and compile, just include the --with-http_auth_request_module flag along with any others that you use.

The auth_request module sits between the internet and your backend server that nginx passes requests onto, and any time a request comes in, it first forwards the request to a separate server to check whether the user is authenticated, and uses the HTTP response to decide whether to allow the request to continue to the backend.

This diagram illustrates a request that comes in for the server name stats.avocado.lol. First, nginx fires off a sub-request to login.avocado.lol (1), and if the response (2) to that request returns HTTP 200, it then continues forwarding the request on to the backend stats.avocado.lol.

Choosing an Auth Proxy

Since the nginx auth_request module has no concept of users or how to authenticate anyone, we need something else in the mix that can actually handle logging users in. In the diagram above, this is illustrated by the server name login.avocado.lol.

This server needs to handle an HTTP request and return HTTP 200 or 401 depending on whether the user is logged in. If the user is not logged in, it needs to know how to get them to log in and set a session cookie.

To accomplish this, we’ll use the open source project “Lasso”. Lasso is written in Go, so it’s super easy to deploy. Everything can be configured via a single YAML file. Lasso can be configured to authenticate users via a variety of OAuth and OpenID Connect backends such as GitHub, Google, Okta or any other custom servers.

We’ll come back to configuring Lasso in a few minutes, but for now, let’s continue on to set up your protected server in nginx.

Configure Your Protected nginx Host

Starting with a typical nginx server block, you just need to add a couple lines to enable the auth_request module. Here is an example server block that should look similar to your own config. This example just serves a folder of static HTML files, but the same idea applies whether you’re passing the request on to a fastcgi backend or using proxy_pass.

server {
  listen 443 ssl http2;
  server_name stats.avocado.lol;

  ssl_certificate /etc/letsencrypt/live/avocado.lol/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/avocado.lol/privkey.pem;

  root /web/sites/stats.avocado.lol;

  index index.html;
}

Add the following to your existing server block:

# Any request to this server will first be sent to this URL
auth_request /lasso-validate;

location = /lasso-validate {
    # This address is where Lasso will be listening on
proxy_pass http://127.0.0.1:9090/validate;
proxy_pass_request_body off; # no need to send the POST body

proxy_set_header Content-Length "";
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

# these return values are passed to the @error401 call
auth_request_set $auth_resp_jwt $upstream_http_x_lasso_jwt;
auth_request_set $auth_resp_err $upstream_http_x_lasso_err;
auth_request_set $auth_resp_failcount $upstream_http_x_lasso_failcount;
}

error_page 401 = @error401;

# If the user is not logged in, redirect them to Lasso's login URL
location @error401 {
return 302 https://login.avocado.lol/login?url=https://$http_host$request_uri&lasso-failcount=$auth_resp_failcount&X-Lasso-Token=$auth_resp_jwt&error=$auth_resp_err;
}

Let’s look at what’s going on here. The first line, auth_request /lasso-validate; is what enables this flow. This tells the auth_request module to first send any request to this URL before deciding whether it’s allowed to continue to the backend server.

The block location = /lasso-validate captures that URL, and proxies it to the Lasso server that will be listening on port 9090. We don’t need to send the POST body to Lasso, since all we really care about is the cookie.

The line error_page 401 = @error401; tells nginx what to do if Lasso returns an HTTP 401 response, which is to pass it to the block defined by location @error401. That block will redirect the user’s browser to Lasso’s login URL which will kick off the flow to the real authentication backend.

Configure a Server Block for Lasso

Next, configure a new server block for Lasso so that it has a publicly accessible URL like https://login.avocado.lol. All this needs to do is proxy the request to the backend Lasso server.

server {
  listen 443 ssl;
  server_name login.avocado.lol;

  ssl_certificate /etc/letsencrypt/live/login.avocado.lol/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/login.avocado.lol/privkey.pem;

  # Proxy to your Lasso instance
  location / {
    proxy_set_header Host login.avocado.lol;
    proxy_set_header X-Forwarded-Proto https;
    proxy_pass http://127.0.0.1:9090;
  }
}

Configure and Deploy Lasso

You’ll need to download Lasso and compile the Go binary for your platform. You can follow the instructions in the project’s README file.

Once you’ve got a binary, you’ll need to create the config file to define the way you want Lasso to authenticate users.

Copy config/config.yml_example to config/config.yml and read through the settings there. Most of the defaults will be fine, but you’ll want to create your own JWT secret string and replace the placeholder value of your_random_string.

The easiest way to configure Lasso is to have it allow any user that can authenticate at the OAuth server be allowed to access the backend. This works great if you’re using a private OAuth server like Okta to manage your users. Go ahead and set allowAllUsers: true to enable this behavior, and comment out the domains: chunk.

You’ll need to choose an OAuth 2.0 provider to use to actually authenticate users. In this example we’ll use Okta, since that’s the easiest way to have a full OAuth/OpenID Connect server and be able to manage all your user accounts from a single dashboard. Before you can finish filling out the config file, you’ll need to sign up for an Okta Developer account at developer.okta.com/. Once you create an account, click Applications in the top menu, and create a new application. Choose Web as the application platform.

In the next screen, you’ll need to configure the Base URI and Login redirect URI to match your own server’s settings. Lasso’s redirect URI ends in /auth so your configuration should look like the below screenshot.

Once you’ve done that, Okta will give you a client ID and secret, which you’ll need to include in the config file.

config.yml

oauth:
  provider: oidc
  client_id: {yourClientID}
  client_secret: {yourClientSecret}
  auth_url: https://{yourOktaDomain}/oauth2/default/v1/authorize
  token_url: https://{yourOktaDomain}/oauth2/default/v1/token
  user_info_url: https://{yourOktaDomain}/oauth2/default/v1/userinfo
  scopes:
    - openid
    - email
  # Set the callback URL to the domain that Lasso is running on
  callback_url: https://login.avocado.lol/auth

Now you can run Lasso! It will listen on port 9090, which is where you’ve configured nginx to send the auth_request verifications as well as serve traffic from login.avocado.lol.

When you reload the nginx config, all requests to stats.avocado.lol will require that you log in via Okta first!

Bonus: Who Logged In?

If you’re putting a dynamic web app behind nginx and you care not only about whether someone was able to log in, but also who they are, there is one more trick we can use.

By default, Lasso will extract a user ID via OpenID Connect (or GitHub or Google if you’ve configured those as your auth providers), and will include that user ID in an HTTP header that gets passed back up to the main server.

In your main server block, just below the line auth_request /lasso-validate; which enables the auth_request module, add the following:

auth_request_set $auth_user $upstream_http_x_lasso_user;

This will take the HTTP header that Lasso sets, X-Lasso-User, and assign it to the nginx variable $auth_user. Then, depending on whether you use fastcgi or proxy_pass, include one of the two lines below in your server block:

fastcgi_param REMOTE_USER $auth_user;
proxy_set_header Remote-User $auth_user;

These will set an HTTP header with the value of $auth_user that your backend server can read in order to know who logged in. For example, in PHP you can access this data using:

<?php
echo 'Hello, ' . $_SERVER['REMOTE_USER'] . '!';

Now you can be sure that your internal app can only be accessed by authenticated users!

Learn More About OAuth 2.0 and Secure User Management with Okta

For more information and tutorials about OAuth 2.0, check out some of our other blog posts!

As always, we’d love to hear from you about this post, or really anything else! Hit us up in the comments, or on Twitter @oktadev!

OAuth 2.0 from the Command Line

Aaron Parecki — Mon, 16 Jul 2018 05:00:00 +0000

So you’ve found yourself writing a command line script and needing to talk to an API that uses OAuth 2.0? The typical approaches to getting an OAuth access token from a command line script usually involve copying and pasting the authorization code into the terminal. But we can do better!

In this tutorial, I’ll show you how to write a command line script which is able to complete the OAuth exchange all without any copying and pasting long strings! Why? Because it’s mildly useful, but most importantly, because it’s fun!

Get Started with Okta

We’re going to write this sample app to talk to the Okta API, but it should be easily adapted to any OAuth 2.0 service you’re using. To get started, sign up for a free developer account, and come back here when you’ve made your account.

Why Okta? Well, because Okta is a free-to-use API service that stores user accounts, and makes handling user authentication, authorization, social login, password reset, etc. — simple. Okta utilizes open standards like OAuth 2.0 to make integration seamless.

We first need to create an OAuth application in the Okta Developer dashboard. In the Applications section of your account, click Add Application , and choose Web. (Yes I realize this is counterintuitive, but choosing Web is what tells Okta that we want to do that OAuth Authorization Code flow.) You can accept all the defaults in the application settings.

Click Done and you’ll be taken to the next screen where you can get your new client ID and secret. Copy those two values and enter them in the code below, adding this to a new PHP file called login.php.

<?php
$client_id = '{yourClientId}';
$client_secret = '{yourClientSecret}';

We also need to find the authorization server metadata URL. From the top menu, choose API -> Authorization Servers. You should see one authorization server in the list, default. Click that and fill in the Metadata URI into your PHP file like the below:

$metadata = http('https://{yourOktaDomain}/oauth2/default/.well-known/oauth-authorization-server');

The Trick to OAuth 2.0 on the Command Line

The way we’re going to avoid the need to copy and paste anything during the login flow is by having our PHP command line script start a mini HTTP server just when we need it, and shut down when we’re done.

The script will launch the browser to the authorization URL, and when Okta redirects the user back to the mini built-in server, we’ll catch that response, extract the authorization code, shut down the server, and continue with whatever the script was doing.

To begin, we need to define a few variables that we’ll use when setting up this server, as well as define a function that will help us make HTTP requests. Copy the following code into your PHP file.

$ip = '127.0.0.1';
$port = '8080';

$redirect_uri = 'http://'.$ip.':'.$port.'/authorization-code/callback';
$socket_str = 'tcp://'.$ip.':'.$port;

function http($url, $params=false) {
  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  if($params)
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
  return json_decode(curl_exec($ch));
}

Start the OAuth 2.0 Flow

We’re ready to start the OAuth flow now. First we generate a random “state” value for added security. Since we’re building this in a command line script, we don’t need to worry about storing it in a session or anything, since we’ll generate it and then use it and then be done with it.

$state = bin2hex(random_bytes(5));

Next we can build the authorization URL that we’ll open to start the flow, using the authorization_endpoint from the server’s metadata.

$authorize_url = $metadata->authorization_endpoint.'?'.http_build_query([
  'response_type' => 'code',
  'client_id' => $client_id,
  'redirect_uri' => $redirect_uri,
  'state' => $state,
]);

So far this is a typical OAuth request, nothing particularly unique happening here yet.

Since we’ll be running this from the command line, we obviously can’t use the normal technique of sending an HTTP redirect to the browser, since we aren’t in a browser! Instead, we need to use a shell command to launch a new browser to the URL.

echo "Open the following URL in a browser to continue\n";
echo $authorize_url."\n";
shell_exec("open '".$authorize_url."'");

On a Mac, open will try to open whatever argument is passed to it using the system default handler. Since we give it a URL, it will open a browser window to that URL. If you’re not on a mac, then you’ll have to click the URL that is displayed in the terminal instead.

Now here comes the trick. The script just launched a browser window to the authorization server, and the user now has to log in. After they do, that browser window will be redirected back to http://127.0.0.1:8080/authorization-code/callback with an authorization code in the query string. This means we need to have an HTTP server ready to handle that request so that we can extract the authorization code from the URL.

So we’re going to create a mini HTTP server in our command line script. It will open a socket on port 8080, wait for a complete HTTP request, send back a simple response, and return the authorization code that was in the query string. Here’s a bit of code that will do this, adapted from a real command line tool that does this written by Christian Weiske. Add the function below into your PHP file.

function startHttpServer($socketStr) {
  // Adapted from http://cweiske.de/shpub.htm

  $responseOk = "HTTP/1.0 200 OK\r\n"
    . "Content-Type: text/plain\r\n"
    . "\r\n"
    . "Ok. You may close this tab and return to the shell.\r\n";
  $responseErr = "HTTP/1.0 400 Bad Request\r\n"
    . "Content-Type: text/plain\r\n"
    . "\r\n"
    . "Bad Request\r\n";

  ini_set('default_socket_timeout', 60 * 5);

  $server = stream_socket_server($socketStr, $errno, $errstr);

  if(!$server) {
    Log::err('Error starting HTTP server');
    return false;
  }

  do {
    $sock = stream_socket_accept($server);
    if(!$sock) {
      Log::err('Error accepting socket connection');
      exit(1);
    }
    $headers = [];
    $body = null;
    $content_length = 0;
    //read request headers
    while(false !== ($line = trim(fgets($sock)))) {
      if('' === $line) {
        break;
      }
      $regex = '#^Content-Length:\s*([[:digit:]]+)\s*$#i';
      if(preg_match($regex, $line, $matches)) {
        $content_length = (int)$matches[1];
      }
      $headers[] = $line;
    }
    // read content/body
    if($content_length > 0) {
      $body = fread($sock, $content_length);
    }
    // send response
    list($method, $url, $httpver) = explode(' ', $headers[0]);
    if($method == 'GET') {
      #echo "Redirected to $url\n";
      $parts = parse_url($url);
      #print_r($parts);
      if(isset($parts['path']) && $parts['path'] == '/authorization-code/callback'
        && isset($parts['query'])
      ) {
        parse_str($parts['query'], $query);
        if(isset($query['code']) && isset($query['state'])) {
          fwrite($sock, $responseOk);
          fclose($sock);
          return $query;
        }
      }
    }
    fwrite($sock, $responseErr);
    fclose($sock);
  } while (true);
}

Now we can use this function to start a server and wait for the browser to hit it.

// Start the mini HTTP server and wait for their browser to hit the redirect URL
// Store the query string parameters in a variable
$auth = startHttpServer($socket_str);

Handle the Authorization Response

At this point, after the user logs in, their browser will be redirected to http://127.0.0.1:8080/authorization-code/callback?code=XXXX&state=YYYY. Our built-in web server will look at the URL of the request and extract the code and state parameters. We need to double check that the state parameter matches the one we set at the beginning, and then we can use the code.

if($auth['state'] != $state) {
  echo "Wrong 'state' parameter returned\n";
  exit(2);
}

$code = $auth['code'];

From here out, we’re proceeding with the normal OAuth Authorization Code request just like any other app. We make a POST request to the token endpoint to exchange the authorization code for an access token.

echo "Getting an access token...\n";
$response = http($metadata->token_endpoint, [
  'grant_type' => 'authorization_code',
  'code' => $code,
  'redirect_uri' => $redirect_uri,
  'client_id' => $client_id,
  'client_secret' => $client_secret,
]);

if(!isset($response->access_token)) {
  echo "Error fetching access token\n";
  exit(2);
}

$access_token = $response->access_token;

Now we have an access token in $access_token! If this were a real tool, you’d probably want to store that somewhere your script can find it next time it’s run. But for the purposes of this demo, we won’t store it anywhere. Instead, we’ll make a request to find out the username of who just logged in.

echo "Getting the username...\n";
$token = http($metadata->introspection_endpoint, [
  'token' => $access_token,
  'client_id' => $client_id,
  'client_secret' => $client_secret,
]);

if($token->active == 1) {
  echo "Logged in as ".$token->username."\n";
  die();
}

This makes a request to the token introspection endpoint to find the username of the person who logged in, prints it to the terminal, and quits.

That’s it! You can open a terminal and run this code with the command below:

php login.php

You can see the full source code for this application on GitHub at https://github.com/aaronpk/command-line-oauth.

Learn More About OAuth 2.0 and Secure User Management with Okta

For more information and tutorials about OAuth 2.0, check out some of our other blog posts!

As always, we’d love to hear from you about this post, or really anything else! Hit us up in the comments, or on Twitter @oktadev!

Add Authentication to your PHP App in 5 Minutes

Aaron Parecki — Mon, 09 Jul 2018 05:00:00 +0000

Have you ever found yourself building an app and needing to add authentication, dreading the thought of setting up yet another username and password database? In this post, I’ll show you how easy it is to use Okta to add authentication to a simple PHP app in 5 minutes. By leveraging Okta’s simple OAuth API, we can breeze past most of the challenges involved in authenticating users by letting Okta take care of the hard parts.

To follow this tutorial, you’ll first need an Okta Developer account if you don’t yet have an account, sign up for free and come back here when you’re done. We won’t use any external PHP libraries or dependencies in this example just to keep things simple.

We’ll start with a single PHP file to demonstrate the logged in/logged out state of our application. Then we’ll integrate the Okta API to authenticate users and find their username after they’re logged in. You can use this guide as the basis of adding authentication to your own real application.

Set Up the Sample PHP App

If you want to skip to the finished project, check out the source code on GitHub. This post builds up the code in the finished project and explains it step by step.

Create a new file, index.php, with the following contents. This will set up two different “views” of our application based on whether the user is logged in (whether there is a username in the PHP session).

<?php
// Begin the PHP session so we have a place to store the username
session_start();

// If there is a username, they are logged in, and we'll show the logged-in view
if(isset($_SESSION['username'])) {
  echo '<p>Logged in as</p>';
  echo '<p>' . $_SESSION['username'] . '</p>';
  echo '<p><a href="/?logout">Log Out</a></p>';
  die();
}

// If there is no username, they are logged out, so show them the login link
if(!isset($_SESSION['username'])) {
  $authorize_url = 'TODO';
  echo '<p>Not logged in</p>';
  echo '<p><a href="'.$authorize_url.'">Log In</a></p>';
}

With that simple skeleton created, we have a place to start working on adding authentication. This app now looks for a “username” in the session variable and considers the user logged in when it’s set.

Next, let’s add a simple function that we’ll use when making API calls to Okta. This function will make an HTTP request and return the JSON-decoded response. It takes a URL and optionally an array of parameters. If there are parameters, it will make a POST request with the parameters as the HTTP body. Otherwise it makes a GET request to the given URL. Since all the API calls we’re doing will result in a JSON response body, this function decodes the JSON response and returns the resulting object.

function http($url, $params=false) {
  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  if($params)
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
  return json_decode(curl_exec($ch));
}

Create an OAuth Application in Okta

Before we can get much further, we need to configure our Okta Developer account to get a client ID and secret to use to talk to the API. In the Applications section of your Okta Developer account, click Add Application **, and choose **Web. The only change we need to make to the default application settings is changing the callback URL to http://localhost:8080/, since we’re writing the entire flow in this one PHP file.

Click Done and you’ll be taken to the next screen where you can get your new client ID and secret. Copy those two values into the variables below, and add this chunk to the top of your PHP file, right after session_start():

$client_id = '';
$client_secret = '';
$redirect_uri = 'http://localhost:8080/';

We also need to find the authorization server metadata URL. From the top menu, choose API -> Authorization Servers. You should see one authorization server in the list, default. Click that and copy the Metadata URI below the client and redirect lines:

$metadata_url = 'https://{yourOktaOrg}/oauth2/default/.well-known/oauth-authorization-server';
// Fetch the authorization server metadata which contains a few URLs
// that we need later, such as the authorization and token endpoints
$metadata = http($metadata_url);

Build the Login URL

Now we’re ready to start building the login URL where we can send the user to authenticate. Replace the line $authorize_url = 'TODO'; with the following code.

  // Generate a random state parameter for CSRF security
  $_SESSION['state'] = bin2hex(random_bytes(5));

  // Build the authorization URL by starting with the authorization endpoint
  // and adding a few query string parameters identifying this application
  $authorize_url = $metadata->authorization_endpoint.'?'.http_build_query([
    'response_type' => 'code',
    'client_id' => $client_id,
    'redirect_uri' => $redirect_uri,
    'state' => $_SESSION['state'],
    'scope' => 'openid',
  ]);

This bit of code sets up the beginning of the OAuth Authorization Code flow. If you want more details about these parameters, I wrote about the Authorization Code flow previously on this blog: What is the OAuth 2.0 Authorization Code Grant Type?

We’ve got enough built now to try this out. From the command line, navigate to the folder with your index.php file and start a PHP server:

php -S 127.0.0.1:8080

Now you can visit this page in a browser http://127.0.0.1:8080/ and you’ll see your login prompt.

Don’t click the link just yet, since we still need to set up handling the callback and getting an access token.

Handle the OAuth Redirect

When the user clicks the login URL, they’re sent to the Okta authorization server. The authorization server will ask them to log in (if they aren’t already logged in), and will then generate a temporary authorization code and redirect the user back to this application. To verify that the user did in fact log in, the application needs to check that this temporary authorization code is valid by exchanging it for an access token at Okta’s authorization server.

Between your client ID configuration lines and the section that renders the logged-out view, we’re going to add a new section that handles exchanging the authorization code for an access token.

Let’s start by adding a check for the authorization code in the query string. Your code should look something like this now.

// ...
$metadata = http($metadata_url);

if(isset($_GET['code'])) {

  // TODO: we'll work on filling out this section next

}

if(!isset($_SESSION['username'])) {
// ...

Inside this new section, in place of the “TODO” comment we just added, let’s first add a few bits of error checking. We’ll start by checking that the authorization server returned the same state parameter we set when the user started logging in.

  if($_SESSION['state'] != $_GET['state']) {
    die('Authorization server returned an invalid state parameter');
  }

  if(isset($_GET['error'])) {
    die('Authorization server returned an error: '.htmlspecialchars($_GET['error']));
  }

It’s also possible that the authorization server returns an error here, so we’ll display the error if that happens.

Next, we need to take the authorization code from the URL and exchange it for an access token at the token endpoint. To do this, we use the token endpoint from the metadata response, and include our client ID and secret in the API call:

  $response = http($metadata->token_endpoint, [
    'grant_type' => 'authorization_code',
    'code' => $_GET['code'],
    'redirect_uri' => $redirect_uri,
    'client_id' => $client_id,
    'client_secret' => $client_secret,
  ]);

  if(!isset($response->access_token)) {
    die('Error fetching access token');
  }

If all goes well, we’ll end up with an access token in the $response object. We don’t actually need the access token for anything except finding out who logged in, so we won’t be storing it anywhere. Instead, we’ll use it to make a request to the token introspection endpoint.

  $token = http($metadata->introspection_endpoint, [
    'token' => $response->access_token,
    'client_id' => $client_id,
    'client_secret' => $client_secret,
  ]);

  if($token->active == 1) {
    $_SESSION['username'] = $token->username;
    header('Location: /');
    die();
  }

This code takes the access token and sends it, along with the client credentials, to the token introspection endpoint. The introspection endpoint tells us the username of the person who logged in. If the token is active, we set the username in the session, then redirect back to the home page. Now that the username is in the session, our “app” considers the user logged in and we see the logged-in page with the user’s email address!

Hopefully this has been a helpful illustration of how easy it is to add authentication to a simple PHP app! Obviously this is a minimalist example, and in reality your application is much more featureful and probably better organized into more than one file. But you should be able to take what you’ve learned here and adapt it to other frameworks or use cases that you’re working with!

You can see the full source code for this application on GitHub.

What is the OAuth 2.0 Implicit Grant Type?

Aaron Parecki — Thu, 24 May 2018 05:00:00 +0000

The Implicit Grant Type is a way for a single-page JavaScript app to get an access token without an intermediate code exchange step. It was originally created for use by JavaScript apps (which don’t have a way to safely store secrets) but is generally no longer recommended.

This post is the second in a series where we explore frequently used OAuth 2.0 grant types. Previously we covered the Authorization Code grant type. If you want to back up a bit and learn more about OAuth 2.0 before we get started, check out What the Heck is OAuth?, also on the Okta developer blog.

What is an OAuth 2.0 Grant Type?

In OAuth 2.0, the term “grant type” refers to the way an application gets an access token. OAuth 2.0 defines several grant types, including the authorization code flow. OAuth 2.0 extensions can also define new grant types.

Each grant type is optimized for a particular use case, whether that’s a web app, a native app, a device without the ability to launch a web browser, or server-to-server applications.

The Implicit Grant

Like the Authorization Code Grant Type, the Implicit Grant starts out by building a link and directing the user’s browser to that URL. At a high level, the flow has the following steps:

The application opens a browser to send the user to the OAuth server
The user sees the authorization prompt and approves the app’s request
The user is redirected back to the application with an access token in the URL fragment

Get the User’s Permission

OAuth is all about enabling users to grant limited access to applications. The application first needs to decide which permissions it is requesting, then send the user to a browser to get their permission. To begin the Implicit flow, the application constructs a URL like the following and directs the browser to that URL.

https://authorization-server.com/auth
 ?response_type=token
 &client_id=29352910282374239857
 &redirect_uri=https%3A%2F%2Fexample-app.com%2Fcallback
 &scope=create+delete
 &state=xcoiv98y3md22vwsuye3kch

Here’s each query parameter explained:

response_type=token - This tells the authorization server that the application is initiating the Implicit flow. Note the difference from the Authorization Code flow where this value is set to code.
client_id - The public identifier for the application, obtained when the developer first registered the application.
redirect_uri - Tells the authorization server where to send the user back to after they approve the request.
scope - One or more space-separated strings indicating which permissions the application is requesting. The specific OAuth API you’re using will define the scopes that it supports.
state - The application generates a random string and includes it in the request. It should then check that the same value is returned after the user authorizes the app. This is used to prevent CSRF attacks.

When the user visits this URL, the authorization server will present them with a prompt asking if they would like to authorize this application’s request.

Redirect Back to the Application

If the user approves the request, the authorization server will redirect the browser back to the redirect_uri specified by the application, adding a token and state to the fragment part of the URL.

For example, the user will be redirected back to a URL such as

https://example-app.com/redirect
  #access_token=g0ZGZmNj4mOWIjNTk2Pw1Tk4ZTYyZGI3
  &token_type=Bearer
  &expires_in=600
  &state=xcoVv98y2kd44vuqwye3kcq

Note the two major differences between this and the Authorization Code flow: the access token is returned instead of the temporary code, and both values are returned in the URL fragment (after the #) instead of in the query string. By doing this, the server ensures that the app will be able to access the value from the URL, but the browser won’t send the access token in the HTTP request back to the server.

The state value will be the same value that the application initially set in the request. The application is expected to check that the state in the redirect matches the state it originally set. This protects against CSRF and other related attacks.

The server will also indicate the lifetime of the access token before it expires. This is usually a very short amount of time, along the lines of 5 to 10 minutes, because of the additional risk in returning the token in the URL itself.

This token is ready to go! There is no additional step before the app can start using it!

When to use the Implicit Grant Type

In general, there are extremely limited circumstances in which it makes sense to use the Implicit grant type. The Implicit grant type was created for JavaScript apps while trying to also be easier to use than the Authorization Code grant. In practice, any benefit gained from the initial simplicity is lost in the other factors required to make this flow secure. Instead, JavaScript apps should use the Authorization Code grant without the client secret.

The main downside to the Implicit grant type is that the access token is returned in the URL directly, rather than being returned via a trusted back channel like in the Authorization Code flow. The access token itself will be logged in the browser’s history, so most servers issue short-lived access tokens to mitigate the risk of the access token being leaked. Because there is no backchannel, the Implicit flow also does not return a refresh token. In order for the application to get a new access token when the short-lived one expires, the application has to either send the user back through the OAuth flow again, or use tricks such as hidden iframes, adding back complexity that the flow was originally created to avoid.

One of the historical reasons that the Implicit flow used the URL fragment is that browsers could manipulate the fragment part of the URL without triggering a page reload. However, the History API now means that browsers can update the full path and query string of the URL without a page reload, so this is no longer an advantage of the Implicit flow.

The one remaining reason to use the Implicit flow is if the authorization server doesn’t or can’t support cross-origin requests (CORS). The Authorization Code grant requires that the JavaScript app make a POST request to the authorization server, so the authorization server will need to support the appropriate CORS headers in order to allow the browser to make that request. This is a relatively easy change to make if you’re building your own authorization server, but if you are using an existing server then you may be stuck using the Implicit grant to get around the CORS limitation.

For more details and links to additional research and documentation of these limitations, check out the Implicit Grant Type on oauth.net.

The Implicit Grant Type and OpenID Connect

While we haven’t discussed OpenID Connect in this series yet, it’s worth pointing out one important point with regards to how the Implicit grant relates to OpenID Connect. (For some more background on OpenID Connect, see An OpenID Connect Primer also on the Okta Developer blog.)

In OpenID Connect, the server returns an id_token in addition to the access_token in the URL fragment. This is considered an insecure channel to transmit this data, as it can easily be tampered with. Since OpenID Connect ID tokens contain claims such as user identity, this token’s signature must be verified before it can be trusted. Otherwise, the user could change the data in the token and potentially impersonate other users in the JavaScript app. In contrast, when the app uses the Authorization Code grant to obtain the id_token, the token is sent over a secure HTTPS connection which provides a baseline level of security even if the token signature isn’t validated.

Learn More About OAuth and Okta

Try out a live demo of the Implicit grant type on the OAuth Playground

You can learn more about OAuth 2.0 on OAuth.net, or check out any of these resources to get started building!

Or hit up Okta’s OIDC/OAuth 2.0 API for specific information on how we support OAuth. And as always, follow us on Twitter @oktadev for more great content.

WebAuthn: A Developer's Guide to What's on the Horizon

Aaron Parecki — Tue, 17 Apr 2018 05:00:00 +0000

There’s been a lot of news lately about the new W3C Web Authentication API, also known as WebAuthn. Want to know what it’s all about? Let’s take a closer look.

The Web Authentication API allows browsers to make use of hardware authenticators such as the Yubikey or a mobile phone’s biometrics, like a thumbprint reader or facial recognition. WebAuthn can be used with these technologies to enable two-factor authentication to websites, or even as the primary authentication mechanism.

Much of the motivation behind the development of the spec is to reduce reliance on passwords or other authentication methods that are easily phished. The effort began under the FIDO Alliance, and was adopted by the W3C to create the WebAuthn spec as the major browser vendors got on board.

How Does WebAuthn Work?

Under the hood, the WebAuthn spec uses public key cryptography to provide a way for browsers to sign a challenge using a private key stored by the operating system or on a physical hardware token. The private key never leaves the device, and is never made available to the browser. For hardware tokens like the Yubikey, the private key isn’t even accessible to the underlying operating system!

If you already have existing users with an existing authentication mechanism, letting users enroll a WebAuthn credential will work something like this:

Have your users log in using their existing credentials
Create a new WebAuthn credential and associate it with the user account
When the user returns, prompt them for their WebAuthn credential, and once verified, you can sign them in

A unique property of the WebAuthn API is that it can’t be used to identify users between different websites. The credentials generated are tied to the domain of the website that generated them. This provides an additional layer of privacy to users, since websites can’t use the WebAuthn credential to identify users across domains.

The WebAuthn JavaScript API

The WebAuthn spec defines two new JavaScript APIs available to web applications: navigator.credentials.create and navigator.credentials.get.

You’ll use the navigator.credentials.create function to enroll a new authenticator and store the resulting identifier at your server. To set up a new authenticator, you’ll first need to generate 32 random bytes on the server, and provide that to your JavaScript function. These 32 random bytes are part of the data that the authenticator will sign, so it’s important that this be generated by your server so your server knows that the resulting signed challenge was one that it initiated.

When you want to ask the user to log back in with an existing credential, you can use the navigator.credentials.get function to request that the user prove the possession of an existing enrolled device. If they’ve registered multiple devices, you can pass multiple identifiers to the function and the matching one will be returned.

When the site runs the navigator.credentials.create function, all available USB keys or other authentication mechanisms will wait for the user to interact with them. In the case of Yubikeys, you’ll see the blinking light on all of them that are currently plugged in. If you specify an existing identifier to the navigator.credentials.get function, then only that one key will blink.

See Mozilla’s Using Hardware Token-based 2FA with the WebAuthn API guide for more details on the JavaScript code necessary to make this work.

When Can I Use WebAuthn?

As of April 2018, the WebAuthn API is available in Firefox Nightly, and can be turned on in Chrome by enabling a setting in chrome://flags. Apple has not yet commented on whether or when WebAuthn will be available in Safari. They were involved with the development of the spec, though, so they will likely be shipping it soon.

The spec itself is currently a W3C “Candidate Recommendation”, which is the second to last step before it’s finalized as a “Recommendation.”

Learn More About WebAuthn

What is the OAuth 2.0 Authorization Code Grant Type?

Aaron Parecki — Tue, 10 Apr 2018 05:00:00 +0000

The Authorization Code Grant Type is probably the most common of the OAuth 2.0 grant types that you’ll encounter. It is used by both web apps and native apps to get an access token after a user authorizes an app.

This post is the first part of a series where we explore frequently used OAuth 2.0 grant types. If you want to back up a bit and learn more about OAuth 2.0 before we dive in, check out What the Heck is OAuth?, also on the Okta developer blog.

What is an OAuth 2.0 Grant Type?

Each grant type is optimized for a particular use case, whether that’s a web app, a native app, a device without the ability to launch a web browser, or server-to-server applications.

The Authorization Code Flow

The Authorization Code grant type is used by web and mobile apps. It differs from most of the other grant types by first requiring the app launch a browser to begin the flow. At a high level, the flow has the following steps:

The application opens a browser to send the user to the OAuth server
The user sees the authorization prompt and approves the app’s request
The user is redirected back to the application with an authorization code in the query string
The application exchanges the authorization code for an access token

Get the User’s Permission

OAuth is all about enabling users to grant limited access to applications. The application first needs to decide which permissions it is requesting, then send the user to a browser to get their permission. To begin the authorization flow, the application constructs a URL like the following and opens a browser to that URL.

https://authorization-server.com/auth
 ?response_type=code
 &client_id=29352915982374239857
 &redirect_uri=https%3A%2F%2Fexample-app.com%2Fcallback
 &scope=create+delete
 &state=xcoiv98y2kd22vusuye3kch

Here’s each query parameter explained:

response_type=code - This tells the authorization server that the application is initiating the authorization code flow.
client_id - The public identifier for the application, obtained when the developer first registered the application.
redirect_uri - Tells the authorization server where to send the user back to after they approve the request.
scope - One or more space-separated strings indicating which permissions the application is requesting. The specific OAuth API you’re using will define the scopes that it supports.
state - The application generates a random string and includes it in the request. It should then check that the same value is returned after the user authorizes the app. This is used to prevent CSRF attacks.

When the user visits this URL, the authorization server will present them with a prompt asking if they would like to authorize this application’s request.

Redirect Back to the Application

If the user approves the request, the authorization server will redirect the browser back to the redirect_uri specified by the application, adding a code and state to the query string.

For example, the user will be redirected back to a URL such as

https://example-app.com/redirect
 ?code=g0ZGZmNjVmOWIjNTk2NTk4ZTYyZGI3
 &state=xcoiv98y2kd22vusuye3kch

The state value will be the same value that the application initially set in the request. The application is expected to check that the state in the redirect matches the state it originally set. This protects against CSRF and other related attacks.

The code is the authorization code generated by the authorization server. This code is relatively short-lived, typically lasting between 1 to 10 minutes depending on the OAuth service.

Exchange the Authorization Code for an Access Token

We’re about ready to wrap up the flow. Now that the application has the authorization code, it can use that to get an access token.

The application makes a POST request to the service’s token endpoint with the following parameters:

grant_type=authorization_code - This tells the token endpoint that the application is using the Authorization Code grant type.
code - The application includes the authorization code it was given in the redirect.
redirect_uri - The same redirect URI that was used when requesting the code. Some APIs don’t require this parameter, so you’ll need to double check the documentation of the particular API you’re accessing.
client_id - The application’s client ID.
client_secret - The application’s client secret. This ensures that the request to get the access token is made only from the application, and not from a potential attacker that may have intercepted the authorization code.

The token endpoint will verify all the parameters in the request, ensuring the code hasn’t expired and that the client ID and secret match. If everything checks out, it will generate an access token and return it in the response!

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
  "token_type":"bearer",
  "expires_in":3600,
  "refresh_token":"IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk",
  "scope":"create delete"
}

The Authorization Code flow is complete! The application now has an access token it can use when making API requests.

When to use the Authorization Code Flow

The Authorization Code flow is best used in web and mobile apps. Since the Authorization Code grant has the extra step of exchanging the authorization code for the access token, it provides an additional layer of security not present in the Implicit grant type.

If you’re using the Authorization Code flow in a mobile app, or any other type of application that can’t store a client secret, then you should also use the PKCE extension, which provides protections against other attacks where the authorization code may be intercepted.

The code exchange step ensures that an attacker isn’t able to intercept the access token, since the access token is always sent via a secure backchannel between the application and the OAuth server.

Learn More About OAuth and Okta

You can learn more about OAuth 2.0 on OAuth.com, or check out any of these resources to get started building!

Get Started with Spring Boot, OAuth 2.0, and Okta
Token Authentication in ASP.NET Core 2.0 - A Complete Guide
Secure your SPA with Spring Boot and OAuthOr hit up Okta’s OIDC/OAuth 2.0 API for specific information on how we support OAuth. And as always, follow us on Twitter @oktadev for more great content.

Forem: Aaron Parecki

How to export your complete Foursquare checkin history

Is the OAuth 2.0 Implicit Flow Dead?

The Best Practice Around Implicit in OAuth 2.0 is Changing

The OAuth Authorization Code Flow is Better

The OAuth 2.0 Implicit Flow for Existing Apps

Does the Authorization Code Flow Make Browser-Based Apps Totally Secure?

Start Using the Implicit Flow with PKCE in JavaScript Today

Set Up the HTML Structure

Begin the PKCE Request

Get an Access Token using the Authorization Code

Learn More about OAuth 2.0, the Implicit Flow, and Secure Authentication

Use nginx to Add Authentication to Any Application

Why Authenticate at the Web Server?

Using the nginx auth_request Module

Choosing an Auth Proxy

Configure Your Protected nginx Host

Configure a Server Block for Lasso

Configure and Deploy Lasso

Bonus: Who Logged In?

Learn More About OAuth 2.0 and Secure User Management with Okta

OAuth 2.0 from the Command Line

Get Started with Okta

The Trick to OAuth 2.0 on the Command Line

Start the OAuth 2.0 Flow

Handle the Authorization Response

Learn More About OAuth 2.0 and Secure User Management with Okta

Add Authentication to your PHP App in 5 Minutes

Set Up the Sample PHP App

Create an OAuth Application in Okta

Build the Login URL

Handle the OAuth Redirect

Further Reading

What is the OAuth 2.0 Implicit Grant Type?

What is an OAuth 2.0 Grant Type?

The Implicit Grant

Get the User’s Permission

Redirect Back to the Application

When to use the Implicit Grant Type

The Implicit Grant Type and OpenID Connect

Learn More About OAuth and Okta

WebAuthn: A Developer's Guide to What's on the Horizon

How Does WebAuthn Work?

The WebAuthn JavaScript API

When Can I Use WebAuthn?

Learn More About WebAuthn

What is the OAuth 2.0 Authorization Code Grant Type?

What is an OAuth 2.0 Grant Type?

The Authorization Code Flow

Get the User’s Permission

Redirect Back to the Application

Exchange the Authorization Code for an Access Token

When to use the Authorization Code Flow

Learn More About OAuth and Okta