{"id":16914,"library":"tauri-plugin-auth-session-api","title":"Tauri Plugin Auth Session API","description":"This package provides the TypeScript API for `tauri-plugin-auth-session`, a Tauri v2 plugin designed for secure in-app OAuth authentication across mobile and desktop platforms. It leverages native browser authentication sessions: `ASWebAuthenticationSession` on macOS and iOS, and Chrome Custom Tabs on Android. The plugin enables a seamless, secure authorization flow by capturing OAuth redirects to custom URL schemes directly within the app, bypassing the need for external browser launches or localhost web server listeners. It's crucial for Tauri v2 mobile development, where traditional desktop OAuth patterns are impractical. The current stable version is 0.2.2, indicating active development within the v0 series, with new features and stability improvements likely tied to the progression of Tauri v2 itself. Key differentiators include a single `start()` API call, native browser security (credentials never touch WebView), SSO support, and full compatibility with PKCE/OAuth 2.0/OIDC providers.","status":"active","version":"0.2.2","language":"javascript","source_language":"en","source_url":"https://github.com/yanqianglu/tauri-plugin-auth-session","tags":["javascript","tauri","tauri-plugin","oauth","authentication","ios","android","macos","custom-tabs","typescript"],"install":[{"cmd":"npm install tauri-plugin-auth-session-api","lang":"bash","label":"npm"},{"cmd":"yarn add tauri-plugin-auth-session-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add tauri-plugin-auth-session-api","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for interacting with the Tauri core and invoking plugin functionality.","package":"@tauri-apps/api","optional":false}],"imports":[{"note":"The primary function to initiate the authentication flow. Use named import as the package is ESM-first.","wrong":"const { start } = require('tauri-plugin-auth-session-api');","symbol":"start","correct":"import { start } from 'tauri-plugin-auth-session-api';"},{"note":"Type import for the configuration object passed to the `start` function, common in TypeScript projects.","wrong":"import { AuthSessionOptions } from 'tauri-plugin-auth-session-api';","symbol":"AuthSessionOptions","correct":"import type { AuthSessionOptions } from 'tauri-plugin-auth-session-api';"}],"quickstart":{"code":"import { start } from 'tauri-plugin-auth-session-api';\n\n/**\n * Initiates an OAuth 2.0 PKCE authentication flow with Google.\n * Replace placeholders with your actual OAuth provider details.\n * \n * NOTE: This client-side code assumes a backend will handle the code exchange for tokens.\n * For a purely public client, you'd exchange the code directly.\n */\nasync function authenticateWithGoogle(): Promise<void> {\n  const clientId = 'YOUR_GOOGLE_CLIENT_ID'; // Replace with your actual client ID\n  const redirectUri = 'myapp://oauth-callback'; // Must match your native app setup (AndroidManifest, Associated Domains)\n  const scope = 'openid profile email';\n\n  // In a real application, you would securely generate code_verifier and code_challenge\n  // For simplicity, placeholders are used here.\n  const codeVerifier = 'YOUR_GENERATED_CODE_VERIFIER';\n  const codeChallenge = 'YOUR_GENERATED_CODE_CHALLENGE_S256';\n\n  const authorizeUrl = `https://accounts.google.com/o/oauth2/v2/auth?` +\n                       `client_id=${clientId}&` +\n                       `redirect_uri=${encodeURIComponent(redirectUri)}&` +\n                       `response_type=code&` +\n                       `scope=${encodeURIComponent(scope)}&` +\n                       `state=secure_random_state_string&` + // Always generate a cryptographically secure state\n                       `code_challenge=${codeChallenge}&` +\n                       `code_challenge_method=S256`;\n\n  try {\n    console.log('Starting OAuth flow...');\n    const callbackUrl = await start({\n      authorizeUrl,\n      redirectUri: redirectUri, // The scheme and host your app will intercept\n      ephemeral: false // Set to true on Apple platforms for non-SSO sessions\n    });\n\n    console.log('OAuth callback URL received:', callbackUrl);\n    const url = new URL(callbackUrl);\n    const code = url.searchParams.get('code');\n    const state = url.searchParams.get('state');\n\n    if (code && state) {\n      console.log('Authorization Code:', code);\n      console.log('State:', state);\n      // Now, exchange the 'code' for access/refresh tokens.\n      // This is typically done on a backend server to keep client secret secure.\n    } else {\n      console.error('Authorization code or state not found in callback URL.');\n    }\n  } catch (error) {\n    console.error('OAuth flow failed:', error);\n    if (error instanceof Error && error.message.includes(\"unsupported platform\")) {\n      console.warn(\"Authentication is not supported on this platform (Windows/Linux).\");\n    }\n  }\n}\n\n// Example usage (e.g., triggered by a button click)\n// authenticateWithGoogle();","lang":"typescript","description":"Demonstrates how to initiate an OAuth 2.0 PKCE authorization flow using the `start` function, targeting a Google provider. It shows the construction of the authorization URL, handling the intercepted redirect callback, and extracting the authorization code and state."},"warnings":[{"fix":"Add `tauri-plugin-auth-session = { git = \"https://github.com/yanqianglu/tauri-plugin-auth-session\" }` to `src-tauri/Cargo.toml` and `tauri::Builder::default().plugin(tauri_plugin_auth_session::init()).run(...)` to your `lib.rs`.","message":"This package is the frontend API for `tauri-plugin-auth-session`. You must also install and configure the Rust plugin counterpart in `src-tauri/Cargo.toml` and register it in `src-tauri/src/lib.rs` for the JavaScript API to function.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Add the provided `<activity>` and `<intent-filter>` XML snippet to `src-tauri/gen/android/app/src/main/AndroidManifest.xml`, replacing `myapp` with your actual custom URL scheme.","message":"For Android, you must manually add an `intent-filter` to `AuthSessionActivity` in your app's `AndroidManifest.xml` to correctly capture OAuth redirect URLs. Failure to do so will prevent the redirect from returning to your application.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Add `\"auth-session:default\"` to the `permissions` array in your capability file, e.g., `src-tauri/capabilities/default.json`.","message":"The `tauri-plugin-auth-session` requires the `auth-session:default` capability to be enabled in your Tauri application's `default.json` or other capability file.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Handle the error gracefully in your application logic, or conditionally disable the authentication flow on unsupported platforms. Provide alternative authentication methods for Windows/Linux if necessary.","message":"The plugin's core `start()` function is a stub on Windows and Linux platforms. Calling it on these systems will always result in an error, as the native authentication methods (ASWebAuthenticationSession, Chrome Custom Tabs) are not available.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Install the correct version of the peer dependency: `npm install @tauri-apps/api@next` or `yarn add @tauri-apps/api@next`.","message":"This package relies on `@tauri-apps/api` version `2.0.0` or higher as a peer dependency. Ensure your project has the correct major version installed, specifically `@tauri-apps/api@next` for Tauri v2.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Verify the Rust installation steps, ensuring both `Cargo.toml` specifies the plugin dependency and `lib.rs` registers `tauri_plugin_auth_session::init()`.","cause":"The Tauri Rust plugin `tauri-plugin-auth-session` was not correctly added to `src-tauri/Cargo.toml` or not initialized in `src-tauri/src/lib.rs`.","error":"Plugin 'auth-session' not found or not initialized."},{"fix":"Add `import { start } from 'tauri-plugin-auth-session-api';` at the top of your relevant source file.","cause":"The `start` function was not correctly imported from the `tauri-plugin-auth-session-api` package in your TypeScript/JavaScript file.","error":"Cannot find name 'start'."},{"fix":"Add the provided `<activity>` and `<intent-filter>` XML snippet, replacing `myapp` with your actual scheme, to `src-tauri/gen/android/app/src/main/AndroidManifest.xml`.","cause":"The `AndroidManifest.xml` for your Android application was not correctly configured with the `intent-filter` for `AuthSessionActivity` and your custom URL scheme.","error":"java.lang.RuntimeException: AuthSessionActivity not found. Did you register the intent filter in AndroidManifest.xml?"},{"fix":"Implement platform-specific logic (e.g., using `import { platform } from '@tauri-apps/api/os';`) to disable or provide alternative authentication methods when running on Windows or Linux, or ensure error handling is robust.","cause":"Attempted to call the `start()` function on an unsupported platform (Windows or Linux).","error":"error invoking 'plugin:auth-session|start': unsupported platform"},{"fix":"Replace `const { start } = require('tauri-plugin-auth-session-api');` with `import { start } from 'tauri-plugin-auth-session-api';`.","cause":"Attempting to use CommonJS `require()` syntax in a modern JavaScript or TypeScript project that is configured for ES Modules (ESM).","error":"ReferenceError: require is not defined"}],"ecosystem":"npm","meta_description":null}