Implement FR #2693: Implement OAuth2 Device Authorisation Flow (#3313)

Adds support for Microsoft’s OAuth2 Device Authorisation Flow, enabling the client to authenticate using device and user codes on a second device. This is particularly useful for headless or limited-input environments where interactive browser login is not possible.

Includes:
- Initiating device code requests and displaying user instructions
- Polling token endpoint until user authorises the device or the code expires
- Error handling for pending, declined, and expired authorisation states
- Countdown display showing remaining authorisation window

This feature is enabled via the `use_device_auth` config option

Author: abraunegg

.github/actions/spelling/allow.txt

@@ -7,15 +7,21 @@ abraunegg
 accrights
 accrightslen
 adamdruppe
+ADand
 addrepo
+Adevice
 adr
+Agrant
 ags
+Aietf
 aip
 alex
 alpinelinux
 annobin
 antix
+Aoauth
 aothmane
+Aparams
 apng
 archlinux
 ARequest
@@ -83,6 +89,7 @@ debian
 dechunk
 Deepin
 deimos
+devicecode
 devuan
 dhparams
 dirmask
@@ -108,6 +115,7 @@ eis
 ele
 endinaness
 enduml
+Entra
 envp
 epfd
 eselect
@@ -154,13 +162,14 @@ gshared
 GVariant
 hideonindex
 hnsecs
+hotmail
 howto
 hskrieg
 htons
-ietf
 idk
 idlol
 idup
+ietf
 ifrom
 includedir
 ine

config

@@ -178,6 +178,9 @@
 ## Only upload changes to OneDrive, do not download from cloud.
 #upload_only = "false"
 
+## Authenticate using the Microsoft OAuth2 Device Authorisation Flow
+#use_device_auth = "true"
+
 ## Single Sign-On (SSO) via Intune using the Microsoft Identity Device Broker
 #use_intune_sso = "true"
 

docs/application-config-options.md

@@ -64,6 +64,7 @@ Before reading this document, please ensure you are running application version
   - [threads](#threads)
   - [transfer_order](#transfer_order)
   - [upload_only](#upload_only)
+  - [use_device_auth](#use_device_auth)
   - [use_intune_sso](#use_intune_sso)
   - [use_recycle_bin](#use_recycle_bin)
   - [user_agent](#user_agent)
@@ -1018,6 +1019,20 @@ _**CLI Option Use:**_ `--upload-only`
 > [!IMPORTANT]
 > To ensure that data deleted locally remains accessible online, you can use the 'no_remote_delete' option. If you want to delete the data from your local storage after a successful upload to Microsoft OneDrive, you can use the 'remove_source_files' option.
 
+### use_device_auth
+_**Description:**_ Enable this option to authenticate using the Microsoft OAuth2 Device Authorisation Flow (`device_code` grant). This flow allows the client to initiate a sign-in process without launching a web browser directly — ideal for headless systems or remote sessions. A short code and URL will be provided for the user to complete authentication via a separate browser-enabled device.
+
+_**Value Type:**_ Boolean
+
+_**Default Value:**_ False
+
+_**Config Example:**_ `use_device_auth = "false"` or `use_device_auth = "true"`
+
+_**CLI Option Use:**_ *None - this is a config file option only*
+
+> [!IMPORTANT]
+> This option is fully supported for Microsoft Entra ID (Work/School) accounts. For personal Microsoft accounts (e.g., @outlook.com or @hotmail.com), this method of authentication is not supported. Please use the interactive interactive authentication method (default) to authenticate this application.
+
 ### use_intune_sso
 _**Description:**_ Enable this option to authenticate using Intune Single Sign-On (SSO) via the Microsoft Identity Device Broker over D-Bus. This method is suitable for environments where the system is Intune-enrolled and allows seamless token retrieval without requiring browser interaction.
 

docs/usage.md

@@ -336,6 +336,7 @@ If you explicitly want to use HTTP/1.1, you can do so by using the `--force-http
 > If you continue to use a curl/libcurl version with known HTTP/2 bugs you will experience application runtime issues such as randomly exiting for zero reason or incomplete download/upload of your data.
 
 ## First Steps
+
 ### Authorise the Application with Your Microsoft OneDrive Account
 Once you've installed the application, you'll need to authorise it using your Microsoft OneDrive Account. This can be done by simply running the application without any additional command switches.
 
@@ -344,6 +345,7 @@ Please be aware that some companies may require you to explicitly add this app t
 This client supports the following methods to authenticate the application with Microsoft OneDrive:
 * Supports interactive browser-based authentication using OAuth2 and a response URI
 * Supports seamless Single Sign-On (SSO) via Intune using the Microsoft Identity Device Broker D-Bus interface
+* Supports OAuth2 Device Authorisation Flow for Microsoft Entra ID accounts
 
 #### Interactive Authentication using OAuth2 and a response URI
 When you run the application for the first time, you'll be prompted to open a specific URL using your web browser, where you'll need to log in to your Microsoft Account and grant the application permission to access your files. After granting permission to the application, you'll be redirected to a blank page. Simply copy the URI from the blank page and paste it into the application.
@@ -380,6 +382,54 @@ Intune SSO via Microsoft Identity Broker dbus session usage criteria met - will
 > [!NOTE]
 > The installation and configuration of Intune for your platform is beyond the scope of this documentation.
 
+#### OAuth2 Device Authorisation Flow for Microsoft Entra ID accounts
+To use this method of authentication, you must add the following configuration to your 'config' file:
+```
+use_device_auth = "true"
+```
+You will be required to open a URL using a web browser, and enter the code that this application presents:
+```
+Configuring Global Azure AD Endpoints
+
+Authorise this application by visiting:
+
+https://microsoft.com/devicelogin
+
+Enter the following code when prompted: ABCDEFGHI
+
+This code expires at: 2025-Jun-02 15:27:30
+```
+You will have ~15 minutes before the code expires.
+
+> [!IMPORTANT]
+> #### Limitation: OAuth2 Device Authorization Flow and Personal Microsoft Accounts
+>
+> While the OneDrive Client for Linux fully supports OAuth2 Device Authorisation Flow (`device_code` grant) for **Microsoft Entra ID (Work/School)** accounts, **Microsoft currently does not allow this flow to be used with personal Microsoft accounts (MSA)** unless the application is explicitly authorised by Microsoft.
+>
+> **Application Configuration Summary:**
+>
+> - `signInAudience`: `AzureADandPersonalMicrosoftAccount`
+> - `allowPublicClient`: `true`
+> - Uses Microsoft Identity Platform v2.0 endpoints (`/devicecode`, `/token`, etc.)
+> - Microsoft Graph scopes properly defined
+>
+> Despite this correct configuration, users signing in with a personal Microsoft account will see the following error:
+>
+> > **"The code you entered has expired. Get a new code from the device you're trying to sign in to and try again."**
+>
+> This occurs even if the code is entered immediately. Microsoft redirects the user to:
+>
+> ```
+> https://login.live.com/ppsecure/post.srf?username=......
+> ```
+>
+> This behaviour confirms that Microsoft **blocks the `device_code` grant flow for MSA accounts** on unapproved apps.
+>
+> **Recommendation:**  
+> If using a personal Microsoft account (e.g., @outlook.com or @hotmail.com), please complete authentication using the interactive authentication method detailed above.
+>
+> **Further Reading:**  
+> 📚 [Microsoft Documentation — OAuth 2.0 device authorization grant](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-device-code)
 
 ### Display Your Applicable Runtime Configuration
 To verify the configuration that the application will use, use the following command:
@@ -1259,7 +1309,7 @@ journalctl --unit=onedrive -f
 #### OneDrive service running as a non-root user via systemd (All Linux Distributions)
 In some instances, it is preferable to run the OneDrive client as a service without the 'root' user. Follow the instructions below to configure the service for your regular user login.
 
-1. As the user who will run the service, launch the application in standalone mode, authorize it for use, and verify that synchronization is functioning as expected:
+1. As the user who will run the service, launch the application in standalone mode, authorise it for use, and verify that synchronisation is functioning as expected:
 ```text
 onedrive --sync --verbose
 ```

readme.md

@@ -25,6 +25,7 @@ Since forking in early 2018, this client has evolved into a clean re-imagining o
 * Supports seamless access to shared folders and files across both OneDrive Personal and OneDrive for Business accounts
 * Supports single-tenant and multi-tenant applications
 * Supports Intune Single Sign-On (SSO) authentication via the Microsoft Identity Device Broker (D-Bus interface)
+* Supports OAuth2 Device Authorisation Flow for Microsoft Entra ID accounts
 * Supports national cloud deployments including Microsoft Cloud for US Government, Microsoft Cloud Germany, and Azure/Office 365 operated by VNET in China
 * Provides rules for client-side filtering to select data for syncing with Microsoft OneDrive accounts
 * Protects against significant data loss on OneDrive after configuration changes

src/config.d

@@ -420,6 +420,9 @@ class ApplicationConfig {
 		// Use authentication via Intune SSO via Microsoft Identity Broker (microsoft-identity-broker) dbus session
 		boolValues["use_intune_sso"] = false;
 
+		// Use authentication via OAuth2 Device Authorisation Flow
+		boolValues["use_device_auth"] = false;
+		
 		// EXPAND USERS HOME DIRECTORY
 		// Determine the users home directory.
 		// Need to avoid using ~ here as expandTilde() below does not interpret correctly when running under init.d or systemd scripts
@@ -1557,6 +1560,7 @@ class ApplicationConfig {
 
 		// authentication
 		addLogEntry("Config option 'use_intune_sso'               = " ~ to!string(getValueBool("use_intune_sso")));
+		addLogEntry("Config option 'use_device_auth'              = " ~ to!string(getValueBool("use_device_auth")));
 
 		// logging and notifications
 		addLogEntry("Config option 'enable_logging'               = " ~ to!string(getValueBool("enable_logging")));