Resource Types
The Resource Types node exposes your existing Resource Types and their corresponding Resource Type Parameters (think of the Resource Type as a container for the parameters required to connect to a particular service). Resource Types are usually system-specific and there may be several default Resource Types already installed in your environment. If your installation does not already contain a Resource Type for the service you want to connect to, you will need to create a new Resource Type.
On the Resource Types screen you can add, edit or delete Resource Types and their corresponding parameters. (Note that Resource Type Parameters will only display after selecting a Resource Type, since parameters are specific to a Resource Type.) Each OAuth system may have unique parameters within the OAuth protocol, and each parameter used for requesting and responding needs to be defined.
Follow these steps to add a Resource Type:
- Click New from the Resource Type view.
- Type values in the fields for the new Resource Type. Use the table below as a guideline.
Field Description Name Provide a unique name for the OAuth Resource Type. The Name is usually the name of the service you wish to connect to (e.g. SalesForce or LinkedIn) since the parameters are usually specific to that service Description Provide a description for the OAuth Resource Type. Extension Extensions are used to handle any scenarios that are not covered by the OAuth2 specification. SharePoint, for example, uses a Server to Server token in on-premises installations that is not part of the OAuth2 specification. Refresh Token Expiration Days Indicates the number of days before the refresh token will expire. This varies from Resource to Resource and may not be applicable if the system supports rolling refreshes.
Expiration Warning Days The number of days before the token expires to send the warning message to the administrator of the expiring token. Expiring Message The message to send to the administrator when the token is going to expire. Invalid Message The message to send to the administrator when the token has expired or has failed for another reason. Invalid Message Delay Minutes A time value (in minutes) to delay the Invalid Message that is sent to the administrator if the token is invalid. Usage Default value of Authorization. If a Resource is based upon a type that has a Usage='Validation', then a Metadata Endpoint value is required in the OAuth Resource. - Click OK. The new Resource Type will display in the Resource Types view.
Follow these steps to edit a Resource Type:
- Select a Resource Type and then click Edit from the Resource Type view.
- On the Edit OAuth Resource Type screen, edit the values in the fields that requires changing. Refer to the table in add for details on the configuration settings.
- Click OK to apply the changes. The Resource Type will be saved with the new values.
Follow these steps to delete a Resource Type:
- Select the Resource Type you want to delete by clicking on it and click Delete.
- Click OK to confirm that you want to delete the resource type.
The Refresh button allows the refreshing of the Resources Types list after changes have been applied and provides an updated list of Resource Types view.
Resource Type Parameters
Although OAuth2 is an industry-standard authorization framework, each OAuth2 implementation can vary slightly in regard to the parameters used during the token flows. For this reason, OAuth resource configurations between services will also vary. The first step of this process is to discover what parameters and parameter values are used by the external OAuth resource for authorization, token and refresh requests.
For example, the Azure Active Directory OAuth2 implementation uses an encrypted 'client_id' parameter for Authorization requests, Token requests and Refresh requests. It also uses the following parameters: grant_type, api_version, scope, client_secret, resource, entity_id, response_type and redirect_uri. All of these properties make up the external OAuth resource configuration.
Each of the parameters used in the external OAuth resource needs to be defined as a Resource Type Parameter within the OAuth Resource Type. These definitions are used when communicating with the external OAuth URI.
Follow these steps to add a Resource Type Parameter:
- Select the Resource Type you want to add new Parameters for, from the Resource Types view.
- Click New from the Resource Type Parameter view.
- Enter configuration values for the Resource Type Parameter. Use the table below for guidance.
- Click OK.
Field | Description |
---|---|
Resource Type | The Resource Type you wish to add a Parameter to. You can select another Resource Type from the drop-down. |
Parameter Name | The Parameter name. Enter the name of the required parameter (for example ‘client_name’) in the Parameter Name text box. The value you enter must match the name of the parameter as expected by the external service |
Parameter Description | A description for the Parameter. |
Url Encode | Select whether or not to URL encode the parameter value. |
Authorization Default Value | The default authorization value to be used. |
Token Default Value | The default token value to be used. |
Refresh Default Value | The default refresh value to be used. |
Authorization Request | Indicates that this parameter should be used during the authorization request. |
Authorization Response | Reserved for future use. |
Token Request | Indicates that this parameter should be used during the token request. |
Token Response | Reserved for future use. |
Refresh Request | Indicates that this parameter should be used during the refresh request. |
Store Encrypted Value | Indicates that this parameter should be encrypted. See Store Encrypted Value for more information about this feature. |
Follow these steps to edit Resource Type Parameters:
- Select the Resource Type Parameter and click Edit from the Resource Type Parameter list.
- Change the values for the fields that need to be modified on the Edit OAuth Resource Type Parameter page. See the section Adding a Resource Type Parameter for configuration guidance.
- Click OK to commit the changes.
Follow these steps to delete Resource Type Parameters:
- Select the Resource Type Parameter you want to delete by clicking on it and click Delete.
- Click OK to confirm that you want to delete the Resource Type Parameter.
The Refresh button will refresh the Resources Type Parameters list after changes have been applied.
Store Encrypted Value
Use the Store Encrypted Value option to encrypt sensitive information for OAuth resource type parameters such as a client_secret.
When you select this option, all values associated with this parameter are encrypted in the K2 database and masked (hidden) with dots in the user interface. When typing new values into the fields on the configuration screen, the values display in clear text, and when you save it, dots replace the values in all user interfaces. The encryption and masking of the values have no impact on using the OAuth resource. OAuth flows still use the values as before in an unencrypted way. The option only affects how it is stored in the database and how it is shown in user interfaces.
When the option is selected, it applies to the following values:
- OAuth resource type parameter default values - Authorization, token, and refresh default values.
- OAuth resource parameter values linked to the specific OAuth resource type parameter - Authorization, token, and refresh values.
- OAuth resource parameter token replacement values linked to the specific OAuth resource type parameter.
- Once you select the option and save the configuration, it cannot be reverted. This is to protect the sensitive information from any compromise. If you no longer want to store a particular parameter's value as encrypted, you must delete and recreate the parameter. This deletes the parameter from all linked resources, and you must re-enter the value for the new parameter.
- When using the Store Encrypted Value option, note that the following values have a limit of 3950 characters when encrypted:
- Authorization Default Value
- Token Default Value
- Refresh Default Value
See OAuth resources and the protection of sensitive information for information about how this feature affects your existing OAuth resource type parameters.