Skip to content

HOW TO #1 – Authorize an Org

Jump to bottom
ubraig edited this page Jul 12, 2023 · 1 revision

Overview

Every data handling command requires authorization details in the first parameter. There are three basic options how this could look like:

  1. Get the token via the sfauth command and store its return value in a Powershell variable. Provide the variable as the first parameter on every command. Example:
    1. $MyOrgAuthToken = sfauth <My Parameters>
    2. sfextract $MyOrgAuthToken Account "SELECT Id, Name FROM Account"
  2. Enclose the sfauth command as subexpression as the first parameter. Example:
    1. sfextract (sfauth <My Parameters>) Account "SELECT Id, Name FROM Account"
  3. Provide a string with a SFDX Org Alias as the first parameter. The command will run the sfauth command for you to convert this into an auth token. Example:
    1. sfextract 'MySfdxOrgAlias' Account "SELECT Id, Name FROM Account"

Before the actual token can be handed over to Data Loader, it always needs to be encrypted based on an encryption key file.

  • This obviously is for security reasons to prevent tokens or passwords showing up as plain text in scripts.
  • For some scenarios the module will automatically create a default key file in a default directory for you. It will then use that in the background.
  • But be aware: A key file MUST always be there. If you switch your working directory between commands, it might lose the path to the automatically created key file and create another one in the background. So for some other scenarios you will need to handle the key file yourself.

SFDX

The most simple approach when you are actively using the SFDX Command Line Interface: Just re-use the orgs you already have authorized via SFDX as shown in the list sfdx auth list.

Get-SfCredential will call the SFDX Command sfdx org display to get the json representation of the Username, the OAuth token and the Instance URL. Then it will encrypt the OAuth token and convert it into a representation that is suitable for being handed over to scripted dataloader.

Use SFDX Default Org

Prerequisites:

  • Your current directory MUST be the SFDX project directory. Otherwise it won't find the project's default settings.
  • A default org is defined in this SFDX project.

The following commands are equivalent:

  • $MyOrg = sfauth
  • $MyOrg = Get-SfCredential

Provide SFDX OrgAlias or Username

Prerequisites:

  • The Org you want to authorize shows up in the list sfdx auth list.
  • There is no need to be in a specific directory.

You can use either the OrgAlias or the username. For the example below, we assume an OrgAlis of 'MySfdxOrgAlias' and an username of 'MyExampleUser@example.org'.

The following commands are equivalent:

  • $MyOrg = sfauth MySfdxOrgAlias
  • $MyOrg = Get-SfCredential MySfdxOrgAlias
  • $MyOrg = Get-SfCredential MyExampleUser@example.org
  • $MyOrg = Get-SfCredential -OrgAliasOrUsername MySfdxOrgAlias
  • $MyOrg = Get-SfCredential -OrgAliasOrUsername MyExampleUser@example.org

Password Entered on the Console

This will be the best approach if you do not use SFDX and want to authenticate on the console just for this session.

Prerequisites:

  • You will need to provide the instance URL. Either use the generic ones, i.e. https://login.salesforce.com or https://test.salesforce.com for Production or Sandbox respectively. Or use your MyDomain URL.
  • The password + security token can NOT be provided via command line parameter. It will always ask via secure console input, i.e. without showing the characters entered.
  • A key file is needed to encrypt the password: If you do not provide your own keyfile, it will check whether it can find a default key file. one in the current directory. If not, it will generate one on the fly. The default path is .\.SfDataloader\SfDataloader.key

The following commands are equivalent:

  • $MyOrg = sfauth MyUser@example.org -ConsoleInput -InstanceUrl https://test.salesforce.com
  • $MyOrg = Get-SfCredential MyUser@example.org -ConsoleInput -InstanceUrl https://test.salesforce.com

Encrypted Password

This is the proper approach for unattended operation with username/password authentication. It requires a 3 step approach:

Step 1: Create your own key file.

If you don't have one yet, create your own key file:

New-SfEncryptionKeyFile .\MyPath\MyKeyfile.key

Step 2: Encrypt your password.

Encrypt your password and, if applicable, security token using this key file. The following command will let you enter password and security token via secure input on the console. The resulting value is the encrypted to be stored in your script.

ConvertTo-SfEncryptedString -KeyFile .\MyPath\MyKeyfile.key -Prompt 'Enter password and, if applicable, security token'

Step 3: Use encrypted string in your script.

Pass this encrypted string and the same key file as parameters to Get-SfCredential command:

$MyOrg = sfauth MyUser@example.org -EncryptedString 'MyEncryptedStringFromPreviousStep' -KeyFile .\MyPath\MyKeyfile.key -InstanceUrl https://test.salesforce.com

Browser Login

If you prefer to enter username and password via browser just as you run a data operation, you can do so via:

  1. Run the data operation:
    • sfextract (sfauth -BrowserLogin Sandbox) Account "SELECT Id, Name FROM Account"
  2. A browser window will be launched:
    1. Confirm the "the 8-digit code" shown.
    2. Enter username and password.
  3. Dataloader will be authorized to run its operation.
Clone this wiki locally