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:
- System Recommendations and Supported Platforms
- OAuth API
- Management user interface - SSO
- Installation - SSO
- SSO Installation: Appendixes for authentication methods
- Authentication Providers
- External directory integration - SSO
- SSO Management API Configuration
This guide describes how to configure Ubisecure SSO to use external user directories (Active Directory, LDAP or SQL) and perform access control based on group membership in these directories. Please refer to the individual guides.
- 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
PolicyItem
Create/Update PolicyItem:
PUT /policyItem/{path to policyItem}
Form parameters are needed to create the policyitems:
attributeName
- Example:
attributeName=mail
- Example:
attributeValue
- Example:
attributeValue=${user.mail}
- Example:
nameValue
- Example:
nameValue=scope mail
- Example:
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
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
- Authentication Method(s)
- Parent site
GET /site/{path to site}/$link/site
Cannot be set using this URI
- Parent site
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
- Parent site
- 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 applicationPUT /application/{path to application}/$link/policy/{path to policy}
Link authorization policy to applicationDELETE /application/{path to application}/$link/policy/{path to policy}
Remove a link to authorization policy
- 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
- Parent site
- group authentication methods
GET /group/{path to group}/$link/method
List methods linked to groupPUT /group/{path to group}/$link/method/{path to method}
Set group's authentication methodDELETE /group/{path to group}/$link/method/{path to method}
Remove authentication method from a group
- group authentication methods
- Authorization policy
GET /group/{path to group}/$link/policy
Get authorization policies linked to a groupPOST /group/{path to group}/$link/policy/{path to policy}
Set authorization policy for a groupDELETE /group/{path to group}/$link/policy/{path to policy}
Remove authorization policy from a group
- Authorization policy
- Authorization policy items
GET /group/{path to group}/$link/policyitem
List Policy items linked to a policyPUT /group/{path to group}/$link/policyitem/{path to policyitem}
Add policy item to a policy linked to this group
- Authorization policy items
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}
- Sites
- 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}
- Applications
- 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}
- groups
- servers
GET /method/{path to method}/$link/server
Cannot be set using this URI
- servers
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}
- Methods
Policy
- Get and set other objects linked to policy
- Sites
GET /policy/{path to policy}/$link/site
Cannot be set using this URI
- Sites
- 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}
- Applications
- 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}
- groups
- Policyitems
GET /policy/{path to policy}/$link/policyitem
- Policyitems
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}
- groups
- policy
GET /policyitem/{path to policyitem}/$link/policy
PUT /policyitem/{path to policyitem}/$link/policy/{path to group}
- policy
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
- Application: SampleApplication
- Site: SampleSite
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
- Group: SampleOfficeGroup
- Site: SampleOfficeSite
This should be preconfigured in the Ubisecure SSO server
- Site: common
- Application: Office365
- Method: password.1
- Authorization policy: Office365Policy
- Policy: Office365Policy
- Application: Office365
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)