Setup OAuth and SSO

Orvanta supports Single Sign-On for Google, Microsoft, Okta, GitHub, GitLab, Jumpcloud, Keycloak, Authentik, Authelia, Kanidm, Zitadel, Nextcloud, and PocketID, along with domain restriction.

Orvanta also supports OAuth for Slack, GitHub, GitLab, Bitbucket, Google Sheets, Google Drive, Gmail, Google Calendar, Google Forms, Google Cloud, Google Workspace, Basecamp, LinkedIn, QuickBooks, Visma, Snowflake, and Custom OAuth.

OAuth configuration on self-hosted instances is set in the instance settings.

SSO

Create a Google OAuth Client by:

Going to https://console.developers.google.com/apis/credentials
Creating a project if needed
Clicking Create Credentials then OAuth Client ID
Setting Application Type to Web Application
Naming it “Orvanta”
Adding Authorized Redirect URL: https://<YOUR_INSTANCE>/user/login_callback/google

Copy the Client ID and Client Secret. In Instance settings under SSO OAuth → SSO, toggle Google and enter the credentials.

Microsoft

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

Create a new OAuth 2.0 Client in the Microsoft portal. In the Authentication tab, set the redirect URI to BASE_URL/user/login_callback/microsoft and logout channel to BASE_URL/auth/logout. Set accounts to Any Microsoft Entra ID tenant - Multitenant.

Toggle microsoft in Instance settings SSO OAuth → SSO and enter client id, org, and client secret.

Okta

From the Admin page:

Create a new app integration with OIDC as sign-in method and Web Application type.
Select Authorization Code, Refresh Token, and Implicit grant types.
Enable Rotate token after every use for Refresh Token.
Under LOGIN, set:
- Sign-in redirect URIs: https://<your orvanta hostname>/user/login_callback/okta/
- Sign-out redirect URIs: https://<your orvanta hostname>
- Login initiated by: App Only
- Initiate login URI: https://<your orvanta hostname>/user/login

Toggle okta in Instance settings and enter client id, org, and client secret.

GitHub (SSO)

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

Toggle github in Instance settings SSO OAuth → SSO and enter client id, org, and client secret.

GitLab (SSO)

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

Toggle gitlab in Instance settings and enter client id, org, and client secret.

Jumpcloud

Under SSO > Custom OIDC:

Name: Orvanta
Redirect URI: https://<YOUR_INSTANCE>/user/login_callback/jumpcloud
Login: https://<YOUR_INSTANCE>/user/login
Client Authentication Type: Client Secret Basic
Standard Scopes: Check Email

Toggle jumpcloud in Instance settings, enter client id and secret, and set Client Authentication Type to Client Secret Basic.

Keycloak

Set up your realm in Keycloak. Toggle Keycloak in Instance settings SSO OAuth → SSO. Add the client scope offline_access to the Keycloak client.

Authentik

Create OAuth Client in Authentik:
- Redirect URI: https://<YOUR_INSTANCE>/user/login_callback/authentik
- Post-Logout Redirect URI: https://<YOUR_INSTANCE>/user/login
- Grant Types: Authorization Code, Refresh Token
In Instance settings SSO OAuth → SSO:
- Toggle authentik
- Enter Authentik URL: https://<AUTHENTIK_HOST>/application/o/authorize/
- Enter Client ID and Client Secret

Authelia

Create OAuth Client in Authelia:
- Redirect URI: https://<YOUR_INSTANCE>/user/login_callback/authelia
- Post-Logout Redirect URI: https://<YOUR_INSTANCE>/user/login
- Scopes: OpenID, Email
In Instance settings SSO OAuth → SSO:
- Toggle authelia
- Enter Authelia URL: https://<AUTHELIA_URL>/api/oidc/authorization
- Enter Client ID and Client Secret

Kanidm

Create OAuth 2.0 client in Kanidm:
- Redirect URI: https://<YOUR_INSTANCE>/user/login_callback/kanidm
- Post-Logout Redirect URI: https://<YOUR_INSTANCE>/user/login
In Instance settings SSO OAuth → SSO:
- Toggle kanidm
- Enter Kanidm URL: https://<KANIDM_URL>/ui/oauth2
- Enter Client ID and Client Secret

