​
OAuth SSO

We recommend using a private navigation tab to test the new settings as soon as they are saved by refreshing the login page as a non authed user.

​
Google login

Create Google OAuth keys

First, you need to create a Google OAuth Client:

  • Go to https://console.developers.google.com/apis/credentials and create a project if you did not have one.
  • Click “Create Credentials”, then click “OAuth Client ID” in the drop-down menu.
  • Enter the following:
    • Application Type: Web Application
    • Name: getOperate
    • Authorized Redirect URLs: https://<YOUR_INSTANCE>/user/login_callback/google
  • Click Create.
  • Copy the Client ID and Client Secret from the “OAuth Client” modal.

Superadmin Settings -> Instance Settings -> SSO -> Toggle “Google” -> set client id, org and client secret.

​
Microsoft

Redirect URI: https://<YOUR_INSTANCE>/user/login_callback/microsoft Login: https://<YOUR_INSTANCE>/user/login

Create a new OAuth 2.0 Client in Microsoft portal.

In the “Authentication” tab, set the redirect URI to BASE_URL/user/login_callback/microsoft, the logout channel to BASE_URL/auth/logout where BASE_URL is what you configured as core BASE_URL. Also set “Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)”, you can restrict the emails directly in getOperate using the “allowed_domains” setting.

Superadmin Settings -> Instance Settings -> SSO -> Toggle “microsoft” -> set client id, org and client secret.

​
Okta

From your Admin page, setup getOperate using the service flow:

  1. Create a new app integration:
  • For “sign-in method” select “OIDC - Open ID Connect”.
  • For “application type” select “Web Appliction”.
  1. Select all of the following options for Grant type of “Client acting on behalf of a user”:
  • Authorization Code
  • Refresh Token
  • Implicit (hybrid)
  • Allow ID Token with implicit grant type
  • Allow Access Token with implicit grant type

  1. For Refresh Token, select “Rotate token after every use”.

  2. Under “LOGIN”, set the following:

  • “Sign-in redirect URIs” https://<your getOperate's public hostname as configured in values.yaml>/user/login_callback/okta/
  • “Sign-out redirect URIs” https://<your getOperate's public hostname as configured in values.yaml>
  • “Login initiated by” App Only
  • “Initiate login URI” https://<your getOperate's public hostname as configured in values.yaml>/user/login

Superadmin Settings -> Instance Settings -> SSO -> Toggle “okta” -> set client id, org and client secret.

​
GitHub

Redirect URI: https://<YOUR_INSTANCE>/user/login_callback/github Login: https://<YOUR_INSTANCE>/user/login

Superadmin Settings -> Instance Settings -> SSO -> Toggle “github” -> set client id, org and client secret.

​
GitLab

Redirect URI: https://<YOUR_INSTANCE>/user/login_callback/gitlab Login: https://<YOUR_INSTANCE>/user/login

GitLab’s Single Sign-On integration is supported by getOperate. Detailed steps for setting up GitLab as an OAuth SSO provider will be provided in the upcoming documentation but the entry for the oauth.json is as following:

Superadmin Settings -> Instance Settings -> SSO -> Toggle “gitlab” -> set client id, org and client secret.

​
Custom OAuth

You can use other custom OAuths as resources using the “Add OAuth” button in: Superadmin Settings -> Instance Settings -> Resources -> Add OAuth.

​
OAuth Resources

​
Slack

Create a new slack app at https://api.slack.com/apps?new_app=1

Pick “From an app manifest”, then YAML.

Your app manifest should look like this, replacing <YOUR INSTANCE URL> in 2 places:

display_information:
  name: getOperate
  description: getOperate.dev slackbot and oauth integration
  background_color: "#3b82f6"
  long_description: The getOperate app allows to use command to run jobs inside getOperate as well as receiving message as the getOperate app. The getOperate app pairs a slack workspace with a getOperate workspace. It must be installed from within the settings of a getOperate workspace.
features:
  app_home:
    home_tab_enabled: true
    messages_tab_enabled: true
    messages_tab_read_only_enabled: true
  bot_user:
    display_name: getOperate
    always_online: true
  slash_commands:
    - command: /getOperate
      url: <YOUR INSTANCE URL>/api/oauth/slack_command
      description: Trigger the script set in your workspace settings for slack
      usage_hint: the text that will be passed to the script
      should_escape: false
oauth_config:
  redirect_urls:
    - <YOUR INSTANCE URL>
  scopes:
    user:
      - chat:write
      - admin
      - channels:write
    bot:
      - chat:write
      - chat:write.public
      - channels:join
      - commands
settings:
  org_deploy_enabled: false
  socket_mode_enabled: false
  token_rotation_enabled: false

Then from your Superadmin Settings, fill with Client ID and Client Secret.

As for any OAuth Settings, make sure that there is a corresponding resource type with the same name with a “token” field in the superadmin workspace. That should be the case by default with Slack.

Now users should be able to connect to Slack through OAuth:

​
Google Sheet

Create GSheet OAuth keys

  • Create a Google OAuth account by going to https://console.developers.google.com/apis/credentials and create a project if you did not have one.

  • Click “Enable APIs and Services”

    • Search “Google Sheets API”
    • Enable this API

  • Click “Create Credentials”, then click “OAuth 2.0 Client IDs” in the drop-down menu.

  • Enter the following:

    • Application Type: Web Application
    • Name: getOperate
    • Authorized Redirect URLs: https://<YOUR_INSTANCE>/oauth/callback/gsheets

  • Click Create.

  • Copy the Client ID and Client Secret from the “OAuth Client” modal.

  • Superadmin Settings -> Instance Settings -> Resources -> Add OAuth “gsheet” -> set client id and client secret

The same steps apply to enable more APIs (Gmail, Gdrive, etc.) on your Google Account to set up the resources in getOperate.

​
Custom OAuth

You can add a completely custom OAuth without requiring a dev setup. The item accepts an extra optional field: connect_config or login_config of type OAuthConfig:

interface OAuthConfig {
    auth_url: string,
    token_url: string,
    userinfo_url?: string,
    scopes?: string[],
    extra_params?: Record<string, string>,
    extra_params_callback?: Record<string, string>,
    req_body_auth?: bool
}

connect_config is used for resources, and login_config for SSO.

​
Add new OAuth provider

Once you have validated your custom item, we would be grateful if you could open a PR.

To add a new OAuth provider format is as follows:

"<name_of_resource_type_for_integration>": {
     "auth_url": "<auth_url>",
     "token_url": "<token_url>",
     "scopes": <the list of default scopes to suggest by default>,
     "extra_params": {
         "<key>": "<val>",
     }
 },

Where extra_params is an escape hatch to deal with OAuth provider that need some extra fields to be passed along to the authorization URL.

You can iterate without requiring a dev setup. The item accepts an extra optional field: connect_config or login_config for SSO.

connect_config is used for resources, and login_config for SSO.