Configure connectors

OpenRAG uses OAuth credentials to authorize access to cloud storage services so you can ingest documents from cloud storage.

If you provide Google OAuth credentials, these credentials are also used to enable OAuth mode for OpenRAG and your OpenSearch knowledge base.

OAuth credentials and OpenSearch authentication modes

When you install OpenRAG, you provide the initial configuration values for your OpenRAG services, including authentication credentials for OpenSearch and optional OAuth connectors.

warning

Google is the only supported OAuth provider for OpenRAG.

Other OAuth credentials are used only to authorize cloud storage connectors.

The presence of Google OAuth credentials determines how OpenRAG authenticates with your deployment's OpenSearch knowledge base, and how it controls user access to documents in your knowledge base:

• No-auth mode: If you don't provide Google OAuth credentials, then the OpenRAG OpenSearch knowledge base runs in no-auth mode. This mode uses one anonymous JWT token for OpenSearch authentication. There is no differentiation between users; all users that access your OpenRAG instance can access all documents uploaded to your knowledge base.

• OAuth mode: If you provide Google OAuth credentials, then the OpenRAG OpenSearch knowledge base runs in OAuth mode. This mode uses a unique JWT token for each OpenRAG user, and each document is tagged with user ownership. Documents are filtered by user owner; users see only the documents that they uploaded or have access to through their cloud storage accounts.

tip

To enable OAuth mode, you must configure the Google Drive cloud storage connector for document ingestion. This is because OpenRAG uses Google OAuth credentials for both OAuth mode and the Google Drive cloud storage connector.

You can enable OAuth mode after initial setup by configuring the Google Drive connector.

Cloud storage connectors

You can use OpenRAG's cloud storage connectors to ingest files from cloud storage. Specifically, you can connect to the following services:

• AWS S3
• Google Drive
• Microsoft OneDrive
• Microsoft Sharepoint

To configure a cloud storage connector, you must register an OAuth app, get OAuth credentials, and then add the OAuth credentials to your OpenRAG configuration.

Register an OAuth app and generate credentials

Register OpenRAG as an OAuth application in your cloud provider. Then, obtain OAuth credentials for the app, such as a client ID and secret key.

To enable multiple connectors, you must register an app and generate credentials for each provider.

Add OAuth credentials to OpenRAG

TUI-managed services

If you use the Terminal User Interface (TUI) to manage your OpenRAG services, enter OAuth credentials on the Advanced Setup page. You can do this during installation, or you can add the credentials afterwards:

1. If OpenRAG is running, click Stop All Services in the TUI.

2. Open the Advanced Setup page, and then add the OAuth credentials for the cloud storage providers that you want to use under API Keys:

   • Google: Enter your Google OAuth Client ID and Google OAuth Client Secret. You can generate these in the Google Cloud Console. For more information, see the Google OAuth client documentation.

     Providing these Google credentials enables OAuth mode and the Google Drive cloud storage connector.

     warning

     Google is the only supported OAuth provider for OpenRAG.

     You must enter Google credentials if you want to enable OAuth mode.

     The Microsoft and Amazon credentials are used only to authorize the cloud storage connectors. OpenRAG doesn't offer OAuth provider integrations for Microsoft or Amazon.

   • Microsoft: For the Microsoft OAuth Client ID and Microsoft OAuth Client Secret, enter Azure application registration credentials for SharePoint and OneDrive. For more information, see the Microsoft Graph OAuth client documentation.

   • Amazon: Enter your AWS Access Key ID and AWS Secret Access Key with access to your S3 instance. For more information, see the AWS documentation on Configuring access to AWS applications.

3. For each connector you configured, register the redirect URIs shown in the TUI in your OAuth apps.

   The redirect URIs are used for the cloud storage connector webhooks. For Google, the redirect URIs are also used to redirect users back to OpenRAG after they sign in.

4. Optional: Under Others, set the Webhook Base URL to the base address for your OAuth connector endpoints. If set, the OAuth connector webhook URLs are constructed as WEBHOOK_BASE_URL/connectors/${provider}/webhook. This option is required to enable automatic ingestion from cloud storage.

5. Click Save Configuration to add the OAuth credentials to your OpenRAG .env file.

6. Click Start Services to restart the OpenRAG containers with the new configuration.

7. Launch the OpenRAG app.

   If you provided Google OAuth credentials, you must sign in with Google before you are redirected to your OpenRAG instance.

Self-managed services

If you installed OpenRAG with self-managed services, set OAuth credentials in your OpenRAG .env file.

You can do this during initial set up, or you can add the credentials afterwards:

1. Stop all OpenRAG containers:

   Docker

   docker stop $(docker ps -q)

   Podman

   podman stop --all

2. Edit your OpenRAG .env file, and then add the OAuth and cloud storage environment variables for the providers that you want to use:

   GOOGLE_OAUTH_CLIENT_ID=
   GOOGLE_OAUTH_CLIENT_SECRET=
   
   MICROSOFT_GRAPH_OAUTH_CLIENT_ID=
   MICROSOFT_GRAPH_OAUTH_CLIENT_SECRET=
   
   AWS_ACCESS_KEY_ID=
   AWS_SECRET_ACCESS_KEY=

   • Google: Enter your Google OAuth Client ID and Google OAuth Client Secret. You can generate these in the Google Cloud Console. For more information, see the Google OAuth client documentation.

     Providing these Google credentials enables OAuth mode and the Google Drive cloud storage connector.

     warning

     Google is the only supported OAuth provider for OpenRAG.

     You must enter Google credentials if you want to enable OAuth mode.

     The Microsoft and Amazon credentials are used only to authorize the cloud storage connectors. OpenRAG doesn't offer OAuth provider integrations for Microsoft or Amazon.

   • Microsoft: For the Microsoft OAuth Client ID and Microsoft OAuth Client Secret, enter Azure application registration credentials for SharePoint and OneDrive. For more information, see the Microsoft Graph OAuth client documentation.

   • Amazon: Enter your AWS Access Key ID and AWS Secret Access Key with access to your S3 instance. For more information, see the AWS documentation on Configuring access to AWS applications.

3. Optional: Set the WEBHOOK_BASE_URL to the base address for your OAuth connector endpoints. If set, the OAuth connector webhook URLs are constructed as WEBHOOK_BASE_URL/connectors/${provider}/webhook. This option is required to enable automatic ingestion from cloud storage.

4. Save the .env file.

5. For each connector, you must register the OpenRAG redirect URIs in your OAuth apps:

   • Local deployments: http://localhost:3000/auth/callback
   • Production deployments: https://your-domain.com/auth/callback

   The redirect URIs are used for the cloud storage connector webhooks. For Google, the redirect URIs are also used to redirect users back to OpenRAG after they sign in.

6. Restart your OpenRAG containers:

   Docker

   docker compose up -d

   Podman

   podman compose up -d

7. Access the OpenRAG frontend at http://localhost:3000.

   If you provided Google OAuth credentials, you must sign in with Google before you are redirected to your OpenRAG instance.

Ingest documents with cloud connectors

See Ingest files from cloud storage.

Disconnect and reconnect cloud storage connectors

In OpenRAG, click Settings to manage cloud storage connections. You can connect, disconnect, reconnect, and trigger ingestion for each configured connector.

See also

• About knowledge
• Ingest knowledge
• Configure ingestion
• Browse and manage knowledge