Authentication

Diagram

GRAX Authentication Methods

Generalities

Within GRAX supplied infrastructure, all traffic is encrypted in flight via HTTPS/SSL at TLS 1.2 or higher with a public certificate (behind the ALB we recommend self-signed certificates). All data stores are encrypted by - at a minimum - AES-256. GRAX offers a pre-built secure architecture via the AWS Marketplace but choosing to use the GRAX Software on custom architecture enables you to build your own security model. As such, any operations including the transmission of network traffic or the storage of data at rest which take place on customer-provided/operated infrastructure is the responsibility of the customer.

GRAX Token-based Authentication

GRAX uses a standard JSON Web Token (JWT) authentication flow to secure the Managed Package to Backend/Instance traffic. This is specifically traffic that the Managed Package sends to submit data, triggers, or configuration changes to the backend.

Token

The secret used to drive the JWT authentication is generated on app installation/deployment and stored in an encrypted state in the app database. This is then passed into the Salesforce Managed Package by one of your Salesforce administrators after installation. Randomly generated via secure means that at a length of at least 30 characters, the complexity of brute forcing such a token is considered implausible. Rotation of this token isn't supported via automated means but GRAX Support can help provide relevant details via a support request.

This token is submitted in the x-api-token header as part of every API request from the managed package to the backend which contains, accesses, or controls data. Endpoints such as job summary reports (which contain only object names) aren't secured for ease of sharing/review. These paths, however, are all the concatenation of many randomized IDs and not regarded to be "guessable."

The full list of token secured endpoints isn't available for security reasons.

Salesforce Storage

The GRAX Tokens are stored on the Salesforce side within a protected custom secret. For more information on these, see here. Modification to these values is accomplished via the GRAX Managed Package GUI.

Verification

When the backend receives a request from the Managed Package that requires authentication, it verifies the supplied API token against the token loaded in the app configuration. This configuration loads the contents of the connected AWS Secret, sources the value from the attached Database, or reads from the local environment on each boot.

Use Case Example

Joe Smith is an ABC Company Salesforce Administrator. He is newly responsible for configuration and maintenance of the GRAX Managed Package as well as the related data backup operations. He logs into Salesforce, chooses the GRAX app from the "app launcher," and is greeted by the GRAX "Configuration" tab. He switches to the "Schedule" tab and selects "Execute Now" on an existing backup job. This sends a request to the backend, secured via the afore-mentioned token, which is verified against the expected token value. This request adds the backup job to the internal work queue.

GRAX SSO via Salesforce

Within the GRAX webapp experience, authentication is driven by the user's Salesforce access. Via this control, your admins can completely prevent access to GRAX, hide fields, hide features, and/or grant permission to modify general app settings.

OAuth Sessions

There are always two login types to consider with GRAX: the integration user (for backing up/archiving/restoring data) and the user that logs into the GRAX interface to run said archives, restores, or searches. The integration user must have extensive permissions and be connected to the GRAX backend via OAuth. To be a user of GRAX, your Salesforce user must be given a custom permission set, named along the lines of "GRAX - [Name]" (that is "GRAX - Configuration Admin").

Please note that 'Log In As' (User Impersonation) does not work with OAuth

OAuth Flow

The OAuth flow for the GRAX app consists of multiple steps. First, the GRAX backend calls out to hq.grax.com with the OAuth request. This GRAX service then proxies that request to Salesforce, relating it to a unified GRAX Connected App configuration. After generating an access token for the user session, this GRAX service discards the session token and passes the access token back to the backend. The backend then uses the received access token to generate a new session.

This multi-party flow is a requirement of GRAX licensing processes as well as ensuring GRAX works under several of the more restrictive Salesforce security options. No credentials, session tokens, or access tokens are stored within the GRAX beyond the lifetime of the specific authorization events they're related to. All related data stores are encrypted. Login attempts against the user as part of this flow originate from 3.232.229.75.

Permissions Management

GRAX respects field and "row" (record) level visibility to protect your sensitive data. If a user doesn't have access to data within Salesforce, they won't be able to view that same data in the GRAX webapp or Lightning Web Components. For added guarantees you can prevent integration user access to specific data so that it can never be seen, read, backed up, archived, or restored by GRAX and thus avoid the whole end user access issue in the first-place. We don't recommend this, as that data cannot be protected in backups in this case. To manage this visibility, simply manage it as your normally would in Salesforce.

GRAX drives webapp access permissions based off of custom permission sets which are installed alongside the managed package and can be customized by advanced users. To grant a user access to the permissions covered under a permission set, simply assign them that permission set.

Use Case Examples

Joe Smith is an ABC Company Salesforce Administrator. He is newly responsible for restoring all Cases to their value as of last Friday. He connects to the GRAX webapp URL (unique for each customer), logs in with SSO via his intended Salesforce org, and navigates to the "Restore" page. He chooses a Salesforce report as the source for Case IDs from a list populated by the backend polling the Salesforce REST API with the integration user's OAuth session token. After clicking next, the restore execution begins processing. During this time, the GRAX backend is querying the Salesforce API and GRAX storage to build a restore plan for the cases. Once Joe triggers the restore execution to run after processing is complete, the GRAX backend begins submitting REST calls to the Salesforce API with the integration user's session token to create records.

Jane Smith is an ABC Company Support Associate. She receives a customer complaint referencing a major case from 13 months ago. ABC Company's Salesforce leadership has opted to archive any cases last modified more than 9 months ago with GRAX. Jane navigates to the "Related" tab on the Account record and uses the GRAX Related Records component to see the archived case record, review the fields, and even restore that case along with related records (via linking into the GRAX webapp). All data retrieval in this scenario and the potential jump into the GRAX webapp are powered by Jane's OAuth session with her Salesforce org. The API calls for records originate on Jane's machine, and are verified via the OAuth process when they arrive at the GRAX application.

Telemetry Data

Telemetry information, app level statistics about the internal performance of the GRAX system, is sent out to hq.grax.com on a regular interval. This information doesn't contain any of your Salesforce data. The connection to hq.grax.com is write-only and secured via a combination of username and password used in the basic authentication process.

Data Storage Authentication

PostgreSQL

Authentication to the app database is protected via "Password" authentication, as seen here. No other authentication methods to the database are currently supported. GRAX does not use SSL with Certificate Verification on Postgres databases; no action is needed regarding Root Certificates or Certificate Authorities as this will not impact the application.

AWS S3 (or Azure/GCP alternatives)

As a general rule, the GRAX product supports the most common and accepted authentication methods for each bucket/blob storage provider. Details for each are linked below: