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.

Access to API

To operate REST API an OAuth2 access token is needed. To get the access token an OAuth2 Resource Server configured as Ubisecure agent needs to be activated and configured in the Ubisecure SSO server.

SSO Management REST API calls need to have the access token in the bearer authorization header.

Please check OAuth 2.0 API - SSO page for more information about OAuth API.
Please check SSO Management API Configuration Guide for information how to configure and start using SSO API.

Related pages

For more information about Ubisecure SSO, please refer to the following pages and topics:

• System Recommendations and Supported Platforms

• OAuth API

• Management user interface - SSO

• Installation - SSO

• SSO Installation: Appendixes for authentication methods

• Authentication Providers

• External directory integration - SSO

• SSO Management API Configuration
  This guide describes how to configure Ubisecure SSO to use external user directories (Active Directory, LDAP or SQL) and perform access control based on group membership in these directories. Please refer to the individual guides.

Scope of the API

Ubisecure SSO REST API can be used to create:

• Site

• Application (note that application can be called agent in Ubisecure SSO management UI)

  • Update application metadata

• Group

• Authentication Policy

  • PolicyItem

• Links between objects (See chapter 11 Linking objects)

• User

• Mappings

URI format

The URI format of Ubisecure SSO Management API is based on the following principles:

• Path starts with object type (in the version 7.5.0, value can be: site, application, group or policy)

  • Example: /site

• After object type, the path to the object

  • Example: /site/acmecorporation/

  • Example: /group/acmecorporation/users

  • Example: /application/acmecorporation/salesforce

  • Example: /policy/acmecorporation/policy

URI can contain a terminator ($link, $attribute) after the path to an object. This is described in more detail below in section Terminators.

HTTP methods

GET is used to query data.

POST writes a new object.

PUT writes object (update existing object)

DELETE is used to delete object or remove object linking.

Terminators

$link

Is used as part of the URI to link objects to other objects, and to list/query objects linked to other objects.
After $link the URI contains the path to another object as setter for the scope for the listing of related objects.
Section Response Messages describes in detail how links are used.

$attribute

Is used to query or update object attribute values. Version Ubisecure SSO 7.5.0 contains $attribute setting for application metadata – other $attribute settings will be available in future versions.

HTTP response status codes

Ubisecure SSO Management REST API uses following HTTP response status codes:

• HTTP Response Status 200 (GET, DELETE)

  • Operation was successful. Returned when no error in GET, and after DELETE.

• HTTP Response Status 201 (Create, Update) (POST, PUT)

  • Resource created or updated successfully.

• HTTP Response Status 400 (Bad Request)

  • The request was invalid.

• HTTP Response Status 401 (Not Authorized)

  • Invalid credentials

Response messages

Client can choose the result to be plain text, JSON or XML.This is set on the HTTP accept – header by setting the media type to Accept: text/plain; or Accept: application/json; or Accept: application/xml.

Example

POST /site/AcmeCorporation

Response:

• Plain text: site /site/SiteTest

• JSON: {"type":"site","id":"/site/SiteTest","attributes":{"name":"SiteTest"}}

• XML: <object type="site" id="/site/SiteTest"><attribute name="name" value="SiteTest"/></object>

HTTP methods

GET

For successful GET operations the API returns HTTP status code 200. Response content contains object type, id (path) and attributes as described in section Appendix A.
Format of query to Ubisecure SSO REST API is as described in the section URI Format. Section Response Messages describes in more detail the querying of object links.

Example GET-query and response

POST

Used to create objects.

For successful operations the API returns HTTP status code 201. Response content contains object type, id (path) and attributes as described in section Appendix A.

PUT operations can be used to update any data created with POST operation.

PUT

Used to create objects or links to other objects.

For successful operations the API returns HTTP status code 201.

Response content contains object type, id (path) and attributes as described in section Appendix A.

PUT can be used to update data created using POST operation.

DELETE

Used to delete objects or remove a links.

The response is 200 (OK) when delete was successful.

Create/Update objects

More detailed information regarding object parameters in section Appendix A.

If POSTing an object with same path twice the system will give an error as the object already exists. PUT can be used to update existing objects (parameters).

Site

Create site:

Update site:

Application

Create application:

Update application:

Group

Create Group:

Update Group:

Policy

