diff --git a/docs/application-security.md b/docs/application-security.md index 7c22c4f1..cf5769f3 100644 --- a/docs/application-security.md +++ b/docs/application-security.md @@ -63,6 +63,13 @@ When these delegated API permissions are combined, these provide the effective a These 'default' permissions will allow the OneDrive Client for Linux to read, write and delete data associated with your OneDrive Account. +## How are the Authentication Scopes used? + +When using the OneDrive Client for Linux, the above authentication scopes will be presented to the Microsoft Authentication Service (login.microsoftonline.com), where the service will validate the request and provide an applicable token to access Microsoft OneDrive with. This can be illustrated as the following: + +![Linux Authentication to Microsoft OneDrive](http://www.plantuml.com/plantuml/proxy?src=https://raw.github.com/plantu) + + ## Configuring read-only access to your OneDrive data In some situations, it may be desirable to configure the OneDrive Client for Linux totally in read-only operation. diff --git a/docs/puml/onedrive_linux_authentication.puml b/docs/puml/onedrive_linux_authentication.puml new file mode 100644 index 00000000..4d89f0db --- /dev/null +++ b/docs/puml/onedrive_linux_authentication.puml @@ -0,0 +1,47 @@ +@startuml +participant "OneDrive Client for Linux" +participant "Microsoft OneDrive\nAuthentication Service\n(login.microsoftonline.com)" as AuthServer +participant "User's Device (for MFA)" as UserDevice +participant "Microsoft Graph API\n(graph.microsoft.com)" as GraphAPI +participant "Microsoft OneDrive" + +"OneDrive Client for Linux" -> AuthServer: Request Authorization\n(Client Credentials, Scopes) +AuthServer -> "OneDrive Client for Linux": Provide Authorization Code + +"OneDrive Client for Linux" -> AuthServer: Request Access Token\n(Authorization Code, Client Credentials) + +alt MFA Enabled + AuthServer -> UserDevice: Trigger MFA Challenge + UserDevice -> AuthServer: Provide MFA Verification + AuthServer -> "OneDrive Client for Linux": Return Access Token\n(and Refresh Token) + "OneDrive Client for Linux" -> GraphAPI: Request Microsoft OneDrive Data\n(Access Token) + loop Token Expiry Check + "OneDrive Client for Linux" -> AuthServer: Is Access Token Expired? + alt Token Expired + "OneDrive Client for Linux" -> AuthServer: Request New Access Token\n(Refresh Token) + AuthServer -> "OneDrive Client for Linux": Return New Access Token + else Token Valid + GraphAPI -> "Microsoft OneDrive": Retrieve Data + "Microsoft OneDrive" -> GraphAPI: Return Data + GraphAPI -> "OneDrive Client for Linux": Provide Data + end + end +else MFA Not Required + AuthServer -> "OneDrive Client for Linux": Return Access Token\n(and Refresh Token) + "OneDrive Client for Linux" -> GraphAPI: Request Microsoft OneDrive Data\n(Access Token) + loop Token Expiry Check + "OneDrive Client for Linux" -> AuthServer: Is Access Token Expired? + alt Token Expired + "OneDrive Client for Linux" -> AuthServer: Request New Access Token\n(Refresh Token) + AuthServer -> "OneDrive Client for Linux": Return New Access Token + else Token Valid + GraphAPI -> "Microsoft OneDrive": Retrieve Data + "Microsoft OneDrive" -> GraphAPI: Return Data + GraphAPI -> "OneDrive Client for Linux": Provide Data + end + end +else MFA Failed or Other Auth Error + AuthServer -> "OneDrive Client for Linux": Error Message (e.g., Invalid Credentials, MFA Failure) +end + +@enduml \ No newline at end of file diff --git a/docs/puml/onedrive_windows_ad_authentication.puml b/docs/puml/onedrive_windows_ad_authentication.puml new file mode 100644 index 00000000..43b312fa --- /dev/null +++ b/docs/puml/onedrive_windows_ad_authentication.puml @@ -0,0 +1,59 @@ +@startuml +participant "Microsoft Windows OneDrive Client" +participant "Azure Active Directory\n(Active Directory)\n(login.microsoftonline.com)" as AzureAD +participant "Microsoft OneDrive\nAuthentication Service\n(login.microsoftonline.com)" as AuthServer +participant "User's Device (for MFA)" as UserDevice +participant "Microsoft Graph API\n(graph.microsoft.com)" as GraphAPI +participant "Microsoft OneDrive" + +"Microsoft Windows OneDrive Client" -> AzureAD: Request Authorization\n(Client Credentials, Scopes) +AzureAD -> AuthServer: Validate Credentials\n(Forward Request) +AuthServer -> AzureAD: Provide Authorization Code +AzureAD -> "Microsoft Windows OneDrive Client": Provide Authorization Code (via AzureAD) + +"Microsoft Windows OneDrive Client" -> AzureAD: Request Access Token\n(Authorization Code, Client Credentials) +AzureAD -> AuthServer: Request Access Token\n(Authorization Code, Forwarded Credentials) +AuthServer -> AzureAD: Return Access Token\n(and Refresh Token) +AzureAD -> "Microsoft Windows OneDrive Client": Return Access Token\n(and Refresh Token) (via AzureAD) + +alt MFA Enabled + AzureAD -> UserDevice: Trigger MFA Challenge + UserDevice -> AzureAD: Provide MFA Verification + AzureAD -> "Microsoft Windows OneDrive Client": Return Access Token\n(and Refresh Token) (Post MFA) + "Microsoft Windows OneDrive Client" -> GraphAPI: Request Microsoft OneDrive Data\n(Access Token) + loop Token Expiry Check + "Microsoft Windows OneDrive Client" -> AzureAD: Is Access Token Expired? + AzureAD -> AuthServer: Validate Token Expiry + alt Token Expired + "Microsoft Windows OneDrive Client" -> AzureAD: Request New Access Token\n(Refresh Token) + AzureAD -> AuthServer: Request New Access Token\n(Refresh Token) + AuthServer -> AzureAD: Return New Access Token + AzureAD -> "Microsoft Windows OneDrive Client": Return New Access Token (via AzureAD) + else Token Valid + GraphAPI -> "Microsoft OneDrive": Retrieve Data + "Microsoft OneDrive" -> GraphAPI: Return Data + GraphAPI -> "Microsoft Windows OneDrive Client": Provide Data + end + end +else MFA Not Required + AzureAD -> "Microsoft Windows OneDrive Client": Return Access Token\n(and Refresh Token) (Direct) + "Microsoft Windows OneDrive Client" -> GraphAPI: Request Microsoft OneDrive Data\n(Access Token) + loop Token Expiry Check + "Microsoft Windows OneDrive Client" -> AzureAD: Is Access Token Expired? + AzureAD -> AuthServer: Validate Token Expiry + alt Token Expired + "Microsoft Windows OneDrive Client" -> AzureAD: Request New Access Token\n(Refresh Token) + AzureAD -> AuthServer: Request New Access Token\n(Refresh Token) + AuthServer -> AzureAD: Return New Access Token + AzureAD -> "Microsoft Windows OneDrive Client": Return New Access Token (via AzureAD) + else Token Valid + GraphAPI -> "Microsoft OneDrive": Retrieve Data + "Microsoft OneDrive" -> GraphAPI: Return Data + GraphAPI -> "Microsoft Windows OneDrive Client": Provide Data + end + end +else MFA Failed or Other Auth Error + AzureAD -> "Microsoft Windows OneDrive Client": Error Message (e.g., Invalid Credentials, MFA Failure) +end + +@enduml diff --git a/docs/puml/onedrive_windows_authentication.puml b/docs/puml/onedrive_windows_authentication.puml new file mode 100644 index 00000000..43a458a0 --- /dev/null +++ b/docs/puml/onedrive_windows_authentication.puml @@ -0,0 +1,47 @@ +@startuml +participant "Microsoft Windows OneDrive Client" +participant "Microsoft OneDrive\nAuthentication Service\n(login.microsoftonline.com)" as AuthServer +participant "User's Device (for MFA)" as UserDevice +participant "Microsoft Graph API\n(graph.microsoft.com)" as GraphAPI +participant "Microsoft OneDrive" + +"Microsoft Windows OneDrive Client" -> AuthServer: Request Authorization\n(Client Credentials, Scopes) +AuthServer -> "Microsoft Windows OneDrive Client": Provide Authorization Code + +"Microsoft Windows OneDrive Client" -> AuthServer: Request Access Token\n(Authorization Code, Client Credentials) + +alt MFA Enabled + AuthServer -> UserDevice: Trigger MFA Challenge + UserDevice -> AuthServer: Provide MFA Verification + AuthServer -> "Microsoft Windows OneDrive Client": Return Access Token\n(and Refresh Token) + "Microsoft Windows OneDrive Client" -> GraphAPI: Request Microsoft OneDrive Data\n(Access Token) + loop Token Expiry Check + "Microsoft Windows OneDrive Client" -> AuthServer: Is Access Token Expired? + alt Token Expired + "Microsoft Windows OneDrive Client" -> AuthServer: Request New Access Token\n(Refresh Token) + AuthServer -> "Microsoft Windows OneDrive Client": Return New Access Token + else Token Valid + GraphAPI -> "Microsoft OneDrive": Retrieve Data + "Microsoft OneDrive" -> GraphAPI: Return Data + GraphAPI -> "Microsoft Windows OneDrive Client": Provide Data + end + end +else MFA Not Required + AuthServer -> "Microsoft Windows OneDrive Client": Return Access Token\n(and Refresh Token) + "Microsoft Windows OneDrive Client" -> GraphAPI: Request Microsoft OneDrive Data\n(Access Token) + loop Token Expiry Check + "Microsoft Windows OneDrive Client" -> AuthServer: Is Access Token Expired? + alt Token Expired + "Microsoft Windows OneDrive Client" -> AuthServer: Request New Access Token\n(Refresh Token) + AuthServer -> "Microsoft Windows OneDrive Client": Return New Access Token + else Token Valid + GraphAPI -> "Microsoft OneDrive": Retrieve Data + "Microsoft OneDrive" -> GraphAPI: Return Data + GraphAPI -> "Microsoft Windows OneDrive Client": Provide Data + end + end +else MFA Failed or Other Auth Error + AuthServer -> "Microsoft Windows OneDrive Client": Error Message (e.g., Invalid Credentials, MFA Failure) +end + +@enduml \ No newline at end of file