Management API (draft) - SSO

Owned by Tomi Pelttari
2020-06-17
4 min read

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

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

Ubisecure Privacy Policy & Cookie Statement