How does Authentication Work?

TrueVault has several authentication mechanisms that support the main access patterns our customers use. This primer will give you a quick overview of how to authenticate in these common scenarios.

End Users

When your end users connect to TrueVault, they need to authenticate to access their data. We recommend you make these connections directly from your client application, not from your server side, to ensure sensitive data doesn’t pass through your servers. End users authenticate with passwords and User Access Tokens.

We recommend that every human being who uses your product is represented by a user in TrueVault. This ensures accurate and compliant audit logs and allows you to leverage our flexible access control rules. You can read more about building the registration process for end users here.

Passwords

When your end-users open your application after they’ve been inactive, you should ask them to log in. Login requests should be made directly from your client application to the TrueVault login endpoint, which accepts the username and password for this user.

TrueVault manages the password verification and secure password storage for you, so your system never has to interact with these sensitive bits of data. If the login request succeeds, TrueVault returns a User Access Token.

User Access Tokens

Aside from the login endpoint, all requests that are made by end-users should use a User Access Token for authentication. User Access Tokens are returned by the login endpoint. By default, they expire after 24 hours but you can always revoke them sooner by calling the logout endpoint. You can use a User Access Token for any request you make to TrueVault. You pass it in the Basic Auth Header by base64-encoding the User Access Token (after appending a : to it). Read our authentication docs for details on how to form the auth header.

Advanced: User MFA

On our Advanced Security plan, you can offer your users MultiFactor Authentication to protect their logins from social engineering attacks. MultiFactor Authentication is a good practice for all users, but it is especially important for any high-privilege users in your systems, like administrators, since a compromise to their account generally has a bigger impact. Check out our detailed guide on adding User MFA to your application, or contact sales@truevault.com to enable User MFA in your account.

System Users

System users do not represent human beings; they represent background processes or asynchronous tasks. They use non-expiring API Keys instead of passwords and transient User Access Tokens. API Keys are added to the Basic Auth Request header just like User Access Tokens.

When to use a System User?

Imagine you need to send a nightly reminder to all doctors who haven’t submitted their daily notes to your product. You’d probably run this analysis on your own server operating on de-identified metadata (i.e. whether the notes were submitted, not what their contents are. More on de-identification here.) To send the emails, you’d probably want to use TrueVault’s Email API. To connect to that API, you’d need to authenticate as a user. In this case, there’s no end-user or human being that is taking this action; the system is sending this email. So, you would create a System User in the console or through the api. It doesn’t make sense for this user to have a password, since no human will log in as this user. You can leave the password blank. Once the user has been created, you should note the API Key for the user. In the console, you can find the API Key by clicking the “REASSIGN” button in the user view. This will invalidate the old API Key and generate a new one (users can only have one at a time). You can accomplish the same task through the API using the Create API Key.

Skip the login dance

If you have a background process or a script that needs to connect to TrueVault, API Keys are the right choice. Since they don’t expire, you can set them in a config file and leave them alone until you decide to rotate them. This saves you from managing expired User Access Tokens and login requests in your script, which cuts down on complexity, error cases, and API Requests.

Other?

Does your application have authentication needs that aren’t met by these strategies? Shoot us an email or ask away on Stack Overflow (tag it truevault so we see.).