This page illustrates the use of the SSO Management API using the curl command line tool. Note that the commands have been run on windows, escaping of special characters and referencing of environment variables will differ depending on the command shell used.
This is an illustrative example only - typically these calls would be made by other scripting languages or orchestration techniques.
Refer also to the API description in the documentation available at SSO Management API.
The first step when using the SSO Management API is to discover the scope required to request in the access token:
The response is unauthorized and includes the reason why - you must present an access_token with the scope "openid 45625ffa-912d-427d-bf27-2f36fe1c4ecf"
Get the token using the scope shown above.
The access token can be requested using any supported grant_types. Authorization code flow is recommended and enables single sign-on using the operator credentials.
For the purposes of this example only, we will use the password grant. The client_id and secret of the SSO Management API OAuth2 agent are given in the HTTP Basic user credentials.
The access token is the value of the access_token in the returned json.
The environment variable BEARER can be set to this value and is referred to in future calls as %BEARER%.
To register an OAuth2 (or OpenID Connect) application using the SSO Management API which has the following settings:
- add new OAuth2 application called
Example5in the site Helsinki
- add Technical Name (
- add Description
- add UI template name
- add Contact e-mail
- add Status (enabled)
- add Force reauthentication (active)
- add Prevent sso after use (active)
- add Application compatibility flags:
Metadata describing the connecting service must be applied to the application. For the following metadata:
the following command would be used. This JSON metadata needs to escaped within the curl command:
A client_id and secret will be returned in the JSON response to this request.
In rare cases, such as GSMA MobileConnect, the client_id and secret is dictated and provided by a third-party. To upload the metadata provided by someone else containing client_id and secret such as
the following command would be used. Note the
?policy=keep_client_credentials option, which will ensure client_id and secret is taken from the metadata and not generated. This JSON metadata needs to escaped within the curl command:
The following command will create a PersistentID mapping in the
Helsinki site called
PersistentIDExample5. This is known as an outboundMappingPolicy .
The PersistentID outboundMappingPolicy will now be attached to the Example5 application:
To set permissions of which groups may use the applications, set the Allowed to group. This command assumes there is a group called "Example5 Users" in the site "Helsinki".
An Authorization Policy defines which user or session attributes are sent to a connected application. In this example, the Authorization Policy called
AuthPolicyX in the Helsinki site is connected to the Example5 application. Only one Authorization Policy can be connected to an application - setting a new one will remove the old one.
The following command sets the Authentication Methods that are allowed to be used for the connected Application. In this example,
password.1 is enabled.
You can enable an existing application using the following command:
You can disable an existing application using the following command:
When an application is disabled, a user trying to log in will be shown the error message
AGENT_DISABLED will be shown. This can be customised in
All actions done via the SSO Management API are logged in the ubisecure-sso\ubilogin\logs\sso-api.log file. It is rolled over daily.