- 03 May 2024
-
DarkLight
-
PDF
Integration Token Management
- Updated on 03 May 2024
-
DarkLight
-
PDF
Overview
Previously, Itential users would import an Integration Model into IAP and then add the token manually using the Configuration editor. This was inconvenient since tokens would expire relatively soon (as early as 30 minutes), and it created a less than desirable user experience since the expired token could no longer be used to authenticate automation requests.
The new Integration Token Management feature programmatically retrieves authentication tokens by using the properties provided by the Integration Model for schema integration. Specifically, the feature works by reading the securitySchema
property on the Integration Model schema.
There are two types of configurations available at this time: password
and clientCredentials
. These must be manually configured in the Integration Model that is imported.
⚠ Important Note: Although Itential designed this new feature to work for as many services as possible, it is important to note that not all services will be compatible with the password
or clientCredentials
configuration. It is incumbent upon every user to check the service to see if these configurations are provided. Itential hopes to provide more usable configurations in the future.
Property Configurations
This section illustrates how to set the properties for the password
and clientCredentials
configuration.
An example for password
is shown in Figure 1.
Figure 1: Password
An example for clientCredentials
is shown in Figure 2.
Figure 2: Client Credentials
Notice the only difference is the property name in the flows
object and in the case of Figure 1 there is a refreshUrl
parameter included in the password
flow.
Integration Configurations
Depending on which configuration is used, the user will see a specific configuration available on the Integration Details page. The user will then have to fill-in the authentication fields (see figures below) in order for the programmatic token retrieval to work properly.
For more detail on using Integrations in IAP, see the Configuring Integrations documentation page.
Authentication
Below are the configuration parameters used to support authentication.
Authentication Parameters | Description |
---|---|
client_id client_secret |
Provided by the service that is in use. User must retrieve it from the service. |
username password |
The account credentials to be used in the authentication. |
token_url refresh_url |
The endpoints that the service provides to retrieve authentication tokens. These fields will be populated upon creating the integration instance if the values are provided in the OpenAPI specification. |
Token
Below are fields that are included in the token
property of the integration configuration.
⚠ Editing these fields is not recommended, unless the user would like to manually enter an access_token
as it worked in previous versions of IAP.
Token Parameters | Description |
---|---|
access_token refresh_token |
Authorization tokens that are used with the integration tasks. The access_token will be retrieved programmatically if the field is empty or if the token is expired. If present with the refresh_url , the refresh_token will be utilized to retrieve a new access_token . |
token_type | Type of token to be utilized. The default value is set to Bearer . |
expires_in | Length of time that the access_token will be valid. |
expires_at | Time in which the token will expire. Upon calling an integration task, this value will be used to check if a new token should be retrieved. |
created_at | Time at which the access_token was created. |
scope | Scope that is provided by the token. |
In Figure 3, the clientCredentials
configuration is used to set authentication via the Integration UI.
Figure 3: Client Credentials Authentication
In Figure 4, the password
configuration is used in the Integration UI.
Figure 4: Password Authentication
Once all configurations are completed, the user should be able to utilize the Integration Tasks seamlessly without needing to continuously configure their Integration. Additionally, once the token is retrieved programmatically, it is then stored in the Mongo Database available in IAP.