Security

This guide explains gau’s security features.

Host Validation

To protect against common web vulnerabilities, gau uses the trustHosts option to validate where requests are coming from and where users are being sent. This is a critical defense against both CSRF and Open Redirect attacks.

This is configured via the trustHosts option in createAuth.

Open Redirect Prevention

After login, you might want to send users to a specific page using the redirectTo parameter. Without validation, an attacker could trick users into being redirected to a phishing site.

gau checks that the redirectTo URL points to a hostname in your trustHosts list. If it doesn’t match, the redirect is blocked.

Note

Client-side integrations automatically set redirectTo to their URL. You just need to whitelist the hostnames on the server’s createAuth config.

CSRF Protection

A malicious site could try to make requests to your auth endpoints on behalf of a logged-in user. gau prevents this by checking the Origin header on all POST requests (like /api/auth/signout). Only requests from hosts in your trustHosts list are allowed.

Configuration

• Default behavior: By default, trustHosts is an empty array ([]), which means gau will only allow requests and redirects that originate from or point to the same host as your application.

  Note

  In development, localhost and 127.0.0.1 are automatically trusted.

• Configuring specific hosts: When your frontend and backend are on different domains, or you need to redirect to a subdomain, you must add those hosts to the list.

  trustHosts: [
    'app.example.com',  // Production frontend
    'tauri.localhost',  // Production Tauri app
  ]

• Trust all hosts ('all'): This setting disables host validation and is not recommended for production.

In addition to trustHosts, gau also uses a temporary state-based CSRF token (__gau-csrf-token cookie) during the OAuth flow itself. This ensures that the user who starts the authentication process is the same one who finishes it, providing an extra layer of security against CSRF during login.

PKCE

OAuth 2.1 added PKCE to ensure that the client asking for the token is the same client that initiated the login flow. gau implements this in two layers, for both web and native apps.

Server-to-Provider PKCE

gau automatically uses PKCE when communicating with OAuth providers.

1. The gau server generates a code_verifier and code_challenge.
2. It sends the code_challenge to the provider during the authorization request.
3. When exchanging the provider’s authorization code for tokens, it sends the code_verifier.

Client-to-Server PKCE (Native Apps)

Deep links (like my-app://callback) can potentially be intercepted by other apps on the device. To prevent this, gau adds another PKCE layer between your app and the server:

1. Initiation: The Tauri app generates a code_verifier and code_challenge. It sends the code_challenge to the gau server when starting the sign-in.
2. Callback: After authenticating with the provider, the gau server issues a short-lived Auth Code (instead of a session token) and redirects back to the app via deep link.
3. Exchange: The app intercepts the deep link, extracts the Auth Code, and sends it along with the original code_verifier to the server’s /token endpoint.
4. Validation: The server verifies the Auth Code and checks that the code_verifier matches the initial challenge. Only then is a session token issued.

This way, even if another app intercepts the deep link, it can’t get a session token because it doesn’t have the secret code_verifier.

Secure Cookie Defaults

gau applies safe defaults to the session cookie (__gau-session-token):

• httpOnly: true: JavaScript can’t read the cookie, protecting against XSS attacks.
• secure: true: The cookie is only sent over HTTPS.
• sameSite: 'lax': Protects against most CSRF attacks while still working with normal navigation.

You can customize these settings via the cookies option, for example, to enforce 'strict' same-site policies if your application’s flow allows for it.