> ## Documentation Index
> Fetch the complete documentation index at: https://docs.btsscorp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth PKCE Authentication

> Enterprise authentication with OAuth 2.0 PKCE for Oracle Fusion Cloud

## Overview

OAuth 2.0 PKCE authentication provides enterprise-grade security for connecting to Oracle Fusion Cloud. This feature integrates with your organization's existing Single Sign-On (SSO) through Oracle Identity and Access Management (IAM).

<Note>
  OAuth PKCE authentication requires a paid license. See [Free vs Paid Features](/koala/licensing/free-vs-paid) for more information.
</Note>

## Benefits of OAuth PKCE

### Enhanced Security

* No password storage in VS Code
* Token-based authentication with PKCE
* Automatic token refresh
* Leverages existing enterprise SSO and MFA

### Enterprise Integration

* Uses your existing Oracle Identity Domain
* Centralized access management through Oracle IAM
* Compliance with corporate security policies
* Full audit trail in Oracle systems

### User Experience

* Single sign-on with enterprise credentials
* No password management required
* Seamless re-authentication
* Session persistence across VS Code restarts

## Authentication Flow

Koala Data Explorer implements OAuth 2.0 PKCE authentication specifically with:

* **Oracle Identity Domains** (part of Oracle Cloud Infrastructure)
* **Oracle Fusion Cloud Applications** resource access
* **PKCE (Proof Key for Code Exchange)** for enhanced security

## Setting Up OAuth PKCE Authentication

OAuth PKCE setup requires coordination between your Oracle administrator and end users. The process has two phases:

### Phase 1: Administrator Setup (One-Time)

Your Oracle administrator must first configure OAuth in Oracle Identity and Access Management (IAM).

#### Prerequisites for Administrators

* Access to Oracle Cloud console
* Administrator privileges in the Fusion Identity Domain
* Same identity domain used by your Oracle Fusion instance

#### Admin Configuration Steps

**Step 1: Access Oracle IAM Console**

1. Log into Oracle Cloud console
2. Navigate to **Identity & Security** → **Identity Domains**
3. Select your Fusion Identity Domain
4. Go to **Applications**

**Step 2: Create OAuth Application**

1. Click **Add Application**
2. Select **Mobile Application** (creates a public PKCE client)
3. Click **Launch Workflow**

**Step 3: Configure Application Details**

*Basic Information:*

* **Name**: `Koala Data Explorer OAuth Client`
* **Description**: `VS Code extension for Oracle Fusion data access`

*Client Configuration:*

* **Client Type**: Public (automatically set)
* **Grant Types**: Select "Authorization Code"
* **PKCE**: Enabled (automatic for mobile apps)
* **Redirect URI**: Add exactly:
  ```
  vscode://btss-corp.koala-data-explorer/oauth/callback
  ```
  <Warning>This URI must match exactly - no trailing slashes or variations</Warning>

*Resource and Scope Configuration:*

* **Add Resource**: Select "Oracle Applications Cloud (Fusion)"
* **Scopes**: System auto-generates required scope like:
  ```
  urn:opc:resource:fa:instanceid=12345urn:opc:resource:consumer::all
  ```
* **Bypass Consent**: Enable (recommended for internal use)
* **Trust Scope**: Enable for all selected scopes

**Step 4: Collect Configuration Values**

Document these values for end users:

* **Client ID**: Found in General → Client ID
* **Authorization Endpoint**: `https://your-idcs-instance.identity.oraclecloud.com/oauth2/v1/authorize`
* **Token Endpoint**: `https://your-idcs-instance.identity.oraclecloud.com/oauth2/v1/token`
* **Scope**: The auto-generated resource identifier from Step 3

### Phase 2: End User Setup

Once administrators complete Phase 1, end users can configure OAuth connections:

#### Step 1: Add OAuth Connection

1. Open Koala Data Explorer in VS Code
2. Press `Ctrl+Shift+P` → "Koala: Manage Connections"
3. Click **Add Connection**
4. Select **OAuth PKCE** as authentication type

#### Step 2: Enter Configuration Details

Use the values provided by your administrator:

* **Connection Name**: Descriptive name (e.g., "Production OAuth")
* **Oracle Fusion URL**: Your Fusion instance URL
* **Client ID**: From administrator
* **Authorization Endpoint**: From administrator
* **Token Endpoint**: From administrator
* **Scope**: From administrator

#### Step 3: Authenticate

1. Click **Save** to save the connection
2. Select the connection and click **Connect**
3. Your browser opens for SSO authentication
4. Log in with your enterprise credentials
5. Complete any MFA requirements
6. VS Code receives the authentication token
7. Connection is established

#### Step 4: BIP Catalog Deployment

<Warning>
  OAuth connections cannot automatically deploy the required BIP catalog.
</Warning>

After successful authentication:

1. Click **Deploy to BIP** button in the query editor
2. Select **Download Catalog** option
3. Save the `Koala.catalog` file
4. Send this file to your Oracle administrator
5. Request deployment to `/Custom/Koala/` in the BIP catalog

## Token Management

OAuth PKCE authentication uses secure token-based access with automatic refresh capabilities.

### Automatic Token Refresh

Koala Data Explorer automatically:

* Monitors token expiration
* Refreshes tokens before expiry
* Handles refresh failures gracefully
* Prompts for re-authentication when needed

### Token Security

* Tokens stored in VS Code's secure credential storage
* Encrypted at rest and in transit
* Never logged or exposed in diagnostics
* Automatically cleared when connection is removed

## Troubleshooting OAuth PKCE

### Common Issues

**"Client authentication failed"**

* Verify application is configured as Mobile/Public client in Oracle IAM
* Ensure PKCE is enabled in grant types
* Check Client ID matches exactly

**"Invalid redirect URI"**

* Verify redirect URI matches exactly: `vscode://btss-corp.koala-data-explorer/oauth/callback`
* Check for typos or extra characters
* Ensure no trailing slashes

**"Invalid scope"**

* Verify scope string from Oracle administrator
* Check that Fusion resource is properly configured in Oracle IAM
* Ensure identity domain matches Fusion instance

**Browser doesn't open for authentication**

* Check that default browser is set in your system
* Try copying the authorization URL manually to browser
* Verify network firewall settings allow browser communication

**Authentication successful but connection fails**

* Verify token endpoints are correct
* Check Oracle Fusion URL is accessible
* Ensure user has proper Fusion access rights and roles

## Best Practices

### For Administrators

* Use descriptive names for OAuth applications in Oracle IAM
* Document configuration values for end users
* Regularly review OAuth application permissions
* Monitor authentication logs in Oracle IAM console
* Keep identity domain aligned with Fusion instance

### For End Users

* Use OAuth PKCE for production environments
* Leverage existing enterprise SSO and MFA policies
* Test connections after Oracle system maintenance
* Remove unused connections to maintain security
* Contact administrators for configuration issues

### Security Considerations

* OAuth PKCE provides enhanced security over Basic authentication
* No passwords stored in VS Code
* Centralized access control through Oracle IAM
* Full audit trail in Oracle systems
* Automatic compliance with corporate identity policies

## Next Steps

<CardGroup cols={2}>
  <Card title="Managing Connections" icon="server" href="/koala/connections/managing-connections">
    Manage multiple connections
  </Card>

  <Card title="Security Best Practices" icon="shield" href="/koala/config/extension-settings">
    Configure security settings
  </Card>
</CardGroup>