# Configuring Vault File Manager

Vault File Manager for Windows provides an efficient way to check out, edit, and check in Vault documents. When users check out documents, Vault File Manager downloads them automatically. Users can open files to edit them directly from the Vault File Manager client installed on their Windows computer.

## Enabling Vault File Manager {#enabling}

To enable Vault File Manager, navigate to **Admin > Settings > Checkout Settings** and select the **Enable check out to File Manager** checkbox. To allow users to download the installer for the Vault File Manager client directly from their Vaults, select the **Provision Vault File Manager from Vault** checkbox. These flags are typically enabled automatically in new Vaults.

After enabling Vault File Manager, you must also grant users the _Application: Document: Vault File Manager_ permission. This permission is included in the _Vault Owner_ and _System Administrator_ standard security profiles. Users without this permission will not see the **Document Check Out** bulk action or the **Check Out to File Manager** option in the document **Actions** menu, nor will they see the Vault File Manager **Download Installer** link on their **User Profile** page.

## Configuring Auto Open Settings for Vault File Manager {#auto-open-settings}

You can define which documents open automatically for users upon checkout from Vault File Manager. Vault uses the _VFM File Security Policy_ object to determine which file types Vault File Manager opens automatically. Vault stores the file types as object records.

To configure these settings, first navigate to  **Admin > Configuration > Objects > VFM File Security Policy** and ensure that the **Display in Business Admin menu** checkbox is selected. Next, navigate to **Business Admin > Objects > VFM File Security Policy**. By default, Vault includes _VFM File Security Policy_ records to auto-open most common file types. To prevent a file type from opening automatically:

  1. From the **Actions** menu next to the **Description** of the file type, click **Edit**.
  2. From the **Status** picklist, select **Inactive**.
  3. Click **Save**.

To add a new file type:

  1. From the **VFM File Security Policy** object record list page, click the **Create** button.
  2. Enter a **Description** for the file type.
  3. Select from the **Status** picklist. If you select **Active**, Vault File Manager will auto-open files with this file type. If you select **Inactive**, users will need to open these file types manually.
  4. Enter one or more **File Extensions** for the file type. For example, doc and docx for Microsoft Word files. Separate multiple values with commas.
  5. Click **Save**.

## Vault File Manager & Corporate Identity Systems

<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>: Vault File Manager supports authenticating with your existing SAML SSO without requiring any additional configuration. However, you can optionally complete the steps below to configure Vault File Manager to use OAuth for SSO instead if preferred.</p>
    </div>
  </div>
</div>



To enable OAuth SSO authentication for Vault File Manager using your corporate identity system, you must configure an OAuth2.0 / OpenID Connect profile in your Vault, along with an associated OAuth 2.0 / OpenID Connect App on your Authorization Server. Vault File Manager currently only supports OAuth 2.0 / OpenID Connect with Ping Federate, ADFS 4.0, or Okta.



<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>:  For security purposes, we recommend that <a class="external-link " href="https://datatracker.ietf.org/doc/html/rfc7636" target="_blank" rel="noopener">PKCE<i class="fa fa-external-link" aria-hidden="true"></i></a>is enabled in your AS.</p>
    </div>
  </div>
</div>



### Configuring an OAuth Profile for Vault File Manager

Configuring Vault File Manager to work with OAuth is a two-step process. First, configure OAuth 2.0 / OpenID Connect Profile for your Vault. See [Configuring OAuth 2.0 / OpenID Connect Profiles](/en/lr/43329/) for detailed instructions.

Next, you'll need to configure an SSO Security Policy. When defining your SSO Security Policy, set the **OAuth 2.0 / OpenID Connect Profile** to the OAuth 2.0 profile you create for Ping Identity, ADFS, or Okta. See [Configuring Single Sign-on](/en/lr/13977/) for detailed instructions.

Finally, you'll need to provision users to use your defined SSO Security Policy. Navigate to **Admin > Users & Groups > Domain Users > {User}**, and set the **Security Policy** in the _Settings_ section to the SSO policy you defined. If the associated OAuth 2.0 profile you configured has a **User ID Type** of _Federated ID_, you must also set the **Federated ID** value in the user profile.

<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>: If you have <em>Ping</em> or <em>Other</em> selected in your OAuth 2.0/OpenID Connect profile, we recommend that you update your redirection URI in your Authorization Server to <code class="language-plaintext highlighter-rouge">com.veeva.vaultfilemanager://authorize</code>. It is not recommended to continue using dynamic redirect URIs.</p>
    </div>
  </div>
</div>



#### Ping Identity

When creating an OAuth 2.0 profile in Vault for Ping Federate, you must select **PingFederate** in the **Authorization Server Provider** drop-down to utilize standard OAuth.

