Authentication

Block authentication methods supported by OpenOps

OpenOps supports several forms of authentication for blocks: basic, secret-based, custom, and OAuth2.

Block authentication defines which credentials the user must enter to log in to the API that your block integrates with. Once authentication is implemented for your block, the user can create a connection. Apart from implementing authentication, no additional setup is required to enable the connection UI.

Authentication for a block must be defined using the auth parameter in the createBlock function within your block definition, as well as in all createAction functions within your action definitions.

Each block can use only one authentication type.

Basic authentication

This authentication type collects a username and password as two separate fields. It can also be used to pass an API key and an API secret, or similar pairs of public/private credentials, in which case they are sent in the HTTP Authorization: Basic header.

BlockAuth.BasicAuth({
  required: true,
  authProviderKey: 'myservice',
  authProviderDisplayName: 'My Service',
  authProviderLogoUrl: 'https://static.openops.com/blocks/myservice.png',
  description: '',
  username: {
    displayName: 'Username',
    description: 'Enter your username',
  },
  password: {
    displayName: 'Password',
    description: 'Enter your password',
  },
})

The connection UI for this authentication type requests two credentials, typically a username and a password:

Basic authentication is not currently used in any OpenOps blocks.

Secret-based authentication

Use secret-based authentication when an API key is all that’s required to authenticate with a service you’re integrating with, and the service’s base URL is always the same.

This authentication type is used by many OpenOps blocks, including CloudHealth, CloudZero, Flexera, Linear, Monday.com, nOps, and Vantage.

BlockAuth.SecretAuth({
  displayName: 'API Key',
  required: true,
  authProviderKey: 'myservice',
  authProviderDisplayName: 'My Service',
  authProviderLogoUrl: 'https://static.openops.com/blocks/myservice.png',
  description: '',
    // Optional validation
  validate: async ({ auth }) => {
    if (auth.startsWith('sk_')) {
      return {
        valid: true,
      };
    }
    return {
      valid: false,
      error: 'Invalid API Key',
    };
  },
})

The connection UI for this authentication type only requests an API key:

Custom authentication

This type of authentication allows collecting multiple properties, such as a base URL and an access token. Use this type when you need the user to enter more than just an API key.

In OpenOps, this is currently the most commonly used authentication type. It’s used by blocks such as AWS, Azure, Google Cloud, Zendesk, Ternary, ServiceNow, Kion, Flexera One, Databricks, and CloudFix.

Using the custom authentication type is demonstrated in Contributing an Integration, a guide that explains how to create a fully functional integration block.

BlockAuth.CustomAuth({
  authProviderKey: 'myservice',
  authProviderDisplayName: 'My Service',
  authProviderLogoUrl: 'https://static.openops.com/blocks/myservice.png',
  description: 'Enter custom authentication details',
  required: true,
  props: {
    baseUrl: Property.ShortText({
      displayName: 'Base URL',
      description: 'Enter the base URL',
      required: true,
    }),
    accessToken: Property.SecretText({
      displayName: 'Access Token',
      description: 'Enter the access token',
      required: true,
    }),
  },
  // Optional validation
  validate: async ({ auth }) => {
    if (auth.baseUrl.endsWith('/')) {
      return {
        valid: false,
        error: 'Base URL must not end with a slash',
      };
    } else {
      return { valid: true };
    }
  },
})

The connection UI for this authentication type requests whatever inputs you defined in the props object:

OAuth2

This authentication type allows logging in with an OAuth2 provider either on behalf of a specific user (authorization code grant) or on behalf of a service (client credentials grant).

It’s currently used by some OpenOps blocks, including GitHub, Slack, Microsoft Teams, and Microsoft Outlook.

BlockAuth.OAuth2({
  authProviderKey: 'bitbucket',
  authProviderDisplayName: 'Bitbucket',
  authProviderLogoUrl: `https://static.openops.com/blocks/bitbucket.png`,
  description: '',
  required: true,
  scope: [
    'account:write',
    'repository:read',
    'repository:write',
    'pullrequest:write',
  ],
  authUrl: 'https://bitbucket.org/site/oauth2/authorize',
  tokenUrl: 'https://bitbucket.org/site/oauth2/access_token',
})

In the connection UI, the user can either click Connect to log in to the OAuth2 provider with their own credentials, or enter a client ID and client secret to authenticate a service.

No authentication

If your block doesn’t require authentication, declare this explicitly by assigning BlockAuth.None() to the auth property.