Authentication

Keeping Data Flowing Securely

Diagram

GRAX Authentication MethodsGRAX 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 utilize 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 application installation/deployment and stored in an encrypted state in the application database. This is then passed into the SFDC 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 is not supported via automated means but [email protected] 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) are not secured for ease of sharing/review. These paths, however, are all the concatenantion of many randomized ids and not regarded to be "guessable".

The full list of token secured endpoints is not 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 application 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 application from the "app launcher", and is greated 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 above-mentioned token, which is verified against the backend's 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 application 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 be a highly-permissioned user 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 - ..." (i.e. "GRAX - Configuration Admin").

OAuth Flow

The OAuth flow for the GRAX application 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 will originate from 3.232.229.75 (hq.grax.com).

Permissions Management

GRAX respects field and "row" (record) level visibility to protect your sensitive data. If a user does not have access to data within Salesforce, they will not 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 do not 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 SFDC report as the source for Case IDs from a list populated by the backend polling the SFDC 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 SFDC 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 SFDC 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 on the instance.

Telemetry Data

Telemetry information, application level statistics about the internal performance of the GRAX system, is sent out to hq.grax.com on a regular interval. This information does not 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.

Datastore Authentication

PostgresSQL

Authentication to the application database is protected via "Password" authentication, as seen here. No other authenticaiton methods to the database are currently supported.

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: