Authentication Defaulting

When authenticating to Vault API, Vault authenticates the user to the Vault specified in the POST URI {vaultDNS}. For example:

https://{vaultDNS}/api/{version}/auth

You can also override the {vaultDNS} URI parameter with the optional vaultDNS body parameter, which instead generates a session for the DNS specified in vaultDNS. When the optional vaultDNS body parameter is present, the {vaultDNS} URI parameter is ignored.

If the specified DNS is invalid or inactive, Vault executes logic to authenticate the user to their most relevant available Vault. A DNS is considered invalid if the given user cannot access any Vaults in that DNS, for example, if the user does not exist in that DNS or if all Vaults in that DNS are inactive.

The most relevant available Vault is calculated with the following steps:

Where the user last logged in.
If the user has never logged in, or if the last logged-in Vault is inactive, the oldest active Vault where that user is a member.
If the user is not a member of any active Vaults, the user receives an error message and cannot authenticate.

This is also known as authentication defaulting or session defaulting. Authentication defaulting means that authenticating to Vault API could return a sessionId for any Vault to which the user has access, which may not be the Vault specified in vaultDNS. For this reason, it is best practice to inspect the response, compare the desired Vault ID with the list of returned Vault IDs, and confirm the DNS matches the expected login.

Authentication Defaulting Example

As an example demonstrating authentication defaulting, Miyah is cross-domain user with access to the following Vaults in her home domain:

An inactive Vault created in 2019, where she last logged in: my2019vault.veevavault.com
An inactive Vault created in 2020: my2020vault.veevavault.com
An active Vault created in 2018: my2018vault.veevavault.com
An active Vault created in 2016: my2016vault.veevavault.com

Miyah executes the following authentication call:

curl -X POST https://my2020vault.veevavault.com/api/v24.1/auth \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
-d "username=miyah.miller@veepharm.com&password={password}"
-d "vaultDNS=my2050vault.veevavault.com"

Because the optional vaultDNS body parameter is present, Vault ignores the {vaultDNS} URI parameter.

Then, Vault attempts to generate a valid sessionId for Miyah in the following order:

The Vault specified in the optional vaultDNS body parameter: my2050vault.veevavault.com
- Miyah does not have access to this Vault, so this Vault is invalid. Vault begins the process of authenticating Miyah to her most relevant available Vault.
Where Miyah last logged in: my2019vault.veevavault.com
- This Vault is inactive, so this Vault is invalid. Vault continues the process of authenticating Miyah to her most relevant available Vault.
The oldest active Vault where Miyah is a member: my2016vault.veevavault.com
- This Vault is valid, so Vault generates a session for this Vault and returns SUCCESS.

Miyah’s authentication call returns the following response:

{
  "responseStatus": "SUCCESS",
  "sessionId": "C7EFE4B29EF9914B170BAA01F232B462BE5ACB82F6704FDA2162B",
  "userId": 12021,
  "vaultIds": [
    {
      "id": 1776,
      "name": "PromoMats",
      "url": "https://my2016vault.veevavault.com/api"
    },
    {
      "id": 1777,
      "name": "eTMF",
      "url": "https://my2019vault.veevavault.com/api"
    },
    {
      "id": 1779,
      "name": "QualityDocs",
      "url": "https://qualitydocs-veevapharm.veevavault.com/api"
    }
  ],
  "vaultId": 1776
}

After authenticating, Miyah compares the returned vaultId with the Vault ID where she expected to authenticate. Because this ID does not match, she understands her user must not have access to any Vaults in the specified vaultDNS and she instead authenticated to her most relevant available Vault: "vaultId": 1776.