Configuration

• 1: Authentication
• 1.1: Google
• 1.2: Keycloak
• 1.3: Microsoft Entra ID
• 1.4: Okta
• 2: Connectors
• 2.1: Atlassian Bitbucket Connector
• 2.2: Atlassian Confluence Connector
• 2.3: Atlassian Connector for Jira & Confluence Data Center
• 2.4: Atlassian Jira Connector
• 2.5: GitHub Connector
• 2.6: GitLab Connector
• 2.7: Google Connector
• 2.7.1: Gmail Connector Setup
• 2.7.2: Google Drive Connector Setup
• 2.7.3: Google Sites Connector Setup
• 2.8: Keycloak Connector
• 2.9: Linear Connector
• 2.10: Microsoft Connectors
• 2.10.1: OneDrive Connector Setup
• 2.10.2: Outlook Connector Setup
• 2.10.3: SharePoint Connector Setup
• 2.10.4: Teams Connector Setup
• 2.11: Notion Connector
• 2.12: Okta Connector
• 2.13: Salesforce Connector
• 2.14: ServiceNow Connector
• 2.15: Slack Connector
• 2.16: SolarWinds Service Desk Connector
• 2.17: Staffbase Connector
• 2.18: Web Connector
• 2.19: Zendesk Connector
• 2.20: Zulip Connector
• 3: AI Services / LLM

1 - Authentication

Atolio requires a single sign-on (SSO) provider for two purposes:

• To enable authentication using the OpenID Connect (OIDC) protocol, as outlined in this document.
• To support user mappings, ensuring that a user’s identity is mapped correctly across the variety of sources where those users do their work. Refer to configuring sources for additional information.

Note: For particular connectors (e.g. Google Drive, Gmail), the steps outlined below for Google are also required even if your authentication provider is different (e.g. Okta).

Identity Provider Configuration

1.1 - Google

Create OAuth Client

Note: The instructions in this section are only needed when Google is used for authentication of the Atolio web application.

Create a new project in the Google Cloud Console by visiting https://console.cloud.google.com/cloud-resource-manager and clicking CREATE PROJECT. Provide a project name (e.g. Atolio) and select the correct Organization and Location. Note the Project ID field displayed below the Project name. You’ll need this value when setting up Terraform later. Click CREATE.

This project will be used to create credentials for the Google OAuth Client (for authenticating Atolio users) and to create necessary resources to (allow) access to the Google Workspace by the Atolio stack later on.

Create the Google OAuth Client using the following steps:

1. Visit https://console.cloud.google.com/apis/credentials/consent to set up the OAuth consent screen.
2. Select Internal for User Type and click CREATE.
3. Provide Atolio for the App name and enter email addresses for both support and developer contact information.
4. Press SAVE AND CONTINUE.
5. In the next Scopes screen there is no need for changes, just click SAVE AND CONTINUE again.
6. Review your changes in the next Summary screen and click BACK TO DASHBOARD.

The OAuth credentials (client ID and secret) can now be created by:

1. Navigating to https://console.cloud.google.com/apis/credentials and clicking CREATE CREDENTIALS in the top menu bar.
2. Then select OAuth client ID from the drop down menu.
3. For application type on the next screen choose Web application and fill out the rest of the form as shown in the table below (using your own domain name instead of the example).
4. Click CREATE. The OAuth client will be created providing you with a Client ID and Secret.
5. Download the JSON file.

The client ID and secret which will be needed later in the deployment process as described below. We recommend storing this information in a safe place (e.g. 1Password secure note) to be shared with your Deployment Engineer.

Setup Google Connector

Once your Atolio infrastructure has been deployed, you will also need to setup the Google Connector so that Atolio can resolve each signed-in user to their Atolio identity and user mappings.

1.2 - Keycloak

Configure Keycloak as your identity provider for user authentication. Atolio signs users in using the OpenID Connect authorization code flow against a client you create in your Keycloak realm.

Create OIDC Client

Note: The instructions in this section are only needed when Keycloak is used for authentication of the Atolio web application.

1. Sign in to the Keycloak admin console and select the realm your users authenticate against from the realm selector in the top-left.
2. Navigate to “Clients” and click “Create client”.
3. Leave “Client type” set to “OpenID Connect”, enter a “Client ID” (e.g. atolio), and click “Next”.
4. Turn on “Client authentication” so the client is confidential and issues a client secret. Leave “Standard flow” enabled under “Authentication flow”; the other flows are not required. Click “Next”.
5. Under “Valid redirect URIs”, add https://search.example.com/auth/_callback (replace search.example.com with your actual Atolio deployment URL; contact your Atolio onboarding support team if you need clarification on the correct URL).
6. (Optional) Set “Valid post logout redirect URIs” and “Web origins” to https://search.example.com to scope sign-out and CORS to your deployment.
7. Click “Save”.
8. Open the “Credentials” tab and copy the “Client secret”. Save it for later.

The profile and email scopes are part of Keycloak’s default client scopes, so the realm already returns the claims Atolio needs. No custom scope or mapper configuration is required.

Provide Configuration

Provide the following values to your Deployment Engineer to complete OIDC configuration. We recommend storing these in a safe place (e.g. a 1Password secure note).

• Issuer URL, the realm issuer in the form https://keycloak.example.com/realms/<realm> (replace the host and <realm> with your values)
• Client ID, the client identifier created above (e.g. atolio)
• Client Secret, the secret copied from the “Credentials” tab

Setup Keycloak Connector

Once your Atolio infrastructure has been deployed, you will also need to setup the Keycloak Connector so that Atolio can resolve each signed-in user to their Atolio identity and user mappings.

1.3 - Microsoft Entra ID

Configure Microsoft Entra ID as your identity provider for user authentication. This App Registration is specifically for authentication purposes and user/group identity mapping.

Create New App Registration

1. Authenticate to the Azure Portal via your Microsoft Identity.
2. Head over to App Registrations.
3. Click “New Registration”:
   • Enter “Atolio Authentication” for the name.
   • Ensure “Accounts in this organizational directory only” is selected from Supported account types.
   • Add a redirect URI https://search.example.com/auth/_callback (replace search.example.com with your actual Atolio deployment URL - contact your Atolio onboarding support team if you need clarification on the correct URL).
   • Click “Register”.
4. You should now be on the page of your new app registration. In the Essentials blade, locate the “Add a certificate or secret” link.
5. Create a Client Secret for use with OIDC:
   • Select the “Client Secrets (0)” tab.
   • Click “New Client Secret”.
   • Enter “Atolio OIDC Authentication” for the description.
   • Set desired expiry. Follow internal procedures for rotation.
   • Copy the newly created “Value” of the Client Secret and store it in a safe place (e.g. 1Password). This will be referenced later for OIDC configuration.
6. Add a certificate for client authentication:
   • Obtain a .PFX file that includes the public and private keys. The certificate key algorithm must be RSA. A private key password is optional, but recommended.
   • Export the public key to a .CER file.
   • Select the “Certificates (0)” tab.
   • Click “Upload certificate”.
   • Enter “Atolio Client Authentication” for the description.
   • Select the .CER file and select “Add”.
   • Export the .PFX file contents to base 64 and store it in a safe place (e.g. 1Password). You can obtain the base 64 encoding from the command line with cat my-cert.pfx | base64. This value will be referenced later for source configuration.
7. Add Microsoft Graph API Permissions:
   • In your App Registration, click “API permissions” in the left menu
   • Click “Add a permission”
   • Select “Microsoft Graph”
   • Click “Application permissions” (not Delegated permissions)
   • Add these permissions:

*Optional: You can omit Directory.Read.All and set disable_full_permissions: true in your configuration for more restrictive access.

⚠️ Important: This App Registration should only contain the directory permissions listed above. Do not add content source permissions (Files, Sites, Teams, etc.) to this registration.

8. Grant Admin Consent:

   • Click “Grant admin consent for [your tenant name]” at the top of the API permissions page
   • Confirm by clicking “Yes”
   • Verify all permissions show “Granted for [your tenant name]” with green checkmarks

9. Finally, revisit the app registration Overview and copy the Directory (tenant) ID as well as the Application (client) ID. These will be used later when configuring Entra ID authentication.

Sample Configuration

Here’s a complete YAML configuration example for Entra ID as an identity provider:

connector: microsoft
source: entraid
common:
  enabled: true
  identity-provider: true     # This is the identity provider
  cron-spec: "0 */1 * * *"   # Sync users/groups every hour
secrets:
  client_secret:
    value: "<CLIENT_SECRET_VALUE>"  # From step 5 above
  client_cert:
    value: "<BASE64_ENCODED_PFX_CONTENT>"  # From step 6 above
  client_cert_password:
    value: "<CERTIFICATE_PASSWORD>"  # Optional if no password set
configuration:
  client-id: "<APPLICATION_CLIENT_ID>"      # From step 7 above
  tenant-id: "<DIRECTORY_TENANT_ID>"        # From step 7 above
  disable_full_permissions: true           # Optional: reduces required permissions

Configuration Notes:

• identity-provider: true - Marks this as the identity provider source
• client_secret - Required for OIDC authentication flow
• client_cert - Required for Microsoft Graph API access to sync users/groups
• disable_full_permissions: true - Omits Directory.Read.All permission if you prefer more restrictive access

Important: Separate App Registrations for Content Sources

This App Registration is specifically for authentication and identity provider purposes.

For security and scalability best practices, create separate App Registrations for each Microsoft content source (SharePoint, Teams, OneDrive, Outlook) you plan to configure. Each content source should have its own dedicated App Registration with only the minimum permissions required.

See the individual connector documentation:

• SharePoint Connector
• Teams Connector
• OneDrive Connector
• Outlook Connector

1.4 - Okta

Create OAuth Client

Note: The instructions in this section are only needed when Okta is used for authentication of the Atolio web application.

