The single sign-on with one-way hash method relies on a one-way hash of query string parameters (also known as a signature).
The following HTTP API, using a signature, prompts the CMC to create an authenticated session for the client that submitted the request:
https://<cmc_FQDN>:<cmc_port>/Vault/ssosecurelogin.htm?user=USERID&group=GROUPID ×tamp=TIMESTAMP&signature=SIG&redirect=RELATIVE_OR_ABSOLUTE_URL
-
user: Nicman Vault userId of the user
-
group: Nicman Vault groupId of the group to which the user belongs
-
timestamp: Current Epoch time in milliseconds (eg. "1346881953440"). The timestamp is used to implement the configurable request expiration (mts-ui.properties: sso.tolerance.millis; expiration defaults to one hour).
-
signature: This is the URI encoding of the base64 representation of the calculated signature. For further information see below.
-
redirect: This optional parameter can be used to redirect the client to the given URL upon successful sign-in. It is typically set to a CMC interior page such as explorer.htm or admin.htm.
Each value must be URL-encoded by the client. Order of the parameters does not matter.
If the signature is found valid, the CMC creates an authenticated session for the Vault user, allowing the client to skip the login page and access to a CMC interior page.
How to Create the Signature
The portal server can create the signature by the following steps.
-
Assemble the query string.
-
querystring = "user=USERID&group=GROUPID×tamp=TIMESTAMP"
When using the querystring to create the signature, do not URL-encode the querystring. Also do not reorder the items. (By contrast, when the client subsequently submits the SSO secure login request to the CMC, it’s desirable to URL encode the request querystring.)
-
-
Calculate one-way hash for the querystring using the standard HmacSHA1 and the CMC SSO shared key. The shared key is configured by mts-ui.properties: sso.shared.key.
-
hashresult = HmacSHA1(querystring, sharedkey)
-
-
Base64 encode the resulting hash.
-
base64string = Base64Encode(hashresult)
-
-
URI encode the base64 encoded hash result.
-
signature = encodeURIComponent(base64string)
-
For a sample of a Python script that uses the one-way hash login API, see Nicman Vault SSO Sample Script.
Access to a CMC’s Interior Page
After creating the signature, the portal server can return an HTML page with a hyperlink to the CMC SSO secure login API. The following example will display CMC’s Data Explorer page (explorer.htm) embedded in the inline frame on the portal’s page.
<iframe src="https://<cmc_FQDN>:<cmc_port>/Vault/ssosecurelogin.htm ?user=USERID&group=GROUPID×tamp=TIMESTAMP&signature=SIG &redirect=explorer.htm"></iframe>
CMC SSO Secure Login HTTP Response
If redirect=RELATIVE_OR_ABSOLUTE_URL is given, the CMC’s SSO secure login API returns an HTTP redirect response.
-
If the request was successful, the redirect response will take the client to the URL specified by redirect.
-
If the request failed, the redirect response will take the client to the CMC’s Login panel.
If redirect=RELATIVE_OR_ABSOLUTE_URL is not given, the CMC’s SSO secure login API returns an HTTP response with content-type "text/plain".
-
If the request was successful, the HTTP response status is 200 OK.
-
If the request failed, a 400 BAD REQUEST status is returned, along with a plain text status description. Possible reasons for failure include:
-
Missing required parameters
-
SSO token already exists (request is ignored)
-
Timestamp in request is outside of configured tolerance range
-
Invalid signature
-
Invalid credentials (group ID and/or user ID is invalid)
-
CMC Logout
This API method allows for immediately invalidating the CMC session.
https://<cmc_FQDN>:<cmc_port>/Vault/logout.htm&redirect=RELATIVE_OR_ABSOLUTE_URL
-
redirect: This optional parameter can be used to redirect the client to the URL after logging out from the CMC. It is typically set to a portal page. The URL must be URL-encoded by the client.
CMC Logout HTTP Response
If redirect=RELATIVE_OR_ABSOLUTE_URL is given, the CMC’s logout API returns an HTTP redirect response to take the client to the given URL after logging out from the CMC.
If redirect=RELATIVE_OR_ABSOLUTE_URL is not given, the CMC’s logout API returns an HTTP redirect response to take the client to the CMC’s Login panel.
Logging Out from the CMC and Portal at Once
You may want the logout link on the portal page to also trigger logout from the CMC. You can achieve this by using redrect parameter.
For example, if you have the portal’s logout link like this:
<a href="/auth/logout">Logout</a>
You can change it to the following:
<a href="https://<cmc_FQDN>:<cmc_port>/Vault/logout.htm ?redirect=https:%2F%2F<portal_FQDN>:<portal_port>%2Fauth%2Flogout">Logout</a>
-
The redirect URL must be an absolute URL including the protocol (e.g. https://) and portal’s FQDN.
-
The redirect URL must be URL-encoded.