Auth for webviews

[aisraelov]

App webviews don't have a way of authenticating with AugmentOS right now, meaning they can't be personalized per-user.

[OkGoDoIt]

I've already built a potential solution to this for my own use, I'd be happy to take this one on

[OkGoDoIt]

The goal of this is to provide a secure and straightforward mechanism for third-party web applications, loaded within the AugmentOS manager application's webview, to identify the current AugmentOS user. This enables personalized experiences within the third-party context without requiring the user to log in separately to that service.

2a. Initial Scope

• Authentication flow for web applications loaded via the integrated webview within the AugmentOS manager app.
• Generation of short-lived, temporary tokens within the AugmentOS ecosystem.
• Passing the temporary token via a URL query string parameter.
• A secure server-to-server cloud endpoint for exchanging the temporary token and developer API key for a validated User ID.
• SDK helper functions (optional but recommended) to simplify implementation for developers using supported frameworks.
• Documentation detailing the flow and security requirements for all developers.

2b. Additional Options

Once the initial implementation is done, we will want a more complete implementation that allows users to authenticate on devices other than the phone where they are running the AugmentOS app.

• Option A: Full OAuth 2.0 Implementation:
  • Implement AugmentOS as a standard OAuth 2.0 provider. Third-party applications (web, mobile, desktop) would redirect users to an AugmentOS authorization page. Users log in (if needed) and grant consent. AugmentOS redirects back with an authorization code, which the third-party backend exchanges for access/refresh tokens to call AugmentOS APIs or get user info.
  • Pros: Industry standard, flexible, supports various grant types, familiar to developers.
  • Cons: Significant implementation complexity (authorization server, consent screens, token management, scope definition), potentially longer timeline.
• Option B: On-Glasses Token Display:
  • For authenticating on devices not directly connected via the manager app (e.g., a desktop browser). The user visits the third-party site, which prompts for a code. The user requests a short code via their glasses interface (e.g., voice command, gesture). The code (e.g., 4-6 digits/characters, short-lived) appears on the glasses display. The user enters this code into the website. The website backend validates the code with an AugmentOS cloud endpoint.
  • Pros: Allows linking from any device, leverages the unique hardware, much faster to implement than full OAuth
  • Cons: Requires user interaction (manual code entry), less seamless UX than OAuth redirects, non-standard flow.

The choice between these (or combining elements) depends on product strategy, developer needs, desired user experience, and engineering resources.

3. Webview Query String Token Exchange

This solution leverages a short-lived temporary token passed in the URL, which is then securely exchanged server-side for user identification.

3.1 User Experience

1. The user interacts with the AugmentOS manager app (e.g., taps the gear, long-presses the app in the app list)
2. The manager app opens an integrated webview, loading the specified third-party URL.
3. The third-party web application loads and, through the mechanism described below, recognizes the AugmentOS user, potentially displaying personalized content. The user does not need to manually enter credentials.

3.2 Detailed Technical Flow

1. Trigger: An action within the AugmentOS manager app initiates the loading of a third-party URL into a webview.
2. Temporary Token Request (App -> AugmentOS Backend/SDK): Before loading the URL, the manager app requests a single-use, temporary authentication token from a secure AugmentOS service. This service generates a cryptographically secure, opaque token associated with the current User ID and the target developer (identified implicitly or explicitly). The token has a short Time-To-Live (TTL).
3. Token Generation & Storage (AugmentOS Backend): The AugmentOS backend generates the token (e.g., a UUID or secure random string), stores it temporarily (e.g., in Redis/Memcached) along with the associated User ID, the intended developer's identifier (e.g., their App ID or API Key ID), and an expiry timestamp (e.g., 60 seconds from creation).
4. URL Construction (App): The manager app receives the temporary token and appends it as a query string parameter to the target URL. Example: https://partnerapp.com/dashboard?aos_temp_token=TEMP_TOKEN_ABC123XYZ
5. Webview Load (App): The manager app loads the modified URL into the integrated webview component.
6. Request Reception (Developer Backend): The developer's web server receives the incoming GET request for the URL.
7. Token Extraction (Developer Backend): The developer's server-side application code extracts the value of the aos_temp_token parameter from the request URL.
8. Token Exchange (Developer Backend -> AugmentOS Cloud API): The developer's backend makes a server-to-server API call to a dedicated AugmentOS cloud endpoint (e.g., POST https://cloud.augmentos.com/auth/v1/exchange). This request MUST include:
   • The extracted aos_temp_token.
   • The developer's secret API key (provided via a secure mechanism, typically an Authorization HTTP header like Authorization: Bearer <developer_secret_api_key>).
9. Validation (AugmentOS Cloud API): The AugmentOS /exchange endpoint performs the following checks:
   • Authenticates the developer using the provided API key.
   • Retrieves the temporary token data from its temporary store.
   • Verifies that the token exists, has not expired, and has not already been used.
   • Verifies that the token was intended for use by the authenticated developer (matching API key/App ID).
10. Mark Token Used (AugmentOS Cloud API): If validation succeeds, the endpoint immediately marks the temporary token as used in the temporary store to prevent replay attacks.
11. Response (AugmentOS Cloud API -> Developer Backend): If validation is successful, the API responds with a success status (e.g., 200 OK) and a JSON payload containing the authenticated AugmentOS User ID. Example Success Response Body: { "user_id": "AUG_USER_987654321" } Example Error Responses: 401 Unauthorized (invalid API key), 404 Not Found (token doesn't exist), 410 Gone (token expired or already used), 403 Forbidden (token not intended for this developer), 400 Bad Request (malformed request).
12. Session Creation (Developer Backend): The developer's backend receives the User ID. It can now trust that the request originated from the specified AugmentOS user within the app's webview. The backend uses this User ID to:
    • Look up or create a corresponding user account in its own system.
    • Establish a standard web session for the user (e.g., by setting a secure, HttpOnly session cookie).
13. Personalized Response (Developer Backend -> Webview): The developer's server renders and returns the web page, now tailored or authenticated for the identified user.

3.3 Component Responsibilities

• AugmentOS Manager App: Responsible for initiating the flow, requesting the temporary token, constructing the URL, and loading the webview.
• AugmentOS Cloud/Backend: Responsible for generating, storing, and validating temporary tokens; providing the secure /exchange endpoint; authenticating developers via API keys; returning the User ID.
• Developer Backend: Responsible for extracting the token from the URL, securely storing its API key, calling the /exchange endpoint, handling the response, managing its own user sessions, and ensuring overall web application security.
• AugmentOS SDK (Optional): Can provide helper functions for developers to simplify extracting the token and calling the /exchange endpoint within supported backend frameworks (e.g., Node.js/Express, Python/Flask).

4. Implementation Details

• Temporary Token:
  • Format: Securely generated random string (e.g., 32+ bytes of randomness, base64 encoded) or UUID v4.
  • Lifetime: Configurable, recommended default 60 seconds.
• Cloud Endpoint (/auth/v1/exchange):
  • Standard RESTful API principles.
  • Requires POST method.
  • Expects Authorization: Bearer <developer_secret_api_key> header.
  • Expects JSON body: { "temp_token": "value" }.
  • Returns JSON responses with appropriate HTTP status codes.
• SDK:
  • Handles the developer side automatically (listens for the aos_temp_token and exchanges it on a developer's behalf)
  • Provide clear examples.
• Documentation:
  • Clearly explain the flow.
  • Provide code examples for extracting the token and calling the endpoint (e.g., using curl, Python requests, Node.js fetch).

5. Security Considerations

This section addresses the security implications and required mitigations:

• Query String Exposure:
  • Risk: The temporary token is visible in the URL, potentially logged by browsers, proxies, or server logs.
  • Mitigation: This is acceptable the token meets all the following criteria:
    1. Extremely Short-Lived: Limits the window for interception and use (e.g., 60 seconds).
    2. Opaque: Contains no sensitive user or session information itself. It's merely a pointer.
    3. Requires Server-Side Secret: Useless without the developer's secret API key, which is never exposed client-side. The exchange must happen server-to-server.
    4. HTTPS: End-to-end TLS encryption protects the token (and the rest of the request/response) in transit.
• API Key Security:
  • Risk: Compromise of a developer's API key would allow an attacker (if they could also obtain temporary tokens) to impersonate users within that developer's application.
  • Mitigation: This is the most critical aspect for the developer to manage.
    1. Strict Server-Side Use: Keys must never be embedded in client-side code (JavaScript, mobile app binaries).
    2. Secure Storage: Keys must be stored securely on the developer's backend (e.g., environment variables, secrets management systems).
    3. Clear Documentation: AugmentOS documentation must heavily emphasize these points.
• Replay Attacks:
  • Risk: An attacker intercepts a token and tries to reuse it.
  • Mitigation: Enforced single-use nature of the token (backend invalidation upon first successful use) combined with the short expiry time.
• Transport Security:
  • Risk: Eavesdropping or modification of requests/responses.
  • Mitigation: Mandate HTTPS for the webview load and the server-to-server /exchange API call.
• Token Predictability:
  • Risk: Attacker guesses valid tokens.
  • Mitigation: Use a cryptographically secure random number generator (CSRNG) to create tokens with sufficient entropy (e.g., >= 128 bits). Do not use sequential or easily guessable identifiers.