Portal Setup: Storage Options - indiana-university/kumo GitHub Wiki

This document describes how to configure your Kumo tenant to work with supported cloud storage services.

Skip directly to instructions for:

• Box
• Dropbox
• Google Drive
• OneDrive
• OneDrive for Business

OAuth2

OAuth2 is an authorization framework that enables resource owners (students, faculty, staff) to delegate access to their resources (cloud-based files) to 3rd party services (Kumo) without having to share their credentials. The OAuth2 specification and a helpful primer are available if you'd like to learn more.

Granting an Access Token

In order to make a storage service available to your users a bit of configuration must be performed at both the storage service's site and in your Kumo admin portal. Specific instructions for each supported storage service are provider later in this document, but the general process is illustrated below.

1. A Kumo administrator will create a Kumo application on the storage service's website. Note: For the purposes of OAuth2 your institution does not need to have to have any sort of pre-existing or enterprise agreement with the storage service in order to create this application. However, if you do have such an agreement in place you may wish to consult with the service owners at your institution prior to creating this application.)
2. This application will have a unique identifier and a shared secret that you'll set in a corresponding storage option in your Kumo portal.
3. A user visits the Kumo portal and elects to authorize Kumo to access their files on the storage service. The user will be redirected to the storage service's website where they will login and be prompted to explicitly delegate access to Kumo. This prompt typically includes information about the application that is requesting access, including the name of the application the scope of access requested.
4. The user grants access to the application and the storage service redirects the user back to your Kumo portal. The Kumo portal will fetch an API access token from the storage service on the user's behalf.
5. When the Kumo client launches, it will fetch this access token from the portal (after first authenticating with an Access Broker.)
6. The Kumo client will use the API access token to make authenticated requests to the storage service's public API on the user's behalf.

Refreshing an Access Token

The API access token granted by the storage service expires after roughly an hour. This is a security measure intended to mitigate the release of any single access token by a poorly coded application. OAuth2 specifies an optional workflow for refreshing an access token in order to provide for a seamless user experience. Most storage services have adopted this option. For increased security all token refresh operations are routed through the Kumo portal. The refresh workflow is illustrated below.

1. After some period of API use the access token will expire and the Kumo client will receive an HTTP 401 Unauthorized response from the storage service.
2. The Kumo client will request a new access token from the Kumo portal.
3. The Kumo portal contacts the storage service to exchange the expired access token for new one.
4. This request is validated by the storage service and a new access token is returned to the portal.
5. The portal returns the new access token to the client.
6. The client retries the original API request with the new access token and a successful result is returned.

Box

Register a Box Application

1. Browse to https://box.com/developers/console and log in.
2. Select an application name. We suggest Kumo or Kumo - <name of your institution>
3. Click Box Content and then Create Application to create the application.
4. Click Configure your application to continue.
5. Under General information enter a support email address and the address for Kumo at your school.
6. Under OAuth2 parameters set the redirect_uri to https://YOUR_KUMO_DOMAIN/OAuth2/Authorize/Box
7. Optional: Under Trademark images of the service provide logos for your school.
8. Scroll to the bottom of the screen and click Save Application to finalize your settings.

Integrate your Box Application with Kumo

9. In a separate tab, browse to the Admin section of Kumo.
10. Select Box from the storage options dropdown and click Add.
11. From the OAuth2 parameters, copy the following values to Kumo’s Box configuration:

• client_id to API Key
• client_secret to API Secret

12. Click Save to update your Kumo settings for Box.

Dropbox

Register a Dropbox Application

1. Browse to https://www.dropbox.com/developers/apps and log in.
2. Click Create app
3. You will be prompted to answer several questions:
   • Choose an API
     • Scoped access.
   • Choose the type of access you need
     • Select Full Dropbox- Access to all files and folders in a user's Dropbox.
   • Name Your App
     • We suggest Kumo or Kumo - <name of your institution>;
4. Click on the Create app button.
5. On the Settings tab
   • Status - By default, the status will be 'Development' which limits the application to 500 users (see the Development vs Production section).
   • Set the OAuth Redirect URI to https://YOUR_KUMO_DOMAIN/OAuth2/Authorize/Dropbox
6. On the Permissions tab
   • Set Individual Scopes - Files and Folders and collaboration.
7. Optional: On Branding tab
   • Provide logos for your school in the App icons.
8. Click Save changes

Integrate your Dropbox Application with Kumo

9. In a separate tab, browse to the Admin section of Kumo.
10. Select Dropbox from the storage options dropdown and click Add.
11. From the Settings tab of your Dropbox application, copy the following values to Kumo’s Dropbox configuration:

• App key to API Key
• App secret to API Secret
• Set Service URL to https://www.dropbox.com

12. Click Save to update your Kumo settings for Dropbox.

Development vs. Production

Dropbox limits applications in ‘development’ mode to 500 users. This should be sufficient for small-scale pilots and testing. Prior to the general Kumo release, you’ll need to apply for ‘production’ status, which removes the user limit. In lieu of letting Dropbox test your app, you can create a short video showing them how users will authorize Kumo in the portal and access their files from the desktop.

