Authorization Property
OAuth 2.0 Authorization Token.
Syntax
onedrive.getAuthorization([callback]) onedrive.setAuthorization( authorization, [callback])
Default Value
""
Callback
The 'callback' parameter specifies a function which will be called when the operation completes (or an error is encountered). If the 'callback' parameter is not specified, then the method will block and will not return until the operation completes (or an error is encountered).
The callback for the getAuthorization([callback]) method is defined as:
function(err, data){ }
'err' is the error that occurred. If there was no error, then 'err' is 'null'.
'data' is the value returned by the method.
The callback for the setAuthorization([callback]) method is defined as:
function(err){ }
'err' is the error that occurred. If there was no error, then 'err' is 'null'.
'err' has 2 properties which hold detailed information:
err.code err.message
Remarks
Authentication is performed via OAuth 2.0. Use the OAuth class included in the toolkit, or any other OAuth implementation to perform authentication and retrieve an authorization string. Once you've obtained an authorization string like:
Bearer ya29.AHES6ZSZEJzATdZYjeihDn5W-VrXSsxEZu5p0pclxGdKKQ
Assign this value to the Authorization property before attempting any operations.
Authorization Notes
Microsoft currently offers two different OAuth systems, Azure AD and Azure AD 2.0 (across which there are 3 sets of OAuth endpoints).Azure AD 2.0 is newer, and it supports nearly everything that Azure AD does (there are some limitations, refer to the Microsoft documentation for details). For the purpose of these notes, here are some notable differences:
- The place where you register your application is different based on which OAuth system you choose.
- The Azure AD 2.0 OAuth system supports all Microsoft account types, but the Azure AD OAuth system only supports business and education accounts.
- The Azure AD 2.0 OAuth system supports both the Microsoft Graph API and the legacy OneDrive API (using two sets of endpoints), whereas Azure AD only supports the Microsoft Graph API.
- The Azure AD 2.0 OAuth system has support for OAuth scopes, but the Azure AD OAuth system does not*.
The below sections summarizes the relevant information based on use case. For additional details please consult the Microsoft documentation.
OneDrive (Personal) Notes
Applications that want to authenticate users to OneDrive (Personal) must use Azure AD 2.0, but can use either the Microsoft Graph or the legacy OneDrive API. To begin, your application must be registered as a "Converged Application" at https://apps.dev.microsoft.com. Once the application is registered, use this table to help you use the OAuth and OneDrive classs to access the service; each row represents a valid use-case:
API Endpoint | Auth Endpoints | Valid OAuth Scopes |
Microsoft Graph https://graph.microsoft.com/v1.0 (Set UseGraphAPI to True) | https://login.microsoftonline.com/common/oauth2/v2.0/authorize https://login.microsoftonline.com/common/oauth2/v2.0/token | Refer to the Microsoft Graph API's OneDrive documentation. |
OneDrive (legacy) https://api.onedrive.com/v1.0 (Set UseGraphAPI to False) | https://login.live.com/oauth20_authorize.srf https://login.live.com/oauth20_token.srf | offline_access, onedrive.readonly, onedrive.readwrite, onedrive.appfolder |
OneDrive for Business and/or SharePoint Online Notes
Applications that want to authenticate users to OneDrive for Business and/or SharePoint Online can use either Azure AD or Azure AD 2.0, but must use the Microsoft Graph API (set UseGraphAPI to True). Depending on which OAuth system you choose, your application must be registered in a different place, and you'll use slightly different endpoints to authenticate. Use this table to help you determine where to register your application and which endpoints to use for authentication; each row represents a valid use-case:
OAuth System | App Registration Portal | Auth Endpoints |
Azure AD 2.0 | https://apps.dev.microsoft.com ("Converged Application") | https://login.microsoftonline.com/common/oauth2/v2.0/authorize https://login.microsoftonline.com/common/oauth2/v2.0/token |
Azure AD | "App Registrations" Blade onhttps://portal.azure.com | https://login.microsoftonline.com/common/oauth2/authorize https://login.microsoftonline.com/common/oauth2/token |
Since the Azure AD OAuth system doesn't support OAuth scopes, you must pre-configure your application's permissions in
the appropriate registration portal (noted below), and then add a "resource" parameter to your OAuth requests. Using our OAuth class, you can do this (before calling GetAuthorization) by doing:
oauth.AddParam("resource", "https://graph.microsoft.com/");
Supporting Both OneDrive Personal and OneDrive Business
In order to support all Microsoft account types (and thus OneDrive (Personal), OneDrive for Business, and SharePoint Online), use Azure AD 2.0 and the Microsoft Graph API. Refer to the relevant information in either of the sections above.
Data Type
String