Create SSO Server Definition

Edit online

The Create SSO Server Definition operation creates an SSO Server Definition object with the given properties. [Added by feature single-sign-on]

HTTP method and URI

POST /api/console/sso-server-definitions

Request body contents

The request body is expected to contain a JSON object with the following fields:

Name	Type	Rqd/Opt	Description
name	String	Required	The value to be set as the SSO Server Definition's name property.
description	String	Optional	The value to be set as the SSO Server Definition's description property.
type	String Enum	Required	The value to be set as the SSO Server Definition's type property.
client-id	String	Required if type is "oidc"	The value to be set as the SSO Server Definition's client-id property.
client-secret	String	Required if type is "oidc"	The value to be set as the SSO Server Definition's client-secret property.
issuer-url	String/ URL	Required if type is "oidc"	The value to be set as the SSO Server Definition's issuer-url property.
authentication-url	String/ URL	Required	The value to be set as the SSO Server Definition's authentication-url property.
token-url	String/ URL	Required if type is "oidc"	The value to be set as the SSO Server Definition's token-url property.
jwks-url	String/ URL	Required if type is "oidc"	The value to be set as the SSO Server Definition's jwks-url property.
logout-url	String/ URL	Required if logout-sso-session-on-reauthentication-failure is true	The value to be set as the SSO Server Definition's logout-url property.
authentication-page-servers	Array of objects	Optional	The value to be set as the SSO Server Definition's authentication-page-servers property.
logout-sso-session-on-reauthentication-failure	Boolean	Optional	The value to be set as the SSO Server Definition's logout-sso-session-on-reauthentication-failure property.

Response body contents

On successful completion, the response body contains a JSON object with the following field:

Table 1.
Field name	Type	Description
`element-uri`	String/ URI	The canonical URI path of the new SSO Server Definition object.

Description

This operation creates a new SSO Server Definition object.

On successful execution, an SSO Server Definition object has been created using the values specified in the request body. The URI of the new SSO Server Definition object is provided in the response body and in a Location response header. An Inventory Change notification is emitted asynchronously to this operation.

The request body is validated against the schema described in Request body contents. If the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the validation error encountered. The request body validation will fail if it contains a property that is not valid because the specified name is not unique. In addition, the API user must have action/task permission to the Manage Single Sign-On Servers task; otherwise, status code 403 (Forbidden) is returned.

Authorization requirements

This operation has the following authorization requirement:

Action/task permission to the Manage Single Sign-On Servers task

HTTP status and reason codes

On success, HTTP status code 201 (Created) is returned, the response body is provided as described in Response body contents, and the Location response header contains the URI of the newly created object.

The following HTTP status codes are returned for the indicated errors, and the response body is a standard error response body providing the reason code indicated and associated error message.

HTTP error status code	Reason code	Description
400 (Bad Request)	Various	Errors were detected during common request validation. See Common request validation reason codes for a list of the possible reason codes.
	8	An SSO Server Definition with the name specified in the request body already exists.
	315	The authentication-page-servers array contains a duplicate element.
403 (Forbidden)	1	The API user does not have the required permission for this operation.

Additional standard status and reason codes can be returned, as described in Invoking API operations.

Example HTTP interaction

Figure 1. Create SSO Server Definition: Request

POST /api/console/sso-server-definitions HTTP/1.1
Content-Length: 591
Content-Type: application/json
x-api-session: 5fq550pwrzy88lkk7e3902cdfnucp606f4jgsm40docnaqzfj8
{
   "authentication-page-servers":[
      {
         "hostname-ipaddr":"images1.example.com",
         "port":443
      },
      {
         "hostname-ipaddr":"images2.example.com",
         "port":80
      }
   ],
   "authentication-url":"https://sso1.example.com/auth",
   "client-id":"sso1-123456",
   "client-secret":"sso1-client-secret",
   "description":"Primary SSO server",
   "issuer-url":"https://sso1.example.com/issuer",
   "jwks-url":"https://sso1.example.com/jwks",
   "logout-sso-session-on-reauthentication-failure":true,
   "logout-url":"https://sso1.example.com/logout",
   "name":"SSO Server 1",
   "token-url":"https://sso1.example.com/token",
   "type":"oidc"
}

Figure 2. Create SSO Server Definition: Response

201 Created
Cache-control: no-cache
Content-Length: 90
Content-Type: application/json
Date: Wed, 13 Nov 2024 22:51:09 GMT
Location: /api/console/sso-server-definitions/c6a464c2-a211-11ef-bbc4-fa163e7cf285
{
   "element-uri":"/api/console/sso-server-definitions/c6a464c2-a211-11ef-bbc4-fa163e7cf285"
}