OpenAPI 3.1 Authentication Authorization

Updated on 11 Feb 2025

Dark

Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

OAUTH2 and OIDC

Support has been added for custom parameters for integrations in Platform 6 by including an OpenAPI specification extension via x-itential-parameters. Specifically for this feature, support was added for OAUTH2 and OIDC authorization requests, which include token and refresh requests.

 See OpenAPI Extensions for more information on specification extensions.

Example

An imported integration model with x-itential-parameters is presented below as an example. The x-itential-parameters are defined in the securitySchemes object of the imported integration model.

{
    "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"
                        ]
                    }, 
                    {
                        "name" : "nice_one",
                        "in" : "query",
                        "description" : "test body",
                        "x-itential-use-in" : [ 
                            "refresh"
                        ],
                        "x-itential-variable" : "niceOne"
                    }, 
                    {
                        "name" : "asdf_cool",
                        "in" : "header",
                        "description" : "test body",
                        "x-itential-use-in" : [ 
                            "refresh", 
                            "token"
                        ]
                    }
                ]
            }
        }
    },
    "versionId" : "ServiceNow Product Order API:1.0.0"
}

In the code example, four (4) custom parameters were used in the oauth2 request. In this case:

The x-itential-variable properties are not specific to the security scheme (i.e., not specific to oauth2).
The x-itential-use-in property defines the specific requests the parameter is used in.
The client_assertion header is set to be the clientAssertion variable defined in the integration and used in both token and refresh requests.
If x-itential-variable is not defined on a parameter, the value used in the request is set under "parameters" in the integration and is specific to the security scheme.

For additional detail on OpenAPI specification extensions and how they are used by Itential, see the next section of this article.

The image presented below depicts the custom configuration parameters for the example Integration Model (example) shown above.

Figure 4: Integration Custom URI Parameters
Custom Parameters

Itential Specification Extensions

This section will explain Itential’s custom OpenAPI specification extensions and how they impact API interactions.

Extension	Type	Description
`x-itential-variable`	string	• Used in Parameter Objects and allows users to define variables that will be captured in the Service Configuration properties per instance of an Integration and is not optional. • The value of this field is the variable name, which is also a unique identifier. This means that if the same variable name is used in multiple different places, then it will generate only one variable, whose given runtime value will be used more than once.
`x-itential-parameters`	parameter-object[]	• The Open API specification has a model for parameters, which are parts of an API request like headers, query parameters, path parameters, and cookies. The only places where these can be defined are in the: Components Object, Path Item Object, and Operation Object. The `Operation Object` is the root of the OpenAPI document and where the parameters would apply to all APIs modeled in the document. Another location is inside the Security Scheme Object, where additional parameters may be needed for Authorization. • The Parameter Objects in the array are near identical to the OpenAPI Specification definition of a Parameter Object. The only difference is that the parameters in a Security Scheme Object are allowed to use the additional value of `"body"` for the `"in"` field, when the security request will have an `x-www-form-urlencoded` request body (ex. OAuth 2.0 grant flows). • When defined at the root level, the parameters are applicable for all the operations described in the Open API Model. These parameters can be overridden at the Path Item Object and Operation Object levels, but cannot be removed. The list MUST NOT include duplicated 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 that are defined by the components-parameters that comprise the OpenAPI Specification Object.
`x-itential-use-in`	string[]	• In most places where parameters are defined, the definition of a request is individual. When additional parameters are defined during OAuth 2.0 grant flows, the model applies to multiple requests. The best example of this is the Authorization Code Grant Flow, which can have an authorization request (`authorizationUrl`), access token request (`tokenUrl`), and refresh token request (`refreshUrl`). If using the security scheme type `openIdConnect`, there can also be an `openIdConnectUrl`. • Values in the string will be any of the following: `"authorization"`, `"token"`, `"refresh"`, `"openIdConnect"`.

OpenAPI 3.1 Authentication Authorization

OAUTH2 and OIDC

Example

Itential Specification Extensions

Further Reading

What's Next