Set up single sign on using Okta

Cloud with Teams add-onSelf-Managed CommunitySelf-Managed Enterprise Compare

This guide shows you how to set up Okta and Airbyte so your users can log into Airbyte using your organization's identity provider (IdP).

Overview

This guide is for administrators. It assumes you have:

• Basic knowledge of Okta, OpenID Connect (OIDC), and Airbyte
• The permissions to manage Okta in your organization
• The permissions to manage Airbyte in your organization

The exact process differs between the Cloud or Self-Managed versions of Airbyte. Steps for both are below.

Cloud Teams with Okta OIDC

Follow the steps below to set up single sign on with Okta.

warning

For security purposes, when a user who owns applications logs in with SSO for the first time, Airbyte disables their existing applications. Those users must replace any application secrets that were previously in use to ensure API and Terraform integrations don't break.

Set up SSO for the first time

Follow these steps to set up SSO in Airbyte Cloud.

Create a new Okta application

1. In Okta, create a new Okta OIDC App Integration for Airbyte. For help, see Okta's documentation. Create an app integration with the following options.

   • Sign-in method: OIDC - OpenID Connect

   • Application type: Web application

     

2. Click Next.

3. Set the following parameters for your app integration.

   • App integration name: Airbyte (or something similar)

   • Grant type: Authorization code

   • Sign-in redirect URIs: https://cloud.airbyte.com/auth/realms/<your-company-identifier>/broker/default/endpoint

   • Sign-out redirect URIs: https://cloud.airbyte.com/auth/realms/<your-company-identifier>/broker/default/endpoint/logout_response

   • Trusted origins: Leave empty.

   • Assignments > Controlled access: Depending on your needs, choose either Limit access to selected groups or Allow everyone in your organization to access.

   • Leave other values as defaults unless you have a reason to change them.

4. Click Save.

Configure SSO in Airbyte

1. In Airbyte, click Settings.

2. Under Organization, click General.

3. Click Set up SSO, then input the following information.

   • Email domain: The full email domain of users who sign in to Okta. For example, airbyte.io.

     note

     If you use multiple email domains, only enter one domain here. Contact Airbyte's support team to have them add additional domains after you're done.

   • Client ID: In Okta's administrator panel, Applications > Applications > Airbyte > General tab > Client ID.

   • Client secret: Your client secret from your Okta application.

   • Discovery URL: Your OpenID Connect (OIDC) metadata endpoint. It's similar to https://<yourOktaDomain>/.well-known/openid-configuration.

   • SSO subdomain: Your company identifier, which Airbyte users use to access Airbyte.

     • It must be a unique.

     • It must be consistent with the company identifier you used in the redirect URI you defined in Okta.

     • It's often your organization name or domain. For example, airbyte.

4. Click Save changes.

5. Test SSO to make sure people can access Airbyte. Stay logged in so you don't lock yourself out and ask a colleague to complete the following steps.

   1. Sign out of Airbyte.

   2. On the Airbyte login page, click Continue with SSO, enter your company identifier, and click Continue with SSO. The Okta sign in page appears.

   3. Sign into Okta. Okta then forwards you back to Airbyte, which logs you in.

   note

   If you were already logged into your company’s IdP somewhere else, you might not see a login screen. In this case, Airbyte forwards you directly to Airbyte's logged-in area.

If you successfully set up SSO, but your users can't log into Airbyte, verify that they have access to the Airbyte application you created in Okta.

Update or delete SSO configurations

To prevent a situation where you could lock yourself out of Airbyte, we require that you contact Airbyte's support team if you need to change or remove SSO in your Cloud organization.

Self-Managed Enterprise with Okta OIDC

You need to create a new Okta OIDC App Integration for Airbyte. Documentation on how to do this in Okta can be found here. You should create an app integration with OIDC - OpenID Connect as the sign-in method and Web Application as the application type:

Before you can proceed, you require your Company Identifier so you can properly fill in these values. Your contact at Airbyte gives this to you.

Create the application with the following parameters:

App integration name

Please choose a URL-friendly app integration name without spaces or special characters, such as my-airbyte-app. Screenshot of Okta app integration name Spaces or special characters in this field could result in invalid redirect URIs.

Logo (optional)

You can upload an Airbyte logo, which you can find at https://airbyte.com/company/press

Grant type

Only Authorization Code should be selected

Sign-in redirect URIs

<your-airbyte-domain>/auth/realms/airbyte/broker/<app-integration-name>/endpoint

<your-airbyte-domain> refers to the domain you access your Airbyte instance at, e.g. https://airbyte.internal.mycompany.com

<app-integration-name> refers to the value you entered in the App integration name field

Sign-out redirect URIs

<your-airbyte-domain>/auth/realms/airbyte/broker/<app-integration-name>/endpoint/logout_response

Trusted Origins

Leave empty

Assignments > Controlled Access

You can control whether everyone in your Okta organization should be able to access Airbyte using their Okta account or limit it only to a subset of your users by selecting specific groups who should get access.

