NOTE: This page must be reviewed - see the non-draft version of this same page name.

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

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

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 Management API (draft) - SSO
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

Resources - GET /site/System/SSO%20API

<object id="/site/System/SSO%20API" type="site">
    <attribute value="SSO API" name="name" />
    <attribute name="description">
        <value>SSO Management API</value>
    </attribute>
</object>

Links - GET /site/System/SSO%20API/$link/one

<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

Resources - GET /site/System/SSO%20API

{
    "type": "site",
    "id": "/site/System",
    "attributes": {
        "name": "System",
        "description": [
            "Ubilogin System"
        ]
    }
}

Links - GET /site/System/SSO%20API/$link/one

{
    "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"
        }
    ]
}

Browser not supported