Introduction

This document guides on how to enable Ubisecure SSO Management API in Ubisecure SSO.

Getting started

Enable SSO Management API

SSO Management API is not enabled by default. To enable the SSO Management API in Ubisecure SSO, use a text editor to edit a custom version of the server.xml in the following directory:

...\ubilogin-sso\ubilogin\custom\tomcat\server.xml

If the file does not already exist in that location, copy the currently used server.xml to the custom directory. Modifications to files in the custom directory will be retained when a software upgrade is performed.

Windows

copy "c:\Program Files\Ubisecure\ubilogin-sso\tomcat\conf\server.xml" "c:\Program Files\Ubisecure\ubilogin-sso\ubilogin\custom\tomcat\server.xml"

Unix

cp /usr/local/ubisecure/ubilogin-sso/tomcat/conf/server.xml /usr/local/ubisecure/ubilogin-sso/ubilogin/custom/tomcat/server.xml

Uncomment the following line:

<Context path="/sso-api" docBase="${catalina.base}/webapps/sso-api"/>

Save the file and run Tomcat update to update and restart SSO.

Windows

cd /d c:\Program Files\Ubisecure\ubilogin-sso\ubilogin
config\tomcat\update.cmd

Unix

cd /usr/local/ubisecure/ubilogin-sso/ubilogin/config/tomcat
./update.sh

Verify SSO API has successfully started

Since v. 9.1.0 SSO API logs to the shared SSO diagnostic log file: sso_diag.YYYY-MM-DD.log. Review that log file indicates successful startup. Confirm that no unexpected errors have occurred since the previous restart.

$UBISECURE_HOME/ubilogin/logs/sso_diag.YYYY-MM-DD.log

YYYY-MM-DD hh:mm:ss,SSS init INFO   ServletContainerApplication version X.X.X starting 
... 
YYYY-MM-DD hh:mm:ss,SSS sso-api com.globalsign.iam.sso.api.oauth2.validator.BearerTokenValidatorFeature INFO   ServletBearerTokenValidatorFeature enabled 
YYYY-MM-DD hh:mm:ss,SSS sso-api com.globalsign.iam.sso.api.oauth2.bearer.BearerTokenFeature INFO   BearerTokenFeature enabled 
YYYY-MM-DD hh:mm:ss,SSS sso-api com.globalsign.iam.sso.api.application.ServletContainerFeature INFO   ServletContainerFeature enabled 
YYYY-MM-DD hh:mm:ss,SSS sso-api com.globalsign.iam.sso.api.message.ObjectMessageFeature INFO   ObjectMessageFeature enabled 
...
YYYY-MM-DD hh:mm:ss,SSS uas init INFO Ubilogin Authentication Server X.X.X started 
YYYY-MM-DD hh:mm:ss,SSS uas tech INFO ping: the system is alive

Import certificates

The SSO Management API connects to the SSO OAuth2 endpoints. The issuer of the SSL certificate on those endpoints must be trusted by the java installation used. By default, no publically issued CAs are trusted and must be trusted explicitly.

The certificates can be imported using the following syntaxes. The whole certificate chain must be imported using the keytool tool. keytool (linux) or Keytool.exe (Windows) can be found in the bin directory of the Java installation under JAVA_HOME.

Import the server certificate.

./keytool -importcert -file ../lib/security/login.example.com.crt -cacerts

Import the intermediate certificate. Use the intermediate certificate of the issuer of your externally facing SSL certificate. In this example, the login.example.com certificate was issued by Comodo.

./keytool -importcert -alias "COMODO RSA Domain Validation Secure Server CA" -file ../lib/security/COMODORSADomainValidationSecureServerCA.crt -cacerts

Import the CA certificate of the issuer of your externally facing SSL certificate.

./keytool -importcert -alias "COMODO RSA Certification Authority" -file ../lib/security/COMODORSACertificationAuthority.crt -cacerts

Create a Client Application

In a production environment a new client application MUST be registered, using the SSO management web console or by other bootstrapping methods. The client id and secret of SSO Management API MUST NOT be used outside the server environment.

Log in to the Ubisecure SSO management console and navigate to System → SSO API → Applications. Create a new application as illustrated in picture below.

Create client_id and secret for the new application and save it somewhere safe. These will be needed later on.

By clicking on the Activate button SSO prompt you and you may click OK.

Save the file and open it using a text editor. Below is an example.

{"client_id":"085bc54a-5a4e-4806-a07b-c97f8dc466c7","client_secret":"X90gQo4WLHovZLoyBXxQpViojgaoqJRd"}

Click on 'Upload' and paste the content into the window and click 'OK'.

Next, activate password.1 method to the application and click on 'Update' -button.

Add the group "SSO API Admins" to the application

Create an API user

Navigate to the System → Users tab and click on the 'New user…' -button.

On Methods tab, activate authentication method password.1 and click 'Update'.

Enter and confirm a password for SSO API user.

Next, add the user to SSO Management API Administrators –group.

Testing the connection

You can start testing the connection using the following syntax using Curl. You may use the ‘--insecure’ flag in case self-signed certificates are used.

curl -i https://<SSO_SERVER_NAME>/sso-api/site

At this point a unauthorized response should come back. This indicates that you SSO Management API is up and running. The response includes the scope to be used in API operations.

HTTP/1.1 401 Unauthorized
Server: Apache-Coyote/1.1
Cache-Control: no-cache, must-revalidate, no-transform, max-age=0, private
WWW-Authenticate: Bearer realm="95023596-c645-4f56-bc19-0cc4428cbe34" scope="openid 95023596-c645-4f56-bc19-0cc4428cbe34"
Content-Length: 0
Date: Thu, 15 Sep 2016 10:02:04 GMT

Get the token

curl --basic -u 085bc54a-5a4e-4806-a07b-c97f8dc466c7:X90gQo4WLHovZLoyBXxQpViojgaoqJRd https://<SSO_SERVER_NAME>/uas/oauth2/token -d grant_type=password -d "scope=openid 95023596-c645-4f56-bc19-0cc4428cbe34" -d username=ssoapiuser -d password=t3kn11kant1314

Response