Zitadel

Create OAuth Client in Zitadel:
- Redirect URI: https://<YOUR_INSTANCE>/user/login_callback/zitadel
- Post-Logout Redirect URI: https://<YOUR_INSTANCE>/user/login
In Instance settings SSO OAuth → SSO:
- Toggle zitadel
- Enter Zitadel URL: https://<ZITADEL_URL>/oauth/v2/authorize
- Enter Client ID and Client Secret

Nextcloud

Create OAuth Client in Nextcloud:
- Go to Administration settings → Security → OAuth 2.0 clients
- Click Add client
- Redirect URI: https://<YOUR_INSTANCE>/user/login_callback/nextcloud
- Name: Orvanta
In Instance settings SSO OAuth → SSO:
- Toggle nextcloud
- Enter Nextcloud Instance Domain (without https://)
- Enter Client ID and Client Secret

PocketID

Create OAuth client in PocketID:
- Redirect URI: https://<YOUR_INSTANCE>/user/login_callback/pocketid
In Instance settings SSO OAuth → SSO:
- Toggle pocketid
- Enter PocketID URL (base URL of your instance)
- Optionally enter a Custom Name for the login button
- Enter Client ID and Client Secret

Custom OAuth

Use custom SSO clients from Instance settings SSO OAuth → SSO by providing a client id to Add custom SSO client.

OAuth

When OAuth options are set, you can create a resource containing a token automatically generated by the third-party provider. Go to Resources and create a new resource of your OAuth client type.

Slack

Create a new Slack app at https://api.slack.com/apps?new_app=1. Select From an app manifest then YAML.

The app manifest should include:

display_information:
  name: Orvanta
  description: orvanta.cloud slackbot and oauth integration
  background_color: '#3b82f6'
  long_description: The Orvanta app allows to use commands to run jobs inside Orvanta as well as receiving messages as the Orvanta app. The Orvanta app pairs a Slack workspace with an Orvanta workspace. It must be installed from within the settings of an Orvanta workspace.

features:
  app_home:
    home_tab_enabled: true
    messages_tab_enabled: true
    messages_tab_read_only_enabled: true
  bot_user:
    display_name: Orvanta
    always_online: true
  slash_commands:
    - command: /orvanta
      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
      - files:write
      - commands
      - app_mentions:read
      - im:history
      - im:read

settings:
  event_subscriptions:
    request_url: <YOUR INSTANCE URL>/api/oauth/slack_events
    bot_events:
      - app_mention
      - message.im
  interactivity:
    is_enabled: true
    request_url: <YOUR INSTANCE URL>/api/slack
  org_deploy_enabled: false
  socket_mode_enabled: false
  token_rotation_enabled: false

These URLs must be publicly accessible:

<YOUR INSTANCE URL>/api/oauth/slack_command
<YOUR INSTANCE URL>/api/oauth/slack_events
<YOUR INSTANCE URL>/api/slack

From Instance settings, fill in Client ID and Client Secret.

A corresponding resource type named slack with a token field should exist in the superadmin workspace by default.

Non-interactive CLI alternative

The Slack bot install can be done non-interactively via CLI with a pre-minted bot token: orvanta instance connect-slack --bot-token ... --team-id ... --team-name .... For workspace-level: orvanta workspace connect-slack ....

Workspace-level Slack app

Workspace admins can configure their own Slack app with workspace-specific credentials for isolation, separate rate limits, and independent management.

Follow the app manifest setup to create a Slack app.
In workspace settings, navigate to the Slack app section.
Enter the workspace-specific Client ID and Client Secret.

Via CLI, commit slack_oauth_client_id and slack_oauth_client_secret to the workspace’s settings.yaml and run orvanta sync push.

Microsoft Teams

Go to Azure Portal and create a new Bot Service of type Azure Bot.
Give your bot a unique handle.
Select Single tenant.
Go to Microsoft Entra App Registration and select your bot.
Click Manage → API permissions → Add a permission → Microsoft Graph → Application permissions → Select Channel.ReadBasic.All and Team.ReadBasic.All.
Click Manage → Certificates & secrets → New client secret → Add.
Copy the Client Secret, the Application (client) ID, and the Directory (tenant) ID.
Sign in to the Teams Bot Framework Portal and create a new App.
Fill in Basic Information with the Application ID.
In Branding, upload icons and accent colors.
In App Features, select Bot and use the Application ID.
Go to Domains and add your Orvanta instance domain.
Preview or Publish the app to your organization.

In Instance settings → Resources → Add OAuth teams and set the client id (Application ID), client secret, and tenant id (Directory ID).

GitHub (OAuth)

Go to GitHub Developer Settings.
Click New OAuth App.
Enter:
- Application Name: Orvanta
- Homepage URL: https://<YOUR_INSTANCE>
- Authorization Callback URL: https://<YOUR_INSTANCE>/oauth/callback/github
Copy Client ID and Client Secret.
In Instance settings → Resources → Add OAuth github and set client id and secret.

GitLab (OAuth)

Go to GitLab profile settings.
Click New Application.
Enter:
- Name: Orvanta
- Redirect URI: https://<YOUR_INSTANCE>/oauth/callback/gitlab
- Scopes: Choose appropriate scopes like api, read_user, etc.
Copy Application ID and Secret.
In Instance settings → Resources → Add OAuth gitlab and set client id and secret.

Bitbucket

Go to Bitbucket’s App Creation page.
Click Create App Password.
Enter:
- Label: Orvanta
- Redirect URI: https://<YOUR_INSTANCE>/oauth/callback/bitbucket
- Select appropriate scopes.
Copy Client ID and Client Secret.
In Instance settings → Resources → Add OAuth bitbucket and set client id and secret.

Google Sheets

Go to https://console.developers.google.com/apis/credentials.
Create a project if needed.
Click Enable APIs and Services and search “Google Sheets API”.
Enable this API.
Click Create Credentials → OAuth 2.0 Client IDs.
Enter:
- Application Type: Web Application
- Name: Orvanta
- Authorized Redirect URLs: https://<YOUR_INSTANCE>/oauth/callback/gsheets
Copy Client ID and Client Secret.
In Instance settings → Resources → Add OAuth gsheet and set client id and secret.

The same steps apply for Gmail, Google Drive, and other Google APIs.

Google Drive (GDrive)

Follow the Google Sheets instructions but search for and enable Google Drive API. Add the Authorized Redirect URL: https://<YOUR_INSTANCE>/oauth/callback/gdrive. In Instance settings, add OAuth gdrive.

Gmail

Follow the Google Sheets instructions but search for and enable Gmail API. Add the Authorized Redirect URL: https://<YOUR_INSTANCE>/oauth/callback/gmail. In Instance settings, add OAuth gmail.

Google Calendar (GCal)

Follow the Google Sheets instructions but search for and enable Google Calendar API. Add the Authorized Redirect URL: https://<YOUR_INSTANCE>/oauth/callback/gcal. In Instance settings, add OAuth gcal.

Google Forms (GForms)

The Google Forms API may use Google Drive, so follow the Google Drive API instructions. Add the Authorized Redirect URL: https://<YOUR_INSTANCE>/oauth/callback/gforms. In Instance settings, add OAuth gforms.

Google Cloud (GCloud)

Follow the Google Sheets instructions but search for and enable Google Cloud APIs. Add the Authorized Redirect URL: https://<YOUR_INSTANCE>/oauth/callback/gcloud. In Instance settings, add OAuth gcloud.

Google Workspace (GWorkspace)

Follow the Google Sheets instructions but ensure you enable Admin SDK API. Add the Authorized Redirect URL: https://<YOUR_INSTANCE>/oauth/callback/gworkspace. In Instance settings, add OAuth gworkspace.

Basecamp

Go to Basecamp’s Developer Portal.
Click Register Your Application.
Enter:
- Name: Orvanta
- Redirect URI: https://<YOUR_INSTANCE>/oauth/callback/basecamp
Copy Client ID and Client Secret.
In Instance settings → Resources → Add OAuth basecamp and set client id and secret.

Go to LinkedIn Developers.
Click Create App.
Enter:
- App Name: Orvanta
- Authorized Redirect URLs: https://<YOUR_INSTANCE>/oauth/callback/linkedin
Copy Client ID and Client Secret.
In Instance settings → Resources → Add OAuth linkedin and set client id and secret.

QuickBooks

Go to QuickBooks Developer.
Click Create an App.
Enter:
- App Name: Orvanta
- Redirect URL: https://<YOUR_INSTANCE>/oauth/callback/quickbooks
Copy Client ID and Client Secret.
In Instance settings → Resources → Add OAuth quickbooks and set client id and secret.

Visma

Go to the Visma Developer Portal.
Click Create New Application.
Enter:
- Name: Orvanta
- Redirect URI: https://<YOUR_INSTANCE>/oauth/callback/visma
Copy Client ID and Client Secret.
In Instance settings → Resources → Add OAuth visma and set client id and secret.

Snowflake

Go to Snowflake and open a new worksheet. Edit and run:

CREATE OR REPLACE SECURITY INTEGRATION <enter a name for the OAuth integration>
TYPE = OAUTH
OAUTH_CLIENT = CUSTOM
OAUTH_CLIENT_TYPE = 'CONFIDENTIAL'
OAUTH_REDIRECT_URI = 'https://<public url of your Orvanta instance>/oauth/callback/snowflake_oauth'
OAUTH_USE_SECONDARY_ROLES = IMPLICIT
ENABLED = TRUE
COMMENT = '<enter a description of your security integration>'

Retrieve client_id and client_secret:

WITH oauth_data AS (
  SELECT PARSE_JSON(SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('<OAuth integration name>')) AS oauth_json
)
SELECT
    oauth_json:OAUTH_CLIENT_ID::string AS client_id,
    oauth_json:OAUTH_CLIENT_SECRET::string AS client_secret
FROM
    oauth_data;

Get your Snowflake account identifier from the URL or account settings, or run:

SELECT CURRENT_ORGANIZATION_NAME() || '-' || CURRENT_ACCOUNT_NAME() AS org_account_formatted;

In Instance settings → Resources → Add OAuth snowflake_oauth and set client id, client secret, and account identifier.

Azure OAuth

Go to Azure AAD App registrations.
Create a new registration.
Set:
- Name: (your choice)
- Redirect URL: https://<YOUR ORVANTA BASE URL>/oauth/callback/azure_oauth
- Application type: Web
Go to Certificates and secrets.
Create a new client secret and copy the Secret Value (not the Secret ID).
Go to API permissions and select appropriate permissions (e.g. Azure SQL Database → user_impersonation for SQL).
In Instance settings, create a new OAuth client and fill in:
- Client ID (Application (client) ID from Overview)
- Client Secret (Secret Value)
- Tenant ID (from Overview)

Depending on your application, add extra scopes like https://database.windows.net//.default for MS SQL Server.

Custom OAuth

Under Enterprise Edition, add a completely custom OAuth. The item accepts optional fields: 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.

Setup OAuth and SSO

SSO

Google login

Microsoft

Okta

GitHub (SSO)

GitLab (SSO)

Jumpcloud

Keycloak

Authentik

Authelia

Kanidm

Zitadel

Nextcloud

PocketID

Custom OAuth

OAuth

Slack

Non-interactive CLI alternative

Workspace-level Slack app

Microsoft Teams

GitHub (OAuth)

GitLab (OAuth)

Bitbucket

Google Sheets

Google Drive (GDrive)

Gmail

Google Calendar (GCal)

Google Forms (GForms)

Google Cloud (GCloud)

Google Workspace (GWorkspace)

Basecamp

LinkedIn

QuickBooks

Visma

Snowflake

Azure OAuth

Custom OAuth