Credentials

Note: Permission to manage Credentials is needed to use the functionality described on this page. However, all users can use credentials when configuring modules in flows.

The Credentials library is a central repository for storing credentials needed by flow modules when accessing external services, for example username/password or API keys. Once a credential has been added to the library it can be selected in the module settings by referencing the name of the credential. In this way only the credential managers will ever see the actual data used, regular users will only access credentials by name referal. Credentials are stored encrypted in Crosser Cloud and are also delivered to and stored in the edge nodes encrypted. When configuring a module only credentials supported by that module will be available. A module can support multiple credential types.

The Credentials page lists all currently available credentials and their type. To add a new credential use the + Add Credential button on the Credentials page or use the New button next to the credential selector in the settings UI on modules that use credentials. In the form that is opened, start by giving the credential a name. This is the name shown to users when configuring a module, so you should preferably use a name that helps the users to select the apropriate credential. Then select a type and enter the actual credential settings, see Credential types below for information on supported types. There is also a description field that can be used to enter any relevant information about the credential, eg expiration times, endpoints supported and so on. The description can be seen by expanding the row for a credential in the table on the Credentials page.

Credential types

The following credential types are currently supported:

• API Key - Used for HTTP Bearer authentication. Just enter the key here, the authorization header and the Bearer keyword is added by the modules when using this credential
• AWS Credential - Credential for access to AWS services using access keys. Enter Access key, Secret access key and Region. The region is specified using the short-form format found here, in the Region column.
• Azure access key - Credentials for accessing Azure services using an access key.
• Azure Device credential - Credential for devices connecting to the IoT hub or IoT edge. Provide the Device ID and Device Key
• Azure Shared Access Signature - Credentials for accessing Azure services using a shared access signature. These must be generated in the Azure portal or using the Azure CLI. If using the portal, copy the SAS token but without the initial question mark (it is provided as a query parameter).
• Certificate - Upload a certificate file either from local storage or by copying the data into the editor window. Provide a password to use with the certificate.
• Connection string - Credentials for services using a connection string.
• Data - This type allows you to upload any type of credentials data, either as a file from local storage or by entering data in the editor. Crosser Cloud will not try to interpret the data and it is provided as is to the modules. It is then up to each module to use this information apropriately. Can for example be used with custom modules that uses an authentication method not covered by any of the other types.
• OAuth Authorization code grant - Provide: ClientID, ClientSecret, Refresh token, and Token renewal URL, Scope is optional. See example below how to get these.
• OAuth Client credential grant - Provide: ClientID, ClientSecret and Authorization URL. Token renewal URL and Scope are optional
• Username and Password - Credentials for services using username and password authentication. Also used for HTTP Basic authentication.

OAuth Code Grant example (device flow) - Connecting to SalesForce

This is a step by step guide to setting up OAuth credentials with your SalesForce account, using the Device flow variant. Salesforce supports multiple variants of OAuth authentication and you can also use the Web server variant, see the Google example below. Other services will be different but the concepts should be similar. You need a SalesForce account that includes the “Web services API” product and API access must be explicitly enabled, see the SalesForce documentation on how to do this.

To start, go to the Credentials page and click on + Add Credential. In the dropdown, select OAuth Authorization Code Grant. You should then see the following screen:

1. The first thing you need are the ClientID and ClientSecret settings. This typically requires setting up an ‘App’ on the service you want to connect to. In the SalesForce case this is done in the App Manager where you use New Connected App.
2. In the new window you should make the followig settings (only settings that are important for the OAuth setup are covered here, there are other required settings that need to be set as well):
   • Check Enable OAuth Settings
   • Check Enable for device flow
   • Set the callback URL to https://login.salesforce.com/services/oauth2/callback
   • Add the following scopes to the list of Selected OAuth scopes:
     • Full access (full)
     • Access and manage your data (api)
     • Perform requests on your behalf at any time (refresh_token, offline_access)
   • Save the app
