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.

Authorization: Bearer {YOUR_SECURE_TOKEN}

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.

Scope of the 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 Management API - SSO#Using Management API to manage keys for API calls and SSO key rotation for further details

URI format

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.

Data types, attributes and linking

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

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

type=site
name=Sitetest 

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

GET /site/System

Response JSON:

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

Response XML:

<object type="site" id="/site/System"><attribute name="name" value="System"/><attribute name="description"><value>Ubilogin System</value></attribute></object>

POST

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.

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.

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

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:

POST /site/{parent site path}

Form parameters example:
type=site
name=acmecorporation
description=Acme corporation site
mail=e@mail.com

Update site:

PUT /site/{site path}

Form parameters example:
mail=e@mail.com

Application

Create application:

POST /site/{site path}

Form parameters example:
name=Acme corporation application name
enabled=true
By default enabled is false.

Update application:

PUT /site/{path to application}

Form parameters example:
enabled=false

Group

Create Group:

POST /site/{site path}

Form parameters example:
type=group
name=Acme corporation group name

Description, condition and memberurl are optional parameters.

Update Group:

PUT /site/{path to group}

Form parameters example:
memberurl=path to another group

Policy

Create Policy:

POST /site/{site path}

Form parameters example:
type=policy
name=Acme Corporation policy name

Description, required, singlevalue, configuration and platform are optional parameters.

Update Policy:

PUT /site/{path to policy}

Form parameters example:
required=true

PolicyItem

Create/Update PolicyItem:

PUT /policyItem/{path to policyItem}

Form parameters are needed to create the policyitems:

• • attributeName
    
    • Example: attributeName=mail
  • attributeValue
    
    • Example: attributeValue=${user.mail}
  • nameValue
    • Example: nameValue=scope mail

User

Create User:

POST /site/Example

Form parameters example:
type=user
name=user1
mail=user1@example.com
uid=user1
enabled=true

Update User:

PUT /user/Example/user1

Form parameters example:
mail=user1@example.com
uid=user1
enabled=true

Enable authentication method for a user:
PUT /user/Example/user1/$link/method/password.1
enabled=true

Remove user

DELETE /user/Example/user1

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

PUT /outboundMappingPolicy/Example/userMappingPolicy1
nameIDFormat=urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

Add user mapping 

POST /outboundMappingPolicy/Example/userMappingPolicy1/$link/user/Example/user1
username=mapped-username

Enable outbound mapping policy for application

PUT /application/Example/webapp1/$link/outboundMappingPolicy/Example/userMappingPolicy1

Create persistent ID policy 

PUT /outboundMappingPolicy/Example/persistentIDPolicy1
nameIDFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

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

Refresh token policy 

Create refresh token policy

PUT /refreshTokenPolicy/Example/refreshTokenPolicy1

Enable refresh token policy for application

PUT /application/Example/webapp1/$link/refreshTokenPolicy/Example/refreshTokenPolicy1

Querying objects

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

Examples:

GET /site/customer/acmecorporation
GET /site/customer/acmecorporation/application1
GET /site/customer/acmecorporation/usergroup
GET /site/customer/acmecorporation/samplepolicy
GET /site/customer/acmecorporation/$link/managedBy

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

• • Example: site/acmecorporation/$link/one

/site/{path to site}/$link/one/{type}
List the object and all objects matching the "type" one level under site

• • Example: site/acmecorporation/$link/group

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

/site/{path to site}/$link/sub
List the object and all objects under it

• • Example: site/acmecorporation/$link/sub

/site/{path to site}/$link/sub/{object type}
List the object and all objects matching the "type" under site

• • Example: site/acmecorporation/$link/sub/policy

• 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 /site/path to site}/$link/managedBy
List the groups that manage the site

PUT /site/{path to site}/$link/managedBy/{path to group}
Set a group that manages the site

DELETE /site/{path to site}/$link/managedBy/{path to group}
Remove a link to a group that manages the site

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

• • Authentication Method(s)
    
    GET /site/{path to site}/$link/method
PUT /site/{path to site}/$link/method/{path to method}
DELETE /site/{path to site}/$link/method/{path to method}
    Remove a link to a method

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

