Management API - SSO

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:

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

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

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

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

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

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

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)