3. Your app should now show up in the list of apps. In the table, to the far right, click the arrow and select View
   • From the page that shows the settings for you new app: copy the Consumer Key into the Client ID field in Crosser and the Consumer Secret into the Client Secret field.
   • Add the following URL in the Token renewal URL field in Crosser: https://login.salesforce.com/services/oauth2/token (this URL can be found in SalesForce API documentation)
4. Now comes the tricky part, we need to get hold of a refresh token. This requires making some calls against the SalesForce API. Fortunatley there are tools in the credentials wizard to help you with this.
   • Click on the + button to the right of the Request header. This will open up a request editor that allows you to make HTTP requests. It supports template syntax to include the settings you entered above in these calls and also to use the response from a previous request in the next request. In this case we will have to make two requests.
   • In the Edit request window enter the information shown in the picture (this information is taken from the SalesForce API specification). Note how you can refernce settings you have already entered using {} syntax ({clientId} in this case).

• Click on the Execute button. You should get a 200 OK response. Then you can watch the result on the Response tab.
• Copy the string found after user_code in the response
• In a web browser open: https://login.salesforce.com/setup/connect and enter the code you copied above and then click Allow when asked.
• Close this editor and add a new request (+) and enter the settings shown below. Notice how you can reference data in the response to the previous request ({device_code}).

• In the response to the second request you will get the refresh_token we will need. Add this to the settings using template syntax, as shown in the picture.

1. At this point the credential is ready and you can test it with the Test Credential button. Make sure you get a 200 OK response.
2. Save the credential using Add Credential
3. Your new credential is now ready to be used in any Universal Connector you build.

As you can see from the above example setting up OAuth credentials can be quite challenging and typically requires studying the API documentation of the service you want to connect to.

OAuth Code Grant example - Google

The following example shows how you can create credentials for accessing Google services, such as Docs, Drive and Gmail, using the Web server variant. To get the right credential you need to give user consent by following the steps below. You can skip steps 1-3 if you’ve already completed them for another Google module in Crosser.

Prerequisites

• Google Workspace
• Access to the Google API Console for your organisation
• Access to a Google Account within your Google Workspace organisation

1. If you don’t already have one, create a project in the Google API Console and enable the APIs you want to use, e.g. the Gmail API for emails or the Drive API for working with documents.
2. Create an OAuth Client ID from the Credentials page. Choose Application type: “Web application” and add https://cloud.crosser.io as an Authorized redirect URI. Press Create.
3. Save the Client ID and Client Secret in a safe location.
4. Open this URL in the browser, but fill in the Client ID you just saved and the access rights you want to enable in the scope, e.g. gmail.readonly for reading emails or drive to access documents: https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=https://cloud.crosser.io&response_type=code&access_type=offline&scope=https://www.googleapis.com/auth/[YOUR_ACCESS].
   You can add multiple access rights by combining full scope URLs with “+”.
5. Sign in to your Google Workspace account on the landing page opened above and grant Crosser the permissions you have specified.
6. When you are redirected to cloud.crosser.io, copy the code parameter from the URL and save it in a safe location.

By the end of step 6, you should have a Client ID, Client Secret and Code saved in a safe location.

Create Credential in Crosser Cloud

1. Create a new credential in the Crosser Cloud Platform. Select type: OAuth Authorization Code Grant.
2. Enter {refresh_token} as the Refresh Token.
3. Enter your Client ID and Client Secret.
4. Enter https://oauth2.googleapis.com/token as the Token Renewal URL and the same scope that you used above e.g. https://www.googleapis.com/auth/drive.
5. Create a request by clicking on the “+” sign above the settings. In the URL field, enter: https://oauth2.googleapis.com/token
6. Choose Action POST.
7. Choose Content-Type: application/x-www-form-urlencoded.
8. In the Body, paste the following and provide the code you saved above: code=[YOUR_CODE]&client_id={clientId}&client_secret={clientSecret}&redirect_uri=https://cloud.crosser.io&grant_type=authorization_code
9. Click on Execute to run your request and make sure you get a status of 200.
10. Exit the request popup.
11. Press Test Credentials and make sure you get a status 200.
12. Press Add Credential