Application

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

GET /application/{path to application}/$link/allowedTo
List group(s) that have access to this application

PUT /application/{path to application}/$link/allowedTo/{path to group}
Set a group that is allowed to this application

DELETE /application/{path to application}/$link/allowedTo/{path to group}
Remove a link to a group that is allowed to this application

• Get and set other objects linked to application

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

• • Application's authentication method

GET /application/{path to application}/$link/method

PUT /application/{path to application}/$link/method/{path to method}

Form parameter "enabled" needs to be set "true" to have the method enabled for the application.

• • Authorization policy
    

    GET /application/{path to application}/$link/policy
    List authorization policies linked to application 

    PUT /application/{path to application}/$link/policy/{path to policy}
    Link authorization policy to application 

    DELETE /application/{path to application}/$link/policy/{path to policy}
    Remove a link to authorization policy

Group

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

GET /group/{path to group}/$link/accessTo
List applications that this group has access to

PUT /group/{path to group}/$link/accessTo/{path to application}
Set an application that this group has access to

DELETE /group/{path to group}/$link/accessTo/{path to application}
Remove a link to a application that this group has access to

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

GET /group/{path to group}/$link/manages
List sites that this group can manage

PUT /group/{path to group}/$link/manages/{path to site}
Set a site that this group can manage

DELETE /group/{path to group}/$link/manages/{path to site}
Remove a link to a site that this group can manage

• Member
  • To set, get or remove the group members

GET /group/{path to group}/$link/member
List group and users that this group can manage

PUT /group/{path to group}/$link/member/{path to group}
Set a group as a member of this group

DELETE /group/{path to group}/$link/member/{path to group}
Remove group's membership of group

• 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 /group/{path to group}/$link/memberOf
List groups that this group is member of

PUT /group/{path to group}/$link/memberOf/{path to group}
Set this group as a member of other group

DELETE /group/{path to group}/$link/memberOf/{path to group}
Remove this group from a membership of other group

• Get, set and remove other objects linked to group

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

• • group authentication methods
    

    GET /group/{path to group}/$link/method
    List methods linked to group 
    
    PUT /group/{path to group}/$link/method/{path to method}
    Set group's authentication method 
    
    DELETE /group/{path to group}/$link/method/{path to method}
    Remove authentication method from a group

• • Authorization policy
    

    GET /group/{path to group}/$link/policy
    Get authorization policies linked to a group 
    
    POST /group/{path to group}/$link/policy/{path to policy}
    Set authorization policy for a group 
    
    DELETE /group/{path to group}/$link/policy/{path to policy}
    Remove authorization policy from a group

• • Authorization policy items
    
    GET /group/{path to group}/$link/policyitem
    List Policy items linked to a policy 
    
    PUT /group/{path to group}/$link/policyitem/{path to policyitem}
    Add policy item to a policy linked to this group

Method

• Get and set other objects linked to method

• • Sites
    GET /method/{path to method}/$link/site
PUT /method/{path to method}/$link/site/{path to site}
DELETE /method/{path to method}/$link/site/{path to site}

• • Applications
    GET /method/{path to method}/$link/application
PUT /method/{path to method}/$link/application/{path to application}
DELETE /method/{path to method}/$link/application/{path to application}

• • groups
    GET /method/{path to method}/$link/group
PUT /method/{path to method}/$link/group/{path to group}
DELETE /method/{path to method}/$link/group/{path to group}

• • servers
    GET /method/{path to method}/$link/server
    Cannot be set using this URI
•  
  • Next factor method
    • GET /method/{path to method}/$link/nextFactor/method/{path to next method}
    • PUT /method/{path to method}/$link/nextFactor/method/{path to next method}
    • DELETE /method/{path to method}/$link/nextFactor/method/{path to next method}
• • Previous factor method
    • GET /method/{path to previous method}/$link/previousFactor/method/{path to method}
    • PUT /method/{path to previous method}/$link/previousFactor/method/{path to method}
    • DELETE /method/{path to previous method}/$link/previousFactor/method/{path to method}

Server

• Get and set other objects linked to server