1. Navigate to Applications in the Okta admin console (https://example.okta.com/admin/apps/active).
2. Click “Create App Integration”.
3. Select “OIDC - OpenID Connect” from the list of Sign-in methods.
4. Select “Web Application” from the list of Application types and hit “Next” to create the app.
5. (Optional) Edit the name and provide the Atolio logo for the app.
6. Under “Grant type” –> “Client acting on behalf of a user”, ensure that “Authorization Code” is enabled.
7. Under “Sign-in redirect URIs”, add the URL https://search.example.com/auth/_callback (note this is identical for Google).
8. Under “Sign-out redirect URIs”, remove the default http://localhost:8080 URI.
9. Under “Assignments”, choose who should have access to the Atolio app. This setting can be modified later. If you choose to “Skip group assignment for now”, remember to add yourself to the Assignments list in order to be able to sign-in.
10. Click “Save”.
11. Under “Client Credentials”, copy the “Client ID” & “Client Secret” and save them for later.

Setup Okta Connector

Once your Atolio infrastructure has been deployed, you will also need to setup the Okta Connector to enable users and user mappings using an API token.

2 - Connectors

Note: Configuration of sources is regularly evolving and curretly requires access to the kubernetes custer. This document covers responsibilities shared by both the Deployment Engineer and Admin.

Atolio can be configured to index content across a variety of sources. This document describes the steps required in both the source systems and within Atolio:

1. First, follow the steps required in the source system (links provided below).
2. Then, provide the necessary configuration to your Deployment Engineer in order to setup the Atolio connector in your environment as outlined in Atolio Configuration.

Atolio Configuration

All source configuration in Atolio is currently performed by your Deployment Engineer. It is accomplished using atolioctl which is a terminal based UI (TUI) that allows your Deployment Engineer to configure all available sources. In the future, this interface will be a browser-based IT Administrator function.

Installing atolioctl

Atolio provides an installer script within the lumen-infra repository that will automatically grab the latest version of atolioctl and install it locally.

Note: The installer script requires that you have curl or wget installed:

• curl
• wget

1. Navigate to the lumen-infra repository and into the scripts directory

cd lumen-infra/deploy/terraform/scripts

2. Run the installer script

./get-atolioctl.sh

3. From there, you should be able to run the tool: atolioctl --help

You can re-run this script to download the latest version of atolioctl or run the script with the --version flag to install a specific version of atolioctl, ex:

./get-atolioctl.sh --version 4.10.2

Deploying Connectors

Prior to configuring a source, the connector (ie the deployment in which the source will run on) must be deployed. Atolio uses the concept of instances to support one or more instances of a source (eg multiple tenants), and the creation of these deployments is managed by modifying values-lumen.yaml. Specify connectors like so:

connectors:
  microsoft:
    default:
      enabled: true
  okta:
    default:
      enabled: true
  jiracloud:
    default:
      enabled: true

Connectors are deployed under a default instance. This is an identifier which can be changed as desired, and multiple connectors can be deployed under different instances. Once the instance is set, it should be treated immutable. Modifying this value will result in loss of data and a need to re-index under the new instance. This is due to the instance being part of every resource identifier ingested by Atolio.

  jiracloud:
    internal:
      enabled: true
    external:
      enabled: true

Customizing Connector Deployments

The above YAML examples are the minimal definitions required to deploy a connector to your Atolio cluster. There are additional properties that can be set in your values-lumen.yaml file as directed by your Atolio support team to apply different options. For example:

connectors:
  google:
    default:
      enabled: true
      lumenImageTag: 4.13.0-alpha1
      log:
        level: "debug"
      resources:
        requests:
          cpu: 500m
          memory: 2Gi
        limits:
          cpu: 1000m
          memory: 4Gi

To provision the updates into the cluster, you’d upgrade the lumen Helm chart by running create-infra.sh (recommended) or:

helm upgrade lumen-chart ../../k8s/charts/lumen --values values-lumen.yaml --values values-lumen-templated.yaml -n atolio-svc

Configuring Sources

All source configuration is accomplished through atolioctl which can be obtained through the Releases page. This is a terminal based UI (TUI) which allows an administrator to configure all available sources. In the future, this interface will be browser based.

This section details how to configure each source, including how to obtain the necessary JWT.

First an API token needs to be created for use with atolioctl. This token can be generated as follows using the config.hcl file that was used to run the create-infra.sh script:

export JWT_TOKEN=$(atolioctl connector create-jwt --raw --config-dir . "atolio:*:*:*")

Feeder exposed on Load Balancer

To run configuration, provide the configure command to atolioctl. Make sure to use the correct API host name for your deployment. Once loaded, you should see a collection of configuration options and sources in your terminal:

atolioctl configure --jwt-token-sdk ${JWT_TOKEN} --feeder-address feed.search.example.com:443

Port Forwarding (Feeder not exposed on Load Balancer)

To run configuration, port-forward 8889 from service/feeder and provide the configure command to atolioctl. Ensure the correct AWS profile is in context. Once loaded, you should see a collection of configuration options and sources in your terminal:

kubectl port-forward -n atolio-svc service/feeder 8889
atolioctl configure --jwt-token-sdk ${JWT_TOKEN} --feeder-address :8889

Note that for the time being all atolioctl commands below (unless noted otherwise) will require the port forwarding command.

Configuration Tips

To obtain source-specific information, head to source configuration and find the source you’re interested in configuring. Some tips when running atolioctl:

• Run the application in a maximized window to ensure full visibility of all information.
• Press ? to toggle the help menu / key map. You will typically use up/down arrows and <TAB> to navigate the menus.
• No data is persisted until Review & Save is selected and validation has completed. A report will be shown detailing which sources were successfully configured and which not.

YAML export/import

As a reminder, the stack is not yet running at this point. Configuration of most sources does not require an operational stack as the validation is simply making a call to the source API and there is no expectation of the source’s connector running yet. There are some exceptions (in particular Jira, Confluence, and BitBucket)

Once desired sources have been configured and the stack deployed, you can import the pre-configured file. Note at this point it’s expected Feeder is operational and port-forwarding to the service address can occur:

atolioctl configure import atolio.yaml --jwt-token-sdk ${JWT_TOKEN} --feeder-address :8889
Writing key: /lumen/connectors/github/default/github
Writing key: /lumen/connectors/linear/default/linear
Writing key: /lumen/connectors/notion/default/notion
Writing key: /lumen/connectors/slack/default/slack
Writing key: /lumen/connectors/web/default/web
Writing key: /lumen/connectors/bitbucket/default/bitbucket

Similarly, source configuration of the stack can be exported to a local file. This can be useful if wishing to view the entire configuration in a human-readable YAML file, or perhaps store a backup of the configuration in a vault like 1Password. This file will be in the same format as the one imported in the prior step, allowing a loop of export, modify, import:

atolioctl configure export --jwt-token-sdk ${JWT_TOKEN} --feeder-address :8889 atolio.yaml

Both export and import commands can also combined into a single edit command that exports the current source configuration into a text editor (specified by the EDITOR environment variable) allowing manual edits. Upon saving/closing the editor, the configuration will be imported. This command is invoked a follows:

atolioctl configure edit --jwt-token-sdk ${JWT_TOKEN} --feeder-address :8889

Common Fields: Resources

Atolio supports the ability to avoid certain content from being indexed at all. The example below shows how to specifically exclude a Jira project (with the project key “SP”).

When configuring the Jira source, enter the following in the Resources field:

project:
    excluded:
        - "SP" # The Secret Project

The excluded keyword contains a list of Jira project keys to be excluded from indexing. Similarly you can also use the included keyword to achieve the opposite (in that case only those resources that are specifically listed will be indexed, nothing else). Note that the list entries (e.g. SP in the example above) are case sensitive.

In the absence of both included (opt-in) or excluded (opt-out), everything that the credentials (e.g. API key) have access to will be indexed. Note that this is a layer on top of the permissions model provided to the source. Anything added to included will only be indexed if the underlying credentials grant the indexing job access.

This feature is supported by a majority of Atolio connectors, see each connectors respective documentation for details and scope of inclusions / exclusions.

Source Configuration

2.1 - Atlassian Bitbucket Connector

The Atlassian Bitbucket connector indexes repositories, projects, pull requests, commits, and comments across your Bitbucket instance.

The connector supports Atlassian Bitbucket Cloud.

Installing the Bitbucket App Descriptor

In order to target your specific Atolio deployment, the Atlassian Bitbucket connector requires a private listing to be installed instead of the Atlassian marketplace version. This can be disabled again after the connect app is installed.

In your Bitbucket instance:

1. Under Settings -> Workplace settings, navigate to Installed apps under the APPS AND FEATURES section.
2. After clicking Enable development mode, click the link for Install app from URL.

3. Specify the URL provided by your Deployment Engineer. It will be similar to the following with your chosen DNS name:

• https://relay.search.example.com/connectors/bitbucketcloud/default/install/atlassian-connect.json
• Note: if you have multiple Bitbucket instances, please make sure to provide the correct instance name in the URL above (i.e. default in the example).

Once the Atolio Connect app has been installed, the configuration will be stored securely in your Atolio deployment. You can now disable the development mode as needed.

2.2 - Atlassian Confluence Connector

The Atlassian Confluence connector indexes spaces, pages, and comments across your Confluence instance.

The connector supports Atlassian Confluence Cloud.

Installing the Confluence App Descriptor

In order to target your specific Atolio deployment, the Atlassian Confluence connector requires a private listing to be installed instead of the Atlassian marketplace version, as explained here. This can be disabled again after the connect app is installed.

To start, within your Confluence instance:

1. Navigate to the application management page by clicking Apps -> Manage your apps.
2. Click Settings at the bottom, then enable private listings and development mode before clicking Apply.

3. The Upload app link will now be enabled.

4. Specify the URL provided by your Deployment Engineer. It will be similar to the following with your chosen DNS name:

• https://relay.search.example.com/connectors/confluencecloud/default/install/atlassian-connect.json
• Note: if you have multiple Confluence instances, please make sure to provide the correct instance name in the URL above (i.e. default in the example).

Once the Atolio Connect app has been installed, the configuration will be stored securely in your Atolio deployment. You can now disable the development mode and private listings as needed.

(Optional) Scope Confluence indexing

If you want fine-grained control over which Confluence spaces should be indexed, provide a list of inclusions or exclusions to your Deployment Engineer: they can use the includes or excludes feature in Atolio configuration to control the relevant spaces that should be indexed.

2.3 - Atlassian Connector for Jira & Confluence Data Center

The Atlassian Connector for Jira & Confluence Data Center indexes:

• Projects, issues, comments, and attachments across your Jira instance.
• Spaces, pages, blog posts, comments, and attachments across your Confluence instance.
• Users and groups in Jira & Confluence for the purpose of understanding permissions.

The connectors authenticate to Jira and Confluence as a dedicated service user using a Personal Access Token (PAT). They run as part of your Atolio deployment — no plugin or app needs to be installed in Jira or Confluence.

Note: Earlier releases of this connector shipped as Atlassian SDK plugins (jira-dc-connector-*.jar and confluence-dc-connector-*.jar) installed via Manage apps. Clients are encouraged to migrate to the new connectors described below.

Create a Service User

In each of Jira DC and Confluence DC, create a dedicated user for Atolio to authenticate as (for example, atolio-connector-user).

You have two options for the permission scope you grant this user:

Option 1 — Administrator access (recommended for easy setup). Grant the service user administrator membership:

• In Jira, add the user to the Jira Administrators group (or an equivalent admin role).
• In Confluence, add the user to the Confluence Administrators group (or grant System Administrator).

With admin access, the connector automatically registers the webhook it needs for live updates on startup. No further setup is required in Jira or Confluence.

Option 2 — Read-only access. Grant the service user only the permissions required to read the content you want indexed:

• In Jira, grant Browse Projects on every project to be indexed (the easiest way is to add the user to the default permission scheme).
• In Confluence, grant View permission on every space to be indexed (the easiest way is to add the user to the default space permission scheme).

Read-only access means the connector cannot register its own webhook. You can either:

• Skip webhook registration entirely — the connector will still backfill and periodically resync, but changes in Jira and Confluence will not be reflected live, or
• Register the webhook manually (see Manual Webhook Setup below).

Create a Personal Access Token

For each of Jira and Confluence:

1. Log in as the service user.
2. Go to Profile → Personal Access Tokens → Create token.
3. Give the token a name (e.g. atolio-connector-token) and set an expiry if required by your policy.
4. Copy the token — this is the value you will provide to your Deployment Engineer.

Provide Configuration

Provide the following to your Deployment Engineer for each connector instance:

• base-url: the base URL of the Jira or Confluence DC instance, e.g. https://jira.example.com or https://confluence.example.com.
• personal_access_token (secret): the PAT created in the previous step.
• disable-webhook-registration: set to true if the service user is read-only or if you want to manage the webhook yourself. Defaults to false.

You can optionally restrict indexing to specific projects (Jira) or spaces (Confluence) via the resources field — see Common Fields: Resources.

Manual Webhook Setup

If the service user does not have admin permissions, or if you prefer to manage webhooks yourself, register the webhook manually after the connector is running. Set disable-webhook-registration: true in the connector configuration to prevent the connector from attempting to register one.

Jira

1. In Jira, go to Administration → System → WebHooks → Create a WebHook.
2. Set the URL to {callbackBaseURL}/connectors/jiradc/{instance}/callback, where {instance} is the connector instance name (e.g. default). Your Deployment Engineer can provide the correct callbackBaseURL.
3. Enable the following events:
   • jira:issue_created, jira:issue_updated, jira:issue_deleted
   • comment_created, comment_updated, comment_deleted
   • project_created, project_updated, project_deleted

Confluence

1. In Confluence, go to Administration → General Configuration → Webhook → Create webhook.
2. Set the URL to {callbackBaseURL}/connectors/confluencedc/{instance}/callback, where {instance} is the connector instance name (e.g. default). Your Deployment Engineer can provide the correct callbackBaseURL.
3. Enable the following events:
   • page_created, page_updated, page_removed, page_trashed, page_restored
   • blog_created, blog_updated, blog_removed, blog_trashed, blog_restored
   • comment_created, comment_updated, comment_removed
   • space_created, space_updated, space_removed

2.4 - Atlassian Jira Connector

The Atlassian Jira connector indexes projects, issues, and comments across your Jira instance.

The connector supports Atlassian Jira Cloud.

Installing the Jira App Descriptor

In order to target your specific Atolio deployment, the Atlassian Jira connector requires a private listing to be installed instead of the Atlassian marketplace version, as explained here. This can be disabled again after the connect app is installed.

To start, within your Jira instance:

1. Navigate to the application management page by clicking Apps -> Manage your apps.
2. Click Settings at the bottom, then enable private listings and development mode before clicking Apply.

3. The Upload app link will now be enabled.

4. Specify the URL provided by your Deployment Engineer. It will be similar to the following with your chosen DNS name:

• https://relay.search.example.com/connectors/jiracloud/default/install/atlassian-connect.json
• Note: if you have multiple Jira instances, please make sure to provide the correct instance name in the URL above (i.e. default in the example).

Once the Atolio Connect app has been installed, the configuration will be stored securely in your Atolio deployment. You can now disable the development mode and private listings as needed.

(Optional) Scope Jira indexing

If you want fine-grained control over which Jira projects should be indexed, provide a list of inclusions or exclusions to your Deployment Engineer: they can use the includes or excludes feature in Atolio configuration to control the relevant projects that should be indexed.

2.5 - GitHub Connector

The GitHub connector enables the indexing of pull requests, commits, comments, and markdown in your GitHub repositories.

Create Access Token

To install the GitHub connector, use a GitHub account with admin access to the organization (requires read access to teams). Using this account, create a personal access token (currently Classic only) according to these instructions. You will need to ensure repo and user scopes are set (as shown below):

Note: for GitHub Enterprise Server installations, you would need to enable the site_admin scope too.

(Optional) Create GitHub App

Note: GitHub App flow does not work with GitHub Enterprise Server installations. You would need to use a personal access token like above

Instead of using a personal access token, a GitHub app can be created to install the GitHub connector. This provide better rate limits, especially if your org is on Enterprise Cloud. You can create a GitHub app according to these instructions.

You will need to ensure the following app permissions are set:

Repository Permissions:

Organization Permissions:

Setup Webhooks

If live indexing of GitHub content is desired, you will want to setup Webhooks. Go to Settings->Webhooks->Add Webhook. After authentication, you can now setup the webhook with the following configs:

The following events are indexed at the repository level:

• Collaborator add, remove, or changed
• Commit comments
• Issues
• Issue comments
• Pull requests
• Pull requests reviews
• Pull requests reviews comments
• Pushes
• Repositories

The following events are indexed at the organization level:

• Team

Please manually check the boxes for each of the events above.

Warning: Setting up webhooks at the organization level will send webhook events for all repositories within the organization. If this is not desireable, please make changes to the configuration to only process and index specific repositories.

Provide Configuration

Provide these configuration values to your Deployment Engineer:

• OrgName should be the identifier for your org (e.g. atolio)
• ApplicationID is your GitHub app ID, can be found at your GitHub app settings page. This field only affects GitHub and GitHub Enterprise Cloud installations with no effects to GitHub Enterprise Server installations
• InstallationID is created on the first installation of the GitHub app on your org, can be found at the end of the URL for your installation: https://github.com/organizations/{ORG}/settings/installations/{INSTALLATION_ID}. This field only affects GitHub and GitHub Enterprise Cloud installations with no effects to GitHub Enterprise Server installations
• SamlAuthenticationLevel is where you enabled SAML authentication, 2 options: enterprise or org
• EnterpriseBaseURL is the hostname of your GitHub Enterprise Server instance
• EnterpriseSlug is your GitHub Enterprise name

Note: If you have many GitHub repositories, it may be worth using the includes or excludes feature in Atolio configuration to control the relevant repositories that should be indexed.

The GitHub connector provides two types of inclusion/exclusions in the resources field of the configuration as illustrated in the example below:

resources:
    repository:
        included:
            - lumen-infra
    file:
        included:
            - .md

The repository name lumen-infra in this example is the repo part in the repository’s URL (which has the following generic format: https://github.com/repos/{owner}/{repo}). The example above will only index the lumen-infra repository.

File filtering is done of the basis of file extension names (including the preceding dot .). The example above will configure the connector to index all markdown files. Note that by default file filtering is completely disabled as it is a relatively time consuming process.

Provide Secrets

Provide these secrets to your Deployment Engineer:

• WebhookSecret is the webhook secret previously created
• Token is the personal access token
• AppPrivateKey is the GitHub App private key in PEM format

(Optional) Configure GitHub user mappings

If employees have brought pre-existing GitHub accounts to their company’s GitHub organization, the identity resolver cannot automatically map them to company user identities. For this reason, the GitHub configuration contains a user mapping table. For example, the entries below map two GitHub user IDs to the user’s username (i.e. email address) in the organization:

12345678:  user1@example.com # "user1"
87654321:  user2@example.com # "user2"

The numerical GitHub ID can easily be obtained using the following: https://api.github.com/users/{USERNAME} in a browser where {USERNAME} is replaced with the GitHub username which can be found in the user’s profile (under the full name printed below the user’s avatar). The ID is in the id field of the JSON response. Adding an entry like this for every user will allow Atolio to link the GitHub user IDs to other sources.

2.6 - GitLab Connector

The GitLab connector enables indexing of merge requests, commits, and comments across your GitLab projects. Atolio supports GitLab Server (minimum version v16.5-ee) and GitLab Cloud.

Create Access Token

As an admin, perform the following steps:

• Login as admin user
• Go to https://gitlab.company.com/-/user_settings/personal_access_tokens
• Click “Add New Token”
• Give it a name and expiration date, set scope as read_api
• Copy generated token

Setup Webhooks

If live indexing of GitLab content is desired, you will want to setup Webhooks. If you have GitLab Premium you can set up webhooks for groups. If you don’t have GitLab Premium, you need to set up a webhook for each project separately.

• Go to Settings/Webhooks
• Set URL to https://relay.{search.company.com}/connectors/gitlab/{instance}/callback/gitlab
• Set a strong “secret token”
• Check “Comments”, “Issue Events” and “Merge Request Events” under Triggers
• Keep “Enable SSL verification” checked

You also need to set up system hooks for the GitLab instance. This is done by an admin user and is required for getting live project updates.

• Go to Admin Area/System Hooks
• Set URL to the same as the webhook URL
• Set secret token as the same as the webhook secret token
• Keep “Enable SSL verification” checked

Provide Configuration

With the Access Token and Webhook Secret in hand, provide these configuration values to your Deployment Engineer:

• BaseURL is left blank when using gitlab.com. For self-hosted installations specify the base URL for your instance, e.g. gitlab.example.com
• WebhookSecret is the webhook secret previously created
• Token is the personal access token

Note: If you have many GitLab projects, it may be worth using the includes or excludes feature in Atolio configuration to control the relevant projects that should be indexed.

An example inclusion/exclusion configuration will look like the following:

resources:
  group:
    included:
      - examplegroup # Index "examplegroup" from GitLab

GitLab SaaS (gitlab.com) specific configuration

If you’re using the SaaS GitLab product hosted at gitlab.com instead of a self-hosted installation you’ll need to follow the above steps to provide an inclusion filter for at least one group you’d like to index. This is necessary to prevent the connector from attempting to index the entirety of the public SaaS GitLab deployment.

Configuring GitLab user mappings

If people are using their company emails in GitLab, the identity resolver cannot automatically map them to company user identities. For this reason the GitLab configuration contains a user mapping table. For example, the entries:

'12345678':  user1@example.com
'87654321':  user2@example.com

Map two GitLab user IDs to the user’s username (i.e. email address) in the organization. The numerical GitLab ID can easily be obtained using the following URL in a browser where USERNAME is replaced with the GitLab username. The ID is in the id field of the JSON response. On the command this can be obtained by using curl and jq as follows (using the user ID USERNAME in this example):

curl 'https://gitlab.company.com/api/v4/users?access_token=ACCESS_TOKEN&search=USERNAME' | jq '.[0].id'

Adding an entry like this for every user will allow Atolio to link the GitLab user IDs to other sources.

2.7 - Google Connector

The Google connector enables the indexing of:

• Documents, Sheets, Slides, and other Files in Google Drive
• Email in Gmail
• Pages in Google Sites
• Users and Groups as metadata in your Google Workspace to enable user mapping / permissions

Content and updates are streamed as changes are detected and processed in your Google Workspace.

Step 0: Create Terraform Service Account for Google

Note: Depending on installation being BYOK, Managed, or otherwise this step may be skipped. Consult with an Atolio Support Engineer for any clarification.

Terraform will need a service account to make changes to your GCP project. We will grant it permissions which will essentially allow it to create, read, and delete all project resources. As such, you should keep the credentials for this account safe and not reuse them. The Terraform scripts create a much more restricted service account for normal operation.

1. Visit the IAM Service Accounts page https://console.cloud.google.com/iam-admin/serviceaccounts and select the project created previously to set up the Terraform service account.
2. Click CREATE SERVICE ACCOUNT
3. Choose a name. While it can be anything, the name “Atolio Terraform” is recommended.
4. Select CREATE AND CONTINUE.
5. Grant the following roles: “Owner”, “Security Center Admin”, “Project IAM Admin” (without conditions).
6. Click DONE. Skip step 5, you will not need to grant other users access to this service account.

Now the service account is created we can create API keys:

1. Navigate to https://console.cloud.google.com/iam-admin/serviceaccounts and select the project created previously.
2. Click the service user that was created in the previous step.
3. Select the KEYS tab click the ADD KEY pull-down menu
4. Select Create new key and use JSON for key type. Click CREATE.

This will create another JSON file with the API key and related information. This file will be needed by your Deployment Engineer (in their deploy/terraform directory).

In order for Terraform to programmatically make modifications, you need to manually enable the Google Cloud Resource Manager API.

1. Navigate to https://console.cloud.google.com/apis/library
2. Search for “Cloud Resource Manager API”
3. Select “Cloud Resource Manager API”. Click ENABLE.

The project will use additional APIs, but now that this API is available to Terraform, the Atolio deployment scripts will use Terraform to enable those APIs automatically.

Step 1: Grant Service Account Permissions

The Google Workspace domain needs to grant permission to the integration’s default service account to perform operations. Unfortunately Terraform can’t automate this, so it has to be performed manually.

Your Deployment Engineer will need to make note of the unique ID for the default App Engine service account and the list of scopes. Be aware that this ID is of the default service account, typically named App Engine default service account. It is not the Service Account you’ve previously created.

And the list of scopes are:

https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/calendar.readonly,https://www.googleapis.com/auth/drive.readonly,https://www.googleapis.com/auth/admin.directory.domain.readonly,https://www.googleapis.com/auth/drive.activity.readonly

We now need to set up Domain-wide Delegation:

1. Navigate to the Google Admin console: https://admin.google.com/ac/owl. An account with admin access is required.
2. Scroll down and click “MANAGE DOMAIN WIDE DELEGATION”.
3. Click Add new and enter your service account client ID (obtained from your Deployment Engineer in the previous step). No overwrite.
4. Enter the value for google_service_account_id as obtained from your Deployment Engineer.
5. Enter the list of scopes as listed above (as a single comma-delimited string).
6. Click AUTHORIZE.

Now Atolio is authorized to retrieve Google Workspace data.

Step 2: Deploy the Connector

Before the source can be configured, the connector pod must be running in the cluster. Connectors are deployed by enabling them in values-lumen.yaml. See Deploying Connectors for the full details, including how instances work.

connectors:
  google:
    default:
      enabled: true

default is the instance identifier. Treat it as immutable once set, because the instance is part of every resource identifier the connector ingests. Apply the change by upgrading the lumen Helm chart with create-infra.sh (recommended) or helm upgrade as described in the sources overview.

Step 3: Configure the Source

Source configuration is applied with atolioctl using a YAML file. If you have not already installed atolioctl, follow Configuring Sources first. The commands below also need an API token in JWT_TOKEN and the address the feeder server’s gRPC endpoint, both described next.

atolioctl Prerequisites

JWT_TOKEN holds the API token atolioctl uses to authenticate to the feeder. Generate one from the deployment’s Helm values directory, which holds the values-lumen.yaml and values-lumen-templated.yaml files produced by create-infra.sh. The token is signed with the deployment’s jwtSecretKey, and the atolio:*:*:* match pattern grants access across all connectors, instances, and resources:

export JWT_TOKEN=$(atolioctl connector create-jwt --raw --config-dir . "atolio:*:*:*")

--feeder-address is the gRPC address of the feeder server that is used to read and write source configuration through. The standard path is to port-forward the in-cluster service/feeder and point atolioctl at it on localhost:

# Run K8s port forward to feeder as background to re-use same shell
kubectl port-forward -n atolio-svc service/feeder 8889 &

With that port-forward running in current terminal or another, the examples below use --feeder-address :8889. The empty host means localhost, and because the port is not 443 the connection is made in plaintext, which is what the port-forward exposes. If the feeder is instead published on a load balancer, pass that address with port 443, for example --feeder-address feed.search.example.com:443, which connects over TLS.

Edit and Apply the Configuration

Source configuration is stored as a single document that covers every configured connector. The supported workflow is to export the current configuration, edit it, then import it back. Always start from a fresh export so you do not overwrite a change made elsewhere.

Export the current configuration to a local file:

atolioctl configure export --jwt-token-sdk ${JWT_TOKEN} --feeder-address :8889 lumen-connectors.yaml

Add a Google entry alongside the connectors already in the file, substituting the values you collected in Step 1:

connectors:
  # ...existing connectors left in place...
  google:
    default:
      google:
        connector: google
        instance: default
        source: google
        common:
          enabled: true
          identity-provider: true      # This connector is the identity provider
          cron-spec: 0 7 * * *         # Re-sync users on this schedule
        secrets:
          service_account_key:
            value: "<GOOGLE_SERVICE_ACCOUNT_B64>"
        configuration:
          parallelism: 0
          project-id: "<GOOGLE_PROJECT_ID>"
          service-user: "<GOOGLE_SERVICE_USER>"

Exported entries also carry a rendezvous-completed flag and a status block reporting each source’s current state and last validation result. Those fields are managed by Atolio. Leave them untouched on existing entries, and omit them when adding a new entry by hand as shown above.

Import the edited file to write the configuration back into the stack:

atolioctl configure import lumen-connectors.yaml --jwt-token-sdk ${JWT_TOKEN} --feeder-address :8889

Import writes the configuration into the stack after checking that the YAML is well formed. It does not contact Google. The connector validates the credentials and connection itself when it starts and picks up the configuration, and it reads users after that. If something is wrong, the source reports as misconfigured and the connector pod logs the error. See Troubleshooting for the specific messages.

Configuration Schema

In the exported file, every source lives at connectors.<connector>.<instance>.<source>, so the Google source sits at connectors.google.default.google.

GoogleSourceConfiguration

Google Workspace connector configuration.

Common

Common settings shared across all connectors.

Secrets

Sensitive configuration values for authentication.

SecretValue

A reference to a secret value.

Configuration

Google Workspace connector-specific configuration.

2.7.1 - Gmail Connector Setup

Installing the Gmail Connector

Note: For this step, your deployment engineer will be required.

The Gmail and Google Drive connectors depend on a shared Google Workspace configuration section. Google Workspace requires three properties to be set during configuration:

• ProjectID must reference the project created in GCP. The id, not the name, must be specified.
• ServiceUser is currently a reference to a super user or administrator within your organization. For example, the primary IT email. This may change in the future.
• ServiceAccountKey is the base64-encoded string as obtained during initial install of the Google source.

To obtain the service account key, your deployment engineer will run the following Terraform command:

terraform output -raw google_connector_service_account_key

And optionally:

• Domains is a comma-delimited list of domains applicable to this deployment.
• Parallelism is an optimization to increase the concurrency with respect to indexing Google data. Default is 32, so if set, should be higher than this value.

Once the Google source is configured, the Google Drive and Gmail sources can be configured with the same values.

Configuration

Source configuration is applied with atolioctl using a YAML file. If you have not already installed atolioctl, follow Configuring Sources first. The commands below also need an API token in JWT_TOKEN and the address the feeder server’s gRPC endpoint, both described next.

Edit and Apply the Configuration

Source configuration is stored as a single document that covers every configured connector. The supported workflow is to export the current configuration, edit it, then import it back. Always start from a fresh export so you do not overwrite a change made elsewhere.

Export the current configuration to a local file:

atolioctl configure export --jwt-token-sdk ${JWT_TOKEN} --feeder-address :8889 lumen-connectors.yaml

Add a Google entry alongside the connectors already in the file, substituting the values you collected in Step 1:

connectors:
  # ...existing connectors left in place...
  google:
    default:
      # ...existing Google sub-connectors left in place...
      gdrive:
        connector: google              # Reference to parent connector, usually Google
        instance: default
        source: gmail
        common:
          enabled: true
          identity-provider: false     # This connector is a workspace tool, not IDP
        secrets:
          service_account_key:
            value: "<GOOGLE_SERVICE_ACCOUNT_B64>"
        configuration:
          parallelism: 0
          drive-contrib-hydration-method: activity
          project-id: "<GOOGLE_PROJECT_ID>"
          service-user: "<GOOGLE_SERVICE_USER>"

Exported entries also carry a rendezvous-completed flag and a status block reporting each source’s current state and last validation result. Those fields are managed by Atolio. Leave them untouched on existing entries, and omit them when adding a new entry by hand as shown above.

Import the edited file to write the configuration back into the stack:

atolioctl configure import lumen-connectors.yaml --jwt-token-sdk ${JWT_TOKEN} --feeder-address :8889

Import writes the configuration into the stack after checking that the YAML is well formed. It does not contact Google. The connector validates the credentials and connection itself when it starts and picks up the configuration, and it reads users after that. If something is wrong, the source reports as misconfigured and the connector pod logs the error. See Troubleshooting for the specific messages.

Configuration Schema

In the exported file, every source lives at connectors.<connector>.<instance>.<source>, so the Gmail source sits at connectors.google.default.gmail.

GmailSourceConfiguration

Gmail connector configuration.

Common

Common settings shared across all connectors.

Secrets

Sensitive configuration values for authentication.

SecretValue

A reference to a secret value.

GmailConfiguration

Gmail-specific connector configuration.

2.7.2 - Google Drive Connector Setup

Installing the Google Drive Connector

Note: For this step, your deployment engineer will be required.

The Gmail and Google Drive connectors depend on a shared Google Workspace configuration section. Google Workspace requires three properties to be set during configuration:

• ProjectID must reference the project created in GCP. The id, not the name, must be specified.
• ServiceUser is currently a reference to a super user or administrator within your organization. For example, the primary IT email. This may change in the future.
• ServiceAccountKey is the base64-encoded string as obtained during initial install of the Google source.

To obtain the service account key, your deployment engineer will run the following Terraform command:

terraform output -raw google_connector_service_account_key

And optionally:

• Domains is a comma-delimited list of domains applicable to this deployment.
• Parallelism is an optimization to increase the concurrency with respect to indexing Google data. Default is 32, so if set, should be higher than this value.

Once the Google source is configured, the Google Drive and Gmail sources can be configured with the same values.

Configuration

Source configuration is applied with atolioctl using a YAML file. If you have not already installed atolioctl, follow Configuring Sources first. The commands below also need an API token in JWT_TOKEN and the address the feeder server’s gRPC endpoint, both described next.

Edit and Apply the Configuration

Source configuration is stored as a single document that covers every configured connector. The supported workflow is to export the current configuration, edit it, then import it back. Always start from a fresh export so you do not overwrite a change made elsewhere.

Export the current configuration to a local file:

atolioctl configure export --jwt-token-sdk ${JWT_TOKEN} --feeder-address :8889 lumen-connectors.yaml

Add a Google entry alongside the connectors already in the file, substituting the values you collected in Step 1:

connectors:
  # ...existing connectors left in place...
  google:
    default:
      # ...existing Google sub-connectors left in place...
      gdrive:
        connector: google              # Reference to parent connector, usually Google
        instance: default
        source: gdrive
        common:
          enabled: true
          identity-provider: false     # This connector is a workspace tool, not IDP
        secrets:
          service_account_key:
            value: "<GOOGLE_SERVICE_ACCOUNT_B64>"
        configuration:
          parallelism: 0
          drive-contrib-hydration-method: activity
          project-id: "<GOOGLE_PROJECT_ID>"
          service-user: "<GOOGLE_SERVICE_USER>"

Exported entries also carry a rendezvous-completed flag and a status block reporting each source’s current state and last validation result. Those fields are managed by Atolio. Leave them untouched on existing entries, and omit them when adding a new entry by hand as shown above.

Import the edited file to write the configuration back into the stack:

atolioctl configure import lumen-connectors.yaml --jwt-token-sdk ${JWT_TOKEN} --feeder-address :8889

Import writes the configuration into the stack after checking that the YAML is well formed. It does not contact Google. The connector validates the credentials and connection itself when it starts and picks up the configuration, and it reads users after that. If something is wrong, the source reports as misconfigured and the connector pod logs the error. See Troubleshooting for the specific messages.

Configuration Schema

In the exported file, every source lives at connectors.<connector>.<instance>.<source>, so the Google Drive source sits at connectors.google.default.gdrive.

GoogleDriveSourceConfiguration

Google Drive connector configuration.

Common

Common settings shared across all connectors.

Secrets

Sensitive configuration values for authentication.

SecretValue

A reference to a secret value.

GDriveConfiguration

Google Drive-specific connector configuration.

2.7.3 - Google Sites Connector Setup

Installing the Google Sites Connector

Note: For this step, your deployment engineer will be required.

Prerequisites

Google Sites Connector requires you to enable Google Vault for your organization. Google Vault enrollment details are available in the official documentation

You will need a Service Account as described in Grant Service Account Permissions section. In addition to the scopes listed there, you must grant the following scopes to the Service Account:

- https://www.googleapis.com/auth/ediscovery
- https://www.googleapis.com/auth/devstorage.read_only

Vault API access must be manually enabled by the GCP project associated with the Service Account. This can be done via GCP API Console, by following the steps in the official documentation.

Configuration

Source configuration is applied with atolioctl using a YAML file. If you have not already installed atolioctl, follow Configuring Sources first. The commands below also need an API token in JWT_TOKEN and the address the feeder server’s gRPC endpoint, both described next.

Edit and Apply the Configuration

Source configuration is stored as a single document that covers every configured connector. The supported workflow is to export the current configuration, edit it, then import it back. Always start from a fresh export so you do not overwrite a change made elsewhere.

Export the current configuration to a local file:

atolioctl configure export --jwt-token-sdk ${JWT_TOKEN} --feeder-address :8889 lumen-connectors.yaml

Add a Google entry alongside the connectors already in the file, substituting the values you collected in Step 1:

connectors:
  # ...existing connectors left in place...
  google:
    default:
      # ...existing Google sub-connectors left in place...
      gsites:
        connector: google              # Reference to parent connector, usually Google
        instance: default
        source: gsites
        common:
          enabled: true
          identity-provider: false     # This connector is a workspace tool, not IDP
        secrets:
          service_account_key:
            value: "<GOOGLE_SERVICE_ACCOUNT_B64>"
        configuration:
          service-user: "<GOOGLE_SERVICE_USER>"
          site-urls:
            - https://sites.google.com/your-org/your-site
          site-configs:
            https://sites.google.com/your-org/your-site
              # If you have a custom domain for your Google Site, specify it here.
              top-level-url: https://your-custom-domain.com/path

              # If you want to configure deeplinks for each page, 
              # you can do it by providing a "page name" -> "URL suffix" map here.
              # 
              # For a page titled "Home", the deeplink would be:
              # https://your-custom-domain.com/path/home
              page-name-to-url-suffix:
                Home: /home
                About: /about
              
              # If you have setup "Restricted" access for your site, specify it here. 
              # Default is `false`.
              restricted: true

If you do not prefer to have a static configuration for deeplinks, you can also provide a “url path” on each Google Site page. Simply add a text in the form of urlpath:[/relative-path-to-your-page] in the body of each page, and Atolio will index the page with the user-provided deeplink.

Exported entries also carry a rendezvous-completed flag and a status block reporting each source’s current state and last validation result. Those fields are managed by Atolio. Leave them untouched on existing entries, and omit them when adding a new entry by hand as shown above.

Import the edited file to write the configuration back into the stack:

atolioctl configure import lumen-connectors.yaml --jwt-token-sdk ${JWT_TOKEN} --feeder-address :8889

Import writes the configuration into the stack after checking that the YAML is well formed. It does not contact Google. The connector validates the credentials and connection itself when it starts and picks up the configuration, and it reads users after that. If something is wrong, the source reports as misconfigured and the connector pod logs the error. See Troubleshooting for the specific messages.

Configuration Schema

In the exported file, every source lives at connectors.<connector>.<instance>.<source>, so the Google Sites source sits at connectors.google.default.gsites.

GoogleSitesSourceConfiguration

Google Sites connector configuration.

Common

Common settings shared across all connectors.

Secrets

Sensitive configuration values for authentication.

SecretValue

A reference to a secret value.

GSitesConfiguration

Google Sites-specific connector configuration.

SiteConfig

Per-site configuration for Google Sites.

2.8 - Keycloak Connector

The Keycloak connector reads the users in a realm so that Atolio can resolve each signed-in identity to an Atolio user. Every user is ingested under their Keycloak user ID, which is the same identifier Keycloak puts in the sub claim of an OIDC token. That match is what lets Atolio connect a login back to the right user.

Note: As part of Atolio Configuration, this connector should be selected as Identity Provider if it is used to resolve app-user mappings. Point it at the same realm your users authenticate against in Keycloak authentication.

Setting up the connector takes three steps:

1. Create a read-only service account in Keycloak (done by your Keycloak admin).
2. Deploy the connector pod into the Atolio cluster (done by your Deployment Engineer).
3. Configure the source with atolioctl (done by your Deployment Engineer).

Step 1: Create a Service Account in Keycloak

The connector talks to the Keycloak Admin REST API as a realm user, so we recommend creating a dedicated service account rather than using a personal admin account. The connector only reads users; it does not write to Keycloak or read any other resource.

1. In the admin console, select your realm and create a user under “Users” (e.g. atolio-connector).
2. On the new user’s “Credentials” tab, set a password and turn off “Temporary” so it does not expire on first use.
3. On the “Role mapping” tab, click “Assign role”, filter by clients, and assign the view-users role from realm-management. This is the lowest-privilege role that lets the connector list users in the realm.

The connector authenticates with this username and password against the realm’s built-in admin-cli client using the OAuth2 password grant, then refreshes the resulting token as needed. No additional client setup is required, since admin-cli exists in every realm by default.

Note: view-users is scoped to the realm you assign it in. If your users live in more than one realm, deploy a connector instance per realm, each with its own service account. If you rotate the service account’s password in Keycloak, update the password secret (Step 3) so the connector can keep authenticating.

Collect these values to use in the following steps:

Step 2: Deploy the Connector

Before the source can be configured, the connector pod must be running in the cluster. Connectors are deployed by enabling them in values-lumen.yaml. See Deploying Connectors for the full details, including how instances work.

connectors:
  keycloak:
    default:
      enabled: true

default is the instance identifier. Treat it as immutable once set, because the instance is part of every resource identifier the connector ingests. Apply the change by upgrading the lumen Helm chart with create-infra.sh (recommended) or helm upgrade as described in the sources overview.

Step 3: Configure the Source

Source configuration is applied with atolioctl using a YAML file. If you have not already installed atolioctl, follow Configuring Sources first. The commands below also need an API token in JWT_TOKEN and the address the feeder server’s gRPC endpoint, both described next.

atolioctl Prerequisites

JWT_TOKEN holds the API token atolioctl uses to authenticate to the feeder. Generate one from the deployment’s Helm values directory, which holds the values-lumen.yaml and values-lumen-templated.yaml files produced by create-infra.sh. The token is signed with the deployment’s jwtSecretKey, and the atolio:*:*:* match pattern grants access across all connectors, instances, and resources:

export JWT_TOKEN=$(atolioctl connector create-jwt --raw --config-dir . "atolio:*:*:*")

--feeder-address is the gRPC address of the feeder server that is used to read and write source configuration through. The standard path is to port-forward the in-cluster service/feeder and point atolioctl at it on localhost:

# Run K8s port forward to feeder as background to re-use same shell
kubectl port-forward -n atolio-svc service/feeder 8889 &

With that port-forward running in current terminal or another, the examples below use --feeder-address :8889. The empty host means localhost, and because the port is not 443 the connection is made in plaintext, which is what the port-forward exposes. If the feeder is instead published on a load balancer, pass that address with port 443, for example --feeder-address feed.search.example.com:443, which connects over TLS.

Edit and Apply the Configuration

Source configuration is stored as a single document that covers every configured connector. The supported workflow is to export the current configuration, edit it, then import it back. Always start from a fresh export so you do not overwrite a change made elsewhere.

Export the current configuration to a local file:

atolioctl configure export --jwt-token-sdk ${JWT_TOKEN} --feeder-address :8889 lumen-connectors.yaml

Add a Keycloak entry alongside the connectors already in the file, substituting the values you collected in Step 1:

connectors:
  # ...existing connectors left in place...
  keycloak:
    default:
      keycloak:
        connector: keycloak
        instance: default
        source: keycloak
        common:
          enabled: true
          identity-provider: true      # This connector is the identity provider
          cron-spec: 0 7 * * *         # Re-sync users on this schedule
        secrets:
          password:
            value: "<SERVICE_ACCOUNT_PASSWORD>"
        configuration:
          base_url: https://keycloak.example.com
          realm: employees
          username: atolio-connector

Exported entries also carry a rendezvous-completed flag and a status block reporting each source’s current state and last validation result. Those fields are managed by Atolio. Leave them untouched on existing entries, and omit them when adding a new entry by hand as shown above.

Import the edited file to write the configuration back into the stack:

atolioctl configure import lumen-connectors.yaml --jwt-token-sdk ${JWT_TOKEN} --feeder-address :8889
Writing key: /lumen/connectors/keycloak/default/keycloak

Import writes the configuration into the stack after checking that the YAML is well formed. It does not contact Keycloak. The connector validates the credentials and connection itself when it starts and picks up the configuration, and it reads users after that. If something is wrong, the source reports as misconfigured and the connector pod logs the error. See Troubleshooting for the specific messages.

Configuration Schema

In the exported file, every source lives at connectors.<connector>.<instance>.<source>, so the Keycloak source sits at connectors.keycloak.default.keycloak.

KeycloakSourceConfiguration

Keycloak connector configuration for user identity mapping.

Common

Common settings shared across all connectors.

Secrets

Sensitive configuration values for authentication.

SecretValue

A reference to a secret value.

KeycloakConfiguration

Keycloak-specific connector configuration.

Troubleshooting

Almost all errors surface in the connector pod logs, not in the atolioctl output. The import command only checks that the YAML is well formed before writing it to the stack, so a malformed file is the one thing it catches directly. Everything else is reported by the connector as it runs through its lifecycle.

The connector validates first. When it starts and picks up the configuration, it logs in to Keycloak to check the credentials and connection. If that fails, the source moves to a misconfigured state and stops before reading any users. Once validation passes, the connector lists users during its first sync, which is where a missing role shows up. Use the lifecycle phase in the table below to tell the two apart.

2.9 - Linear Connector

The Linear connector indexes teams, projects, issues, and comments across your Linear workspace.

Note: Atolio currently uses an API key for this connector, but will support a published Integration in a future release.

Create the Linear API key & Webhooks

As an administrator:

1. Navigate to Workspace Settings by selecting your tenant and choosing Preferences.
2. Under My Account, click on API.

To create an API key, complete the following steps: 3. Under Personal API keys, provide a Label in the text box, e.g. Atolio. 4. Click on Create new API key. 5. Copy the value of the key to securely share with your Deployment Engineer.

To create a Webhook, complete the following steps: 6. Under Webhooks, click on Create new webhook. 7. Provide a Label in the text box, e.g. Atolio. 8. For URL, specify the URL provided by your Deployment Engineer. It will be similar to the following with your chosen DNS name:

• https://relay.search.example.com/connectors/linear/default/callback/linear
• Note: if you have multiple Linear instances, please make sure to provide the correct instance name in the URL above (i.e. default in the example).

9. Under Data change events, ensure the following are checked:
   • Issues
   • Projects
   • Comments
10. Copy the value of the Signing secret to securely share with your Deployment Engineer.
11. Click on Create webhook to finalize the creation of this webhook.

Provide Configuration

Once the API key and Webhook have been created, provide these configuration values to your Deployment Engineer:

• UrlKey is the name of your Linear workspace.
• Token is the personal access token.
• WebhookSecret is the webhook secret.

2.10 - Microsoft Connectors

The Microsoft connectors support:

• Entra ID - for resolving user mappings across apps as an Identity Provider
• SharePoint - for indexing sites, docs, spreadsheets, slides, and other files
• Teams - for indexing channels, chat, and messages
• OneDrive - for indexing docs, spreadsheets, slides, and other files
• Outlook - for indexing emails and calendar events

Security Best Practice: Separate App Registrations

We recommend creating separate App Registrations for each Microsoft source you plan to use. This follows the principle of least privilege and provides:

• Reduced attack surface - Each connector only has the minimum permissions required
• Better audit trails - Azure logs can isolate which application accessed which data
• Independent lifecycle management - Rotate certificates, disable connectors, or modify permissions without affecting other sources
• Granular admin consent - Security teams can approve smaller, focused permission requests
• Independent rate limits - Each App Registration has separate Microsoft Graph API rate limits, preventing sources from competing for shared quotas in large environments

Architecture Options

Choose the approach that best fits your organization’s security and scale requirements:

Option 1: Separate App Registration per Source (Recommended)

Create individual App Registrations for:

• Entra ID (if using as identity provider)
• SharePoint
• Teams
• OneDrive
• Outlook

Each registration gets only the permissions needed for that specific source.

Option 2: Single Shared App Registration (Evaluation Only)

Use one App Registration for all sources. This requires the superset of all permissions and is not recommended for production environments due to security and rate limiting concerns.

Prerequisites

Before configuring any Microsoft connector, ensure you have:

Azure Access Requirements

• Azure tenant with appropriate licensing (Microsoft 365 E1+ for SharePoint/OneDrive, Teams Premium for meeting transcripts)
• Global Administrator or Cloud Application Administrator role to:
  • Create App Registrations
  • Grant application permissions
  • Provide admin consent
• Certificate for authentication - See Certificate Generation Guide below

Atolio Environment

• Active Atolio deployment - Contact your Atolio onboarding team if you need assistance
• Configuration values - You’ll collect these from Azure and provide them to your Atolio support contact

Certificate Generation

Microsoft Graph API requires certificate-based authentication. Choose one option:

Option 1: Self-Signed Certificate (OpenSSL)

# Generate private key and certificate
openssl req -x509 -newkey rsa:2048 -keyout atolio-key.pem -out atolio-cert.pem -days 365 -nodes

# Create PFX file (no password)
openssl pkcs12 -export -out atolio-cert.pfx -inkey atolio-key.pem -in atolio-cert.pem -passout pass:

# Create CER file for Azure upload
openssl x509 -outform der -in atolio-cert.pem -out atolio-cert.cer

# Get base64-encoded PFX for Atolio configuration
cat atolio-cert.pfx | base64

Option 2: Self-Signed Certificate (PowerShell/Windows)

# Generate certificate
$cert = New-SelfSignedCertificate -Subject "CN=Atolio" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature

# Export CER file for Azure
Export-Certificate -Cert $cert -FilePath "atolio-cert.cer"

# Export PFX file for Atolio (replace 'password' with your preferred password)
Export-PfxCertificate -Cert $cert -FilePath "atolio-cert.pfx" -Password (ConvertTo-SecureString -String "password" -Force -AsPlainText)

# Get base64-encoded PFX
[Convert]::ToBase64String([IO.File]::ReadAllBytes("atolio-cert.pfx"))

Common Setup Steps

All Microsoft connectors require these foundational steps:

1. Create App Registration - Follow Entra ID - Create New App Registration
2. Upload Certificate - Add your .cer file to the App Registration
3. Grant API Permissions - Add Application permissions (not Delegated) for each source:
   • For Entra ID identity provider: Use only the directory permissions listed in the authentication guide
   • For content sources: Use the specific permissions listed in each connector’s documentation
4. Admin Consent - Click “Grant admin consent” in the API permissions page

Configuration Values

Collect these values from Azure and provide them to your Atolio support contact:

• ClientCert - Base64-encoded content of the .PFX file (from certificate generation step)
• ClientCertPassword - Certificate’s private key password (if you set one)
• TenantId - Directory (tenant) ID from the App Registration Overview page
• ClientId - Application (client) ID from the App Registration Overview page

Resource Filtering

All Microsoft connectors support filtering to limit indexing scope using YAML configuration in your connector settings:

resources:
  user:
    included:
      - arthur.dent@example.com
  group:
    excluded:
      - contractors@example.com

Common filter types include:

• User filters - Index content for specific user accounts
• Group filters - Index content accessible by specific Microsoft 365 groups
• LDAP group filters - Index content for members of specific Entra ID security/distribution groups (Outlook only)
• Site/Team filters - Index specific SharePoint sites or Teams

For detailed filtering options, see the individual connector documentation pages.

2.10.1 - OneDrive Connector Setup

Index OneDrive files by creating a dedicated App Registration with the appropriate permissions.

Setup Checklist

Before starting, ensure you have:

• Azure Global Administrator or Cloud Application Administrator role
• Microsoft 365 E1+ licensing for OneDrive content
• Certificate generated (see Certificate Generation Guide)
• Active Atolio deployment

Required API Permissions

Step 1: Create App Registration

1. Navigate to Azure Portal > App Registrations
2. Click “New registration”
3. Enter name: Atolio OneDrive
4. Select “Accounts in this organizational directory only”
5. Click “Register”

Step 2: Add API Permissions

⚠️ Important: Only add Application permissions, not Delegated permissions

1. In your App Registration, click “API permissions” in the left menu
2. Click “Add a permission”
3. Select “Microsoft Graph”
4. Click “Application permissions” (not Delegated permissions)

Add these Microsoft Graph permissions:

Identity & Directory Permissions (Required for ACL mapping)

• Application.Read.All
• Group.Read.All
• GroupMember.Read.All
• User.Read.All
• Directory.Read.All (optional - can omit with disable_full_permissions: true in configuration)

OneDrive Content Permissions

• Files.Read.All
• Reports.Read.All (required for indexing progress display)

Step 3: Grant Admin Consent

1. After adding all permissions, click “Grant admin consent for [your tenant name]” at the top of the API permissions page
2. Confirm by clicking “Yes”
3. Verify all permissions show “Granted for [your tenant name]” with green checkmarks

Step 4: Upload Certificate

1. Click “Certificates & secrets” in the left menu
2. Click “Upload certificate”
3. Select your .cer file (not the .pfx file)
4. Add description: Atolio OneDrive Authentication
5. Click “Add”

Step 5: Collect Configuration Values

From the “Overview” page, copy:

• Application (client) ID
• Directory (tenant) ID

You’ll provide these along with your base64-encoded .pfx certificate to your Atolio support contact.

Resource Filtering

Limit indexing scope using resource filters. OneDrive supports multiple filter types:

User Filtering

Index OneDrive files for specific user accounts:

resources:
  user:
    included:
      - arthur.dent@example.com
      - ford.prefect@example.com
    excluded:
      - galactic-president@example.com

Group Filtering

Index OneDrive files accessible by Microsoft 365 groups:

resources:
  group:
    included:
      - engineering-group@example.com
    excluded:
      - contractors@example.com

Sample Configuration

Here’s a complete YAML configuration example for OneDrive:

connector: microsoft
source: onedrive
common:
  enabled: true
  identity-provider: false
  cron-spec: "10 */1 * * *"
secrets:
  client_cert:
    value: "<BASE64_ENCODED_PFX_CONTENT>"
  client_cert_password:
    value: "<CERTIFICATE_PASSWORD>"  # Optional if no password set
configuration:
  client-id: "<APPLICATION_CLIENT_ID>"
  tenant-id: "<DIRECTORY_TENANT_ID>"
  disable_full_permissions: false
  resources:
    user:
      included:
        - john.doe@contoso.com
        - jane.smith@contoso.com
    group:
      excluded:
        - contractors@contoso.com

Troubleshooting

2.10.2 - Outlook Connector Setup

Index Outlook emails and events by creating a dedicated App Registration with the appropriate permissions.

Setup Checklist

Before starting, ensure you have:

• Azure Global Administrator or Cloud Application Administrator role
• Microsoft 365 licensing for Outlook content
• Certificate generated (see Certificate Generation Guide)
• Active Atolio deployment

Required API Permissions

Step 1: Create App Registration

1. Navigate to Azure Portal > App Registrations
2. Click “New registration”
3. Enter name: Atolio Outlook
4. Select “Accounts in this organizational directory only”
5. Click “Register”

Step 2: Add API Permissions

⚠️ Important: Only add Application permissions, not Delegated permissions

1. In your App Registration, click “API permissions” in the left menu
2. Click “Add a permission”
3. Select “Microsoft Graph”
4. Click “Application permissions” (not Delegated permissions)

Add these Microsoft Graph permissions:

Identity & Directory Permissions (Required for ACL mapping)

• Application.Read.All
• Group.Read.All
• GroupMember.Read.All
• User.Read.All
• Directory.Read.All (optional - can omit with disable_full_permissions: true in configuration)

Outlook Content Permissions

• Mail.Read
• Calendars.Read
• MailboxSettings.Read
• Domain.Read.All

Step 3: Grant Admin Consent

1. After adding all permissions, click “Grant admin consent for [your tenant name]” at the top of the API permissions page
2. Confirm by clicking “Yes”
3. Verify all permissions show “Granted for [your tenant name]” with green checkmarks

Step 4: Upload Certificate

1. Click “Certificates & secrets” in the left menu
2. Click “Upload certificate”
3. Select your .cer file (not the .pfx file)
4. Add description: Atolio Outlook Authentication
5. Click “Add”

Step 5: Collect Configuration Values

From the “Overview” page, copy:

• Application (client) ID
• Directory (tenant) ID

You’ll provide these along with your base64-encoded .pfx certificate to your Atolio support contact.

Resource Filtering

Limit indexing scope using resource filters. Outlook supports multiple filter types:

User Filtering

Index mailboxes for specific user accounts:

resources:
  user:
    included:
      - arthur.dent@example.com
      - ford.prefect@example.com
    excluded:
      - galactic-president@example.com

LDAP Group Filtering

Index mailboxes for members of Entra ID security/distribution groups:

resources:
  ldap:
    included:
      - f47ed439-7c7d-430d-aff3-0acecdec2cae  # Engineering Security Group (ObjectId)

LDAP Group Filter Notes:

• Accepts Entra ID group ObjectIds (GUIDs) or distinguished names
• Filters based on transitive group membership
• Only indexes mailboxes of group members
• Only a single LDAP group filter is supported at a time
• Use Azure AD PowerShell or Graph Explorer to find group ObjectIds

Manually Specify Email Address Domains

If email address domains of your organization are already listed in MS Graph API /domains query, you can skip this step.

For Atolio to identify contributors of Outlook resources correctly, a list of email address domains must be known. If users in your organization have email addresses like user1@example.com and user2@contoso.com, this list should consist of example.com, and contoso.com.

You can manually specify an email address domain list as part of your configuration in the following format:

known-domains:
  - example.com
  - contoso.com

Sample Configuration

Here’s a complete YAML configuration example for Outlook:

connector: microsoft
source: outlook
common:
  enabled: true
  identity-provider: false
  cron-spec: "20 */1 * * *"
secrets:
  client_cert:
    value: "<BASE64_ENCODED_PFX_CONTENT>"
  client_cert_password:
    value: "<CERTIFICATE_PASSWORD>"  # Optional if no password set
configuration:
  client-id: "<APPLICATION_CLIENT_ID>"
  tenant-id: "<DIRECTORY_TENANT_ID>"
  disable_full_permissions: false
  disable-attachments: true    # Set to false to index email attachments
  backfill-start-time: "2025-01-01T00:00:00Z"  # Index emails from this date
  known-domains:
    - contoso.com
    - example.com
  resources:
    user:
      included:
        - arthur.dent@example.com
        - ford.prefect@example.com
    ldap:
      included:
        - f47ed439-7c7d-430d-aff3-0acecdec2cae  # Atolio Users Group

Troubleshooting

2.10.3 - SharePoint Connector Setup

Index SharePoint sites, pages, and files by creating a dedicated App Registration with the appropriate permissions.

Setup Checklist

Before starting, ensure you have:

• Azure Global Administrator or Cloud Application Administrator role
• Microsoft 365 E1+ licensing for SharePoint content
• Certificate generated (see Certificate Generation Guide)
• Active Atolio deployment

Required API Permissions

Step 1: Create App Registration

1. Navigate to Azure Portal > App Registrations
2. Click “New registration”
3. Enter name: Atolio SharePoint
4. Select “Accounts in this organizational directory only”
5. Click “Register”

Step 2: Add API Permissions

⚠️ Important: Only add Application permissions, not Delegated permissions

1. In your App Registration, click “API permissions” in the left menu
2. Click “Add a permission”
3. Select “Microsoft Graph”
4. Click “Application permissions” (not Delegated permissions)

Add these Microsoft Graph permissions:

Identity & Directory Permissions (Required for ACL mapping)

• Application.Read.All
• Group.Read.All
• GroupMember.Read.All
• User.Read.All
• Directory.Read.All (optional - can omit with disable_full_permissions: true in configuration)

SharePoint Content Permissions

• Files.Read.All
• Sites.Read.All

Step 3: Grant Admin Consent

1. After adding all permissions, click “Grant admin consent for [your tenant name]” at the top of the API permissions page
2. Confirm by clicking “Yes”
3. Verify all permissions show “Granted for [your tenant name]” with green checkmarks

Step 4: Upload Certificate

1. Click “Certificates & secrets” in the left menu
2. Click “Upload certificate”
3. Select your .cer file (not the .pfx file)
4. Add description: Atolio SharePoint Authentication
5. Click “Add”

Step 5: Collect Configuration Values

From the “Overview” page, copy:

• Application (client) ID
• Directory (tenant) ID

You’ll provide these along with your base64-encoded .pfx certificate to your Atolio support contact.

SharePoint Site Groups & Associated Permissions

Many SharePoint sites are deployed without connecting to Microsoft Office 365 groups. Microsoft treats certain SharePoint configurations as unsupported unless managed through Office 365 groups. For Atolio to index correct permissions on non-O365 managed sites, the Sites.FullControl.All permission is required. Communication Sites commonly fall into this category. For more information on connecting sites to O365 groups, see Microsoft’s documentation.

Atolio can index these sites if Sites.FullControl.All permission is set on your App Registration. This is the least privileged permission available for read access to the SharePoint API. Atolio never writes back to the SharePoint API.

When configuring the connector for non-O365 group sites:

• Set Sites.FullControl.All permissions on the App Registration, specifically within the SharePoint API. (see below screenshot)
• Set IndexSharePointPermissions configuration to true

All other configuration and certificates remain the same.

Resource Filtering

Limit indexing scope using resource filters. SharePoint supports site-specific filtering:

Site Filtering

Index specific SharePoint sites by URL:

resources:
  site:
    included:
      - https://contoso.sharepoint.com/sites/Engineering
      - https://contoso.sharepoint.com/sites/Marketing
    excluded:
      - https://contoso.sharepoint.com/sites/Confidential

Sample Configuration

Here’s a complete YAML configuration example for SharePoint:

connector: microsoft
source: sharepoint
common:
  enabled: true
  identity-provider: false
  cron-spec: "30 */1 * * *"
secrets:
  client_cert:
    value: "<BASE64_ENCODED_PFX_CONTENT>"
  client_cert_password:
    value: "<CERTIFICATE_PASSWORD>"  # Optional if no password set
configuration:
  client-id: "<APPLICATION_CLIENT_ID>"
  tenant-id: "<DIRECTORY_TENANT_ID>"
  disable_full_permissions: false
  index_sharepoint_permissions: true  # Required for non-O365 group sites
  resources:
    site:
      included:
        - https://contoso.sharepoint.com/sites/Engineering
        - https://contoso.sharepoint.com/sites/Marketing

Troubleshooting

2.10.4 - Teams Connector Setup

Index Teams channels, chat, messages, and meeting transcripts by creating a dedicated App Registration with the appropriate permissions.

Setup Checklist

Before starting, ensure you have:

• Azure Global Administrator or Cloud Application Administrator role
• Teams Premium licensing (for meeting transcripts)
• Certificate generated (see Certificate Generation Guide)
• Active Atolio deployment

Required API Permissions

Step 1: Create App Registration

1. Navigate to Azure Portal > App Registrations
2. Click “New registration”
3. Enter name: Atolio Teams
4. Select “Accounts in this organizational directory only”
5. Click “Register”

Step 2: Add API Permissions

⚠️ Important: Only add Application permissions, not Delegated permissions

1. In your App Registration, click “API permissions” in the left menu
2. Click “Add a permission”
3. Select “Microsoft Graph”
4. Click “Application permissions” (not Delegated permissions)

Add these Microsoft Graph permissions:

Identity & Directory Permissions (Required for ACL mapping)

• Application.Read.All
• Group.Read.All
• GroupMember.Read.All
• User.Read.All
• Directory.Read.All (optional - can omit with disable_full_permissions: true in configuration)

Teams Content Permissions

• Channel.ReadBasic.All
• ChannelMember.Read.All
• ChannelMessage.Read.All
• Chat.Read.All
• ChatMember.Read.All
• ChatMessage.Read.All
• Team.ReadBasic.All
• TeamMember.Read.All

Teams Meeting Transcripts (Optional)

• OnlineMeetings.Read.All
• OnlineMeetingTranscript.Read.All
• Calendars.Read
• Domain.Read.All

Step 3: Grant Admin Consent

1. After adding all permissions, click “Grant admin consent for [your tenant name]” at the top of the API permissions page
2. Confirm by clicking “Yes”
3. Verify all permissions show “Granted for [your tenant name]” with green checkmarks

Step 4: Upload Certificate

1. Click “Certificates & secrets” in the left menu
2. Click “Upload certificate”
3. Select your .cer file (not the .pfx file)
4. Add description: Atolio Teams Authentication
5. Click “Add”

Step 5: Collect Configuration Values

From the “Overview” page, copy:

• Application (client) ID
• Directory (tenant) ID

You’ll provide these along with your base64-encoded .pfx certificate to your Atolio support contact. This link is beside the Add a permission link.

Application Access Policy for Teams Meeting Transcripts

In addition to Entra ID permissions above, you need to setup an application access policy for Atolio to access transcripts.

• Open PowerShell. Install the Microsoft Teams PS module:
  • Install-Module -Name MicrosoftTeams -Force -AllowClobber
• Connect to Teams module w/ an admin account on your shell. This will prompt a login page on your browser:
  • Import-Module MicrosoftTeams
  • Connect-MicrosoftTeams
• Create a new policy. Assuming the policy name is “Atolio-Transcript-Access-Policy”, and the previously registered application ID (client ID) is “some-app-id”, the shell command will be as follows:
  • New-CsApplicationAccessPolicy -Identity Atolio-Transcript-Access-Policy -AppIds "some-app-id" -Description "Access policy for teams transcripts"
• Associate users with the policy. You have two options:
  • Option 1 - Grant tenant-wide access (recommended). This will allow Atolio to index transcripts owned by every user who does not have an application access policy assigned:
    • Grant-CsApplicationAccessPolicy -PolicyName Atolio-Transcript-Access-Policy -Global
  • Option 2 - Grant user-specific access. This will allow Atolio to index transcripts owned by explicitly declared users only:
    • Grant-CsApplicationAccessPolicy -PolicyName Atolio-Transcript-Access-Policy -Identity "some-user-id"

More details about the policy setup can be found in the official documentation:

• https://learn.microsoft.com/en-us/graph/cloud-communication-online-meeting-application-access-policy

Resource Filtering

Limit indexing scope using resource filters. Teams supports team-specific filtering:

Team Filtering

Index specific Teams by name or ID:

resources:
  team:
    included:
      - 66e327b3-321a-4ebf-8e2c-34cebf134bf8 # Engineering Team ID
      - 0507654f-506d-4805-95d5-516bcaf1075c # Sales Team ID
    excluded:
      - b0b083d0-6288-45ce-8ecd-16960ba7b329 # HR Team ID

Sample Configuration

Here’s a complete YAML configuration example for Teams:

connector: microsoft
source: teams
common:
  enabled: true
  identity-provider: false
  cron-spec: "40 */1 * * *"
secrets:
  client_cert:
    value: "<BASE64_ENCODED_PFX_CONTENT>"
  client_cert_password:
    value: "<CERTIFICATE_PASSWORD>"  # Optional if no password set
configuration:
  client-id: "<APPLICATION_CLIENT_ID>"
  tenant-id: "<DIRECTORY_TENANT_ID>"
  disable_full_permissions: false
  enable-transcripts: true  # Enable meeting transcript indexing
  skip-chats: false        # Set to true to skip private chats
  resources:
    team:
      included:
        - 66e327b3-321a-4ebf-8e2c-34cebf134bf8 # Engineering Team ID
        - 0507654f-506d-4805-95d5-516bcaf1075c # Marketing Team ID

Troubleshooting

Limitations

• Only first 1000 replies to a channel post will be indexed, due to limitations with the Microsoft API.

2.11 - Notion Connector

The Notion connector indexes databases, pages, and comments across your Notion workspace.

Create the Notion integration

As an administrator, you can either follow the steps below or navigate directly to My Integrations:

1. Click on Settings & members.
2. Under Workspace, click on Connections.
3. Click the link for Develop or manage integrations.

Create a new Internal integration by following the steps below:

1. Choose the associated workspace and give it an appropriate name, e.g. Atolio.
2. (Optional) Use the Atolio logo here, if needed.
3. Under Secrets, copy the Internal Integration Secret to share with your Deployment Engineer.
4. Under Capabilities:

• Only “Read content” and “Read comments” are necessary. The other permissions can be removed.
• Ensure that “Read user information including email addresses” is enabled.
• Click Save changes.

Once the integration has been created, provide the secret copied above to your Deployment Engineer for configuration in your Atolio deployment.

2.12 - Okta Connector

The Okta connector provides identity mappings for each user based on the apps that they use.

Note: As part of Atolio Configuration, this connector should be selected as Identity Provider if it is used to resolve app-user mappings.

Service Account and Required Permissions

Okta API tokens inherit the permissions of the user that creates them, so we recommend creating a dedicated service account rather than using a personal admin account. The connector only performs read operations against Okta (users, groups, applications, application users, and the System Log).

Assign one of the following to the service account:

• Read-only Administrator (built-in role) — the simplest option, and the lowest-privilege built-in role that covers everything the connector needs.
• A custom admin role with these read permissions, scoped to all users, all groups, and all apps:
  • okta.users.read
  • okta.groups.read
  • okta.apps.read
  • okta.logs.read
  • okta.reports.read

Note: The connector tolerates per-request 403 Forbidden responses and continues processing other events, so an under-scoped token will produce incomplete data rather than a hard failure. If you scope the role to a subset of users, groups, or apps, anything outside that scope will silently be missing from search results.

Creating an API Token

Sign in as the service account and create the token at https://example.okta.com/admin/access/api/tokens (replacing example.okta.com with your Okta domain). See Okta’s Create an API token guide for full details.

Note: Okta revokes API tokens after 30 days of inactivity. The connector polls Okta continuously and keeps the token active during normal operation, but if the connector is paused or disabled for an extended period the token will need to be regenerated.

Provide Configuration

Provide the following configuration values to your Deployment Engineer in order to complete these steps:

• Hostname, the host name for your Okta instance (e.g. example.okta.com)
• Token, the API Token created above

2.13 - Salesforce Connector

The Salesforce connector enables the indexing of Salesforce objects, such as Accounts and Opportunities, using the Salesforce REST API by creating an External Client App in your Salesforce instance.

Note: Salesforce’s External Client Apps (ECA) are the successor to the legacy Connected Apps and follow a least-privilege model with explicit permission grants.

Setup External Client App

Note: The setup assumes that you are using the lightning experience of Salesforce.

As a best practice, we recommend creating a new user account or identifying an existing user account to be used for integrations. This user will be granted access to the External Client App in a later step.

1. As an administrator, navigate to Setup.
2. In the Quick Find box, search for “External Client App Manager” and open it.
3. Click “New External Client App”.

• Choose an External Client App Name and API Name, e.g. Atolio.
• Choose an email for Contact Email.
• (Optional) For Logo Image URL and/or Icon URL, you can use the Atolio logo here.

4. Under “API (Enable OAuth Settings)”, select Enable OAuth.

• For Callback URL, enter a valid URL (e.g. https:/) — Atolio does not use this login flow for authentication.
• For Selected OAuth Scopes, add only the “Manage user data via APIs (api)” scope. Do not add the “Full access (full)” scope — Salesforce now rejects token requests for External Client Apps configured with overly broad scopes.
• Under “Flow Enablement”, check Enable Client Credentials Flow and acknowledge the security prompt.

5. Click “Create” to save the External Client App.

Next, configure the app’s policies:

1. From the External Client App Manager, open your new app and go to the “Policies” tab, then click “Edit”.
2. Under “OAuth Policies”:

• Set Permitted Users to “Admin approved users are pre-authorized”.
• Under “Client Credentials Flow”, set Run As to the integration user identified above.

3. Save the policy changes.

Finally, grant the integration user access to the External Client App. Unlike Connected Apps, ECAs require explicit assignment via a permission set (profile-based access is not supported):

1. From Setup, navigate to “Permission Sets” and click “New”.
2. Give the permission set a name (e.g. Atolio External Client App Access) and save.
3. Open the new permission set and go to “External Client App Access Settings” (or “Assigned External Client Apps”, depending on your org).
4. Enable your Atolio External Client App.
5. Assign this permission set to the integration user identified above.

Provide Configuration

To obtain the necessary client credentials:

1. From the External Client App Manager, open your Atolio app and go to the “Settings” tab.
2. Under “OAuth Settings”, click “Consumer Key and Secret” → “Manage Consumer Details”.
3. Copy the “Consumer Key” and “Consumer Secret” to be shared with your Deployment Engineer.

Provide the following values to your Deployment Engineer for them to configure in Atolio:

• base_url is the URL of your Salesforce tenant, e.g. https://yourcompany.my.salesforce.com.
• client_id is the “Consumer Key” of the External Client App you created.
• client_secret is the “Consumer Secret” of the External Client App you created.

Streaming Configuration

To periodically sync updates in Salesforce to the Atolio index, we need to set the cron-spec. The recommended value is (*/10 * * * *). This would fetch updates from Salesforce every 10 minutes. We also need to set complete_backfill_frequency. This, alongside the cron-spec, controls how often the connector performs a complete backfill of the data (to capture ACL changes). For example, setting a value of 24 would mean that every 24th call to backfill would be a complete fill. This combined with a cron-spec of every 10 minutes, a complete backfill would happen every 4 hours. The recommended value is 48 so a complete backfill happens every 8 hours. This value can be tweaked to reduce the number of API calls. Generally, we want to use a higher value for larger datasets so the connector performs a complete backfill less frequently.

2.14 - ServiceNow Connector

The ServiceNow connector will index:

• IT Service Management (ITSM) tasks - such as incidents, service requests, problems - including work notes and comments.
• Knowledge bases (KBs) and KB articles.

The ServiceNow connector supports all releases from ServiceNow San Diego to the latest.

Note: If you need support for additional modules (e.g. Security Operations) with fields that aren’t indexed in the base tasks, contact your Atolio support team.

Install ServiceNow Update Set

The Atolio ServiceNow plug-in is available as an update set (XML file). The update set will be provided by your Deployment Engineer (from the Atolio GitHub repository) or your Atolio support team. From ServiceNow documentation, follow the steps below to Commit an update set.

1. Elevate privileges to the security_admin role:

2. Navigate to System Update Sets > Retrieved Update Sets.
3. Click the link to Import Update Set from XML. Upload the XML file provided previously.
4. The application is now available as a retrieved update set with state Loaded. Click on Atolio Connector to open the update set.
5. If necessary, skip or accept updates to resolve any problems.
6. Click Commit Update Set to install the application.

Note: You can view the Commit log by navigating to System Update Sets > Update log and filtering to the Atolio Connector Update set.

Setup Application Credentials

First, create an application user by:

1. Navigating to System Security > Users and Groups > Users.
2. For User ID, choose an appropriate name, e.g. atolio_connector. Click Submit.
3. In the new user record that you just created:

• Under Roles, click Edit... and add x_penti_atolio.atolio_connector to the Roles List before clicking Save.
• Click Set Password to generate a password for this application user.

Next, enable the connector API by:

1. Under the Atolio Connector application, navigate to Integration - Atolio Connector > Administration > Properties.
2. If necessary, enable the connector’s API and integration with ServiceNow Knowledge Management.

Provide Configuration

Provide the following values to your Deployment Engineer for them to configure in Atolio:

• Instance URL is the URL of your ServiceNow tenant.
• Username is the User ID of the application user you created, e.g. atolio_connector.
• Password is the password of the application user you created.

2.15 - Slack Connector

The Slack connector indexes messages across public channels, private channels, and threads. It will only index messages where the Atolio bot has been invited.

Choose a Change Notification Mechanism

For Atolio to get notified of changes happening on Slack in real-time, there are 2 options: “HTTP mode”, and “socket mode”. A detailed comparison of these options is available here.

If having a webhook is not ideal for your organization, you can opt in for socket mode.

Create Slack App

In order to target your specific Atolio deployment, the Slack connector for Atolio requires a custom Slack app created from a manifest.

First, create the Slack app according the following instructions:

1. In the Slack app dashboard (https://api.slack.com/apps), click on “Create New App”.
2. Select “From an app manifest” when prompted.
3. Select the workspace where the app should be installed.
4. Select the “YAML” option, and provide the app manifest based on your preferred change notification mechanism:

• Manifest w/ “HTTP mode”: https://relay.search.example.com/connectors/slack/default/install/manifest.yml?socketMode=false
• Manifest w/ “socket mode”: https://relay.search.example.com/connectors/slack/default/install/manifest.yml?socketMode=true

5. Click on “Create”. Once the app is created, open the “Basic Information” page of your new app - it can be accessed from the Slack app dashboard (https://api.slack.com/apps).
6. Locate the “App Credentials” heading and store the client ID, client secret, and signing secret in a safe place. These will be used to configure Slack shortly.
7. (For “socket mode” only) Generate an “app-level token” w/ connections:write scope (screenshot below). Store the value in a safe place.
8. (Optional) To provide an app icon, locate the “Display Information” heading and upload the app icon provided here.

Note: it may be required to distribute the app. This can be done by clicking Manage Distribution in the Slack app dashboard.

Provide Configuration

Once the Slack app has been created, provide these configuration values to your Deployment Engineer:

• DefaultTeamID is the Slack team ID for your workspace (e.g. T012ABCDEG3)
• ClientId, ClientSecret, and SigningSecret are the secrets obtained in the previous step. If you’ve opted in to use “socket mode”, the list should include an AppLevelToken as well.
• Token is a secret which will be populated by the next step. You may leave this blank.
• ConversationTypes are the types of conversations being indexed by the Atolio Slack Bot. If empty, this defaults to public_channel,private_channel,mpim

Once configured, you will finalize the installation of the Slack connector by visiting the following URL (make sure to use your own DNS name for the host part of the URL and include the correct instance name): https://relay.search.example.com/connectors/slack/default/install/setup. Also make sure the Atolio Web application is authenticated (using your SSO provider) before navigating to this URL to avoid an authentication error. The URL https://relay.search.example.com/install/connectors/slack/default/install/oauth/callback must be listed as a Redirect URLin the Slack app manifest. For example, with Okta this was done as part of Okta - Create OAuth Client.

In order for Slack conversations to be indexed by the Atolio Slack Bot, the bot needs to be added to the conversation. By default, this is done manually, but the bot can also be configured to auto-join public channels through configuration. If the bot is added to a channel which is later filtered out by configuration, auto-leave can be configured similarly.

The Slack Team ID can for instance be copied from the URL after logging into your company’s Slack Web app. For instance navigate to https://app.slack.com/ and note down the team ID in the URL that you get redirected to (e.g. T012ABCDEG3 in https://app.slack.com/client/T012ABCDEG3/.../...).

Index Private Content

To enable the indexing of private content such as direct messages (DMs) and private channels, without manually adding the bot to the respective conversation, the following steps must be taken:

• Set slack-auth feature flag on your Atolio deployment
• Set EnablePrivateContent flag on Slack connector configuration

Afterwards, each Atolio user will be prompted with further instructions when they login to Atolio.

2.16 - SolarWinds Service Desk Connector

SolarWinds Service Desk (SWSD) connector enables the indexing of Incidents, Service Catalog, Problems, Solutions, Releases and Changes on your SWSD instance.

Prerequisites

The following configuration should be set on your SWSD instance, by an admin user, before configuring the SWSD connector.

• Create a new admin user:
  • Go to Setup -> Users & Groups -> Users.
  • Create a new user with a descriptive name, such as “Atolio Admin User”. Make sure the user is given “Admin” role.
  • Activate the newly created user through the link sent via email.
  • Altough you can use an existing admin user, creating a new user solely for the purpose of Atolio integration is a best practice.
• Generate JWT:
  • Login as “Atolio Admin User”.
  • Go to Setup -> Users & Groups -> Users. From the user table, click on “Atolio Admin User” to open the details page.
  • From the “Actions” menu, select “Generate JSON Web Token” item to generate an API token. Provide the token value to your Deployment Engineer.

Provide Configuration

Provide the following configuration to your Deployment Engineer:

• Your SWSD domain, e.g., company.samanage.com
• JWT of “Atolio Admin User”
• A full screenshot of Setup -> Account -> Roles & Permissions page. This is needed by your Deployment Engineer to configure the connector with respect to your permission settings.

Optionally, you can provide a backfill configuration, as follows:

# Filter data to be backfilled.
# If not provided, defaults to 1 year.
backfill-start-time: "2024-01-01T00:00:00Z" # Filter out data not updated since 2023.

# Specify when to create "checkpoints".
# If not provided, defaults to 1 year.  
backfill-step-duration: 30 # Create a checkpoint after 30 days of data is backfilled.

2.17 - Staffbase Connector

The Staffbase connector enables indexing of various resources from your Staffbase platform, including Users, Campaigns, Posts, and Comments. This integration allows you to search and access Staffbase content directly through Atolio.

Set Up Administrator API Key and Retrieve Base URL

To set up the Staffbase connector, you’ll need to create an API key with administrator privileges. Follow these steps:

1. Log in to your Staffbase account as an administrator.

2. Navigate to the Admin Panel:

   a. Click your user profile at the top right, then click ‘Studio’ in the drop-down menu.

   

   b. Click the gear icon at the top right corner.

   

   c. In the new page, you will see a column on the left. Click the ‘API Access’ tab.

   

3. Click the “Create New API Key” button.

4. Provide a descriptive name for the key, such as “Atolio Connector”.

5. Under “Access”, select “Read-only” to ensure full access to all resources.

6. Click “Create”.

7. Copy and securely store the generated API key. Note that you won’t be able to view this key again, so make sure to save it in a secure location.

8. On the same page, you’ll also see the base URL for your instance:

Provide Configuration

After creating the API key, provide the following information to your Deployment Engineer:

• API Key: The administrator API key you just generated.
• Staffbase Instance URL: The URL of your Staffbase instance (e.g., https://yourcompany.staffbase.com).

2.18 - Web Connector

The Web connector enables the indexing of HTML web pages.

Enable Access

The Web connector indexes unauthenticated web page content which can be accessed from your Atolio deployment.

First, determine where your website is hosted. The Web connector can crawl HTML content by either:

• Navigating URLs from a configured baseURL.
• Browsing an Amazon S3 bucket from a configured url.

In order to ensure that the content is accessible in your Atolio deployment, ensure that your Deployment Engineer is aware of the necessary network or AWS permissions as part of the infrastructure deployment.

Note: You may also need to ensure that your HTML content is server-side rendered (SSR) in order to index the complete website content.

(Optional) Provide Filters

Additional filters can be configured by your Deployment Engineer in order to:

• Include or exclude pages, e.g. particular URLs that match a given regex.
• Remove extraneous content, e.g. table of contents.

2.19 - Zendesk Connector

Zendesk connector enables the indexing of tickets, and help center articles.

Prerequisites

The following configuration should be set on your Zendesk instance, by the account owner or an admin user, before configuring the Zendesk connector.

• Go to Zendesk admin panel
  • https://{your-zendesk-subdomain}.zendesk.com/admin/apps-integrations/apis/zendesk-api/settings
• Enable “API access”
  • If you don’t see such an option, it means it’s already enabled.
• Enable “Token access”
• Create a new API token
  • If you already have an API token other integrations, it’s still advised to create a new one for the Zendesk connector, and provide a descriptive name such as atolio-connector-token. Note the token value since you cannot retrieve it after its creation. The token will be used to configure the connector.
• Create a new admin user
  • If you already have an admin user for other integrations, it’s still advised to create a new admin user for the Zendesk connector, and provide a descriptive username such as atolio-connector-admin-user@<your-org-domain>. The username will be used to configure the connector.

After the configuration, your API settings page should look like the following:

Provide Configuration

Provide the following configuration and answers to your Deployment Engineer:

• Your Zendesk subdomain
• API token, ideally the one you newly created under the name atolio-connector-token
• Admin user, ideally the one you newly created under the name atolio-connector-admin-user@<your-org-domain>
• Whether you want “Help Center” content to be indexed or not
  • “Help Center” is an optional feature of Zendesk for hosting user-generated content (e.g., articles). If you use this feature and want your Help Center content to be indexed, mention this to your Deployment Engineer for them to configure it appropriately.
  • If you’re not sure if your organization uses “Help Center” functionality, try visiting https://{your-zendesk-subdomain}.zendesk.com/knowledge. A 404 error means your org is not using it.

Deployment engineer will also generate a “webhook secret”, and add it to the configuration. Please do not alter the configuration of any “webhook” or “trigger” starting with the word lumen. These are configured by the connector automatically, to index content changes in real-time.

Content Filtering

Atolio supports the ability to avoid certain content from being indexed at all. You can provide inclusions or exclusions with respect to each resource type.

• Users can be filtered w.r.t. their emails.
• Groups can be filtered w.r.t. their names.
• Organizations can be filtered w.r.t. their names.
• Tickets can be filtered w.r.t. their statuses (e.g., “open”, “closed”)

For Help center content:

• User Segments can be filtered w.r.t. their names.
• Articles can be filtered w.r.t. their section IDs.
  • Section ID is a number that can be identified by executing the following command:
    • curl -L -u "{admin-user}/token:{admin-token}" https://{zendesk-subdomain}.zendesk.com/api/v2/help_center/articles/{article-id}.json | jq ".article.section_id"
    • Replace {admin-user}, {admin-token}, {zendesk-subdomain}, and {article-id} values appropriately.

An example of inclusions/exclusions file would be as follows:

resources:
    user:
        excluded:
            - super_secret_user@example.com
    group:
        included:
            - A group name
            - Another group name
    organization:
        included:
            - An organization name
    user_segment:
        included:
            - A segment name
    ticket:
        excluded: 
            - closed  # ticket status
    article:
        excluded:
            - "12345" # section id

If you need content filtering, provide the inclusions & exclusions similar to the file above to your Deployment Engineer.

2.20 - Zulip Connector

The Zulip connector indexes content from your Zulip organization using Zulip API credentials.

Atolio recommends using a dedicated Zulip bot for this connector rather than a personal user account.

Create Zulip credentials

Create credentials for either:

• a generic bot (recommended), or
• a dedicated service user.

You can retrieve Zulip API credentials using Zulip’s API key documentation: https://zulip.com/api/api-keys.

When creating the account used by Atolio:

• Use a dedicated bot or service account such as atolio-bot or atolio-export-bot.
• Record the account email address.
• Record the account API key.
• Record your Zulip organization URL (for example, https://example.zulipchat.com).

Visibility and access

The Zulip connector can only index content visible to the configured bot or user:

• Public streams are indexed.
• Private streams are indexed only if the configured bot or user has been added to them.
• Private messages (DMs) are not indexed by default but can be enabled per-user (see Index Private Messages below).

Because of this, Atolio recommends using a dedicated generic bot with the appropriate stream access.

Provide Configuration

Provide the following values to your Deployment Engineer:

• Domain: your Zulip organization URL (for example, https://example.zulipchat.com)
• Email: the email address of the Zulip bot or service user
• Token: the Zulip API key for that bot or user

Content Filtering

The Zulip connector supports filtering at the topic resource level.

Topics can be included or excluded using the format:

resources:
  topic:
    excluded:
      - engineering/Incident review

Each entry should be specified as:

• stream/topic

For example:

resources:
  topic:
    excluded:
      - eng-general/Search Results Feedback (query)

If you need topic-level filtering, provide the inclusions or exclusions to your Deployment Engineer as part of the connector configuration.

Index Private Messages

By default, the Zulip connector does not index private messages (DMs). To enable DM indexing, each user who wants their private messages indexed must provide a personal Zulip API key.

Unlike Slack, Zulip does not currently support an OAuth-based authentication flow for this purpose. Each user must retrieve their API key manually and share it securely with their Atolio deployment administrator.

Retrieve your Zulip API key

Each user should follow these steps:

1. In Zulip, open the Settings menu (gear icon in the top right).
2. Navigate to Personal Settings → Account & privacy.
3. Click Manage your API key at the bottom of the page. Your API key will be displayed — copy it.

Warning: Your Zulip API key grants full access to your Zulip account. Share it only through a secure channel (for example, a password manager or encrypted message). Do not share it over Zulip, Slack, email, or other unencrypted channels.

4. Share the API key securely with your Atolio deployment administrator.

Configure user tokens

Once user API keys have been collected, provide them to your Deployment Engineer. They are stored in the connector configuration as a user_tokens secret, mapping each user’s Zulip email address to their API key:

secrets:
  user_tokens:
    value: |
      "alice@example.com": "abc123XXXX"
      "bob@example.com": "def456XXXX"

After the configuration is updated, private messages for those users will be indexed on the next sync.

3 - AI Services / LLM

Overview

Atolio makes it easy to securely configure and manage access to commercial LLMs of your choice.

High-level configuration workflow

With a healthy Atolio deployment running, an administrator may hit the root URL of the deployment (eg. https://search.example.com), visit the administration panel (/admin) and click LLM Provider to jump into the configuration.

Atolio uses a range of models dependent on the use case. Per provider, the following models are currently supported:

Configuration through API Key

For the majority of providers, an access token is required. To enable the provider:

1. Open Atolio and head to the Admin panel

2. Select LLM Provider from the left-pane menu

3. Select the LLM Provider and follow the specific configuration steps:

   • Azure OpenAI
     1. Navigate to the Azure AI Foundry Portal at https://ai.azure.com/ and create a new Azure AI Foundry resource.
     2. Choose subscription, resource group, region, and resource name. Create the resource.
     3. From the service home page, open Deployments from the left-hand menu
     4. Create a new base model deployment for gpt5.2-chat
     5. Create an additional base model deployment for gpt5-mini
     6. On the model deployment page, under Endpoint Settings, copy the API key and base Endpoint URL.
     7. Back within Atolio, enter the copied Endpoint URL and API Key.
   • OpenAI
     1. Navigate to https://platform.openai.com/api-keys
     2. Create a new secret key and copy it.
     3. Specify the API key within Atolio.
   • Anthropic
     1. Navigate to https://platform.claude.com/
     2. Create a new API key and copy it.
     3. Specify the API key within Atolio.
   • Anthropic Bedrock
     1. Ensure Atolio is deployed on an AWS instance with an IAM role that has Bedrock permissions.
     2. In the AWS Console, enable model access in Amazon Bedrock for Anthropic Sonnet 4.6 and Haiku 4.5. In many cases, this is now enabled by default.
     3. Select Anthropic Bedrock as the provider within Atolio. The region is automatically selected based on the deployed region. For more details, see Claude on Amazon Bedrock.
   • Google
     1. Navigate to https://aistudio.google.com
     2. Create a new project and API key and copy it.
     3. Specify the API key within Atolio.

Changing Providers

Upon configuring and validating the provider, Atolio will lock the configuration to ensure the system is stable. For switching providers, please contact your Atolio admin at this time.