Working OAuth pre-flight script

[charles-hill-work]

Here's my solution to managing OAuth tokens in Apollo Studio using Device Authorization Flow.

How it works

1. If env vars already have a non-expired token, nothing to do
2. Get the OAuth arguments from the env vars
3. Begin the Device Authorization Flow
4. Ask the user to go to the url provided by Device Authorization Flow and approve it
5. The user then clicks Submit in the prompt (limitation of Studio)
6. Poll to fetch the approved token and save it in env vars

Limitations

• This OAuth flow wasn't really intended for this scenario, but it prevents the user from using copy & paste in the token, which is often left on the clipboard
• Not all OAuth providers support Device Authorization Flow
• The token is still stored in the env vars, and accessible to the user
• It does not use refresh tokens, thus re-prompting for approval when the token expires. Support for this could be added
• The only user interaction that pre-flight scripts can do is via prompt(). So:
  • the user needs to ignore the input field
  • it's just a blob of text, there is no formatting
  • the user needs to highlight url, right-click, then "open in new tab" (or copy & paste)

Connection settings - Headers
Authorization = Bearer {{token}}

Environment Variables needed

{
  "auth_domain": "",
  "auth_client_id": "",
  "auth_audience": "",
  "auth_scope": ""
}

Pre-flight Script

const domain = explorer.environment.get('auth_domain');
const audience = explorer.environment.get('auth_audience');
const clientId = explorer.environment.get('auth_client_id');
const scope = explorer.environment.get('auth_scope');
const skipWarning = explorer.environment.get('auth_skip_warning');
const currentToken = explorer.environment.get('token');
const currentTokenExpiresAt = explorer.environment.get('token_expires_at');

if (
  !!currentToken &&
  typeof currentToken === 'string' &&
  typeof currentTokenExpiresAt === 'number' &&
  new Date().getTime() < currentTokenExpiresAt
) {
  // We have a non-expired token.  Nothing to do here
  return;
}

if (!domain || !clientId || !scope || !audience) {
  if(!skipWarning) {
    // Using NBSP between the icon and text
    // https://unicode-table.com/en/00A0/
    const resWarn = await explorer.prompt(`
**Missing environment variable**

* ${!!domain   ? '✅' : '❌'}   auth_domain
* ${!!audience ? '✅' : '❌'}   auth_audience
* ${!!clientId ? '✅' : '❌'}   auth_client_id
* ${!!scope    ? '✅' : '❌'}   auth_scope


If you are intentionally executing without authentication, click **submit** to continue.  Otherwise, click **Close** and provide the missing variables before retrying.
`);

    if(resWarn === null) {
      // user clicked Close
      return;
    } else {
      explorer.environment.set('auth_skip_warning', true);
    }
  }
}

const codeRes = await explorer.fetch(`https://${domain}/oauth/device/code`, {
  method: 'POST',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  body: encodeForm({
    client_id: clientId,
    audience,
    scope,
  }),
});

if (codeRes.code < 200 || codeRes.code > 299) {
  console.error(codeRes);
  return;
}

const code = codeRes.json();
// window.open(code.verification_uri_complete, '_blank');
const resApprove = await explorer.prompt(`
**Please read the full instructions before clicking the link.**
Clicking **Close** will cancel this operation.

-----

1. Go to [${domain}](${code.verification_uri_complete})
2. Authorize the code \`${code.user_code}\`
3. Close the authorization tab/window and return here
4. Click **submit** below (ignoring the value field)
`
);

if(resApprove === null) {
  // user clicked Close
  return;
}

let tokens = {};
const timeout = new Date().getTime() + 60000;
do {
  if (
    tokens.error === 'authorization_pending' &&
    typeof code.interval === 'number'
  ) {
    await sleep(code.interval * 1000);
  }

  const grantType = 'urn:ietf:params:oauth:grant-type:device_code';
  const tokensRes = await explorer.fetch(`https://${domain}/oauth/token`, {
    method: 'POST',
    headers: { 'content-type': 'application/x-www-form-urlencoded' },
    body: encodeForm({
      client_id: clientId,
      device_code: code.device_code,
      grant_type: grantType,
    }),
  });

  if (tokensRes.code < 200 || tokensRes.code > 299) {
    console.error(tokensRes);
    return;
  }

  tokens = tokensRes.json();
} while (
  tokens.error === 'authorization_pending' &&
  new Date().getTime() < timeout
);

if (tokens.error) {
  console.error(tokens);
  return;
}

if (
  typeof tokens.access_token !== 'string' ||
  !tokens.access_token ||
  tokens.token_type !== 'Bearer' ||
  typeof tokens.expires_in !== 'number'
) {
  // It's not an error, but not the expecgted format.  Don't log the data, it may contain a secret.
  console.error('Invalid token response.');
  return;
}

// Subtract a few seconds for proactive re-auth
const expiresIn =
  tokens.expires_in >= 300 ? tokens.expires_in - 15 : tokens.expires_in;
const expiresAt = new Date().getTime() + expiresIn * 1000;
explorer.environment.set('token', tokens.access_token);
explorer.environment.set('token_expires_at', expiresAt);

function encodeForm(data) {
  const parts = [];
  for (const [key, value] of Object.entries(data)) {
    parts.push(encodeURIComponent(key) + '=' + encodeURIComponent(value));
  }
  return parts.join('&');
}
function sleep(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

Edited to include markdown formatted prompts (warnings and authorization)

[charles-hill-work]

One thing that would help overcome the limitations of the prompt() just showing a blob of text, would be to support markdown. And possible add a few alternative inputs like confirm() (yes / no) and alert() (ok only).

[cheapsteak]

Thanks for the in-depth walkthrough!

Those all sound very reasonable and doable

Do you have some sample dummy input for markdown that would go in the prompt?

[cheapsteak]

markdown in prompt() is on it's way to release!

[charles-hill-work]

1. Go to [auth.sample.com](https://auth.sample.com/activate?user_code=ABC-123)
2. Authorize the code ABC-123 (and close the tab/window)
3. Click **submit** below (value doesn't matter)

Clicking **Close** will cancel this operation.

The link should open is a new window

[charles-hill-work]

Markdown works very well. Thanks! I've updated the working sample in the original post.

[charles-hill-work]

For those following this, I've edited the script to better handle missing environment variables, user cancelation (Close button), and markdown formatting.