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.

Related pages

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

Release notes - SSO
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.

- Active Directory integration - SSO
- Basic LDAP Integration
- Schema enhanced LDAP integration - SSO
- SQL Integration
Login user interface customization - SSO

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

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

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

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

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

NOTE: At this time it is not possible to manage credentials using management API. Use Password Reset, OTP Server, Customer ID or others to manage credentials.

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.

NOTE: Policy function can not be changed after creation.

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/persistentIDPolicy1nameIDFormat=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/on
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

Server

Get other objects linked to method

- Methods
  GET /server/{path to server}/$link/method
  PUT /server/{path to server}/$link/method/{path 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

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

Form parameters are needed to create the policyitems:

- - attributename (Example: mail)
  - attributevalue (Example: $(user.mail) )

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}

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

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

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:

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"

Appendix A – Data types and attributes

Site

PUT|POST (create)
- name
- mail(zero to many possible values)
- description(zero to many possible values)
PUT (update)
- mail(zero to many possible values)
- description(zero to many possible values)
GET (read)
- name(optionally no value, or single value)
- mail(zero to many possible values)
- description(zero to many possible values)

Application

PUT|POST (create)
- name
- mail(zero to many possible values)
- description(zero to many possible values)
- enabled(optionally no value, or single value)
- platform(optionally no value, or single value)
- url(optionally no value, or single value)
- configuration(zero to many possible values)
- template(optionally no value, or single value)
- ticketvaliditytime(zero to many possible values)
PUT (update)
- mail(zero to many possible values)
- description(zero to many possible values)
- enabled
- platform(optionally no value, or single value)
- url(optionally no value, or single value)
- configuration(zero to many possible values)
- template(optionally no value, or single value)
- ticketvaliditytime(zero to many possible values)

GET (read)
- name(optionally no value, or single value)
- mail(zero to many possible values)
- description(zero to many possible values)
- enabled(optionally no value, or single value)
- platform(optionally no value, or single value)
- url(optionally no value, or single value)
- entityid(optionally no value, or single value)
- configuration(zero to many possible values)
- template(optionally no value, or single value)
- applicationtype(optionally no value, or single value)
- ticketvaliditytime(zero to many possible values)

Group

PUT|POST (create)
- name
- description(zero to many possible values)
- condition(zero to many possible values)
- memberurl(zero to many possible values)
PUT (update)
- description(zero to many possible values)
- condition(zero to many possible values)
- memberurl(zero to many possible values)
GET (read)
- name(optionally no value, or single value)
- description(zero to many possible values)
- condition(zero to many possible values)
- memberurl(zero to many possible values)

Method

PUT|POST (create)
- name
- enabled(optionally no value, or single value)
PUT (update)
- enabled(optionally no value, or single value)
GET (read)
- name(optionally no value, or single value)
- enabled(optionally no value, or single value)
- methodtype(optionally no value, or single value)
- classname(optionally no value, or single value)
- title(optionally no value, or single value)

Server

PUT|POST (create)
- name
PUT (update)
GET (read)
- name(optionally no value, or single value)
- description(zero to many possible values)
- url(optionally no value, or single value)
- entityid(optionally no value, or single value)
- ticketvaliditytime(zero to many possible values)
- protocolsupport(zero to many possible values)

Policy

PUT|POST (create)
- name
- description(zero to many possible values)
- platform(optionally no value, or single value)
- configuration(zero to many possible values)
- required(zero to many possible values)
- singlevalue(zero to many possible values)
PUT (update)
- description(zero to many possible values)
- platform(optionally no value, or single value)
- configuration(zero to many possible values)
- required(zero to many possible values)
- singlevalue(zero to many possible values)
GET (read)
- name(optionally no value, or single value)
- description(zero to many possible values)
- platform(optionally no value, or single value)
- configuration(zero to many possible values)
- required(zero to many possible values)
- singlevalue(zero to many possible values)

Policyitem

PUT|POST (create)
- name(optionally no value, or single value)
- namevalue(zero to many possible values)
- attributename
- attributevalue
- group
PUT (update)
- namevalue(zero to many possible values)
- attributename
- attributevalue
- group
GET (read)
- namevalue(zero to many possible values)
- attributename(optionally no value, or single value)
- attributevalue(optionally no value, or single value)

Management API - SSO

Access to API

Related pages

Scope of the API

URI format

HTTP methods

Terminators

$link

$attribute

HTTP response status codes

Response messages

Example

HTTP methods

GET

Example GET-query and response

POST

PUT

DELETE

Create/Update objects

Site

Application

Group

Policy

User

Mappings

Refresh token policy

Querying objects

Linking objects

Link types, linking and removing links

Site

application

Group

Method

Server

Policy

Policyitem

Examples

Deleting objects

Object request

Examples

Example - SAML2 or OAuth2 integration

Introduction

End result as a tree in the database

Steps to build the application

The needed REST API calls

Example - Office365 Integration

Introduction

End result as a tree in the database

This should be preconfigured in the Ubisecure SSO server

Steps to build the application

The needed REST API calls

Appendix A – Data types and attributes

Site

Application

Group

Method

Server

Policy

Policyitem