Merge pull request #464 from OpenFn/oauth-creds

Add documentation for Oauth credentials

adaptors/salesforce.md

@@ -146,15 +146,33 @@ values (e.g., `M: male, F: female`).
 semicolon-separated strings (e.g.,
 `Services__c: 'Food;Counselling;Medical_Aid`).
 
-
 ### Salesforce Credentials
 
-Salesforce requires a username, password, login URL, and security token to
-authenticate via a user. **Note every time you reset the user's password, the
-security token will reset and you need to update the Credential record used in
-your OpenFn job.**
+Users have two options to connect to Salesforce, via **Oauth2** and via a
+**security token**. We recommend connecting via Oauth2. If this option isn't
+available on your OpenFn instance, reach out to the superuser who deployed it
+and ask them to configure a Salesforce Oauth2 client.
+
+For better auditability and securiy, we recommend creating a dedicated "openfn"
+integration user (rather than using your personal user). Salesforce provides an
+API-only user license.
+[See Salesforce documentation](https://help.salesforce.com/s/articleView?id=sf.integration_user.htm&type=5)
+to learn how to configure this. API-only users require an Oauth credential.
+
+#### Oauth2
+
+When connecting via Oauth2, choose only the scopes you require.
+([See Salesforce](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_tokens_scopes.htm&type=5)
+for explanations of these options.)
+
+![Salesforce Oauth2](/img/salesforce-oauth2.png)
 
-![Credentials Menu](/img/credentials.png)
+#### Security Token
+
+If you are not using Oauth2, you'll need to provide a username, password, login
+URL, and security token to authenticate via a user. **Note every time you reset
+the user's password, the security token will reset and you need to update the
+Credential record used in your OpenFn job.**
 
 A "Salesforce" Credential record should include:
 
@@ -167,7 +185,7 @@ A "Salesforce" Credential record should include:
   you have a custom domain `https://domainName.salesforce.com/`). For sandbox
   environments, `https://test.salesforce.com/`.
 
-![Salesforce Cred](/img/salesforce-cred.png)
+![Salesforce Cred](/img/salesforce-old-cred.png)
 
 For use in the CLI, see an example
 [salesforce configuration](/adaptors/packages/salesforce-configuration-schema)
@@ -209,15 +227,12 @@ Please save this `security token` in your OpenFn `Credential`.
    occur when trying to update a Relationship field, for example a Person
    related to a Person's Visit. The field setting `Allow reparenting` on the
    Master-Detail relationship field may need to be turned on .
-9. `UNABLE_TO_LOCK_ROW: unable to obtain exclusive access to this record`: This error occurs when either 1) the OpenFn job tries to update the same record more than once at the same time or 2) the OpenFn job tries to updates a Salesforce record at the same time as someone else in the Salesforce system (this includes any automation that may be running in parallel to the OpenFn jobs).  
-
-
-## OpenFn Adaptors
-
-OpenFn has a robust
-[`language-salesforce`](https://github.com/OpenFn/language-salesforce) adaptor
-with a range of helper functions for common CRUD & upsert operations, and for
-accessing the Salesforce bulk API.
+9. `UNABLE_TO_LOCK_ROW: unable to obtain exclusive access to this record`: This
+   error occurs when either 1) the OpenFn job tries to update the same record
+   more than once at the same time or 2) the OpenFn job tries to updates a
+   Salesforce record at the same time as someone else in the Salesforce system
+   (this includes any automation that may be running in parallel to the OpenFn
+   jobs).
 
 ## Example Implementations
 

docs/build/credentials.md

@@ -4,9 +4,9 @@ title: Credentials
 
 ## Credentials
 
-Credentials are used to authorize connections to destination systems. In the
-future, our Adaptors will use credentials to fetch meta-data from source and
-destination applications and make the job writing process easier.
+Credentials are used to authorize connections to external systems. Some Adaptors
+will use credentials to fetch meta-data from source and destination applications
+and make the job writing process easier.
 
 Credentials can only be viewed, or edited by a single user — their "owner" (or
 the person that created that credential). All the collaborators on a particular
