Authentication
Set up the different ways Middle users can authenticate an app
Last updated
Set up the different ways Middle users can authenticate an app
Last updated
An auth configuration is a definition of required authentication information that your app needs to authenticate with the system you’re integrating with. Put simply: it is a form that you create and then others can fill it out with the needed information.
Most APIs require some kind of authentication/authorization string, usually passed under the Authorization HTTP header. You can define these parameters within the authentication configuration, as well as any additional inputs your app may need. You will want to determine the authentication needed for the system you’re integrating with. This is often determined by the authorization guidelines provided by the source system’s API.
The information captured by the Auth Configuration form will be accessible to you via the auth dictionary in the Python scripts you write.
Middle handles three types of authentication forms:
To create an authentication configuration, click + Create next to Auth Configs. You are able to define your authentication configuration and determine whether it’s Active or Inactive.
Only one configuration may be active at once for its App Version.
You can also provide help text for the User who is setting up the account connection, such as instructions on how to access the credentials they need.
This authentication is best suited for non-OAuth authentications where the system you are integrating with requires an individual username/password, business ID, key, or a predetermined token for each connection. Data provided in the custom fields form are referencable via app script when Middle performs syncs and actions. There are several types of inputs you can set up: text areas, one-line inputs, protected one-line inputs (good for sensitive information), and boolean switches.
To set up this type of authentication, you will create Field Inputs that can be completed by the user setting up the authentication. These values will be then stored in the auth dictionary for later reference when scripting.
To create a new field, click Add Form Field.
You will then configure a field’s settings:
Type:
text areas (good for multiple lines)
one-line inputs/protected one-line inputs (good for sensitive information)
boolean switches
Field Name: the name or key to be used when scripting.
Display Name: the name that is displayed to the user.
Help Text: Any information that is useful to the user for completing this form field.
Required: A boolean that determines whether this field can be left blank or if it's required.
Here’s an example of a simple username and password that could be inputted through Form Fields.
You may continue to add form fields as needed by clicking Add Form Field and finally hit Save once you are complete.
Information provided through Form Fields is retained in the Account Connection once it is set up. Please note that anyone with access to this Account will be able to see the values provided in these forms. If you have concerns about sensitive fields, please consider storing them using the Password Grant Flow.
Middle supports both password grant and auth code OAuth Flows.
The password grant flow is made to support the OAuth2.0 Password Grant flow of the same name. Password Grant allows you to customize a secure password form for the user to fill out. The password is stored temporarily for use in a token exchange which your Python code will execute.
OAuth flows will need to use your OAuth app, a partner's app, or a customer's app registered with the web application being integrated to facilitate authentication.
To set up an OAuth configuration:
Select the appropriate OAuth flow type from the Auth Config Type drop-down.
Set the toggle to Active and provide a name.
Provide Basic Configuration help text (ex: where can a user find the necessary field inputs)
(Optional) Add Form Fields (ex: business ID, location IDs they are authenticating for, or the site name they will connect with. See example below)
OAuth flows may require sensitive client credentials. We suggest using the API Keys feature to store sensitive information that only the app developer should know over Form Fields.
Hit Save and refresh the page in order to generate the scripts for the next steps.
A Password Grant flow is used when you would like to exchange credentials for a token or to securely submit credentials and not store sensitive credentials like username/password.
Follow the below steps to set up a password grant flow.
Unlike the form fields above, these values will not be stored. They'll persist long enough to invoke the function you've defined in Step Two, and then be deleted. Be sure to hit Save after this step.
For most cases, you will write the script to exchange these credentials for an access token. Any values returned from invoking this script can be stored with the Auth dictionary for later access, such as access tokens, refresh tokens, password form fields, etc. Hit Save to save the script.
Auth Code OAuth Flow is used for integrations that require using a user’s login to exchange for an access token.
Follow the below instructions to setup an OAuth flow.
You will write a script that will direct the user to the URL where they need to authenticate, and request the API scopes (ability to access certain data points) that are needed for the integration. You will also need to provide a valid redirect URL for this Middle instance. Remember to hit Save to save the script.
If this authentication step is completed successfully, it will return an auth code to be used for Step Two.
You will write the script to exchange this auth code for an access token. Middle will invoke this script after a user is redirected back to Middle. Any values returned from invoking this script can be stored with the auth dictionary for later access, such as access tokens, refresh tokens, etc. Remember to hit Save to save the script.