Technical Guide Reference Guide Frequently Asked Questions Tutorials
Show menu

Authentication requirements

Authentication Requirements

Each Salesforce component has an authentication attribute that determines which backend the component uses (SOAP or REST) and how the component authenticates itself in order to gain access to the Salesforce servers.

The choice of backend might seem irrelevant to the end-user but it has consequences for the type of information required to authenticate. Furthermore, it also determines the granularity of control a Salesforce administrator can exercise over what a ConnectPlaza Salesforce component can and cannot do.

The authentication attribute has several predefined values, i.e., SOAP_BACKEND, OAUTH2_PASSWORD, OAUTH2_JWT, and OAUTH2_REFRESH_TOKEN. The rest of this document describes the specific requirements for each value.

Note that for testing purposes you can create a developer account at https://developer.salesforce.com/signup. If you are using an existing Salesforce account, make sure you have the API enabled permission (a developer account has this by default).

The following sections are written to be as self-contained as possible. So they can be read independently of each other.

SOAP_PASSWORD

Upon selecting this value, you are required to further supply:

  • Username - This is the username of the Salesforce account you wish to use.
  • Password - This is the corresponding Salesforce password. Please note that Salesforce passwords can expire. To disable this behaviour:
    • Login at https://login.salesforce.com.
    • Go to setup by clicking on the cog icon, located between the question mark and the notification bell in the upper right corner of your screen, and then selecting setup.
    • Go to Administration > Users > Profiles.
    • Click on Edit next to the profile associated with the account you are using for this app. Note that you can see the profile associated with an account by:
      • First logging in with the account you wish to use.
      • Then go to your account settings (available by clicking on your user icon in the upper right corner and then clicking settings).
      • Finally, go to My Personal Information > Advanced User Details.
      • The profile is listed under profile.
    • Scroll down to Password Policies.
    • Set User Passwords Expire In to Never expires.
    • Click on Save.
  • Security token - The security token is an additional security measure in Salesforce and is generated per Salesforce account. If you do not have the token you should
    • First check your email account (the one that is associated with your Salesforce account) for mails from Salesforce. If the security token has been generated in the past it has been emailed to you.
    • If you cannot find the old one or if you’ve never had one in the first place, you can generate a new one by following the next steps:
      • Login at https://login.salesforce.com.
      • Go to your account settings (available by clicking on your user icon in the upper right corner and then clicking “settings”).
      • Under “My Personal Information” there is the option to “Reset Security Token”.
      • Note that if you reset your token the old token (if it exists) expires and is no longer valid.

OAUTH2_PASSWORD

Upon selecting this value, you are required to further supply:

  • Username - This is the username of the Salesforce account you wish to use.
  • Password - This is the corresponding Salesforce password. Please note that Salesforce passwords can expire. To disable this behaviour:
    • Login at https://login.salesforce.com.
    • Go to setup by clicking on the cog icon, located between the question mark and the notification bell in the upper right corner of your screen, and then selecting setup.
    • Go to Administration > Users > Profiles.
    • Click on Edit next to the profile associated with the account you are using for this app. Note that you can see the profile associated with an account by:
      • First logging in with the account you wish to use.
      • Then go to your account settings (available by clicking on your user icon in the upper right corner and then clicking settings).
      • Finally, go to My Personal Information > Advanced User Details.
      • The profile is listed under profile.
    • Scroll down to Password Policies.
    • Set User Passwords Expire In to Never expires.
    • Click on Save.
  • Security token - The security token is an additional security measure in Salesforce and is generated per Salesforce account. If you do not have the token you should
    • First check your email account (the one that is associated with your Salesforce account) for mails from Salesforce. If the security token has been generated in the past it has been emailed to you.
    • If you cannot find the old one or if you have never had one in the first place, you can generate a new security token by following the next steps:
      • Login at https://login.salesforce.com.
      • Go to your account settings (available by clicking on your user icon in the upper right corner and then clicking “settings”).
      • Under “My Personal Information” there is the option to “Reset Security Token”.
      • Note that if you reset your security token the old token (if it exists) expires and is no longer valid.
  • Instance - The Salesforce instance refers to the server your Salesforce organization lives on. It is visible in part of the url after you login to your Salesforce account. Examples are eu27, ap5, and na12.
  • Client ID + Client Secret - In order to obtain a client id and secret you will need to create a connected app within Salesforce by following the next steps:
    • Login at https://login.salesforce.com.
    • Go to setup by clicking on the cog icon, located between the question mark and the notification bell in the upper right corner of your screen, and then selecting setup.
    • Go to Apps > App Manager, located on the left hand side of the screen under Platform Tools.
    • Click on “New Connected App”.
    • Fill in the required information:
      • Connected App Name - There are no requirements on the name. So just give it a sensible name.
      • API Name - Gets automatically filled (usually just the connected app name with the spaces substituted with underscores).
      • Contact email - Salesforce uses this email address if they need to contact you about the connected app.
      • Enable OAuth Settings.
        • The callback URLs are not used but Salesforce requires you to add one anyway. So just add something like this: https://localhost:/<insert App Name here>/oauth/_callback. Note that if your app name has spaces in it, you should replace them with underscores in the url.
        • Add the following OAuth Scopes:
          • Access and manage your data (api).
          • Perform requests on your behalf at any time (refresh_token, offline_access).
        • Finally click on save.
        • You are presented with an overview of your connected app. The client id and client secret values requested by ConnectPlaza are available under the names consumer key and consumer secret (click to reveal it), respectively.

OAUTH2_JWT

This authentication method requires that you generate a key pair and export the public key as a certificate. This certificate will be uploaded in Salesforce (see below).

 

