OAUTH2 and OIDC
Platform 6 supports custom parameters for integrations through the x-itential-parameters OpenAPI specification extension. This feature enables custom parameters for OAUTH2 and OIDC authorization requests, including token and refresh requests.
Related Reading:
Example
The following example shows an imported integration model with x-itential-parameters defined in the securitySchemes object:
{
"openapi": "3.0.0",
"info": {
"title": "ServiceNow Product Order API",
"description": "API for managing product orders in ServiceNow",
"version": "1.0.0"
},
"servers": [
{
"url": "https://example.service-now.com"
}
],
"paths": {},
"security": [
{
"oauth2": []
}
],
"components": {
"schemas": {
"ProductOrder": {
"type": "object",
"properties": {
"orderId": {
"type": "string",
"description": "ID of the product order"
}
}
}
},
"securitySchemes": {
"oauth2": {
"type": "oauth2",
"flows": {
"clientCredentials": {
"tokenUrl": "",
"refreshUrl": "",
"scopes": {}
}
},
"x-itential-parameters": [
{
"name": "client_assertion",
"in": "header",
"description": "assertion header",
"x-itential-use-in": [
"refresh",
"token"
],
"x-itential-variable": "clientAssertion"
},
{
"name": "other_test",
"in": "body",
"description": "test body",
"x-itential-use-in": [
"refresh",
"token"
],
"schema": {
"type": "string"
}
},
{
"name": "nice_one",
"in": "query",
"description": "test body",
"x-itential-use-in": [
"refresh"
],
"x-itential-variable": "niceOne",
"schema": {
"type": "number"
}
},
{
"name": "asdf_cool",
"in": "header",
"description": "test body",
"x-itential-use-in": [
"refresh",
"token"
]
}
]
}
}
}
}
In this example, the oauth2 request uses four custom parameters:
- The
x-itential-variableproperties are not specific to the security scheme (not specific tooauth2). - The
x-itential-use-inproperty defines which requests use the parameter. - The
client_assertionheader maps to theclientAssertionvariable defined in the integration and applies to both token and refresh requests. - When
x-itential-variableis not defined on a parameter, the request uses the value set under "parameters" in the integration, specific to the security scheme.
For additional detail on OpenAPI specification extensions and how Itential uses them, see the next section.
The following image shows the custom configuration parameters for the example Integration Model:
Figure 4: Integration Custom URI Parameters
Itential Specification Extensions
This section explains Itential's custom OpenAPI specification extensions and their impact on API interactions.
| Extension | Type | Description |
|---|---|---|
x-itential-variable |
string | • Use in Parameter Objects to define variables that are captured in the Service Configuration properties per instance of an Integration. This field is not optional. • The value of this field is the variable name, which also serves as a unique identifier. Using the same variable name in multiple places generates only one variable, and its runtime value applies to all instances. |
x-itential-parameters |
parameter-object[] | • The OpenAPI specification defines a model for parameters, which are parts of an API request such as headers, query parameters, path parameters, and cookies. You can define these parameters in the Components Object, Path Item Object, and Operation Object. The Operation Object is the root of the OpenAPI document, where parameters apply to all APIs modeled in the document. You can also define parameters in the Security Scheme Object, where additional parameters may be needed for Authorization.• The Parameter Objects in the array are nearly identical to the OpenAPI Specification definition of a Parameter Object. The only difference is that parameters in a Security Scheme Object can use the additional value of "body" for the "in" field when the security request has an x-www-form-urlencoded request body (for example, OAuth 2.0 grant flows).• When you define parameters at the root level, they apply to all operations described in the OpenAPI Model. You can override these parameters at the Path Item Object and Operation Object levels, but you cannot remove them. The list must not include duplicate parameters. A unique parameter is defined by a combination of a name and location. The list can use the Reference Object to link to parameters defined by the components-parameters that comprise the OpenAPI Specification Object. • Each parameter must provide either a schema or content property. In most cases, use schema and specify the data type of the variable as type. In rare cases, you might need content. For more information, see Describing Parameters in the OpenAPI 3.0 documentation. If you don't provide schema or content, the system uses a default schema with type: string. |
x-itential-use-in |
string[] | • In most places where you define parameters, the definition applies to an individual request. When you define additional parameters during OAuth 2.0 grant flows, the model applies to multiple requests. For example, the Authorization Code Grant Flow can have an authorization request (authorizationUrl), access token request (tokenUrl), and refresh token request (refreshUrl). If you use the security scheme type openIdConnect, there can also be an openIdConnectUrl.• Valid values are: "authorization", "token", "refresh", "openIdConnect". |