Google Drive

Register a Google Drive Application

1. Browse to https://console.developers.google.com. Login with a Google account.
2. In the Select a project dropdown select Create Project.
3. Enter project name and ID.

• For the Project Name we suggest kumo - <name of your institution>

1. Read and agree to the terms of service box and click Create.
2. From the Project Dashboard, click Overview
3. From the Google APIs tab, click Drive API.
4. Click Enable to enable the Drive API.
5. Click the Go to Credentials button that pops up.
6. Under Find out what kind of credentials you need click the Client ID link.
7. Click the Configure consent screen button.
8. Under OAuth consent screen:

• Set the Product name shown to users to your application name from step 4.
• Set the Homepage URL to https://YOUR_KUMO_DOMAIN
• Optional: Set Product logo URL to your school’s logo.

1. Click Save to continue.
2. Under Application type select Web application. A Restrictions section will appear.
3. Set the Authorized Javascript Origins to https://YOUR_KUMO_DOMAIN.
4. Set the Authorized Redirect URIs to https://YOUR_KUMO_DOMAIN/OAuth2/Authorize/GoogleDrive.
5. Click Create. An OAuth client dialog will pop up. Don't close it!

Integrate your Google Drive Application with Kumo

16. In a separate tab, browse to the Admin section of Kumo.
17. Select Google Drive from the storage options dropdown and click Add.
18. From the Client ID for Web application section of your Google Drive application, copy the following values to Kumo’s Google Drive configuration:

• Client ID to API Key
• Client Secret to API Secret

19. Click Save to update your Kumo settings for Google Drive.

OneDrive

Please Note: OneDrive refers to Microsoft's personal storage service. You can also integrate with OneDrive for Business, Microsoft's enterprise storage service.

Register a OneDrive Application

1. Browse to Azure App registrations page and log in.
2. Under the App registration click on New registration.
3. Select an application name. We suggest Kumo or Kumo - <name of your institution>
4. Under Support account types select the Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox). Learn more about how to specify who can use the application.
5. Under the Redirect URI make sure the type is set to Web and set the Redirect URI to https://YOUR_KUMO_DOMAIN/OAuth2/Authorize/SkyDrive.
6. Click Register to create the application.
7. Under Certificates & secrets, click on New client secret. Give Your Domain Name in the Description and choose Expires time Never.
8. Copy the generated password Value to a text editor -- you'll need it later.
9. (Optional) Under Branding:
   • Upload new Logo to your school’s logo.
   • You can fill the remaining fields Home page URL, Terms of Services URL, Privacy Statement URL
   • Click Save to update your settings.

Integrate your OneDrive Application with Kumo

11. In a separate tab, browse to the Admin section of Kumo.
12. Select OneDrive from the storage option dropdown and click Add Option.
13. Expand the new OneDrive option.
14. From the OneDrive application page copy the Application (client) ID to the API Key field.
15. From Step 8 or your text editor copy the application secret to API Secret
16. Click Save to update your Kumo settings for OneDrive.

OneDrive for Business

Please Note: OneDrive for Business refers to Microsoft's enterprise storage service. You can also integrate with OneDrive, Microsoft's personal storage service.

Register a OneDrive for Business Application

1. Browse to Azure App registrations page and log in.
2. Under the App registration click on New registration.
3. For Name enter Kumo-Office365.
4. Under Support account types select the Accounts in this organizational directory only (Your University only - Single tenant). Learn more about how to specify who can use the application.
5. Under the Redirect URI make sure the type is set to Web and set the Redirect URI to https://<your-kumo-domain>/OAuth2/Authorize/OneDriveBusiness.
6. Click Register to create the application.
7. Under Manage >> API Permissions,
   • Click on Add a permission
   • Search for Office 365 SharePoint Online (Microsoft.SharePoint) and click on Delegated Permissions
   • At MyFiles Section >> Check MyFiles.Read/Read user files and MyFiles.Write/Read and write user files.
   • Click on Add Permissions
8. Under Manage >> Certificates & secrets, click on New client secret. Give Your Domain Name in the Description and choose Expires time Never.
9. Copy the generated password Value to a text editor -- you'll need it later.
10. (Optional) Under Branding:
    • Upload new Logo to your school’s logo.
    • You can fill the remaining fields Home page URL, Terms of Services URL, Privacy Statement URL
    • Click Save to update your settings.

Integrate your OneDrive for Business Application with Kumo

11. In a separate tab, browse to the Admin section of Kumo.

12. Select OneDrive for Business from the storage option dropdown and click Add Option.

13. Set the Service URL to https://<your Office365 domain>-my.sharepoint.com.

14. From your Azure application configuration, copy and paste the following values to the Kumo configuration.

    • Application (client) ID to API Key
    • The application key from Step 9 to API Secret

15. Click Save to update your Kumo settings for OneDrive for Business.