Authenticating to Salesforce

OrgFlow needs to connect to your Salesforce orgs in order to do things like check for metadata changes, deploy and retrieve metadata, run Apex tests and more. OrgFlow supports two authentication methods when connecting to Salesforce: browser-based authorization and credentials.

Browser-based authorization

With browser-based Salesforce authorization, OrgFlow will prompt you to sign in to Salesforce using your web browser and authorize OrgFlow to connect. Once you have completed the authorization flow, Salesforce provides OrgFlow with an access token and a refresh token, and those are stored securely in OrgFlow's cloud. OrgFlow can use the saved tokens to connect to Salesforce for as long as they remain valid, meaning that you will only need to re-authenticate if those tokens get invalidated.

This is the simplest and most secure method of authenticating to Salesforce because OrgFlow never sees the password that is used to authenticate.

With this method, you will need to sign in using a web browser at least once for every Salesforce org that OrgFlow connects to. This means that jobs might pause to wait for user input, which delays completion of the job. For example, a create environment job that creates a new sandbox will need to pause and prompt for authorization, and then wait for a user to perform the sign-in and authorization flow in the new sandbox before it can proceed to add it to your stack.

Token invalidation

Access and refresh tokens can be invalidated or revoked by Salesforce, meaning that the tokens that are saved in OrgFlow's cloud are no longer valid. In this scenario OrgFlow will prompt for an authorization flow to be completed again.

Actions that might invalidate or revoke access and refresh tokens include:

• Refreshing a sandbox
• Manually revoking tokens in the Salesforce setup UI
• Access and refresh tokens expiring because of inactivity
• Deactivation of the Salesforce user account that the tokens were issues for

Tokens acquired using this method are not subject to Salesforce's password expiration policies. However, if the tokens expire or get invalidated, a non-expired password is required to sign-in again and complete a new authorization flow.

Credentials

With this method you provide OrgFlow with credentials, consisting of a username, a password and possibly a security token. OrgFlow then uses these credentials to authenticate whenever connecting to Salesforce.

When also saving those credentials, this is the most convenient method of authenticating to Salesforce because once credentials have been saved, OrgFlow can use them to connect to your Salesforce orgs without requiring user interaction. Additionally, you typically only need to provide credentials for your production org; OrgFlow can use sign-in values transformation to use those credentials also for sandboxes, which means OrgFlow will be able to create and manage sandboxes without the need for any user intervention.

If you choose this method of authentication, you may want to consider excluding the selected user account from password expiration policies because, if the password expires, it must be changed and any saved credentials updated.

Security tokens

Depending on the security policies and configuration of the Salesforce orgs that you are authenticating to, you may need to also provide a security token.

When providing Salesforce credentials in the OrgFlow web app, we provide a specific text field the security token. However, if entering Salesforce credentials into the OrgFlow CLI, the security token must be appended to the end of the password. For example, if your password is 123456 and your security token is abcdef, then you need to enter 123456abcdef.

Saving credentials

Credentials can be saved for reuse. Passwords and security tokens are encrypted when they are saved. Credentials can be saved in two locations:

OrgFlow's cloud

Credentials saved in OrgFlow's cloud can be used by both the OrgFlow web app and the OrgFlow CLI.

If you create a stack via the OrgFlow web app and choose to use credentials, your credentials will automatically be encrypted and saved in the OrgFlow cloud.

Credentials saved in OrgFlow's cloud can be managed by both the OrgFlow web app (using the stack settings page), and the OrgFlow CLI (using the auth:salesforce:save command).

On your device

OrgFlow CLI can also save and read credentials on local disk on the device that the CLI is running on. This is useful if you don't want to save your credentials in OrgFlow's cloud, want to use different credentials on different devices, or want to override credentials saved in OrgFlow's cloud.

Credentials saved locally on your device take precedence over those saved in OrgFlow's cloud.

Credentials saved locally on your device can be managed using the auth:salesforce:save command.

Choosing a Salesforce user account

Regardless of the authentication method you choose, OrgFlow connects to Salesforce using a specific user account. It's important to make sure that this user has sufficient licenses and permissions for OrgFlow to fully operate. The selected user must be able to:

• Retrieve and deploy metadata
• Manage sandboxes
• Run Apex tests
• Read source tracking data (if enabled)

Additionally, we recommend that you:

• Use a dedicated user account only for OrgFlow
• Use an API-only user account
• Consider excluding the user account from password expiration policies (if using username and password authentication)

If you are a system administrator in your Salesforce production org, one option is to use your own user account. This may be suitable for evaluation, experimentation or for very small teams, but it has significant drawbacks. A more robust option is to create a new API-only production user account dedicated for this purpose, as described above.

Sign-in values

The details required for OrgFlow to connect to a Salesforce org are referred to as sign-in values and consist of:

• Username
• Optionally:
  • Custom sign-in URL
  • Password
  • Security token (depending on your Salesforce security settings)

When you create a new stack, you provide sign-in values for connecting to your production org. These details are stored in the stack, and referred to as the base sign-in values.

Sign-in values for connecting to an environment's Salesforce org can usually be inferred automatically from the base sign-in values stored on the stack. For the production environment, the base values on the stack can be used as they are. For sandbox environments, the settings on the stack can be transformed based on the sandbox name.

The following table illustrates this transformation logic:

Setting	Base values	Sandbox ALPHA (inferred)
Sign-in URL	https://acme.my.salesforce.com	https://acme--ALPHA.sandbox.my.salesforce.com
Username	jane.doe@acme.com	jane.doe@acme.com.ALPHA
Password	********	(unchanged)

You can also configure sign-in values directly on an individual environment. These values will then override any inferred values. This can be useful in a variety of scenarios, such as when:

• You have chosen not to store base sign-in values on the stack
• A sandbox has different domain settings than your production org
• You prefer to use a different authorization method or user account to connect to a sandbox than your production org
• You prefer to use different production credentials for metadata flow than sandbox management

Custom sign-in URL

By default, OrgFlow will use https://login.salesforce.com (https://test.salesforce.com for sandboxes) to perform the initial browser-based authorization flow (or perform the initial validation of provided credentials).

Upon successful authorization/validation, Salesforce provides OrgFlow with the enhanced domain for your org. OrgFlow will then use the enhanced domain for further requests to the same Salesforce org (regardless of which URL was used to sign in).

You can also choose to provide your enhanced domain up-front as a custom sign-in URL. The enhanced domain of your production org is typically something similar to https://[company].my.salesforce.com. It is recommended that you provide your enhanced domain if possible; the legacy sign-in URLs may still work, but Salesforce discourages their use and, depending on your Salesforce security settings, they may have been disabled.