gitea-admin/gh-christianlouis-docuelevate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: enhance FTP configuration with TLS options and update documentation

Browse Source 
Enhanced OneDrive workflow and tested
This commit is contained in:
Christian Krakau-Louis
2025-04-02 02:57:30 +02:00
parent 81296b93f8
commit c3df8107d8
15 changed files with 1242 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/OneDriveSetup.md
+61 -20
View File
@@ -14,6 +14,27 @@ This guide explains how to set up the Microsoft OneDrive integration for DocuNov
For a complete list of configuration options, see the [Configuration Guide](ConfigurationGuide.md).
## Setup Methods
You can set up OneDrive integration in two ways:
1. **Using the Auth Wizard (Recommended)**: An interactive setup experience available at `/onedrive-setup` in the web interface
2. **Manual Setup**: Following the step-by-step instructions in this document
## Using the Auth Wizard
The easiest way to set up OneDrive integration is to use the built-in auth wizard:
1. Register an application in Azure AD (see steps below)
2. Navigate to the OneDrive Setup page at `/onedrive-setup`
3. Enter your Client ID and other required information
4. Click "Start Authentication Flow"
5. Complete the Microsoft authentication process
6. The system will automatically exchange the authorization code for a refresh token
7. Copy the generated environment variables for your worker nodes
The auth wizard handles all the token exchange steps and provides you with the exact configuration needed for your environment.
## Types of Microsoft Accounts
There are two main types of Microsoft accounts that can be used with OneDrive integration:
@@ -34,7 +55,9 @@ The setup process differs slightly based on which account type you're using.
5. For "Supported account types", select the appropriate option:
- For personal accounts: "Accounts in any organizational directory and personal Microsoft accounts"
- For corporate accounts only: "Accounts in this organizational directory only"
6. For Redirect URI, select "Web" and enter a URL you can access (e.g., `http://localhost:8000/auth/callback`)
6. For Redirect URI, select "Web" and enter your callback URL:
- For auth wizard: `https://your-domain.com/onedrive-callback`
- For manual setup: any URL you can access (e.g., `http://localhost:8000/auth/callback`)
7. Click "Register"
### 2. Get Application (client) ID
@@ -50,6 +73,21 @@ The setup process differs slightly based on which account type you're using.
4. Click "Add" and immediately copy the secret value (it will only be shown once)
5. Set this value as `ONEDRIVE_CLIENT_SECRET`
### 4. Configure API permissions
1. In your application page, go to "API permissions"
2. Click "Add a permission"
3. Select "Microsoft Graph" > "Delegated permissions"
4. Search for and add the following permission:
- `Files.ReadWrite` (Allows the app to read and write files that the user has access to)
- `offline_access` (Required for refresh tokens)
5. If using application permissions (for service accounts), add:
- `Files.ReadWrite.All` (Required for app-only access)
6. Click "Add permissions"
7. For organizational accounts, you may need an admin to "Grant admin consent"
> **Important Scope Change**: The system now uses the `.default` scope during authentication, which requests all permissions that have been granted to the application. This ensures that the app has all required permissions at once, rather than requesting each scope individually.
## For Personal Microsoft Accounts
If you're using a personal Microsoft account (@outlook.com, @hotmail.com, or personal accounts linked to other emails):
@@ -58,34 +96,31 @@ If you're using a personal Microsoft account (@outlook.com, @hotmail.com, or per
- Set `ONEDRIVE_TENANT_ID=common` in your configuration
### 2. Configure API permissions
### 2. Generate a Refresh Token
1. In your application page, go to "API permissions"
2. Click "Add a permission"
3. Select "Microsoft Graph" > "Delegated permissions"
4. Search for and add the following permissions:
- `Files.ReadWrite` (Allows the app to read and write files that the user has access to)
- `offline_access` (Needed for refresh tokens)
5. Click "Add permissions"
### 3. Generate a Refresh Token
#### Using the Auth Wizard (Recommended)
1. Navigate to the OneDrive Setup page at `/onedrive-setup`
2. Enter your Client ID and leave Tenant ID as "common"
3. Click "Start Authentication Flow" and follow the prompts
4. The wizard will handle token exchange automatically
#### Manual Method
1. Use the following URL (replace CLIENT_ID and REDIRECT_URI with your values):
```
https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=YOUR_REDIRECT_URI&response_mode=query&scope=offline_access%20Files.ReadWrite
https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=YOUR_REDIRECT_URI&response_mode=query&scope=https://graph.microsoft.com/.default offline_access&prompt=consent
```
2. Open this URL in your browser
3. Sign in with your personal Microsoft account
4. After authentication, you'll be redirected to your redirect URI with a code parameter in the URL
5. Copy the code value from the URL (everything after "code=")
### 4. Exchange Code for Refresh Token
### 3. Exchange Code for Refresh Token (Manual Method Only)
1. Use the following command to exchange the code for tokens:
```bash
curl -X POST https://login.microsoftonline.com/common/oauth2/v2.0/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=YOUR_CLIENT_ID&scope=offline_access Files.ReadWrite&code=YOUR_AUTH_CODE&redirect_uri=YOUR_REDIRECT_URI&grant_type=authorization_code&client_secret=YOUR_CLIENT_SECRET"
-d "client_id=YOUR_CLIENT_ID&scope=https://graph.microsoft.com/.default offline_access&code=YOUR_AUTH_CODE&redirect_uri=YOUR_REDIRECT_URI&grant_type=authorization_code&client_secret=YOUR_CLIENT_SECRET"
```
2. From the response JSON, copy the `refresh_token` value
3. Set this as `ONEDRIVE_REFRESH_TOKEN` in your configuration
@@ -104,10 +139,11 @@ If you're using a work/school account provided by your organization:
**Option A: Access your own OneDrive (Interactive Login)**
This option requires a refresh token just like personal accounts:
1. Follow the same steps as for personal accounts, but use your work email to sign in
2. Make sure to set `ONEDRIVE_TENANT_ID` to your organization's tenant ID instead of "common"
3. Set the refresh token you receive as `ONEDRIVE_REFRESH_TOKEN`
This option requires a refresh token:
1. Use the auth wizard with your tenant ID, or
2. Follow the same manual steps as for personal accounts, but use your work email to sign in
3. Make sure to set `ONEDRIVE_TENANT_ID` to your organization's tenant ID instead of "common"
4. Set the refresh token you receive as `ONEDRIVE_REFRESH_TOKEN`
**Option B: Access OneDrive as a system service (App-only access)**
@@ -131,8 +167,13 @@ If you encounter errors during authentication:
- For corporate accounts, ensure an admin has consented to the permissions
3. **Refresh token expired**:
- If uploads stop working, you may need to generate a new refresh token
- Repeat the process to get a new authorization code and refresh token
- If uploads stop working, you can generate a new refresh token using the auth wizard
- Click on "Refresh Token" in the OneDrive setup page
4. **Scope issues**:
- If you see permission errors, make sure your app has the correct permissions added
- The `.default` scope is now used, which includes all permissions granted to the app
- Check that both `Files.ReadWrite` and `offline_access` permissions are added to your app
## Configuration Examples