External authentication

The withProvider method enables your Forge app to communicate with an API that requires OAuth 2.0 tokens. Access is via the asUser method, in the @forge/api package.

1
2
import api from '@forge/api';

const response = await api.asUser()
      .withProvider('google', 'google-apis')
      .fetch('/userinfo/v2/me');

fetch

Before using fetch for authenticated requests, ensure the user is valid with hasCredentials or requestCredentials. If the user is not authenticated, an exception is raised.

Once a user is authenticated, the fetch method automatically includes their authentication token for each request.

Apps using external authentication must define the external domains in the remotes section of the manifest file. See Remotes.

1
2
fetch(url[, options])

Name Type Required Description

url

string

Yes

Relative path from the remote specified in withProvider.

If the url parameter starts with a /, the remote baseUrl path is ignored.

Remote `baseUrl`	Fetch `url`	Result
https://example.atlassian.com/api/v1/	/api/v1/endpoint	https://example.atlassian.com/api/v1/endpoint
https://example.atlassian.com/api/v1/	endpoint	https://example.atlassian.com/api/v1/endpoint
https://example.atlassian.com/api/v1/	/endpoint	https://example.atlassian.com/endpoint

options

object

See the node-fetch library’s Options documentation for the accepted values.

hasCredentials

Determines if the user is authenticated.

Method signature

1
2
api.asUser().withProvider(provider).hasCredentials() => Promise<boolean>

Example usage

1
2
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');
  ...
})

requestCredentials

Triggers the OAuth 2.0 consent flow. The app is replaced with a button for the user to select to start the flow.

1
2
api.asUser().withProvider(provider).requestCredentials()

Example usage

1
2
if (!await api.asUser().withProvider(provider).hasCredentials()) {
  await api.asUser().withProvider(provider).requestCredentials()
}

AuthProfile

The return value of a dynamic profile retriever should be an AuthProfile object. See the dynamic profile retriever guide for more information.

The file containing a dynamic profile retriever cannot import @forge/ui, because when executed, the dynamic profile retriever is run in a different context outside of the UI.

1
2
AuthProfile({id, displayName, avatarUrl})

Property Type Required Description

Property	Type	Required	Description
`id`	`string`	Yes	Used to de-duplicate accounts and add new accounts. Must be a unique string per account.
`displayName`	`string`	Yes	Account name displayed to the user for the purpose of distinguishing between multiple accounts. Should be one of email, username, or some other unique identifier that the user would recognize. This should NOT be a name value, as that may be the same across multiple accounts.
`avatarUrl`	`string`		URL providing the avatar picture.

id

string

Yes

Used to de-duplicate accounts and add new accounts. Must be a unique string per account.

displayName

string

Yes

Account name displayed to the user for the purpose of distinguishing between multiple accounts.

Should be one of email, username, or some other unique identifier that the user would recognize.

This should NOT be a name value, as that may be the same across multiple accounts.

avatarUrl

string

URL providing the avatar picture.

Example usage

1
2
interface ProfileRetrieverParameters {
  status: number;
  body: {
    [key: string]: any;
  };
}

export const retriever = (response: ProfileRetrieverParameters) => {
  const { status, body: externalProfile } = response;

  if (status === 200){
    return new AuthProfile({
      id: externalProfile.user.id,
      displayName: externalProfile.user.name,
    });
  } else {
    // handle error
  }
}

withProvider

1
2
withProvider(provider[, remoteName])

Name Type Required Description

provider string Yes The provider key from the manifest file.

Name	Type	Required	Description
`provider`	`string`	Yes	The provider `key` from the manifest file.
`remoteName`	`string`		The remote to use when using fetch. The `remoteName` must be in the `providers.auth.<key>.remotes` list in the manifest file. `remoteName` may be omitted if only one remote is defined for the provider.

remoteName

string

The remote to use when using fetch. The remoteName must be in the providers.auth.<key>.remotes list in the manifest file.

remoteName may be omitted if only one remote is defined for the provider.