{"access_token":
"eyJjbGllbnRfaWQiOiIwODViYzU0YS01YTRlLTQ4MDYtYTA3Yi1jOTdmOGRjNDY2YzciLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzX3Rva2VuIiwic2Vzc2lvbl9pbmRleCI6Il8zZDRkOTBkNTA2ZjdkNTYxMTc0YjI1ZDNkZjU1ZDU2NGYzMmZhZDQzIiwic2NvcGUiOlsiMDg1YmM1NGEtNWE0ZS00ODA2LWEwN2ItYzk3ZjhkYzQ2NmM3Iiwib3BlbmlkIl0sImNsaWVudF9pZCI6IjA4NWJjNTRhLTVhNGUtNDgwNi1hMDdiLWM5N2Y4ZGM0NjZjNyIsImV4cCI6MTQ3MzkzOTUzMjM2N30.4ARxJqC4HEK0KJsvckICfg7e3ic_gr79uJLOerx5Yzg",
"scope":"95023596-c645-4f56-bc19-0cc4428cbe34 openid","id_token":"eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJDTj1TU08gQVBJIHVzZXIsT1U9U3lzdGVtLENOPVViaWxvZ2luLERDPWVjMi01Mi0xOS0xLTE4NyxEQz1ldS13ZXN0LTEsREM9Y29tcHV0ZSxEQz1hbWF6b25hd3MsREM9Y29tIiwiaXNzIjoiaHR0cHM6Ly9lYzItNTItMTktMS0xODcuZXUtd2VzdC0xLmNvbXB1dGUuYW1hem9uYXdzLmNvbTo4NDQzL3VhcyIsImF1ZCI6WyIwODViYzU0YS01YTRlLTQ4MDYtYTA3Yi1jOTdmOGRjNDY2YzciXSwiZXhwIjoxNDczOTM5NTMyLCJpYXQiOjE0NzM5MzU5MzIsImF1dGhfdGltZSI6MTQ3MzkzNTkzMiwiYW1yIjpbImh0dHBzOi8vZWMyLTUyLTE5LTEtMTg3LmV1LXdlc3QtMS5jb21wdXRlLmFtYXpvbmF3cy5jb206ODQ0My91YXMvc2FtbDIvbmFtZXMvYWMvcGFzc3dvcmQuMSJdLCJhenAiOiIwODViYzU0YS01YTRlLTQ4MDYtYTA3Yi1jOTdmOGRjNDY2YzciLCJzZXNzaW9uX2luZGV4IjoiXzNkNGQ5MGQ1MDZmN2Q1NjExNzRiMjVkM2RmNTVkNTY0ZjMyZmFkNDMiLCJwYXNzd29yZC4xLmdyYW50X3R5cGUiOlsicGFzc3dvcmQiXSwicGFzc3dvcmQuMS5kbiI6WyJDTj1TU08gQVBJIHVzZXIsT1U9U3lzdGVtLENOPVViaWxvZ2luLERDPWVjMi01Mi0xOS0xLTE4NyxEQz1ldS13ZXN0LTEsREM9Y29tcHV0ZSxEQz1hbWF6b25hd3MsREM9Y29tIl0sInBhc3N3b3JkLjEubGRhcCI6WyJsZGFwOi8vL2NuPVViaWxvZ2luLGRjPWVjMi01Mi0xOS0xLTE4NyxkYz1ldS13ZXN0LTEsZGM9Y29tcHV0ZSxkYz1hbWF6b25hd3MsZGM9Y29tIl19.Mzo3WRCqgcXX4gX0noXtUbnamCXxvU3Yn_erdakuT-ZtJOxp3QGxgAun7gexSvdRuia3M77fNfnZvDnbhURIUQH19NYcWjwoyDUaU9BeaXzhjWi0rgbi-8-owEpTK3dX_1qUlYRngwF-s2hCCLy9-d78C2v3huqdQb53QzjBYoleiN3JeYgWLAvdETQtZx2dYFXkkRYUY-6-uLiXxC6BwB16JPNk9UGLBjpoTgy8o3UUJLYZceneZ5KyLiP3GmRdxJqzQ0aQwHpGN2YCXwdTzS3s-cSFtDGO0wzR7EkpIpqs4BEGfgdz78KvyWnIObQCb8DBG7qY-qxt8vYvuF7QiQ","token_type":"Bearer","expires_in":3600}

Test the token

curl -H "Authorization: Bearer eyJjbGllbnRfaWQiOiIwODViYzU0YS01YTRlLTQ4MDYtYTA3Yi1jOTdmOGRjNDY2YzciLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzX3Rva2VuIiwic2Vzc2lvbl9pbmRleCI6Il8zZDRkOTBkNTA2ZjdkNTYxMTc0YjI1ZDNkZjU1ZDU2NGYzMmZhZDQzIiwic2NvcGUiOlsiMDg1YmM1NGEtNWE0ZS00ODA2LWEwN2ItYzk3ZjhkYzQ2NmM3Iiwib3BlbmlkIl0sImNsaWVudF9pZCI6IjA4NWJjNTRhLTVhNGUtNDgwNi1hMDdiLWM5N2Y4ZGM0NjZjNyIsImV4cCI6MTQ3MzkzOTUzMjM2N30.4ARxJqC4HEK0KJsvckICfg7e3ic_gr79uJLOerx5Yzg"
https://<SSO_SERVER_NAME>/uas/oauth2/userinfo

Response

