105 lines
4.4 KiB
Markdown
105 lines
4.4 KiB
Markdown
# 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`):
|
|
|
|
```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`
|