POST OAuth/SetConfiguration

Sets and updates the global OAuth configuration parameters.

SetConfiguration must express the complete configuration as desired. All fields in the structure will be stored when the request is received. If they are not set in the request, they will be defaulted.

A best practice is to get the current configuration using GetConfiguration, modify that response as desired, and then pass the entire structure into the SetConfiguration request.

Requirements

Roles: Admin
Token scope: Admin

Headers

Content type: Content-Type:application/json.
Token: The bearer access token that you received. For example, Authorization:Bearer 4MyGeneratedBearerTknz==. For more information, see Passing a bearer token in your API calls.

Parameters

Name	Description
Configuration object	(Required) An object that contains configuration information for remote access. The following values can be passed in this object. All values are optional. AuthorizeByIntegrated (boolean): Sets whether the authentication server accepts Windows Integrated Authentication. AuthorizeByPassword (boolean): Sets whether the authentication server accepts username/password as authentication credentials. AuthorizeByCertificate (boolean): Sets whether the authentication server accepts certificates as authentication credentials. AuthorizeByJwt (boolean): Sets whether the authentication server accepts JWT authentication. AuthorizeDevice (boolean): Sets whether the authentication server accepts device authentication requests. CertificateConfiguration (object): If object is present, certificate authentication is enabled, which allows the caller to pass a client certificate for authorization. The following values are valid: AuthorizedIssuerDns (array of strings): Policy Tree path to the authorized certificate authority object. When present, only certificates from this CA are valid for authentication. SourceField (string): Specifies which field on the X.509 certificate to use for matching the user identity. There are three valid values: `SAN:UPN`, `SAN:EMAIL`, or `CN`. DefaultAccessTokenValidity (integer): Sets the default number of seconds a token is valid. This can be overridden by an application. DefaultGrantRefreshable (boolean): Sets if, by default, the grant can be refreshed programmatically. DefaultGrantValidity (integer): Sets the default number of seconds a grant is valid. This can be overridden by an application. DeviceConfiguration (object): Sets device authorization specific settings. The following values are valid: VerificationUri (string): Sets the Uri to verify (confirm) a device authorization request. VerificationUriCompleteFormat (string): Sets the Uri to verify (confirm) a device authorization request, with a `{0}` placeholder to hold the unique request ID. OpenApiEnabled (boolean): Sets whether the OpenAPI documentation is accessible. If set to `true`, the documentation is available at `https://tpp-server-url/vedsdk`. OpenApiUi (string): Sets the UI to use for OpenAPI documentation. Valid values are `swagger` or `redoc`. SessionPoolAge (integer): Sets the maximum time an entry can be kept in the session pool, in seconds. SessionPoolExpirationInterval (integer): Sets how often the session expiration process runs, in seconds. SessionPoolSize (integer): Sets the WebSDK Session Pool (Cache) size, in number of entries. SessionRightsRefreshInterval (integer): Sets the maximum number of seconds since the last request, after which the stored rights of a session are refreshed from the database StatisticsApiTracking (boolean): Sets the if API usage is tracked via statistics. StatisticsTrackingIncludesTime (boolean): Sets the if API usage statistics tracks API execution times. StrictExpiration (boolean): Sets the session cache expiration strategy. If set to `true`, the grant will be validated on every API access. RefreshEndpointEnabled (boolean): Sets whether the token refresh endpoint is enabled. UnusedAccessTokenExpiration (integer): Sets the number of seconds an access token must be expired to consider the grant expired, even if the actual grant expiration is further out.

Name

Description

Configuration

object

(Required) An object that contains configuration information for remote access. The following values can be passed in this object. All values are optional.

