Connectors using OAuth require that the user goes through a webflow where they are sent to the third party application to sign in and grant access to Cyclr.
Sign in token
You’ll need to create an Account Sign-In Token for a User to access the account. The Token is only valid for a single use and will be active for 5 minutes, as indicated by the ExpiresAtUtc value in the response.
Request:
POST /v1.0/accounts/{Account ID}/signintoken
Content-Type: application/json
Authorization: Bearer 0000000000000000000000000000000000000000000000000000000000000000
{
"Username": "example_user"
}
Response:
{
"Token": "ABCD12340000000000000=",
"ExpiresAtUtc": "2017-12-08T11:02:48.7436471Z"
}
URL
The user should then be sent here in their browser:
https://{Partner Service Domain}/connectorauth/updateaccountconnectoroauth?id={Account Connector ID}&token={Account Sign-In Token}&targetOrigin=...
For example:
https://app-h.cyclr.com/connectorauth/updateaccountconnectoroauth?id=1234&token=ABCD12340000000000000=&targetOrigin=https://yourapplication.com/complete-page
Parameters
You need to URL encode all parameter values. You can include the following query string parameters:
| Parameter | Description | Example |
|---|---|---|
| token | The account sign-in token generated above | ABCD12340000000000000= |
| targetOrigin | Required. Either the origin of another browser window for the JavaScript callback event to be dispatched to, or a URL to redirect the user to. Used after the OAuth authentication is complete. | https://yourapplication.com/complete-page |
| callbackMessage | Callback message to be sent by JavaScript postMessage to the parent window. Don’t include if using a redirect for targetOrigin. |
done |
Cyclr redirects the user to the appropriate sign in page of the target application, captures the OAuth tokens generated by that app, and stores them internally. Token refresh is handled automatically when required later.
Callback
On completion, 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 allow you to create a single App which you can use with Cyclr to access all of your customer’s accounts. Some systems however, require the use of separate Apps for each customer. The correct setup should be described in each Connector’s Cyclr Connector Guide.
For systems that allow a single App for all customers, you should set the Client ID and Client Secret values of that App in your Cyclr Console’s 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 for each, add the following (using these exact names) as Account Connector Properties:
ClientIdClientSecret
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. It may also require Account Connector Properties and perhaps an AuthValue containing Access and Refresh Tokens and details. 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": "{}"