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.

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.

Ubisecure SSO REST API can be used to create:

• Sites

• Applications

  • Update application metadata

• Groups

• Authentication Policies

  • PolicyItem

• Links between objects

• Users

• Mappings

• Keys - see Using Management API to manage keys for API calls and SSO key rotation for further details

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

• Path starts with object type

  • 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.

To get more information on how the attributes and linkings are connected, there are three sub-pages explaining them in more detail.

• Management API Services - SSO

• Management API inbound integrations - SSO

• Management API application integrations - SSO

You can also see a overview of the schema in our example site https://manage.example.ubidemo.com/sso-api-sample/schema/models

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.

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.

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.

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

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.

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>

For successful GET operations the API returns HTTP status code 200. Response content contains object type, id (path) and attributes.
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

Used to create objects.

For successful operations the API returns HTTP status code 201. Response content contains object type, id (path) and attributes.

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

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.

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

Used to delete objects or remove a links.

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

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).

Create site:

Update site:

Create application:

Update application:

Create Group:

Update Group:

Create Policy:

Update Policy:

Create/Update PolicyItem:

Create User:

Update User:

Remove user

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

Create refresh token policy

Enable refresh token policy for application

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

Examples:

• 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:

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

• Get and set other objects linked to application

• 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

• Get and set other objects linked to method

• Get and set other objects linked to server

• Get and set other objects linked to policy

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

• Get and set other objects linked to policyitem

• Get and set other objects linked to credential

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

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

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

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.

SSO Management API can be used to control signing and encryption keys used by Ubisecure SSO. A simple key rotation process can involve steps like

• Create a new key which becomes valid at the same time with the current key (i.e. the key validity times overlap)

• Associate the key to SSO server

• When the old key has become invalid, remove the association from SSO server

• Delete the old key

A new 2048 bit signing or encryption key can be created using the following endpoint. A successful operation creates a new key to the system but it is not yet in use. To take the key into active use (assuming it is enabled and within its validity window), one has to associate the key to a site.

If the system does not contain a key with the given name, one will be created.

Content type: application/x-www-form-urlencoded