Skip to content

Dms

Overview

The OAuth pickers normally sign users in by redirecting to the third-party integration URL, where the user logs in and is then returned to the page with a token that validates the user's authentication going forward. This approach is a mix of frontend and backend working together to authenticate the user. Due to the nature of the DMS user story, it was required to sign the user in without making any redirects so that the user who attempts to add the file is prompted to log in, and once logged in, can continue adding the file at the content area where they were. The core of the dms logic is coded in dms.js file. This composable abstracts the logic for various Document Management Systems (DMS) and orchestrates the integration and flow.

Google Drive

Works in: production only Log in to https://console.developers.google.com/ Currently, Michal and Jody have access to the console Go to: https://console.cloud.google.com/auth/overview?project=dms-picker Technical details The urls values from where the OAuth request is being made can't contain wildcards or paths. There are four specified origins for the purpose of testing Google Drive, but the integration only works in production: - https://app.methodgrid.com - test in production - works - https://app.development.methodgrid.com - test in local development environment - doesn't work - https://app.bug-dms.staging3.methodgrid.com - test in staging development environment (deploy using this subdomain -subdomain bug-dms) - doesn't work - https://app.dms.staging3.methodgrid.com - another test in staging development environment (deploy using this subdomain -subdomain dms) - doesn't work - https://app.development.methodrid.com - (local dev domain) - not specified in google project - doesn't work

Implementation details

The core of gdrive implementation resides in gd.phtml - a PHP template file that is loaded into an iframe. It contains the client-side JavaScript for interacting with the Google Identity Services (GIS) and Picker APIs.

Authentication and token flow

The authentication journey is designed to be as non-intrusive as possible:

  1. Initiation: When a user clicks to add or update a Google Drive file, the selectFile method in ContentAreaFilesListFile.vue is called. This, in turn, calls the useDms composable.
  2. Iframe Communication: The useDms function for Google Drive doesn't interact with Google's APIs directly. Instead, it sends a postMessage to the gd.phtml iframe, instructing it to open the Google Drive picker.
  3. Token Request: Inside the iframe, the script first checks if it already has a valid accessToken.
  4. No Token: If no token is present, a "Sign in with Google" button is displayed. Clicking this button initiates the OAuth flow using Google's Identity Services (GIS) library. It requests an access token with the https://www.googleapis.com/auth/drive.file scope. Google handles the pop-up window for user login and consent.
  5. Existing Token: If a token exists from a previous session, the sign-in step is skipped.
  6. Token Received: Once the user successfully authenticates, the Google GIS library returns an accessToken to the iframe's JavaScript. This token is short-lived and is held in memory for the duration of the user's session. It is not stored in the backend.
  7. Launching the Picker: With a valid accessToken, the script within the iframe uses Google's Picker API to build and display the file picker interface. The accessToken is passed to the picker to authorize it to show the user's files.
  8. File Selection: The user selects one or more files from the picker.
  9. On selection, the picker returns an object containing file metadata (like name and url) to the iframe. The iframe then uses postMessage to send this data back to the parent window (the main Vue application).
  10. On cancellation, a "cancel" message is sent back to the parent window.
  11. Updating the UI: The main application listens for these messages. When it receives the file data, the dms.js composable executes a callback function that updates the application's state with the new file information, and the user sees the selected file appear in the content area.
  12. This entire process occurs without the main browser window ever navigating away from Method Grid.

preprod.methodgrid.com

We should be able to add another authorized redirect URIs without triggering the verification process. Frontend can adjust the request accordingly.

OneDrive / Sharepoint

Works in: production only App settings reside in MG tenant. To make any changes log in to Azure using your methodgrid.com credentials Go to App registrations - Microsoft Azure

Technical details

The urls values from where the OAuth request is being made can't contain wildcards or paths. There are a few specified origins for the purpose of testing OneDrive/Sharepoint, but the integration only works in production:

  • https://app.demo.methodgrid.com/od
  • https://app.demo2.methodgrid.com/od
  • https://app.staging.methodgrid.com/od
  • https://app.staging2.methodgrid.com/od
  • https://app.methodgrid.com/od
  • http://localhost:3000/od
  • http://localhost:3000 On attempt to open the picker in staging environment, user is presented with redirect to main app.methodgrid.com/sign-in

Implementation details

Similar to the Google Drive integration, the OneDrive file picker is implemented within an iframe to provide a seamless user experience without redirecting the user away from the main application. The od.phtml file contains the logic to display the picker, handle authentication, and communicate the results back to the parent application using the postMessage API.

Authentication and token flow

The process is orchestrated by the official OneDrive File Picker SDK.

  1. Initiation: The main application loads od.phtml into an iframe and sends it a message with the action openOneDrive. This message also contains the parent's origin and a multi setting to determine if multiple files can be selected.
  2. Configuration: The iframe's JavaScript receives this message and configures the odOptions object for the OneDrive SDK. It sets the multiSelect property and stores the parent's origin in the _parent variable for later use.
  3. User Interaction: The iframe displays an "Open OneDrive" button. When the user clicks this button, OneDrive.open(odOptions) is called.
  4. Authentication and Picking: The OneDrive SDK takes over from here. It opens a pop-up window that handles the entire Microsoft login and file selection process. The user signs in and chooses their files within this pop-up.
  5. File Selection – Success: If the user selects files and confirms, the success callback in odOptions is executed. This function sends a postMessage back to the parent window containing the selected file data. The _parent variable is used as the targetOrigin to ensure the message is only sent to the correct parent.
  6. Cancel: If the user closes the picker, the cancel callback is called, which sends a message back to the parent to hide the modal.

preprod.methodgrid.com

It appears to be doable to add another subdomain redirect:

Dropbox

Works in: production, staging, local Log in to dropbox: https://www.dropbox.com/login Credentials: dev@methodgrid.com Go to https://www.dropbox.com/developers/apps There are several redirects URIs specified http://localhost:3000 https://mg.development.methodgrid.com https://mg.methodgrid.com https://mg.staging.methodgrid.com https://mg.staging2.methodgrid.com https://mg.demo.methodgrid.com https://mg.demo2.methodgrid.com https://app.staging.methodgrid.com https://app.staging2.methodgrid.com https://app.demo.methodgrid.com https://app.demo2.methodgrid.com https://app.methodgrid.com

Implementation and authentication flow

Dropbox Picker SDK abstracts away all the complexity of authentication and file selection, providing a simple and secure callback-based mechanism to get the result. The entire logic for the Dropbox file picker is handled within the useDms composable in dms.js. Configuration: The application's API key for Dropbox is set in the main layout file, grid-layout.phtml. This key is assigned to window.Dropbox.appKey, making it available for the Dropbox SDK. Initiation: When a user chooses to add a file from Dropbox, the useDms function is called with "dropbox" as the method. Dropbox Chooser: The code then calls Dropbox.choose(options). This function is part of the Dropbox SDK and handles the entire user interaction. It opens a pop-up window to the Dropbox website. It prompts the user to sign in to their Dropbox account (if they aren't already). It displays a file picker interface for the user to select files.

File Selection: - Success: Once the user selects their files and confirms: - The Dropbox pop-up closes. - The success callback defined in the options object is executed. - This callback receives an array of selected files. - The code then formats this data into a structure the application understands and passes it to the final callback function to update the UI. - Cancel: If the user closes the pop-up without selecting a file: - The cancel callback is executed. - No further action is taken.

preprod.methodgrid.com

It appears to be doable to add another subdomain redirect url:

Box

Works in: production only Log in to box: https://account.box.com/login Credentials: See the team password manager for access details. Go to: https://app.box.com/developers/console/app/1580764

Technical details:

One redirect url is set: https://app.methodgrid.com/box_attachment Several CORS origins are set: https://mg.methodgrid.com, https://app.methodgrid.com, https://mg.staging.methodgrid.com, https://app.staging.methodgrid.com, https://mg.staging2.methodgrid.com, https://app.staging2.methodgrid.com, https://mg.demo.methodgrid.com, https://app.demo.methodgrid.com, https://mg.demo2.methodgrid.com, https://app.demo2.methodgrid.com, http://mg.development.methodgrid.com, https://app.methodgrid.com, http://localhost:3000, https://.staging2.methodgrid.com, https://.methodgrid.com

Implementation and Authentication Flow

The Box integration is the most complex of the four, employing a full OAuth 2.0 Authorization Code Grant flow. Unlike the other integrations that use pop-ups with client-side SDKs to handle authentication, the Box flow involves both the frontend (dms.js) and the backend (PHP controllers and routes) to securely obtain and manage API tokens. The process can be broken down into three main scenarios, all managed within the dms.js composable. Scenario 1: User has a valid Access Token

  1. Token Check: The function first checks localStorage for a non-expired boxAccessToken.
  2. Launch Picker: If a valid token is found, it initializes the Box File Picker (new Box.FilePicker()) and immediately displays it within a modal on the page. The access token is passed directly to the picker.
  3. File Selection: The user selects their files, and the picker's choose event listener fires, sending the file data to the callback function to update the UI.

Scenario 2: Access Token is expired, but a valid Refresh Token exists

  1. Token Check: If the boxAccessToken is missing or expired, the code checks for a boxRefreshToken in localStorage.
  2. Token Refresh: If a refresh token exists, the frontend makes a POST request to a dedicated backend endpoint: /box_token. This request sends the refresh token to the server.
  3. Backend Logic: The backend controller (BoxToken.class defined in user-csrf-routes.php) securely communicates with the Box API, exchanging the refresh token for a new, short-lived access token and a new, long-lived refresh token.
  4. Store New Tokens: The backend returns the new tokens to the frontend. The frontend then saves these new tokens in localStorage with updated expiry times.
  5. Launch Picker: Now possessing a valid access token, the flow proceeds as described in Scenario 1.

Scenario 3: First-time Authentication (No Tokens) This is the initial flow for a user who has never connected their Box account.

  1. Open Auth Window: The code constructs the authorization URL for Box and opens it in a new pop-up window. The user is prompted to log in to Box and grant Method Grid permission.
  2. Redirect to Callback: After the user grants access, Box redirects the pop-up window to a specific callback URL within the Method Grid application: /box_attachment. This URL includes a temporary authorization code.
  3. Handle Callback: The /box_attachment route is handled by the BoxAttachment.php controller. This controller renders a simple page (box-attachment.phtml) containing a script.
  4. Post Message: The script on this page uses window.opener.postMessage to send the authorization code back to the main application window that opened the pop-up.
  5. Exchange Code for Tokens: The main window's message listener receives the code and immediately makes a POST request to the /box_token endpoint, sending the code.
  6. Backend Logic: The backend receives the code and securely exchanges it with the Box API for the initial access token and refresh token.
  7. Store Tokens & Launch Picker: The backend returns the tokens to the frontend. The frontend stores them in localStorage, closes the pop-up window, and finally launches the Box File Picker as described in Scenario 1.

preprod.methodgrid.com

It appears to be possible to add another redirect url:

Last modified by: Unknown