Create Policy:

Update Policy:

PolicyItem

Create/Update PolicyItem:

User

Create User:

Update User:

Remove user

Mappings

Please read page Management UI Mappings - SSO.

Three kind of mappings:

• Type outbound user mapping

  • nameIDFormat = urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified 

• Type persistent ID mapping

  • nameIDFormat = urn:oasis:names:tc:SAML:2.0:nameid-format:persistent 

• Type transient ID mapping

  • nameIDFormat = urn:oasis:names:tc:SAML:2.0:nameid-format:transient 

Policy function is defined with nameIDFormat attribute when policy is created.

Create user mapping policy

Add user mapping 

Enable outbound mapping policy for application

Create persistent ID policy 

Note! At most one outbound mapping policy is allowed per application

Refresh token policy 

Create refresh token policy

Enable refresh token policy for application

Querying objects

To get some object (and parameters) use Http GET method and give path to object as REST query path.

Examples:

Linking objects

Link types, linking and removing links

Site

• one – to set the scope for object list. Link type "one" lists objects only one level below the site (onelevel)
  
  /site/{path to site}/$link/one
  List objects one level under the object

• sub – to set the scope for object list, containing object itself and all objects under site (subtree)

• Possible object types in subtree under site-object: site, application, group, user, policy, mapping, refreshtoken

• managedBy – set, get or delete a link to the group(s) that can manage a site

• Get,set and delete other objects linked to site:

Application

• allowedTo. Set or get the group(s) that are allowed to an application

• Get and set other objects linked to application

Group

• AccessTo

  • To set, get or remove group's access to applications

• Manages

  • To set, get and remove the sites that the group can manage

• Member

  • To set, get or remove the group members

• memberOf

  • To set this group as a member to another, or get the groups that this is member of, or to remove group's membership of other group

• Get, set and remove other objects linked to group

Method

• Get and set other objects linked to method

Server

• Get other objects linked to method

Policy

• Get and set other objects linked to policy

  • Sites
    GET /policy/{path to policy}/$link/site
    Cannot be set using this URI

Policyitem

• Get and set other objects linked to policyitem

Examples

Link authentication method to the site

Link a group to the application (allowedTo-attribute)

Link a method to the application

Link an authentication policy to application

Link a group to customerId group

Update application metadata

Update application metadata and keep client set credentials from query metadata

Deleting objects

DELETE /{object type}/{path to object}

Deletes object from path. Does not check if child objects exist.

Object request

GET /{object type}/{path to object}

Return's the object, and parameters as described in section HTTP Methods.

Client can choose the result to be plain text, JSON or XML as described in section Terminators.

Examples

Example - SAML2 or OAuth2 integration

Introduction

In this example we create a SAML2 or OAauth2 application to Ubisecure SSO server. Users of this application exist in Ubisecure CustomerID and are members of a group that will be linked to this example application. Example application utilizes the password.1 authentication method.

Example application is created under an existing site named AcmeCorporation.

End result as a tree in the database

• Site: AcmeCorporation

  • Site: SampleSite

    • Application: SampleApplication

      • AllowedTo: SampleGroup

      • Method: password.1

      • Authorization policy: SamplePolicy

    • Policy: SamplePolicy

    • Group: SampleGroup

      • Member: link to CustomerID group

Steps to build the application

Example OAuth2/SAML2 application is built in following steps:

• Create a site for this application, named SampleSite. Create under the site AcmeCorporation.

• Create application, named SampleApplication

• Create an authorization policy named SamplePolicy.

• Create the group for the application users, SampleGroup

• Add the authentication method password.1 to SampleSite to allow using of password based login

• Add SampleGroup to SampleApplication's allowed users

• Add the authentication method password.1 also to SampleApplication

• Add attributes to SamplePolicy (To define that also email is sent to the caller of this application)

• Add SamplePolicy to SampleApplication

• Link SampleGroup to correct CustomerID group so that customerID users are linked to SampleGroup.

• Add metadata to SampleApplication

After this Ubisecure CustomerID users (of some group) have access to SampleApplication

The needed REST API calls

Create site:

Create application, policy and group under the site: 

Add method to to the site:

Add group to application's allowedTo (to allow access to application):

Add password method to application:

Add policy to the application: (also email sent to application after user login)