Skip to main content

​
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).
OAuth PKCE authentication requires a paid license. See Free vs Paid Features for more information.

​
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
    This URI must match exactly - no trailing slashes or variations
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

OAuth connections cannot automatically deploy the required BIP catalog.
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

Managing Connections

Manage multiple connections

Security Best Practices

Configure security settings