Once your Okta app is set up, you're ready to deploy Airbyte with SSO. Take note of the following configuration values, as you will need them to configure Airbyte to use your new Okta SSO app integration:

• Okta domain (How to find your Okta domain)
• App Integration Name
• Client ID
• Client Secret

Visit the implementation guide for instructions on how to deploy Airbyte Enterprise using kubernetes, kubectl and helm.

Self-Managed Enterprise with Okta Generic OIDC

To set up single sign using generic OIDC for Airbyte Self-Managed Enterprise, complete the following steps.

• Create an Okta application for Airbyte
• Add an authorization server (optional)
• Add a policy for Airbyte
• Update Airbyte's values.yaml file
• Redeploy Airbyte

note

You can only use generic OIDC after you migrate to Helm chart V2.

Create an Okta app for Airbyte

Follow these steps to set up an Okta app integration for Airbyte. If you need more help setting up an app integration, see Okta's documentation.

1. Log into your Okta administrator dashboard. For example: example.okta.com/admin/dashboard.

2. Click Applications > Applications.

3. Click Create App Integration, then choose the following values.

   • Sign-in method: OIDC - OpenID Connect

   • Application type: Single-Page Application

4. Click Next.

5. Choose the following options:

   • App integration name: Airbyte

   • Grant type: Authorization Code, Refresh Token

   • Sign-in redirect URIs: The domain depends of your Airbyte installation location, but the URI should look similar to https://airbyte.example.com.

   • Sign-out redirect URIs: Set it to your base Airbyte site. For example: https://airbyte.example.com.

   • Controlled access: Depending on your needs, choose either Limit access to selected groups or Allow everyone in your organization to access.

   • Leave other values as defaults unless you have a reason to change them.

6. Click Save. Okta takes you to your app page.

7. On the app page, make sure you have Require PKCE as additional verification enabled. Leave other values as defaults.

Add an authorization server

You need an authorization server, but you probably already have one. If you do, you can use it for Airbyte too. If you need to create a new one, follow these steps.

1. Click Security > API.

2. Click Add Authorization Server.

3. Give your authorization server a name, audience, and description. Then, click Save. For demonstration purposes, this guide assumes you name your authorization server webapps.

tip

Before continuing, go to your authorization server's page in Okta and open the Issuer Metadata URL link in a new tab. This is your well-known endpoint. You need some of these values later, so set it aside for a moment.

Add an access policy

Add an access policy to your authorization server.

1. Click Security > API > choose your authorization server > Access Policies > Add Policy.

2. Give your policy a name and description. Under Assign to, choose The following clients, then search for your Airbyte application (you probably called it Airbyte). Okta shows you your new policy.

3. Click Create Policy.

4. Click Add rule.

5. Fill out the form.

   • Give your rule a descriptive name, like "Log into Airbyte".

   • Grant Authorization Code and Token exchange. Don't grant anything else unless you have a reason to.

   • Choose Any user assigned the app.

   • Choose Any scopes.

   • Click Create rule.

   • Leave other values as defaults unless you have a reason to change them.

Update your values.yaml file

Once you have an app integration for Airbyte, update the values.yaml file you use when you deploy Airbyte. This section is where you need information from the well-known endpoint you opened earlier.

Under global, add a new auth section and fill in the following data.

values.yaml

global: 
  edition: "enterprise"
  airbyteUrl: "airbyte.example.com"
  enterprise:
    secretName: "airbyte-license"
    licenseKeySecretKey: "LICENSE_KEY"
  # Add this new auth section. See below for help populating these values.
  auth:
    identityProvider: 
      type: generic-oidc
      generic-oidc: 
        clientId: YOUR_CLIENT_ID
        audience: YOUR_AUDIENCE
        issuer: YOUR_ISSUER
        endpoints: 
          authorizationServerEndpoint: YOUR_AUTH_ENDPOINT
          jwksEndpoint: YOUR_JWKS_ENDPOINT

You collect these values from Okta in the locations shown below.

• clientId: In Okta's administrator panel, Applications > Applications > Airbyte > General tab > Client ID.

• audience: In Okta's administrator panel, Security > API > Authorization Servers tab > Audience. Choose the audience for the authorization server you're using with Airbyte.

• issuer: In your well-known endpoint, use the issuer.

• authorizationServerEndpoint: In your well-known endpoint, use the authorization_endpoint, but omit the /v1/authorize portion. For example, https://example.okta.com/oauth2/default/.

• jwksEndpoint: In your well-known endpoint, use the jwks_uri.

Deploy Airbyte

In your command-line tool, deploy Airbyte using your updated values file. The examples here may not reflect your actual Airbyte version and namespace conventions, so make sure you use the settings that are appropriate for your environment.

Example using a namespace called 'airbyte'

helm upgrade -i \
--namespace airbyte \
--values ./values.yaml \
airbyte \
airbyte-v2/airbyte \
--version 2.0.3 \
--set global.image.tag=1.7.0