{"id":10135,"date":"2016-09-08T02:39:29","date_gmt":"2016-09-07T17:39:29","guid":{"rendered":"https:\/\/jirak.net\/wp\/authenticating-users-to-existing-applications-with-openid-connect-and-nginx-plus\/"},"modified":"2016-09-08T03:34:50","modified_gmt":"2016-09-07T18:34:50","slug":"authenticating-users-to-existing-applications-with-openid-connect-and-nginx-plus","status":"publish","type":"post","link":"https:\/\/jirak.net\/wp\/authenticating-users-to-existing-applications-with-openid-connect-and-nginx-plus\/","title":{"rendered":"Authenticating Users to Existing Applications with OpenID\u00a0Connect and NGINX\u00a0Plus"},"content":{"rendered":"

Authenticating Users to Existing Applications with OpenID\u00a0Connect and NGINX\u00a0Plus
\n<\/p>\n

Using JWT support to provide SSO for existing applications<\/em><\/h3>\n

OAuth 2.0 has done much to transform the flexibility and user experience of authenticating to websites and applications. But despite the name, the OAuth 2.0 specification<\/a> says very little about verifying end‑user identity and nothing about single sign‑on (SSO). That\u2019s where OpenID Connect<\/a> comes in – it is essentially the missing piece that carries identity information in OAuth 2.0 access tokens.<\/p>\n

OpenID Connect identity tokens comply with the JSON Web Token (JWT) specification<\/a>. JWT (pronounced \u201cjot\u201d) tokens are compact, easy to pass around, and provide a common core schema for describing identity information. The great thing about JWTs is that they can be applied to almost any identity use case, from authenticating API clients to providing SSO for enterprise applications. In fact, many organizations that use Google Apps can utilize Google as the identity provider to provide SSO to their enterprise applications<\/a>. That said, the use of OpenID Connect and JWTs does not prevent them being used to authenticate to, or provide SSO for, existing web applications.<\/p>\n

NGINX Plus R10 and later includes native JWT support, enabling NGINX Plus to validate tokens and decorate upstream requests with the identity of the authenticated user in a way that the application can easily consume. In this blog post we demonstrate how to use the native JWT support in NGINX Plus to enable SSO for existing applications without any changes required to the applications themselves. We’re using Google as the identity provider and a simple website to represent the application. The end‑to‑end flow looks like this:<\/p>\n

\"Diagram
NGINX Plus validates user identity using OAuth 2.0 and OpenID Connect with Google<\/figcaption><\/figure>\n

Enabling OpenID Connect for Your Web Application<\/h2>\n

Our example has two components: the NGINX Plus configuration and the HTML login page.<\/p>\n

NGINX Plus Configuration<\/h3>\n

The NGINX Plus configuration for validating JWTs is very simple.<\/p>\n

server {
\n    listen 80;
\n    root \/var\/www\/public_html;<\/p>\n
    location \/private\/ {
\n        auth_jwt \"Google account\" token=$cookie_auth_token;
\n        auth_jwt_key_file \/etc\/nginx\/google_certs.jwk;
\n    }
\n}<\/pre>\n
<\/code><\/p>\n
The location<\/code> block specifies that any requests to URLs beginning with \/private\/<\/strong> must be authenticated. The auth_jwt<\/code><\/a> directive defines the authentication realm that will be returned (along with a 401<\/code>) if authentication is unsuccessful, and where in the request NGINX Plus can find the JWT. In this case it expects to find the token in a cookie named auth_token<\/strong>. By default, NGINX Plus expects clients to present the JWT as a Bearer Token<\/em><\/a>, using the Authorization<\/code> header as is common with AJAX applications and API clients<\/a>, but it can also obtain the JWT from other HTTP headers, query string arguments, or a cookie as in this example.<\/p>\n
The auth_jwt_key_file<\/code><\/a> directive tells NGINX how to validate the signature element of the JWT. Signature validation ensures that the JWT was issued by Google and has not been modified since. Google publishes its public keys<\/a> and refreshes them regularly. To maintain an up‑to‑date set of keys, use cron(8)<\/code> to fetch them hourly, as in this sample crontab<\/code> entry.<\/p>\n
0 * * * * wget https:\/\/www.googleapis.com\/oauth2\/v3\/certs -O \/etc\/nginx\/google_certs.jwk<\/pre>\n
<\/code><\/p>\n
HTML-Based Login Page<\/h3>\n
To keep this example simple and straightforward, we aren’t building an entire application. Instead we’re using the following basic HTML to create a login page. The HTML file is called \/var\/www\/public_html\/index.html<\/strong> (this matches the root<\/code> path we defined in the NGINX Plus configuration).<\/p>\n
<html>
\n<head>
\n    <meta http-equiv=\"cache-control\" content=\"no-cache\" \/>
\n    <meta http-equiv=\"expires\" content=\"0\" \/>
\n    <title>NGINX OpenID Connect demo<\/title>
\n    <script src=\"https:\/\/apis.google.com\/js\/platform.js\" async defer><\/script>
\n    <meta name=\"google-signin-scope\" content=\"profile email\">
\n    <meta name=\"google-signin-client_id\"
\n          content=\"client-ID<\/em>.apps.googleusercontent.com<\/strong><\/span>\">
\n    <script src=\"https\/\/tools.ietf.org\/js.cookie.js\"><\/script><\/strong><\/span>
\n<\/head>
\n<body>
\n    <h2>NGINX OpenID Connect demo<\/h2>
\n    <hr\/>
\n    <h3>Login with a Google account then visit the <a href=\"\/private\/\">private area<\/a>.<\/h3>
\n    <table><tr><td>
\n    <div class=\"g-signin2\" data-onsuccess=\"onSignIn\" data-theme=\"dark\"><\/div><\/td>
\n    <script>
\n      function onSignIn(googleUser) {
\n        var profile = googleUser.getBasicProfile();
\n        Cookies.set('auth_token', googleUser.getAuthResponse().id_token);
\n        document.getElementById('google_signout').innerHTML = '<a href=\"#\" onclick=\"signOut();\"><img src=\"' + profile.getImageUrl() + '\" width=32 height=32>Sign out<\/a>';
\n      };
\n      function signOut() {
\n        var auth2 = gapi.auth2.getAuthInstance();
\n        auth2.signOut().then(function () {
\n          Cookies.remove('auth_token');
\n          document.getElementById('google_signout').innerHTML = '';
\n        });
\n      }
\n    <\/script>
\n    <td><div id=\"google_signout\"><\/div><\/td>
\n    <\/tr><\/table>
\n    <hr\/>
\n<\/body>
\n<\/html><\/pre>\n
<\/code><\/p>\n
We’ve highlighted two key dependencies in the <head><\/code> block. <\/p>\n