WIP

Author: waldyrious

rest-api/javascript/authentication/web-application-flow/.env.example

@@ -1,5 +1,5 @@
 # Base Url endpoint
-BASE_URL='https://api-sandbox.uphold.com'
+BASE_URL = 'https://api-sandbox.uphold.com'
 
 CLIENT_ID = ''
 CLIENT_SECRET = ''

rest-api/javascript/authentication/web-application-flow/.gitignore

@@ -0,0 +1,2 @@
+.env
+node_modules/

rest-api/javascript/authentication/web-application-flow/README.md

@@ -1,21 +1,41 @@
-# Client credentials web-flow
+# Authorization code flow
 
-This sample project demonstrates how to authenticate in the Uphold API using the client credentials web flow. For further background, please refer to the [API documentation](https://uphold.com/en/developer/api/documentation)
+This sample project demonstrates how a registered app can request authorization from Uphold users to perform actions on their behalf, by using the [authorization code OAuth flow](https://oauth.net/2/grant-types/authorization-code/). For further background, please refer to the [API documentation](https://uphold.com/en/developer/api/documentation).
 
 ## Summary
-**Ideal for web applications** that wish to retrieve information about a user’s Uphold account or take actions on their behalf.
-This example tries to mimic the WEB-FLOW cycle. It creates a simple webserver and tries to run the entire cycle of authenticating against UPHOLD servers and return the token to this web server.
 
-    ```
-    https://sandbox.uphold.com/authorize/PUT_HERE_YOUR_CLIENT_ID?scope=user:read&state=PUT_A_CODE_HERE_TO_IDENTIFY_THE_REQUEST
-    ```
+This flow is **recommended for web applications** that wish to retrieve information about a user's Uphold account, or take actions on their behalf.
+
+This process, sometimes called "3-legged OAuth", requires three steps, each initiated by one of the three actors:
+
+1. The **user** navigates to a particular URL in the Uphold website, where they log in and authorize the app identified in the URL;
+2. **Uphold**'s server sends a short-lived authorization code to the app's server;
+3. The **application**'s server submits this code to Uphold to exchange it for a long-lived access token.
+
+This example sets up a local server that can be used to perform the OAuth web application flow cycle as described above.
 
 ## Requirements
-- `node` v13.14.0 +
+
+To run this example, you must have:
+
+- Node.js v13.14.0 or later
+- An account at <https://sandbox.uphold.com>
 
 ## Setup
-- run `npm install` (or `yarn install`)
-- create a `.env` file based on the `.env.example` file, and populate it with the required data
+
+- Run `npm install` (or `yarn install`)
+- [Create an app on Uphold Sandbox](https://sandbox.uphold.com/dashboard/profile/applications/developer/new)
+  with the redirect URI field set to `https://localhost:3000/callback` (you may use a different port number, if you prefer).
+  Note that this demo expects at least the `user:read` scope to be activated.
+- Create a `.env` file based on the `.env.example` file, and populate it with the required data.
+  Make sure to also update the `SERVER_PORT` if you changed it in the previous step.
 
 ## Run
-- run `node index.js`
+
+- Run `node index.js`
+- Open the URL printed in the command line.
+  - **Attention:** Since the certificate used in this demo is self-signed, not all browsers will allow navigating to the page. You can use Firefox or Safari, which will display a warning but allow you to proceed regardless. Alternatively, you can navigate to `chrome://flags/#allow-insecure-localhost` in Chromium-based browsers to toggle support for self-signed localhost certificates.
+- Click the link in the page to navigate to Uphold's servers.
+- Accept the application's permission request.
+
+Once the authorization is complete and an access token is obtained, the local server will use it to make a test request to the Uphold API. The output will be printed in the command line.

rest-api/javascript/authentication/web-application-flow/authorization-code-flow.js

@@ -0,0 +1,90 @@
+/**
+ * Dependencies.
+ */
+
+import axios from "axios";
+import b64Pkg from "js-base64";
+import dotenv from "dotenv";
+import qs from "qs";
+import path from "path";
+
+const { encode } = b64Pkg;
+
+/**
+ * Dotenv configuration.
+ */
+
+ dotenv.config({ path: path.resolve() + "/.env" });
+
+/**
+ * Compose error page.
+ */
+
+export function composeErrorPage(data, state) {
+  let content = "<h1>Something went wrong.</h1>";
+
+  if (data.state && data.state !== state) {
+    content +=
+      `<p>The received state (<code>${data.state}</code>)
+      does not match the expected value: <code>${state}</code>.</p>`;
+  } else if (Object.values(data).length) {
+    content += "<p>Here's what Uphold's servers returned:</p>";
+    content += `<pre>${JSON.stringify(data, null, 4)}</pre>`;
+  } else {
+    content += "<p>This page should be reached at the end of an OAuth authorization process.</p>";
+    content += "<p>Please confirm that you followed the steps in the README.</p>";
+  }
+
+  return content;
+}
+
+/**
+ * Get assets.
+ */
+
+export async function getAssets(token) {
+  try {
+    const response = await axios.get(`${process.env.BASE_URL}/v0/assets`, {
+      headers: {
+        Authorization: `${token.token_type} ${token.access_token}`,
+      },
+    });
+    return response.data;
+  } catch (error) {
+    console.log(JSON.stringify(error, null, 2));
+    throw error;
+  }
+}
+
+/**
+ * Get Token.
+ */
+
+export async function getToken(code) {
+  // Base64-encoded authentication credentials
+  const auth = encode(process.env.CLIENT_ID + ":" + process.env.CLIENT_SECRET);
+
+  // set POST options for Axios
+  const options = {
+    method: "POST",
+    headers: {
+      Authorization: "Basic " + auth,
+      "content-type": "application/x-www-form-urlencoded",
+    },
+    data: qs.stringify({ code, grant_type: "client_credentials" }),
+    url: `${process.env.BASE_URL}/oauth2/token`,
+  };
+
+  const data = axios(options)
+    .then((response) => {
+      return response.data;
+    })
+    .catch((error) => {
+      error.response.data.errors
+        ? console.log(JSON.stringify(error.response.data.errors, null, 2))
+        : console.log(JSON.stringify(error, null, 2));
+      throw error;
+    });
+
+  return data;
+}

rest-api/javascript/authentication/web-application-flow/index.js

@@ -1,110 +1,81 @@
 /**
  * Dependencies.
  */
-import axios from "axios";
-import b64Pkg from "js-base64";
+
 import dotenv from "dotenv";
 import express from "express";
 import fs from "fs";
 import https from "https";
-import qs from "qs";
 import path from "path";
+import { randomBytes } from "crypto";
+import { composeErrorPage, getAssets, getToken } from "./authorization-code-flow.js";
 
-const { encode } = b64Pkg;
-dotenv.config({ path: path.resolve() + "/.env" });
+/**
+ * Dotenv configuration.
+ */
 
-// For testing purposes point your browser to the fallowing URL
-// https://sandbox.uphold.com/authorize/PUT_HERE_YOUR_CLIENT_ID?scope=user:read&state=PUT_A_CODE_STATE_HERE
+dotenv.config({ path: path.resolve() + "/.env" });
 
 /**
- * Get assets.
+ * Server configuration.
  */
-async function getAssets(token) {
-  try {
-    const r = await axios.get(`${process.env.BASE_URL}/v0/assets`, {
-      headers: {
-        Authorization: `${token.token_type} ${token.access_token}`,
-      },
-    });
-    return r.data;
-  } catch (error) {
-    console.log(JSON.stringify(error, null, 2));
-    throw error;
-  }
-}
+
+const app = express();
+const port = process.env.SERVER_PORT || 3000;
+const state = randomBytes(8).toString('hex');
 
 /**
- * Get Token.
+ * Main page.
  */
-async function getToken(code) {
-  // auth encoded with client ID and Client Secret
-  // set post options for axios
-
-  const auth = encode(process.env.CLIENT_ID + ":" + process.env.CLIENT_SECRET);
-  const url = `${process.env.BASE_URL}/oauth2/token`;
-
-  const options = {
-    method: "POST",
-    headers: {
-      Authorization: "Basic " + auth,
-      "content-type": "application/x-www-form-urlencoded",
-    },
-    data: qs.stringify({ code, grant_type: "client_credentials" }),
-    url,
-  };
-
-  const data = axios(options)
-    .then((response) => {
-      return response.data;
-    })
-    .catch((error) => {
-      error.response.data.errors
-        ? console.log(JSON.stringify(error.response.data.errors, null, 2))
-        : console.log(JSON.stringify(error, null, 2));
-      throw error;
-    });
-
-  return data;
-}
 
-const app = express();
-const hostname = "localhost";
-const port = process.env.USERNAME || 3000;
+app.get("/", async (req, res) => {
+  // Compose the authorization URL. This assumes the `user:read` scope has been activated for this application.
+  const authorizationUrl = 'https://sandbox.uphold.com/authorize/'
+    + process.env.CLIENT_ID
+    + '?scope=user:read'
+    + '&state=' + state;
+
+  res.send(
+    `<h1>Demo app server</h1>
+    <p>Please <a href="${authorizationUrl}">authorize this app</a> on Uphold's Sandbox.</p>`
+  );
+});
+
 
 /**
- * Callback url endpoint.
+ * Callback URL endpoint.
  */
 
 app.get("/callback", async (req, res) => {
-  // Do we have a code?
-  // WARNING!!!!! The code only works for 5 minutes
-  if (req.query.code) {
-    console.log(`code ${req.query.code}`);
-
-    const token = await getToken(req.query.code);
-    const assets = await getAssets(token);
-
-    console.log(token);
-    console.log(assets);
-    res.send("All done !");
-  } else {
-    res.send(`Oops, something went wrong... did you pass the STATE?`);
+  // Show an error page if the code wasn't returned or the state doesn't match what we sent.
+  if (!req.query.code || req.query.state !== state) {
+    res.send(composeErrorPage(req.query, state));
   }
+
+  // Exchange the short-lived authorization code for a long-lived access token.
+  const token = await getToken(req.query.code);
+  console.log(`Authorization code ${req.query.code} successfully exchanged for access token:`, token);
+
+  // Test the new token by making a call to the API.
+  const assets = await getAssets(token);
+  console.log("Output from test API call:", assets[0]);
+
+  res.send(
+    `<h1>Success!</h1>
+    <p>The OAuth authorization code has been successfully exchanged for an access token.</p>`
+  );
 });
 
 /**
  * Run server.
  */
 
 https
-  .createServer(
-    {
-      key: fs.readFileSync("./key.pem"),
-      cert: fs.readFileSync("./cert.pem"),
-      passphrase: "test",
-    },
-    app
-  )
+  .createServer({
+    key: fs.readFileSync("./key.pem"),
+    cert: fs.readFileSync("./cert.pem"),
+    passphrase: "test",
+  }, app)
   .listen(port, () => {
-    console.log(`Serving running at https://${hostname}:${port}/`);
+    console.log(`Server running at https://localhost:${port}`);
   });