Management API (draft) - SSO
Introduction
SSO Management API is a REST API for managing SSO Server. With Management API it is possible to automate management tasks that previously were only possible with the web browser based Management Console.
Authentication
The system uses standard OAuth 2.0 access tokens for controlling access to the API. The access token must be authorized for Management API scope. Any OAuth 2.0 flow supported by Ubisecure SSO can be used to get an access token. Common flows, in the context of automation and system management, are Authorization Code Grant, Resource Owner Password Credentials Grant and Refresh Token.
See OAuth 2.0 API - SSO for detailed instructions how to get an access token for API requests
Using access token
https://tools.ietf.org/html/rfc6750#section-2.1
The client sends the access token with the Authorization header using the Bearer scheme, as defined by OAuth 2.0.
GET /sso-api/site HTTP/1.1 Authorization: Bearer 55d46612-3592-434a-89b2-27c2d66484b7
Scope discovery
https://tools.ietf.org/html/rfc6750#section-3
If the client does not send an access token or the token is not valid for any reason then the server sends a 401 Unauthorized response with a WWW-Authenticate response header. The WWW-Authenticate header attributes indicate required scope of the access token for accessing the requested resource.
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
- application
- group
- outboundMappingPolicy
- outboundUserMapping
- policy
- policyItem
- refreshTokenPolicy
- user
Addressing
The system uses URI paths as resource identifiers. Each resource identifier starts with an object type prefix
/site
/application
Object type is followed by one or more path segments identifying the resource
- /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
URI encoding
https://tools.ietf.org/html/rfc3986#section-2.1
Characters that are not allowed to appear in path segments must be percent-encoded using UTF-8 character set.
- /site/System/SSO%20API
- identifies "SSO API" sub-site of System site
Encoding leading $ character
To represent path segment values starting with $ character the value must be prefixed with a single $ character
- /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.
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.
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.
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.
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 1583710248
- 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
<object id="/site/System/SSO%20API" type="site"> <attribute value="SSO API" name="name" /> <attribute name="description"> <value>SSO Management API</value> </attribute> </object>
<object id="/site/System/SSO%20API" type="site"> <object id="/group/System/SSO%20API/SSO%20API%20Admins" type="group" link="one" /> <object id="/application/System/SSO%20API/SSO%20API" type="application" link="one" /> </object>
JSON
Representation
- uses string, number and boolean json data types
- single-value attributes as string
- multi-value attributes as array of string
{ "type": "site", "id": "/site/System", "attributes": { "name": "System", "description": [ "Ubilogin System" ] } }
{ "type": "site", "id": "/site/System/SSO%20API", "objects": [ { "type": "group", "id": "/group/System/SSO%20API/SSO%20API%20Admins", "link": "one" }, { "type": "application", "id": "/application/System/SSO%20API/SSO%20API", "link": "one" } ] }