Display conditions

Rate this page:

Providers

Forge supports authentication with external applications using OAuth 2.0. An app may authenticate with multiple different providers.

Properties

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

PropertyTypeRequiredDescription
authAuthenticationYes

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.

PropertyTypeRequiredDescription
keystringYes

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_-]+$

namestringYes

The display name of the provider that's shown to the user during the consent flow and on the connected apps page.

typestringYes

Must be oauth2.

scopesArray<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.

clientIdstring

The OAuth2 client_id for your app from the identity provider.

remotesArray<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.

bearerMethodauthorization-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: Sends the token in the POST body of the request.
  • uri-query: Sends the token as a query parameter of the request.
actionsActionsYesThe 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
        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.

PropertyTypeRequired
authorizationAuthorizationYes
exchangeExchangeYes
revokeTokenRevoke token
retrieveProfileProfile retrieverYes

Authorization

Configure the Authorization request.

PropertyTypeRequiredDescription
remotestringYes

The key of a remote to use.

pathstringYes

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.

PropertyTypeRequiredDescription
remotestringYes

The key of a remote to use.

pathstringYes

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.

PropertyTypeRequiredDescription
remotestringYes

The key of a remote to use.

pathstringYes

The path to the revocation endpoint.

Profile retriever

Retrieves profile information about the account once authenticated.

A profile retriever may be used to:

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

The key of a remote to use.

pathstringYes

The path to the authorization endpoint.

functionstring 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.

resolversstatic profile retriever

Maps the response shape using a fixed field mapping.

Static profile retriever

PropertyTypeRequiredDescription
idstringYes

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

displayNamestringYes

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.

avatarUrlstring

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.

PropertyTypeRequiredDescription
typeauthorization-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: Sends the token in the POST body of the request.
  • uri-query: Sends the token as a query parameter of the request.
prefixstring

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

We recommend adding a trailing space.

parameterstring

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

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

Examples

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

Rate this page: