Introduction

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

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.

Windows

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

Unix

..\ubilogin-sso\ubilogin\config\tomcat\update.sh
/etc/init.d/ubilogin-server restart

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 ..\ubilogin-sso\java\windows-x64\jre\bin directory (prior to 8.2) or the bin directory of the java installation under JRE_HOME.

Import the server certificate.

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

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 -keystore ../lib/security/cacert

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 -keystore ../lib/security/cacert

Update SSO API Application Agent

In a production environment a new SSO API Application Agent intergration 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. Select SSO API, which is an existing Application Agent that was added during SSO installation.

In the SSO API Application screen, click the Activate button to create new client_id and client_secret for the application.

Clicking Activate button opens a dialog warning you that existing client_id and client_secret will be replaced. This is fine, so click OK.

Browser should now initiate a download for sso api.json file (sso file, if there's a problem with whitespaces in the filename). Save the file, rename it to client.json 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, copy the client.json file to ubilogin-sso/ubilogin/webapps/sso-api/WEB-INF/oauth2/client.json in the SSO installation. Then update Tomcat and restart SSO.

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

Add the group to the application

Navigate the System → User and click on the 'New user…' -button.

Create an API user

Create and enter a password for the ssoapiuser.

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

Next, activate to authentication method to the end user and click 'Update'.

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.

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 username=ssoapiuser -d password=t3kn11kant1314

Response

{"access_token":
"eyJjbGllbnRfaWQiOiIwODViYzU0YS01YTRlLTQ4MDYtYTA3Yi1jOTdmOGRjNDY2YzciLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzX3Rva2VuIiwic2Vzc2lvbl9pbmRleCI6Il8zZDRkOTBkNTA2ZjdkNTYxMTc0YjI1ZDNkZjU1ZDU2NGYzMmZhZDQzIiwic2NvcGUiOlsiMDg1YmM1NGEtNWE0ZS00ODA2LWEwN2ItYzk3ZjhkYzQ2NmM3Iiwib3BlbmlkIl0sImNsaWVudF9pZCI6IjA4NWJjNTRhLTVhNGUtNDgwNi1hMDdiLWM5N2Y4ZGM0NjZjNyIsImV4cCI6MTQ3MzkzOTUzMjM2N30.4ARxJqC4HEK0KJsvckICfg7e3ic_gr79uJLOerx5Yzg",
"scope":"085bc54a-5a4e-4806-a07b-c97f8dc466c7 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:

{
"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"]
}
Available at: https://<SSO_SERVER_NAME>/uas/oauth2/metadata.json

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