@@ -30,8 +30,100 @@ authenticate with your app (e.g., `username`, `api_key`).
 If your app is not listed in the Adaptors section, then inspect your app's API
 documentation to see what is required for "authentication". You can then create
 a `Raw JSON` Credential in OpenFn to define whatever credential inputs are
-require (e.g., `{"api_key": "ADD-your-let", "url": "add-url"}`).
+required. E.g.:
 
-Some systems (Salesforce, OpenMRS, DHIS2) require an instanceUrl, host, or
-ApiUrl. Leave off the final "/" in these Urls: `https://login.salesforce.com` or
-`http://demo.openmrs.org/openmrs` or `https://play.dhis2.org`.
+```json
+{
+  "apiKey": "someSecretKey",
+  "baseUrl": "https://example.com/api/v2"
+}
+```
+
+Note that some systems (Salesforce, OpenMRS, DHIS2) require an instanceUrl,
+host, or ApiUrl. While most adaptors will handle a "trailing slash" in a URL
+gracefully, when in doubt you should leave it off. For example:
+
+- prefer `https://login.salesforce.com` to `https://login.salesforce.com/`,
+- use `http://demo.openmrs.org/openmrs` instead of
+  `http://demo.openmrs.org/openmrs/`,
+- and write `https://play.dhis2.org` rather than `https://play.dhis2.org/`.
+
+### Use OAuth2 credentials
+
+If OAuth2 _clients_ have been configured on your OpenFn instance, you can use
+them create OAuth credentials. These all work the same way:
+
+1. First you pick an OAuth credential type from the "New Credential" interface.
+2. Then you give it a name.
+3. You optionally select additional "scopes" that you want to use. (See the
+   in-app link to third-party documentation on scopes, depending on what
+   application you're using.)
+4. And then click "Sign in with \_\_\_\_\_\_".
+
+You will be asked by the third-party application to verify your identity and
+that you'd like to use OAuth. Once you accept, back on OpenFn you'll be able to
+save and use your new credential just like any other.
+
+:::tip
+
+If you're using a deployed instance of OpenFn and can't find the OAuth
+credential type for your app, please contact the superuser responsible for your
+instance setup and request them to set up OAuth clients for your application.
+Users of the hosted OpenFn platform SaaS can post on
+[community.openfn.org](https://community.openfn.org) or send an email to
+[[email protected]](mailto://[email protected]).
+
+:::
+
+#### e.g., GoogleSheets OAuth Credential
+
+Note the credential selects only required scopes for Google Sheets.
+
+![Google OAuth](/img/google-oauth2.png)
+
+#### e.g., Salesforce OAuth Credential
+
+Note that you can choose which scopes to access on Salesforce.
+
+![Salseforce OAuth](/img/salesforce-oauth2.png)
+
+:::tip
+
+Check out the dedicated [Adaptor docs](/adaptors) page for app-specific
+credential guidance.
+
+:::
+
+### Creating a dedicated "integration user" for your OpenFn workflow
+
+To keep target systems as secure and controlled as possible, we recommend that
+credentials used in the integration be granted API-only access to the target
+application. 
+
+You _can_ use your personal user as an OpenFn credential for your
+workflow, but we recommend that you create a dedicated "OpenFn" integration user
+or service account user to access your target applications. For example, in
+Salesforce, you can create an API-only user with a special API-only license type
+to perform automated tasks and integrations without requiring full user access.
+
+API-only users might not be available in every target system, but many do offer the
+creation of user roles that have API-only access permissions, and may allow you
+to determine the scopes for which APIs or endpoints users can access.
+
+API-only access minimizes risk of data breach. This helps with:
+
+- **Traceability**: Accessing with an integration user provides an audit trail
+  of who logged in when and what changes were made. For example, if you used
+  your personal user login for a system in an integration implementation, it
+  would be hard to know if it was YOU, a human, who made a change vs. an
+  automated system action via the API user.
+
+- **Minimizing breach impact**: The user can be deactivated if user is
+  compromised, and no one can log in through the frontend with API credential if
+  it’s breached.
+
+- **Ensuring the principle of least privilege**: Each integration user need only
+  have access to the subset of data supporting its specific use case.
+
+Check out the docs on
+[Security Best Practices](/documentation/get-started/security) to learn more.