Implementing File System Authentication

Functionality described in this article is supported in User File System 8.2 and later versions.

IT Hit User File System provides authentication methods that you will implements to check if user is authenticated and show login UI.

Probing if User is Authenticated

To test if user is authenticated you will implement the IEngine.IsAuthenticatedAsync() method. The Engine calls this method before every interface method call. In this method you will check if the client has a valid the authentication information and return the result to the Engine. If you do not implement this method, the default Engine the implementation always returns true.

The IEngine.IsAuthenticatedAsync() method must return as soon as possible. Placing a long-running code inside this method may significantly reduce your file system performance.

You must never make server requests inside the IEngine.IsAuthenticatedAsync() method, except to renew tokens that are about to expire (typically in case of OAuth2 if your server supports it).

public override async Task<bool> IsAuthenticatedAsync(
    IItemsChange itemsChange, 
    CancellationToken cancellationToken)
{
    return this.Credentials != null;
}

Here is what you will typically do in your IEngine.IsAuthenticatedAsync() method implementation:

• In case of OAuth2 you will check your token expiration date or create a new token using your refresh token.
• In case of Basic, Digest, NTLM, Kerberos you will just check if you have stored login credentials.
• In case of cookies auth you will check the cookie expiration date and return false if the cookie has expired.

Displaying Login UI

If the IEngine.IsAuthenticatedAsync() method returned false, the Engine will call the EngineWindows.AuthenticateAsync() method. In this method you will display user login UI and if user successfully authenticated you will return true to the Engine. The default EngineWindows method implementation always returns true.

Below is an example of the AuthenticateAsync() method implementation that first tries to read stored credentials from local storage and if not found displays the login UI: 

public override async Task<bool> AuthenticateAsync(
    IItemsChange itemsChange, 
    CancellationToken cancellationToken)
{
    // First try to retrieve credentials from storage.
    this.Credentials = CredentialManager.GetCredentials("MyStorageKey");
    if (this.Credentials == null)
    {
        // If no credentials are retrieved, show the login UI.
        this.Credentials = ShowLoginDialog();
        if(this.Credentials != null)
        {
            CredentialManager.StoreCredentials("MyStorageKey", this.Credentials);
        }
    }

    return this.Credentials != null;
}

Note that on macOS platform the sign-in banner is displayed as integrated UI inside Finder. You will implement a macOS log-in UI in a separate macOS UI extension.

Failed Authentication

If the EngineWindows.AuthenticateAsync() method returns false, the actual operation method (such as IFile.ReadAsync() or IFolder.GetChildrenAsync()) is not called. Instead, the Engine will send the CloudFileStatus.STATUS_CLOUD_FILE_AUTHENTICATION_FAILED status to the platform by calling the IResultContext.ReportStatus() method. In case the operation was initiated in Windows Explorer, it will display the following messages:

In case of folder population (listing), it will display the "Location not available" "The cloud sync provider failed user authentication.":

In case of file hydration, the Windows Explorer displays "Interrupted Action" "Error 0x80070182: The cloud sync provider failed user authentication.":

 

Next Article:

Microsoft Office Documents Merging