• • Methods
    GET /server/$link/method 
PUT /server/$link/method/{path to method}
  • Credential
    GET /server/$link/credential
PUT /server/$link/credential/{path to credential}

Policy

• Get and set other objects linked to policy
  • Sites
    GET /policy/{path to policy}/$link/site
    Cannot be set using this URI

• • Applications
    GET /policy/{path to policy}/$link/application
PUT /policy/{path to policy}/$link/application/{Path to application}
DELETE /policy/{path to policy}/$link/application/{Path to application}

• • groups
    GET /policy/{path to policy}/$link/group
POST /policy/{path to policy}/$link/group/{path to group}
DELETE /policy/{path to policy}/$link/group/{path to group}

• • Policyitems
    GET /policy/{path to policy}/$link/policyitem

Policyitem

• Get and set other objects linked to policyitem

• • groups
    GET /policyitem/{path to policyitem}/$link/group
PUT /policyitem/{path to policyitem}/$link/group/{path to group}

• • policy
    GET /policyitem/{path to policyitem}/$link/policy
PUT /policyitem/{path to policyitem}/$link/policy/{path to group}

Credential

• Get and set other objects linked to credential

• • server
    GET /credential/{path to credential}/$link/server
PUT /credential/{path to credential}/$link/server

Examples

Link authentication method to the site

PUT /site/AcmeCorporation/SalesForce/$link/method/password.1

Link a group to the application (allowedTo-attribute)

PUT /application/AcmeCorporation/SalesForce/salesforcesso/$link/allowedTo/group/AcmeCorporation/SalesForce/users

Link a method to the application

PUT /application/AcmeCorporation/SalesForce/salesforcesso/$link/method/password.1

Link an authentication policy to application

PUT /application/AcmeCorporation/SalesForce/salesforcesso/$link/policy/AcmeCorporation/SalesForce/salesforcepolicy

Link a group to customerId group

PUT /group/AcmeCorporation/SalesForce/users/$link/member/eIDM Users/{path to CID group}

Update application metadata

PUT /application/{path to application}/$attribute/metadata
xml or json (form parameter metadata) Agent metadata
This returns xml or json containing redirect url, client id and client secret. Note that client_id and client_secret can also be set in the metadata.

Update application metadata and keep client set credentials from query metadata

With application metadata attribute setting, note parameter policy: If policy has the value "keep_client_credentials" set then it keeps the client_id and secret from the query (if set in query). If policy has not been set, then SSO creates credentials (regardless of the client_id and secret in the query metadata).

PUT /application/{path to application}/$attribute/metadata?policy=keep_client_credentials

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.

Using Management API to manage keys

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

Create a new key or update an existing 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.

Path parameters

Query parameters

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

Responses

Retrieve a key

This endpoint will return the data related to a key.

Path parameters

Responses

Delete a key

An existing key can be removed using this endpoint. The key is completely removed from the system including its associations.

Path parameters

Responses

Create a new system-wide key association

An existing key can be associated to the server using this endpoint. This operations takes the key into active use in the system (assuming the key is enabled and within its validity window). The key is used in all methods and client applications. An active and associated key is published in the Ubisecure SSO server's OpenID Connect Provider and SAML2 metadata endpoints after Ubisecure SSO has refreshed the keys to publish. This operation typically takes up a minute to complete and be applied.

Path parameters

Responses

Retrieve a key association

This endpoint will return the data related to a key association.

Path parameters

Responses

Remove an existing system-wide key association

This will remove an existing key association from the system. The key itself remains in the system but it is not in active use after this operation. The associated key is un-published from the Ubisecure SSO server's OpenID Connect Provider and SAML2 metadata endpoints after Ubisecure SSO has refreshed the keys to publish. This operation typically takes up a minute to complete and be applied.

Path parameters

Responses

Get certificate signing request

This endpoint returns CSR (Certificate Signing Request) for the specified site and key name.

Path parameters

Responses

Content-Type: application/pkcs10

-----BEGIN CERTIFICATE REQUEST-----
... redacted ...
-----END CERTIFICATE REQUEST-----

Store signed certificate

This endpoint can be used to store the signed certificate created from the CSR on a CA.

Path parameters

Request body

Signed certificate in PEM format.

Content-Type: application/pkix-cert

-----BEGIN CERTIFICATE-----
... redacted ...
-----END CERTIFICATE-----

Responses

Example - SAML2 or OAuth2 integration

Introduction

In this example we create a SAML2 or OAuth2 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:

POST /site/AcmeCorporation

type=site
name=SampleSite

Create application, policy and group under the site: 

POST /site/AcmeCorporation/SampleSite

type=application
name= SampleApplication  

POST /site/AcmeCorporation/SampleSite

type=policy
name=SamplePolicy 

POST /site/AcmeCorporation/SampleSite

type=group
name=SampleGroup

Add method to to the site:

PUT /site/AcmeCorporation/SampleSite/$link/method/password.1

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

PUT /application/AcmeCorporation/SampleSite/ SampleApplication/$link/allowedTo/group/AcmeCorporation/ SampleSite/SampleGroup

Add password method to application:

PUT /application/AcmeCorporation/SampleSite/ SampleApplication/$link/method/password.1 

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

PUT /application/AcmeCorporation/SampleSite/ SampleApplication/$link/policy/AcmeCorporation/SampleSite/SamplePolicy 

Add data to authorization policy:

POST /policy/AcmeCorporation/SampleSite/SamplePolicy

group=/group/AcmeCorporation/SampleSite/SampleGroup
name=email
value=${user.mail}

Note that the field value is a Java EL expression

Link group to the CID group to add access for the users of the CID group:

PUT /group/AcmeCorporation/SampleSite/SampleGroup/$link/member/group/eIDM Users/{path to CID group} 

Create metadata for the site:

PUT /application/AcmeCorporation/SampleSite/salesforcesso/$attribute/metadata

Example - Office365 Integration

Introduction

In this example we create an Office365 application. This differs from the OAuth2/SAML2 example mainly in that office365 needs to have a common application for all Office365 application users.

To make Office365 application available to certain company and group we create a site for the company and under the site a group that is linked to CustomerID group and has access to preconfigured common Office365 application.

End result as a tree in the database

• Site: AcmeCorporation
  • Site: SampleOfficeSite
    • Group: SampleOfficeGroup
      • Member: link to CustomerID group
      • AccessTo: office365 application

This should be preconfigured in the Ubisecure SSO server

• Site: common
  • Application: Office365
    • Method: password.1
    • Authorization policy: Office365Policy
  • Policy: Office365Policy

Steps to build the application

Example Office365 application is built in following steps:

• Create a site for this application, in this example named SampleOfficeSite. Create the site under site AcmeCorporation.
• Create the group for the application users, SampleOfficeGroup
• Link SampleOfficeGroup to correct CustomerID group so that customerID users are linked to SampleOfficeGroup.
• Link SampleOfficeGroup to Office365 application's allowedTo attribute to add access to office365 application.
• Add attributes to Office365Policy (To define that also email is sent to the caller of this application)
  • Note that this adds attributes to common site's Office365Policy

After this CustomerID users (of some group) have access to Office365 application.
 

The needed REST API calls

Create site and group:

POST /site/AcmeCorporation

type=site
name=SampleOfficeSite

POST /site/AcmeCorporation/SampleOfficeSite

type=group
name=SampleOffice365Users

Link group to common office365 users group via accessTo attribute: 

PUT /group/AcmeCorporation/SampleOfficeSite/SampleOffice365Users/$link/accessTo/application/common/Office365

Link group to the CID group to add access for the users of the CID group:

PUT /group/AcmeCorporation/SampleOfficeSite/SampleOffice365Users/$link/member/group/eIDM Users/[path to CID group] 

Add authorization policy data:

POST /policy/common/Office365/office365policy

Group=/group/AcmeCorporation/SampleOfficeSite/SampleOffice365Users
Name=upn
Value=${user.mail} 

POST /policy/common/Office365/office365policy

Group=/group/AcmeCorporation/SampleOfficeSite/SampleOffice365Users
Name=issuer
Value="acmecoprporation.com"