Click or drag to resize

Authentication using OAuth

Workspaces OAuth lets users allow other applications to interact with their Workspaces account without providing that other application their Workspaces authentication credentials, and for only a time-limited basis.For example, a sales management application can integrate Workspaces functionality to allow the controlled sharing of documents via Workspaces, within the sales management app, without requiring users to provide their Workspaces usernames and passwords to the sales management app.

Registering a client with a Workspaces server

Someone wishing to use Workspaces OAuth must register with Workspaces and obtain a client ID and client secret that will be passed to Workspaces in order to obtain a Workspaces authentication token.

Authenticating using StartSessionWithOAuth

The StartSessionWithOAuth method in ApiSession provides an easy way to authenticate users using OAuth.Here are the steps needed to authenticate using this sdk (workspaces-api-sdk-dotnetstandard):

  1. Create an instance of ApiSession by passing the serverUrl.

  2. Make a call to the StartSessionWithOAuth method which takes the current Application and user email to start.

  3. Add the SessionWithOAuthLoginCompleted event to handle the returned apisession object.

After providing the above information, a window will appear to accept the authentication credentials for the user.This window will remain visible until the user successfully authenticates with the Workspaces server or the user closes the window. Because of this the StartSessionWithOAuth method is a blocking call.

ApiSession apiSession = new ApiSession(serverUrl);
apiSession.StartSessionWithOAuth(Application.Current, email);
apiSession.SessionWithOAuthLoginCompleted += c_SessionWithOAuthLoginCompleted;

If the session is started successfully, the returned apisession object will be accessed with theabove defined event handler to further use the workspaces resources.

void c_SessionWithOAuthLoginCompleted(object sender, ApiSession e)
{
    //use the Apisession object returned to access the workspaces resources.
}
Manually authenticating using OAuth

The basic flow is as follows where WORKSPACES_URL refers to the base URL of the Workspaces server being used:

  1. Make an unauthenticated call toWORKSPACES_URL/api/3.0/authentication/parameters to get the authentication URI's. In the returned values, authorizationUri is the URI for the temporary token in #2 below; accessTokenUri is the URI for obtaining the full token in #4 below.

  2. Direct the user to the Workspaces authenticationUri (e.g.via a redirect in your own web app), passing the proper params(see below). One of these params is the redirect URI in your app to which the user should be sent after authenticating with Workspaces. It will look something like this (wrapped across lines here, but one single line when used):

    < WORKSPACES_URL>/< AUTHORIZATION_URI>?response_type=code& client_id=< CLIENT_ID>& locale=en_US
    & redirect_uri=< REDIRECT_URI>
  3. When that redirect URI is serviced in your web app, a temporary code is included on the URL that will be used to obtain a valid auth token. It will look something like this:

    < REDIRECT_URI>/?code=219e5a32-d74f-473a-91a4-fd74f95e091c& locale=en-us
  4. Make a call to the Workspaces accessTokenUri to obtain a valid auth token, refresh token, and an expiration value for the auth token. That auth token can be used to authenticate subsequent API calls to the Workspaces server (wrapped across lines here, but one single line when used).

    < WORKSPACES_URL>/< ACCESS_TOKEN_URI>?client_id=< CLIENT_ID>& redirect_uri=< REDIRECT_URI>&
    client_secret=< CLIENT_SECRET>& grant_type=authorization_code& code=< AUTH_CODE>
  5. That call will return JSON that contains an access token, expiration, and refresh token. The access token can be used in the authorization header of subsequent calls.