Last updated Dec 6, 2021

Rate this page:

Use an external OAuth 2.0 API with fetch

This tutorial explores how to call an external OAuth 2.0 API using the Forge fetch function with authentication handled by the Forge platform. As shown in the example below, this tutorial returns user profile data from a Google account in a Confluence code block.

If you're not familiar with the Forge security model, the security concept page explains the foundations this tutorial builds on top of.

Screenshot

  1. Showing the user profile data from the Google API response.

Before you begin

You'll need to set up your Forge development environment and a development site. See Getting started for step-by-step instructions on setting up Forge.

This guide assumes you already have a Confluence macro app. If not, follow part 1 of the Build a Confluence hello world app guide to build from.

Google console setup

To use external authentication with Google, you'll need an OAuth 2.0 client ID and client secret from the Google console in Google's cloud platform.

  1. Create a project in Google cloud platform.
  2. Go to the Credentials section to create a new client ID.
  3. Click Create credentials at the top, and select OAuth client ID.
  4. Select Web application as the application type.
  5. Set the authorized redirect URI as https://id.atlassian.com/outboundAuth/finish.
  6. Select Create.
  7. Copy the newly created client ID and client secret. You'll need them when defining the provider and deploying the app later.

    Google console

Define the provider

  1. In the manifest.yml file, add a providers section with the following structure:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    providers:
      auth:
        - key: google
          name: Google
          scopes:
            - 'profile'
            - 'https://www.googleapis.com/auth/userinfo.email'
          type: oauth2
          clientId: PLACEHOLDER
          remotes:
            - google-apis
          bearerMethod: authorization-header
          actions:
            authorization:
              remote: google-account
              path: /o/oauth2/v2/auth
            exchange:
              remote: google-oauth
              path: /token
            revokeToken:
              remote: google-oauth
              path: /revoke
            retrieveProfile:
              remote: google-apis
              path: /userinfo/v2/me
              resolvers:
                id: id
                displayName: email
                avatarUrl: picture
  2. Replace PLACEHOLDER with the client ID that you copied, following the instructions in Google console setup.

  3. In the manifest.yml file, add remotes and permissions sections.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    remotes:
      - key: google-apis
        baseUrl: https://www.googleapis.com
      - key: google-account
        baseUrl: https://accounts.google.com
      - key: google-oauth
        baseUrl: https://oauth2.googleapis.com
    permissions:
      external:
        fetch:
          backend:
            - 'https://www.googleapis.com'
            - 'https://oauth2.googleapis.com'
            - 'https://accounts.google.com'
  4. Add a reference to the new provider in the function definition.

    1
    2
    3
    4
    5
    6
    function:
      - key: main
        handler: index.run
        providers:
          auth:
            - google

Calling an API

With a provider defined, use the runtime API to call Google's API and show the profile information of the user in a code block.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
import ForgeUI, { render, Code, Macro, useState } from '@forge/ui';
import api from '@forge/api';

const App = () => {
  const [data] = useState(async () => {
    const google = api.asUser().withProvider('google', 'google-apis')
    if (!await google.hasCredentials()) {
      await google.requestCredentials()
    }
    const response = await google.fetch('/userinfo/v2/me');
    if (response.ok) {
      return response.json()
    }
    return {
      status: response.status,
      statusText: response.statusText,
      text: await response.text(),
    }
  })

  return (
    <Code text={JSON.stringify(data, null, 2)} language="json" showLineNumbers />
  )
}

export const run = render(
  <Macro
    app={<App />}
  />
);

Deploy the app

  1. Navigate to the app's top-level directory and deploy your app by running:

    1
    forge deploy
  2. Set the client secret by running:

    1
    forge providers configure google
  3. Replace the client secret value with the client secret that you copied, following the instructions in Google console setup.

  4. Depending on whether or not you've installed the application, do one of the following:

    • Run forge install to install your macro onto Confluence.
    • Run forge install --upgrade to upgrade your app to the new version.

When deploying your application to production, you will need to also set the secret in production. To do this use forge providers configure -e production after deployment.

Next steps

Links below contain additional detail that you may be interested in as you develop a Forge app using external authentication.

Rate this page: