wiki/d-guides/infomaniak-oauth-setup.md

Infomaniak OAuth 2.0 Setup Guide

Overview

This guide explains how to register an Infomaniak OAuth application so that PowerOn users can connect their Infomaniak account as a data source. The connection exposes two services in the Unified Data Bar:

• kDrive -- browse and download files from any drive accessible to the user.
• Mail -- browse mailboxes, folders, and download messages as .eml.

Infomaniak is a data-only authority in PowerOn. It is not a login provider; users still authenticate against PowerOn via Local / Google / Microsoft.

Prerequisites

• An Infomaniak account with admin rights to create API credentials.
• Access to the Infomaniak Manager (https://manager.infomaniak.com).
• The PowerOn gateway publicly reachable (or http://localhost:8000 for development).

Step 1: Create an Infomaniak API Application

1. Login to https://manager.infomaniak.com.
2. Navigate to your account icon (top right) > API.
3. Click Create a new application.
4. Fill in:
   • Name: PowerOn (or your project name)
   • Description: Data connector for kDrive + Mail
   • Redirect URI: must exactly match the gateway endpoint:
     • Development: http://localhost:8000/api/infomaniak/auth/connect/callback
     • Production: https://<gateway-host>/api/infomaniak/auth/connect/callback
5. Select scopes:
   • user_info -- required to read /1/profile for externalId / email.
   • kdrive -- required for the kDrive ServiceAdapter.
   • mail -- required for the Mail ServiceAdapter.
6. Save and copy the generated Client ID and Client Secret.

Step 2: Configure PowerOn Gateway

Add the following keys to your gateway environment file (e.g. gateway/env_dev.env):

# Infomaniak OAuth -- Data App (kDrive + Mail)
Service_INFOMANIAK_DATA_CLIENT_ID = your-client-id
Service_INFOMANIAK_DATA_CLIENT_SECRET = your-client-secret
Service_INFOMANIAK_OAUTH_REDIRECT_URI = http://localhost:8000/api/infomaniak/auth/connect/callback

For production, replace the redirect URI with your HTTPS gateway host. The URI must be identical (byte-for-byte) to the one registered in step 1.

Restart the gateway after editing the env file so APP_CONFIG is reloaded.

Step 3: Verify the Flow

1. Login to PowerOn and open Basisdaten > Verbindungen.
2. Click Infomaniak in the header actions.
3. A popup opens against https://login.infomaniak.com/authorize.
4. Sign in with your Infomaniak account, grant the requested scopes.
5. The popup closes automatically and the new connection appears with status connected.
6. Open the Unified Data Bar > Sources tab; you should see the Infomaniak authority node with kdrive and mail services.

Token Lifecycle

• Access tokens are short-lived (refresh handled automatically by tokenRefreshService._refresh_infomaniak_token).
• Refresh tokens are stored alongside the connection (Token.tokenRefresh).
• If a refresh returns invalid_grant, the user must reconnect (popup again via the Infomaniak button on ConnectionsPage).

Troubleshooting

invalid_redirect_uri

The URI registered on Infomaniak Manager does not match Service_INFOMANIAK_OAUTH_REDIRECT_URI. They must be byte-identical (including protocol, host, port, and path).

invalid_client

Client ID or secret in the env file does not match what Infomaniak issued. Re-copy the values from Manager > API.

Profile lookup returns 401

The user_info scope was not granted. Re-create the application with the correct scope set, or reconnect the user.

Empty kDrive listing

The user has no kDrives associated. Verify on https://kdrive.infomaniak.com that at least one drive is accessible.

Security Notes

• Never commit the client secret. Use the encrypted env mechanism described in wiki/d-guides/encrypt-env-secrets.md.
• Rotate the client secret if it leaks; update Service_INFOMANIAK_DATA_CLIENT_SECRET and restart the gateway. Existing tokens remain valid only until they expire.
• The connector is scoped to DATA_CONNECTION only. Even with valid Infomaniak credentials, no PowerOn login session is created.

Reference

• Code: gateway/modules/connectors/providerInfomaniak/connectorInfomaniak.py
• OAuth route: gateway/modules/routes/routeSecurityInfomaniak.py
• Token refresh: gateway/modules/auth/tokenManager.py::refreshInfomaniakToken
• Frontend hook: frontend_nyla/src/hooks/useConnections.ts::createInfomaniakConnectionAndAuth