AuthorizeByIntegrated (boolean): Sets whether the authentication server accepts Windows Integrated Authentication.
AuthorizeByPassword (boolean): Sets whether the authentication server accepts username/password as authentication credentials.
AuthorizeByCertificate (boolean): Sets whether the authentication server accepts certificates as authentication credentials.
AuthorizeByJwt (boolean): Sets whether the authentication server accepts JWT authentication.
AuthorizeDevice (boolean): Sets whether the authentication server accepts device authentication requests.
CertificateConfiguration (object): If object is present, certificate authentication is enabled, which allows the caller to pass a client certificate for authorization. The following values are valid:
- AuthorizedIssuerDns (array of strings): Policy Tree path to the authorized certificate authority object. When present, only certificates from this CA are valid for authentication.
- SourceField (string): Specifies which field on the X.509 certificate to use for matching the user identity. There are three valid values: SAN:UPN, SAN:EMAIL, or CN.
DefaultAccessTokenValidity (integer): Sets the default number of seconds a token is valid. This can be overridden by an application.
DefaultGrantRefreshable (boolean): Sets if, by default, the grant can be refreshed programmatically.
DefaultGrantValidity (integer): Sets the default number of seconds a grant is valid. This can be overridden by an application.
DeviceConfiguration (object): Sets device authorization specific settings. The following values are valid:
- VerificationUri (string): Sets the Uri to verify (confirm) a device authorization request.
- VerificationUriCompleteFormat (string): Sets the Uri to verify (confirm) a device authorization request, with a {0} placeholder to hold the unique request ID.
OpenApiEnabled (boolean): Sets whether the OpenAPI documentation is accessible. If set to true, the documentation is available at https://tpp-server-url/vedsdk.
OpenApiUi (string): Sets the UI to use for OpenAPI documentation. Valid values are swagger or redoc.
SessionPoolAge (integer): Sets the maximum time an entry can be kept in the session pool, in seconds.
SessionPoolExpirationInterval (integer): Sets how often the session expiration process runs, in seconds.
SessionPoolSize (integer): Sets the WebSDK Session Pool (Cache) size, in number of entries.
SessionRightsRefreshInterval (integer): Sets the maximum number of seconds since the last request, after which the stored rights of a session are refreshed from the database
StatisticsApiTracking (boolean): Sets the if API usage is tracked via statistics.
StatisticsTrackingIncludesTime (boolean): Sets the if API usage statistics tracks API execution times.
StrictExpiration (boolean): Sets the session cache expiration strategy. If set to true, the grant will be validated on every API access.
RefreshEndpointEnabled (boolean): Sets whether the token refresh endpoint is enabled.
UnusedAccessTokenExpiration (integer): Sets the number of seconds an access token must be expired to consider the grant expired, even if the actual grant expiration is further out.

Response

Response description
Name	Description
HTTP 200	See OAuth result codes.
HTTP 400	For invalid requests, this call returns HTTP 400 Bad Request and the following data in the message body: Error invalid_request: The request is missing a required parameter or is otherwise malformed. Error_description: If available, additional information about how to retry the request.
HTTP 401	For authentication errors, this call returns HTTP 401 Unauthorized and the following data in the message body: Error invalid_token: The access token is missing, or the provided token is expired, revoked, malformed, or invalid for other reasons. insufficient_rights: The underlying user account does not have sufficient permissions for this request. error_description: If available, additional information about how to retry the request.
HTTP 403	If the response is HTTP 403 Forbidden, the requester's token does not include the admin scope. Call POST Authorize/OAuth with the correct scope and restriction. Update the header with the new token and retry. Error insufficient_scope: The request requires a greater scope than provided by the access token. error_description: If available, additional information about how to retry the request.

Example

Request

POST /vedsdk/oauth/SetConfiguration HTTP/1.1
Host: tpp-server-url
Content-Type: application/json
Accept: application/json
Authorization: Bearer 4MyGeneratedBearerTknz==

{
  "Configuration": {
    "AuthorizeByCertificate": true,
    "AuthorizeByIntegrated": true,
    "AuthorizeByJwt": true,
    "AuthorizeByPassword": true,
    "AuthorizeDevice": true,
    "CertificateConfiguration": {
      "AuthorizedIssuerDns": [
        "\\VED\\Intermediate and Root Certificates\\DigiCert_Assured_ID_Root_CA_Root_2031"
      ],
      "SourceField": "CN"
    },
    "DefaultAccessTokenValidity": 7776000,
    "DefaultGrantRefreshable": true,
    "DefaultGrantValidity": 31536000,
    "DeviceConfiguration": {
      "VerificationUri": "\\/aperture\\/activate",
      "VerificationUriCompleteFormat": "\\/aperture\\/activate\\/{0}"
    },
    "OpenApiEnabled": true,
    "OpenApiUi": "redoc",
    "SessionPoolAge": 86400,
    "SessionPoolExpirationInterval": 300,
    "SessionPoolSize": 5000,
    "SessionRightsRefreshInterval": 60,
    "StatisticsApiTracking": true,
    "StatisticsTrackingIncludesTime": true,
    "StrictExpiration": true,
    "UnusedAccessTokenExpiration": 82800
  }
}

Response

{
  "Result": 0,
  "Success": true
}