View Categories

OAuth Authentication

6 min read

For Connectors that authenticate with a third party API using OAuth.

May require the user to go through an authentication flow where they are sent to the third party application to sign in and grant access to Cyclr.

As part of this flow, Cyclr will obtain OAuth tokens to access that application which it stores on the Account Connector, and handles token refreshing automatically later when required.

If the user doesn’t have access to their Cyclr account to do this themselves, you can use the steps explained here to have them authenticate the Account Connector

Summary #

  1. Make a Cyclr API call to the /v1.0/accounts/{id}/signintoken endpoint to retrieve a one-time Cyclr Account Sign-in Token.
  2. Build a URL to direct your user to in their web browser.
  3. Redirect your user to that URL.

Note: This process is expected to be run at the server-side of your own web application so that the user is immediately redirected to the authentication URL in their web browser.

The Sign in Token generated here expires after 5 minutes and can only be used once.

If you wish to email your user to have them authenticate a Connector, you can instead use a Connector Authentication Link which also allows you to set an expiry on the link.

Account Sign-in Token #

You’ll need to obtain an Account Sign-In Token for a User to access the account where the Account Connector is located.

The Token is only valid for a single use and expires after 5 minutes as indicated by the ExpiresAtUtc value in the API call’s Response.

If the value used for Username doesn’t match an existing User, a new one will be created.

Example Request #

POST https://{CyclrAPIDomain}/v1.0/accounts/{AccountId}/signintoken
Authorization: Bearer {access_token}
Content-Type: application/json

{
    "Username": "example_user"
}

Example Response #

{
    "Token": "ABCD12340000000000000=",
    "ExpiresAtUtc": "2022-12-08T11:02:48.7436471Z"
}

Build the URL to Redirect to #

You then build a URL using the Account Sign-in Token obtained above and redirect your user to it in their web browser.

That will take them on to the third party’s OAuth flow, for example Salesforce’s sign in and consent page if it’s a Salesforce Account Connector that’s being authenticated.

Once the user has moved through the third party’s OAuth flow and provided their consent, one of these 2 actions will be performed:

  1. Cyclr will redirect the user to a URL you provided.
  2. Cyclr will use a JavaScript postMessage call to notify your web application the process has been completed.

Note: If the Cyclr Connector requires additional values set on it before it’s able to be used, you’ll need to handle those by perhaps calling one or more of the Connector’s “Triggers” through the Cyclr API to obtain options which you can display in your own system for the user to select from.

Having chosen an option, you can then make a further Cyclr API call to set that value on the relevant Account Connector Property.

The URL #

The Cyclr URL you build to begin the OAuth flow is in this format:

https://{Cyclr Partner Service Domain}/connectorauth/updateaccountconnectoroauth?id={Account Connector ID}&token={Account Sign-In Token}&targetOrigin=...

Example:

https://app-h.cyclr.com/connectorauth/updateaccountconnectoroauth?id=1234&token=ABCD12340000000000000=&targetOrigin=https%3A%2F%2Fyourapplication.com%2Fcomplete-page

Parameters #

The following query string parameters are available and should be URL encoded:

ParameterDescriptionExample
idRequired
ID of the Account Connector to be authenticated.		1234
tokenRequired
The account sign-in token generated for the user.		ABCD12340000000000000=
targetOriginRequired
Either:a URL to redirect the user to in their web browser upon completion, orthe origin of another web browser window for a JavaScript postMessage call to be made to with the value specified in the callbackMessage parameter.Used after the OAuth authentication is complete.		https://yourapplication.com/complete-page
callbackMessageOptional
If this parameter is provided, it prevents redirection to the URL provided in targetOrigin and Cyclr instead makes a JavaScript postMessage call to another web browser with callbackMessage as the value of the message.		completed

Callback #

On completion of the OAuth flow, the user will either be redirected to the targetOrigin if callbackMessage was left blank, or the JavaScript message specified by the callbackMessage will be posted to the parent window to notify the host app that the authentication flow has completed. You can then take appropriate action in your system.

To handle the callbackMessage, your system’s webpage should use window.addEventListener() to listen for messages which Cyclr will send using window.postMessage(). More information on using this methodology can be found on the Mozilla Developer Network’s Web Docs.

Providing Client ID and Client Secret Values #

Typically, systems using OAuth to authenticate with their API allow you to create a single App which you can use with Cyclr to access the accounts of your customers. Some systems however, require the use of separate Apps for each of your customers. The correct setup should be described in each Connector’s Cyclr Connector Guide.

For systems that allow a single App for all of your customers, you should set the Client ID and Client Secret values of your App in your Cyclr Console’s “Connectors > Application Connector Library” entry.

For Connectors that require the Client ID and Client Secret values to be provided separately for each Account Connector, or if you have chosen to provide them separately for each, add the following (using these exact names) as Account Connector Properties:

  • ClientId
  • ClientSecret

Providing Complete Authentication for the Connector #

If your own Cyclr Partner Connector (a Connector that works against your own system’s API) uses OAuth, you’ll perhaps wish to provide all the authentication details yourself, rather than involve the user. This can be done through a LAUNCH or Marketplace call using the PartnerConnector property, or by a separate Cyclr API call.

To do this you must provide all the values the Connector requires to work with the API.

That may simply be by providing ClientId and ClientSecret as mentioned above or it may also require Account Connector Properties and perhaps an AuthValue containing Access and Refresh Tokens. See below for more details on the AuthValue.

AuthValue Property #

Depending on how an API authenticates, you can provide a JSON object containing the Access and Refresh Token details as follows:

{
	"AccessToken": "XXXXXXXXXX",
	"RefreshToken": "XXXXXXXXXX",
	"Expires": "2021-10-01T00:00:00Z",
	"RefreshExpires": "2022-10-01T00:00:00Z"
}

That JSON object should then be serialized – e.g. by using the standard Javascript JSON.stringify() function – then used as the AuthValue property of an Account Connector.

That would look like this in an API call:

"AuthValue": "{\"AccessToken\":\"XXXXXXXXXX\",\"RefreshToken\":\"XXXXXXXXXX\",\"Expires\":\"2021-10-01T00:00:00Z\",\"RefreshExpires\":\"2022-10-01T00:00:00Z\"}"

Or, if other details have been provided that will enable Cyclr to obtain those details itself, you can simply set it as an empty JSON object and the next time Cyclr attempts to call a Method on the Connector, it will automatically attempt to authenticate and retrieve this information:

"AuthValue": "{}"