Providers

Forge supports authentication with external applications using OAuth 2.0. An app may authenticate with multiple different providers. See the following step-by-step tutorial to call an external OAuth 2.0 API.

Properties

The providers section of the manifest.yml file enables integration with external providers.

Property Type Required Description

Property	Type	Required	Description
`auth`	Authentication	Yes	External OAuth 2.0 identity providers See Authentication for more details.

auth

Authentication

Yes

External OAuth 2.0 identity providers

See Authentication for more details.

Authentication

To use OAuth2 providers via external authentication, you must specify the integration details of the identity provider in the auth section.

Property	Type	Required	Description
`key`	`string`	Yes	A key for the provider, used to refer to it from the runtime API, and from the function definition. Must be unique within the this list and have a maximum of 23 characters. Regex: `^[a-zA-Z0-9_-]+$`
`name`	`string`	Yes	The display name of the provider that's shown to the user during the consent flow and on the connected apps page.
`type`	`string`	Yes	Must be `oauth2`.
`scopes`	`Array<string>`		A list of scopes needed to access the provider. Note, scopes cannot be removed. To remove a provider scope, you must create a new integration by changing the provider `key` in the `manifest.yml` file.
`clientId`	`string`		The OAuth2 `client_id` for your app from the identity provider.
`remotes`	`Array<string>`	Yes	A list of remote keys that you wish to use this provider with. This applies to requests made inside your Forge app code using the `withProvider()` function.
`bearerMethod`	`authorization-header`, `form-encoded`, `uri-query` or advanced bearer method.	Yes	The method of sending the user's authentication token to the service after authentication. One of `authorization-header`, `form-encoded`, `uri-query` or advanced bearer method. `authorization-header`: Sends the token in a HTTP header. `form-encoded` (deprecated): Sends the token in the POST body of the request. `uri-query` (deprecated): Sends the token as a query parameter of the request.
`actions`	Actions	Yes	The endpoints needed to perform several parts of the OAuth 2.0 flow. See Actions.

Example

1
2
providers:
  auth:
    - key: google
      name: Google
      scopes:
        - 'profile'
        - 'https://www.googleapis.com/auth/userinfo.email'
      type: oauth2
      clientId: EXAMPLE
      remotes:
        - google-apis
      actions:
        authorization:
          remote: google-account
          path: /o/oauth2/v2/auth
        exchange:
          remote: google-oauth
          path: /token
        refreshToken:
          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
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

Actions

Defines the endpoints needed to perform several parts of the OAuth 2.0 flow.

Property	Type	Required
`authorization`	Authorization	Yes
`exchange`	Exchange	Yes
`refreshToken`	Refresh token
`revokeToken`	Revoke token
`retrieveProfile`	Profile retriever	Yes

Authorization

Configure the Authorization request.

Property Type Required Description

remote

string

Yes

The key of a remote to use.

path

string

Yes

The path to the authorization endpoint.

queryParameters

{[key: string]: string}

Additional query parameters to add to the request.

For example, access_type: "read" adds &access_type=read to the URL.

Exchange

Configure the Authorization code request. This request exchanges the authorization code from the user for an access token.

Property Type Required Description

remote

string

Yes

The key of a remote to use.

path

string

Yes

The path to the authorization endpoint.

resolvers

{accessToken: string, accessTokenExpires: string, refreshToken: string}

Some identity providers may have non-standard response. Use this option to resolve the required fields from the response.

Use . to access nested values, such as user.token

accessToken: Default: access_token
accessTokenExpires: Default: expires_in
refreshToken: Default: refresh_token

Refresh token

Configure the Refresh Access Tokens request. This request uses an existing refresh token to obtain new access tokens (along with new refresh tokens, if the auth provider allows it).

If not specifically configured, the request to refresh tokens will automatically default to using configuration for the Exchange.

Property Type Required Description

remote

string

Yes

The key of a remote to use.

path

string

Yes

The path to the authorization endpoint.

resolvers

{accessToken: string, accessTokenExpires: string, refreshToken: string}

Some identity providers may have non-standard response. Use this option to resolve the required fields from the response.

Use . to access nested values, such as user.token

accessToken: Default: access_token
accessTokenExpires: Default: expires_in
refreshToken: Default: refresh_token

Revoke token

Before revoking a user token, this action is run to notify the identity provider of the revocation.

Property	Type	Required	Description
`remote`	`string`	Yes	The key of a remote to use.
`path`	`string`	Yes	The path to the revocation endpoint.

Profile retriever

Retrieves profile information about the account once authenticated.

A profile retriever may be used to:

To allow the user to differentiate between multiple accounts on the Connected Apps screen.
To differentiate between a new account and an existing account.

Property	Type	Required	Description
`remote`	`string`	Yes	The key of a remote to use.
`path`	`string`	Yes	The path to the authorization endpoint.
`function`	`string`	For a static profile retriever, specify `resolvers`. To use a dynamic profile retriever, specify `function`.	Use a Forge function to map the API response. See Dynamic profile retriever for more information.
`resolvers`	static profile retriever		Maps the response shape using a fixed field mapping.

Static profile retriever

Property Type Required Description

Property	Type	Required	Description
`id`	`string`	Yes	Differentiates between multiple accounts. Must be a unique string for each account. Not displayed to the user.
`displayName`	`string`	Yes	The account name displayed to the user for the purpose of distinguishing between multiple accounts. Can be an email, username, or some other unique identifier that the user would recognize. This should not be the name of the user, as this may be the same across multiple accounts.
`avatarUrl`	`string`		Optional URL to an avatar image.

id

string

Yes

Differentiates between multiple accounts. Must be a unique string for each account. Not displayed to the user.

displayName

string

Yes

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

Can be an email, username, or some other unique identifier that the user would recognize.

This should not be the name of the user, as this may be the same across multiple accounts.

avatarUrl

string

Optional URL to an avatar image.

Advanced bearer method

Some services use non-standard header names or query parameters. The advanced bearerMethod object allows you to override the values expected by the existing bearer method types.

See the above Authentication section for other bearerMethod values.

Property Type Required Description

Property	Type	Required	Description
`type`	`authorization-header`, `form-encoded` or `uri-query`	Yes	Method to send the user authentication token to the service after authentication. `authorization-header`: Sends the token in the an HTTP header. `form-encoded` (deprecated): Sends the token in the POST body of the request. `uri-query` (deprecated): Sends the token as a query parameter of the request.
`prefix`	`string`		A prefix inserted before the token in `authorization-header` type requests. Defaults to `Bearer` . We recommend adding a trailing space.
`parameter`	`string`		Either a custom header name (for `authorization-header`) or parameter name. Defaults to `Authorization` for the `authorization-header` type. Otherwise, `access_token`.

type

authorization-header,
form-encoded or
uri-query

Yes

Method to send the user authentication token to the service after authentication.

authorization-header: Sends the token in the an HTTP header.
form-encoded (deprecated): Sends the token in the POST body of the request.
uri-query (deprecated): Sends the token as a query parameter of the request.

prefix

string

A prefix inserted before the token in authorization-header type requests. Defaults to Bearer .

We recommend adding a trailing space.

parameter

string

Either a custom header name (for authorization-header) or parameter name.

Defaults to Authorization for the authorization-header type. Otherwise, access_token.

Example

1
2
bearerMethod:
  type: authorization-header
  prefix: 'token '
  parameter: 'X-Custom-Header'