NOTE: This page must be corrected prior to publishing reviewed - see the non-draft version of this same page name.
...
Code Block | ||
---|---|---|
| ||
GET /sso-api/site HTTP/1.1 Authorization: Bearer 55d46612-3592-434a-89b2-27c2d66484b7 |
Scope discovery
https://tools.ietf.org/html/rfc6750#section-3
...
Code Block | ||
---|---|---|
| ||
HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer realm="8ec15499-2597-4bf1-910d-0b8ea0d396ba" scope="openid 8ec15499-2597-4bf1-910d-0b8ea0d396ba" |
Types
Types refer to objects, entities and other resources that are manageable with the API. Common resource types are for example site, group and application. In this document resource types are categorized as follows
- Services
- Connections to user repositories such as SQL and Active Directory
- Definitions for REST service integrations
- Session Storage
- Inbound integrations
- Authentication methods and inbound trust
- Directory and service user mapping
- Attribute mapping
- Application integrations
- Sites or containers for organizing resources
- User, group and application
- Policy definitions for authorization, refresh tokens, persistent id mapping etc
See Management user interface - SSO for information on manageable objects and entities.
Management API Services - SSO
- services
- directory
- service
- sessionStore
Management API inbound integrations - SSO
- server
- inboundMappingPolicy
- inboundDirectoryMapping
- inboundServiceMapping
- inboundPolicy
- inboundPolicyItem
- method
- inboundMappingPolicy
Application integration
...
- /site/System
- /application/System/Ubilogin
Links
Links between resources are used to enable functionality and create integrations. A resource identifier with a path segment "$link" defines a link.
- /application/System/Ubilogin/$link/allowedTo/group/System/Administrators
- here two resources are connected with a named accessTo link
- /application/Example/client/$link/policy/Example/policy1
- here two resources are connected with a typed link
Links between two resources are symmetric
- /group/System/Administrators/$link/accessTo/application/System/Ubilogin
- represents the same link as accessTo link above, but from opposite direction
By leaving out the identifying part from the link target it is possible to navigate the Management API namespace
- /site/$link/one
- list of all immediate child objects of the root site
- /application/System/Ubilogin/$link/allowedTo
- list of all groups that are allowed access to Ubilogin application
Attributes
A path segment "$attribute" is used to address special attributes and functionalities of some resource types.
- /application/System/Ubilogin/$attribute/metadata
- identifies metadata of Ubilogin application
Escaping special characters
...
- /site/System/$$link
- identifies "$link" sub-site of System site
Operations
The following standard HTTP methods are used for API operations.
GET
Read resources and links.
Code Block | ||
---|---|---|
| ||
GET /site/System GET /application/System/Ubilogin GET /site/$link/one GET /site/System/$link/sub |
PUT
Create or update resources and links. The response body contains the newly created or updated resource.
Code Block | ||
---|---|---|
| ||
PUT /site/Example PUT /group/Example/users PUT /application/Example/client PUT /application/Example/client/$link/allowedTo/group/Example/users |
POST
Create resources and links.
Code Block | ||
---|---|---|
| ||
POST /site type=site&name=Example POST /site/Example type=group&name=users POST /site/Example type=application&name=client POST /group/Example/users/$link/policy/Example/policy attributename=role&attributevalue=users |
DELETE
Delete resources and links.
Code Block | ||
---|---|---|
| ||
DELETE /application/Example/client/$link/allowedTo/group/Example/users DELETE /application/Example/client DELETE /group/Example/users DELETE /site/Example |
HTTP Status Codes
- 200 OK
- Operation was successful
- 201 Created
- Operation was successful
- Example: in response to creating resources with POST
- 204 No Content
- Operation was successful, but there was an empty response
- Example: in response to deleting resources with DELETE
- 400 Bad Request
- Operation failed because of invalid or missing parameters
- Example: a required attribute was missing when creating a resource
- 401 Unauthorized
- The access token is missing or invalid
- See .Management API (draft) - SSO v8.3
- 405 Method Not Allowed
- Resource exists but the HTTP method is not supported
- Example: attempt to update or remove read-only resource
- 409 Conflict
- Resource exists but operation failed because of system constraints
- Example: attempt to overwrite existing resource
- 501 Not Implemented
- Resource exists but the HTTP method is not implemented
- 503 Service Unavailable
- The system is unable to handle the request, likely caused by issues on the server side such as maintenance work
Schema
Input to the system is HTML form encoded name value pairs (application/x-www-form-urlencoded).
Output from the system is either XML (application/xml) or JSON (application/json) serialization format. The client uses the Accept request header to choose format. Default format is XML.
XML
Representation
- all values as string values
- single-value attributes as "value" attribute
- multi-value attributes as nested "value" elements
Code Block | ||||
---|---|---|---|---|
| ||||
<object id="/site/System/SSO%20API" type="site"> <attribute value="SSO API" name="name" /> <attribute name="description"> <value>SSO Management API</value> </attribute> </object> |
...