#### ADFS

When creating an OAuth 2.0 profile in Vault for ADFS, you must select **ADFS** in the **Authorization Server Provider** drop-down. Selecting ADFS instructs Vault File Manager to use the **Preferred Authentication Library** (MSAL or ADAL) instead of standard OAuth. This is the same authentication scheme used by Microsoft 365 and other Microsoft applications. MSAL is the default value, but you can use the **Preferred Authentication Library** drop-down to select ADAL instead of MSAL for applications that require it.

#### Microsoft Azure AD

To create an OAuth 2.0 profile in Vault for Microsoft Azure AD:

  1. Click Upload AS Metadata, select Provide Authorization Metadata URL, and enter "https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration"
  2. Find the tenant for your domain by navigating to **Custom Domain Names** in Microsoft Azure AD, and copy the tenant ID from the **Name** column.
  3. Select **Azure AD** in the **Authorization Server Provider** drop-down and configure the **Identity Claim** as follows:
      * **Identity Claim**: Identity is in another claim
      * **Claim**: upn
  4. [Create a ClientID Mapping](/en/lr/43329/#client-mapping), setting the following fields:
      * **Application Label**: Enter a name. For this profile, we recommend "Vault File Manager".
      * **Application Client ID**: Enter "VaultCheckOut".
      * **Authorization Server Client ID**: Enter the **Application ID.** You can find this in the **Application Overview** in your Vault File Manager application in Microsoft Azure AD.

#### Okta {#okta-oauth}

When creating an OAuth 2.0 profile in Vault for Okta, you must select **Okta** in the **Authorization Server Provider** drop-down. For an Okta profile with Vault File Manager, you'll need to [create a clientID Mapping](/en/lr/43329/#client-mapping), setting the following fields:

* **Application Label**: Enter a name. For this profile, we recommend "Vault File Manager".
* **Application Client ID**: Enter "VaultCheckOut".
* **Authorization Server Client ID**: Enter the **Client ID** generated in your Vault File Manager application in Okta.

### Authorization Server Support

Next, configure and register an OAuth 2.0 / OpenID Connect App for Vault File Manager in your Authorization Server.

#### Ping Identity

To configure a new Ping Identity profile:

  1. Set the profile clientID to "VaultCheckOut". Ensure that there is "No client secret" for the client ID.
  2. For **Client Authentication**, select _None_.
  3. Enter a display **Name**. For this profile, we recommend "Vault File Manager".
  4. Enter the following **Redirection URI**: `com.veeva.vaultfilemanager://authorize`.

Your application should be configured to honor the following grant types:

* `Authorization Code`
* `Refresh Token`

Vault will use the `sub` claim in the `id_token` and the `access_token` as the _Federated ID_.

Your application configuration should honor the following scopes:

* `openid`
* `offline_access`

After you've set up the profile, get the Authorization Server metadata. Most Authorization Servers expose the AS Metadata via a URL, while some allow you to download an AS Metadata JSON file. Use either the URL or the JSON file to upload the AS Metadata in your OAuth 2.0 / OpenID Connect profile in Vault.

#### ADFS 4.0

To set up Vault File Manager as an application in ADFS:

  1. Within ADFS, navigate to **Application Groups > Application > Native Application**.
  2. Enter the **Client ID**: "VaultCheckOut".
  3. Enter a display **Name**. For this profile, we recommend "Vault File Manager".
  4. Enter the following **Redirection URI**: `vaultfilemanager://authorize`.

Next, you must set up Vault as a Web API:

  1. Within ADFS, navigate to **Application Groups > Application > Web API**.
  2. Click into the **Identifiers** tab to add Vault as a relying party identifier.
  3. Enter "Vault" as the **Display name**.
  4. Enter the following **Relying party identifier**: `https://login.veevavault.com`.
  5. Click into the **Issuance Transform Rules** tab to create a custom claim rule.
  6. In this tab, click **Add Rule > Send Claims Using a Custom Rule > Next**.
  7. Enter the following custom rule, replacing "**mail**" with the field you wish to use as the _Federated ID_:
  <br>`c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] => issue(store = "Active Directory", types = ("sub"), query = ";`**`mail`**`;{0}", param = c.Value);`
  8. Click into the **Client Permissions** tab and select **Vault File Manager**.
  9. Select the **allatclaims** checkbox.
  10. Select the **openid** checkbox.
  11. Click **Apply** to save your Web API configuration. Click **OK** to exit the dialog.

#### Microsoft Azure AD

To set up Vault File Manager as an application in Microsoft Azure AD, you must first create an application registration for `login.veevavault.com`:

  1. Within **Microsoft Azure** navigate to **Azure Active Directory > App Registrations**  and click **New Registration**.
  2. Enter a **Name**. We recommend `login.veevavault.com`.
  3. Click **Register**.
  4. Click on your new app, then click **Manifest**. Change the **identifier URIs** to `https://login.veevavault.com`.

Next, create an application registration for Vault File Manager:

  1. Within **Microsoft Azure**, navigate to **Azure Active Directory > App Registrations**  and click **New Registration**.
  2. Enter a **Name**. We recommend "Vault File Manager."
  3. Configure the **Redirect URI** as **Public client** and enter the following URI: `vaultfilemanager://authorize`.
  4. Click **Register**.
  5. Click **API permissions,** then click **Add a permission**.
  6. Select **`login.veevavault.com`**, then select **Delegated Permissions**.
  7. Check the consent box and click **Add Permissions**.

#### Okta

To set up Vault File Manager as an application in Okta:

  1. Within **Okta**, navigate to **Applications > Add Application > Create New App**.
  2. For **Platform**, select _Native App_.
  3. For **Sign on method**, select _OpenID Connect_.
  4. Click **Create**.
  5. Enter an **Application Name**. For this profile, we recommend "Vault File Manager".
  6. Enter the following **Login redirect URI**: `com.veeva.vaultfilemanager://authorize`.
  7. Click **Save** to create the application.

After you've created the application, navigate to the **General Settings** tab to confirm the following settings:

* **Application label**: Value you entered as the **Application Name**, for example, Vault File Manager
* **Application type: Native**
* Allowed grant types: _Authorization Code_ and _Refresh Token_
* Login redirect URIs: `com.veeva.vaultfilemanager://authorize`

In the **General Settings** tab, you'll also need to scroll to the _Client Credentials_ section. In Okta, you can't configure the **Client ID**; instead, Okta assigns a random unique identifier. To support this, you'll need to [configure ClientID mapping][1] in your Vault and enter this unique identifier in the **Authorization Server Client ID** field. In this section, **Client authentication** should be set to **Use PKCE (for public clients)**.

Next, navigate to the **Sign On** tab to ensure that the **Sign On Methods** are set to **OpenID Connect**.

Finally, navigate to the **Assignments** tab to add Okta users. For every Vault user you assigned to the **OAuth 2.0 / OpenID Connect Profile** for Okta, you must add a corresponding user here. If the **User ID Type** in the OAuth 2.0 / OpenID Connect Profile is set to _Vault User Name_, the Okta user name must match the Vault user name. If it is set to _Federated ID_, the Okta user name must match the Vault user's Federated ID.

### Verifying the OAuth Configuration

  1. Configure a test user with the security policy set to **OAuth SSO** and its corresponding **OAuth 2.0 / OpenID Connection profile** configured as described in the previous section.
  2. Ensure that Vault File Manager is not running.
  3. Open Vault File Manager, enter the test user's username and click **Next**.
  4. You should see the "You are about to log into your Identity Provider" message. Click **Continue.**
  5. If you aren't already logged into the Authorization Server, you will need to enter the test user's username and password when prompted.
  6. The test user's credentials will appear in Vault File Manager showing the user has successfully logged in.

If you do not see the identity provider login or are unable to log in successfully, check your configuration. Learn more about [OAuth 2.0 / OpenID Connect Event Logging and Troubleshooting](/en/lr/43329/#event_logging).

## Related Permissions

Permissions control actions related to Vault File Manager:

| Type | Permission Label | Description |
| --- | --- | --- |
| Security Profile | Application: Document: Vault File Manager | Ability to check out documents using the _Check Out to File Manager_ action or _Document Check Out_ bulk action. |
| Security Profile | Application: Document: Bulk Update | Ability to perform bulk actions. |
| Security Profile | Application: Document: Download Rendition | Ability to download renditions using Vault File Manager. |
| Security Profile | Application: File Staging Access via Vault File Manager | Ability to download renditions and upload source files using Vault File Manager. |
| Security Profile | Application: File Staging: Access Root Folder | Ability to access your Vault's file staging server's root folder. |
| Security Profile | Application: All Documents: Cancel Checkout | Ability to undo document checkouts performed by another user. Must also have the _Edit Document_ role-based permission. |
| Security Profile | Object: VFM File Security Policy: Read | When checking out a document to Vault File Manager, you must have _Read_ permission on the _VFM File Security Policy_ (`vfm_file_security_policy__v`) object for Vault File Manager to automatically open the file. |
| Document Role | Edit Document | Ability to check out and check in the document. |

 [1]: #okta-oauth