Below are the instructions for generating a key pair and exporting its public key as a certificate in Keystore Explorer:

  • Open Keystore Explorer.
  • Open an existing keystore or create a new one.
  • Click on generate key pair in the toolbar.
  • The default settings are fine (RSA with key size 2048).
  • Click on ok.
  • Give it the appropriate validity period for your use case. For testing purposes the default of one year is fine.
  • Give it a name by clicking on the icon next to the name field.
  • Enter a value for “common name”. Other fields are optional.
  • Click on ok.
  • Click on ok to finalize the key generation.
  • Finally enter an alias for the key pair in the keystore and optionally add a key password.
  • Now right click on the key pair and select Export > Export Certificate Chain in the menu.
  • Default settings are fine. Click on export to save the certificate file.

 

Upon selecting this value, you are required to further supply:

  • Username - This is the username of the Salesforce account you wish to use.
  • Instance - The Salesforce instance refers to the server your Salesforce organization lives on. It is visible in part of the url after you login to your Salesforce account. Examples are eu27, ap5, and na12.
  • Client ID - In order to obtain a client id you will need to create a connected app within Salesforce by following the next steps:
    • Login at https://login.salesforce.com.
    • Go to setup by clicking on the cog icon, located between the question mark and the notification bell in the upper right corner of your screen, and then selecting setup.
    • Go to Apps > App Manager, located on the left hand side of the screen under Platform Tools.
    • Click on “New Connected App”.
    • Fill in the required information:
      • Connected App Name - There are no requirements on the name. So just give it a sensible name.
      • API Name - Gets automatically filled (usually just the connected app name with the spaces substituted with underscores).
      • Contact email - Salesforce uses this email address if they need to contact you about the connected app.
      • Enable OAuth Settings.
        • The callback URLs are not used but Salesforce requires you to add one anyway. So just add something like this: https://localhost:/<insert App Name here>/oauth/_callback. Note that if your app name has spaces in it, you should replace them with underscores in the url.
        • Enable use digital signatures.
          • Upload the previously exported certificate.
        • Add the following OAuth Scopes:
          • Access and manage your data (api).
          • Perform requests on your behalf at any time (refresh_token, offline_access).
        • Finally click on save.
        • You are presented with an overview of your connected app. The client id value requested by ConnectPlaza is available under the names consumer key.
        • Finally, we need to pre-authorize the application:
          • Go to Apps > Connected Apps > Click on “Edit” next to the app name.
          • Set Permitted Users under OAuth Policies to “Admin approved users are pre-authorized”
          • Go to Users > profiles. Find the appropriate profile and click on Edit. For example, if you are the system administrator, you would select the profile with the name “system administrator”.
          • Under Connected App Access click on the check box next the connected app name.
          • Scroll down and click on Save.
        • Key Alias - The alias of the key pair in the Connectplaza keystore.
        • Key Password - The password of the key pair in the keystore. If left empty it defaults to the keystore password.

OAUTH2_REFRESH_TOKEN

Upon selecting this value, you are required to further supply:

  • Username - This is the username of the Salesforce account you wish to use.
  • Instance - The Salesforce instance refers to the server your Salesforce organization lives on. It is visible in part of the url after you login to your Salesforce account. Examples are eu27, ap5, and na12.
  • Client ID + Client Secret - In order to obtain a client id and secret you will need to create a connected app within Salesforce by following the next steps:
    • Login at https://login.salesforce.com.
    • Go to setup by clicking on the cog icon, located between the question mark and the notification bell in the upper right corner of your screen, and then selecting setup.
    • Go to Apps > App Manager, located on the left hand side of the screen under Platform Tools.
    • Click on “New Connected App”.
    • Fill in the required information:
      • Connected App Name - There are no requirements on the name. So just give it a sensible name.
      • API Name - Gets automatically filled (usually just the connected app name with the spaces substituted with underscores).
      • Contact email - Salesforce uses this email address if they need to contact you about the connected app.
      • Enable OAuth Settings.
        • Add a callback URL such as: https://localhost:/<insert App Name here>/oauth/_callback. Note that if your app name has spaces in it, you should replace them with underscores in the url. Note that you’ll need this URL when requesting a refresh token.
        • Add the following OAuth Scopes:
          • Access and manage your data (api).
          • Perform requests on your behalf at any time (refresh_token, offline_access).
      • Finally click on save.
      • You are presented with an overview of your connected app. The client id and client secret values requested by ConnectPlaza are available under the names consumer key and consumer secret (click to reveal it), respectively.
  • Refresh Token - In order to get a refresh token, you’ll need to have completed the previous step of creating a connected app. There are several ways of obtaining a refresh token. Here are the instructions for obtaining a refresh token using Postman:
    • Open Postman.
    • Create a new request by clicking on the + New button (located in the top left part of the screen) and selecting
    • Go to the Authorization
    • Type should be set to OAuth 2.0.
    • Then press on the Get New Access Token
    • Now fill in the following information:
      • Token Name - Pick a suitable name.
      • Grant Type - Authorization Code
      • Callback URL - This should be the same callback URL you registered when creating the connected app in Salesforce.
      • Auth URL - https://login.salesforce.com/services/oauth2/authorize
      • Access Token URL - https://login.salesforce.com/services/oauth2/token
      • Client ID - The Client ID of the connected app.
      • Client Secret - The Client Secret of the connected app.
      • Scope - api refresh_token offline_access
      • State -
      • Client Authentication - Send client credentials in body
    • Press the Request Token button and login to Salesforce. Make sure you use the same account that is connected to your connected app.
    • Finally, you’ll be presented with a screen that contains - among other things - the refresh token.