# Oauth Overview

## OAuth Connection Overview

### What is OAuth?

OAuth (Open Authorization) is an industry-standard protocol that allows GRAX to securely access your Salesforce data without storing your credentials. When you connect GRAX to Salesforce, OAuth handles the authentication and authorization process.

### How GRAX Uses OAuth

GRAX uses OAuth for two purposes:

1. [**Integration User Connection**](#integration-user): A dedicated Salesforce user that performs backup, restore, and archive operations
2. [**End User Single Sign-On (SSO)**](https://documentation.grax.com/other/permissions-and-access/roles-for-end-users): Individual users log into the GRAX Application using their Salesforce credentials. Note: End-user access is validated by the Integration User's OAuth connection, so the Integration User must include the `id` scope (or `profile`, `email`) in its OAuth token.

### OAuth Connection Architecture

When GRAX connects to Salesforce, a secure multi-party flow occurs:

1. The GRAX backend initiates an OAuth request through `hq.grax.com`
2. This request is proxied to Salesforce using a unified GRAX Connected App
3. Access tokens are generated and passed back to the GRAX backend
4. No credentials or tokens are stored beyond the lifetime of specific authorization events

**Key Security Features:**

* All data stores are encrypted
* Login attempts originate from IP address `3.232.229.75`
* GRAX respects Salesforce field and record-level security

For complete technical details, see the [Authentication documentation](https://documentation.grax.com/security/authentication).

### Common OAuth Scenarios

#### Initial Connection

To connect GRAX to Salesforce using OAuth:

1. Navigate to your GRAX Application
2. Select Production or Sandbox based on your org type
3. Click "Establish OAuth Connection to Salesforce"
4. Complete the Salesforce login flow
5. Log in with your individual user via SSO

**Learn more:** [Connecting Salesforce](https://documentation.grax.com/other/settings/connecting-salesforce)

#### After Sandbox Refresh

If GRAX loses connection after a sandbox refresh, you'll receive reset emails with a link to reconnect.

**Learn more:** [Sandbox Refresh](https://documentation.grax.com/other/settings/sandbox-refresh) and [Handling Loss of Salesforce Connection](https://documentation.grax.com/settings/sandbox-refresh#post-refresh-reconfiguration)

#### After Enhanced Domain Changes

After Salesforce Enhanced Domain changes, navigate to your GRAX Application URL with `/web` appended and sign in with Salesforce to reestablish the connection.

**Learn more:** [Troubleshooting documentation](https://documentation.grax.com/troubleshooting#does-grax-support-enhanced-domains)

#### OAuth Errors During Connection

If you encounter OAuth errors:

1. Verify "Approve Uninstalled Connected Apps" permission on the connecting user
2. Check that the GRAX Connected App is installed
3. Verify network connectivity and IP whitelisting

**Learn more:** [Connected App troubleshooting](https://documentation.grax.com/other/connected-app#troubleshooting)

### Related Documentation

* [Authentication](https://documentation.grax.com/security/authentication#oauth-flow) - Complete OAuth flow and security details
* [Connected App](https://documentation.grax.com/other/permissions-and-access/connected-app) - Installation and configuration
* [Integration User](https://documentation.grax.com/other/permissions-and-access/integration-user) - User requirements and setup
* [Connecting Salesforce](https://documentation.grax.com/settings#salesforce-panel) - Step-by-step connection guide
* [Network Requirements](https://documentation.grax.com/infrastructure/requirements/network-requirements) - Required network access for GRAX Deployments
* [Troubleshooting](https://documentation.grax.com/other/troubleshooting) - Common issues and solutions