{
"sub":"CN=SSO API user,OU=System,CN=Ubilogin,DC=ec2-52-19-1-187,DC=eu-west-1,DC=compute,DC=amazonaws,DC=com","iss":"https://<SSO_SERVER_NAME>/uas","aud":["085bc54a-5a4e-4806-a07b-c97f8dc466c7"],"exp":1473940339,"iat":1473936739,"auth_time":1473935932,"amr":["https://<SSO_SERVER_NAME>/uas/
saml2/names/ac/password.1"],"azp":"085bc54a-5a4e-4806-a07b-c97f8dc466c7","session_index":"_3d4d90d506f7d561174b25d3df55d564f32fad43","password.1.grant_type":["password"],"password.1.dn":["CN=SSO API user,OU=System,CN=Ubilogin,DC=ec2-52-19-1-187,DC=eu-west-1,DC=compute,DC=amazonaws,DC=com"],"password.1.ldap":["ldap:///cn=Ubilogin,dc=ec2-52-19-1-187,dc=eu-west-1,dc=compute,dc=amazonaws,dc=com"]
}

Add a Site in Ubisecure SSO

curl -H "Authorization: Bearer eyJjbGllbnRfaWQiOiIwODViYzU0YS01YTRlLTQ4MDYtYTA3Yi1jOTdmOGRjNDY2YzciLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzX3Rva2VuIiwic2Vzc2lvbl9pbmRleCI6Il8zZDRkOTBkNTA2ZjdkNTYxMTc0YjI1ZDNkZjU1ZDU2NGYzMmZhZDQzIiwic2NvcGUiOlsiMDg1YmM1NGEtNWE0ZS00ODA2LWEwN2ItYzk3ZjhkYzQ2NmM3Iiwib3BlbmlkIl0sImNsaWVudF9pZCI6IjA4NWJjNTRhLTVhNGUtNDgwNi1hMDdiLWM5N2Y4ZGM0NjZjNyIsImV4cCI6MTQ3MzkzOTUzMjM2N30.4ARxJqC4HEK0KJsvckICfg7e3ic_gr79uJLOerx5Yzg"
-X PUT https://<SSO_SERVER_NAME>/sso-api/site/MyTestSite

The OAuth endpoints of Ubisecure SSO are discovered from OAuth metadata available at https://<SSO_SERVER_NAME>/uas/oauth2/metadata.json and https://<SSO_SERVER_NAME>/uas/.well-known/openid-configuration:

{
"issuer":"https://<SSO_SERVER_NAME>/uas",
"authorization_endpoint":"https://<SSO_SERVER_NAME>/uas/oauth2/authorization",
"token_endpoint":"https://<SSO_SERVER_NAME>/uas/oauth2/token",
"userinfo_endpoint":"https://<SSO_SERVER_NAME>/uas/oauth2/userinfo",
"jwks_uri":"https://<SSO_SERVER_NAME>/uas/oauth2/metadata.jwks",
"tokeninfo_endpoint":"https://<SSO_SERVER_NAME>/uas/oauth2/introspection",
"introspection_endpoint":"https://<SSO_SERVER_NAME>/uas/oauth2/introspection",
"revocation_endpoint":"https://<SSO_SERVER_NAME>/uas/oauth2/revocation",
"response_types_supported":["code"],"grant_types_supported":["authorization_code","password","refresh_token","urn:ietf:params:oauth:grant-type:saml2-bearer","http://globalsign.com/iam/sso/oauth2/grant-type/sms-mt-otp","http://globalsign.com/iam/sso/oauth2/grant-type/smtp-otp"],
"subject_types_supported":["public"],
"id_token_signing_alg_values_supported":["RS256"],
"token_endpoint_auth_methods_supported":["client_secret_post","client_secret_basic"],
"scopes_supported":["openid","userinfo"]
}

Response messages

The default response message format is XML. Use the “Accept” header to request the response message encoded as JSON.

curl -H "Authorization: Bearer %TOKEN%" -H "Accept: application/json" https://<SSO_SERVER_NAME>/sso-api/site

Browser not supported