If you are using a third-party Content Management Software (CMS) platform you have several options on how you can build a single sign-on to the ClearVantage Web forms using our REST based web services.
If your CMS software will handle the login functionality for the website, you will need your CMS developer to add code to the login process to make a call to a login webservice that we host to authenticate the user. A sucessful login will returnn back to the calling server a JSON packet containing information about the logged in user. We can also configure the login webservice call to return an XML packet if that is preferred.
Example login webservices call
curl --location 'https://DOMAIN.com/cv5/cgi-bin/logindll.dll/IndLogin' \ --header 'Content-Type: application/json' \ --data-raw '{ "data":{ "WEBUSERID": "USERNAME", "WEBUSERPASSWORD": "PASSWORD", "WMT": "None", "WRP": "loginaccepted.json", "WDP": "logindenied.json", "WER": "error.json" } }'
Example of the JSON return packet
{ "success": true, "data": { "sessionid": "{11DE9522-AA7F-4ED9-B962-72FA73545E78}", "customercd": "100011", "firstname": "Sam", "lastname": "Smith", "email": "same.smith@domain.com", "ismember": "Y", "customertype": "GOLD", "status": "Active" } }
Example error return
{ "success": false, "errors": { "reason": "The username and password combination you entered was incorrect." } }
The CMS software would then create a root domain cookie with the sessionid value. This will ensure the ClearVantage web forms are logged in as well. The session cookie expiration time should match any session cookie times that are configured for the CMS authentication. Several additional 3rd party integrations (i.e. HigherLogic community) will also look for a cookie value with the name memberid and the value of the customercd in the JSON packet. This authenticates the user to those platforms using the shared root domain cookie.
The login link on your website will be pointed to a login page hosted by the ClearVantage webservices. The login form will authenticate the user to the database and set the approriate root domain session cookies. We can configure the cookies being set based on the requirements for the CMS software platform. For example ISMEMBER=Y, MEMBERID=CUSTOMERCD, etc. The CMS software can read these cookies and make necessary updates or set permissions to the CMS profile as needed.
Example Login Link
https://domain.com/cv5/cgi-bin/utilities.dll/openpage?wrp=mainlogin.htm
A member webservice call can also be configured that allows the CMS to make an API call to get detailed information about the logged in user. This information can be used to populate the CMS profile with additional information from the database. This would return either a JSON or XML packet with the member information from the database. The return packet can be configured based off the requirements for the website.
The security and protection of this member information call cann be configured to only allow specific IP addresses to call the webservice or it can be configured with a CMS specific authentication call. You can refer to the API Information documentation for additional authorization information.
Example Member Info Call
curl --location --request POST 'https://domain.com/cv5/cgi-bin/memberdll.dll/Info?wmt=none&wrp=memberinfo.json&wer=error.json&customercd=12345'
Example Member Info Return
{ "CUSTOMERCD":"12345", "CUSTOMERALT":"5177", "FIRSTNAME":"Sam", "MIDDLENAME":"L.", "LASTNAME":"Smith", "SUFFIX":"", "ORGCD":"226", "ORGNAME":"Record Laboratories", "JOBTITLE":"Staff Accountant", "DEPARTMENT":"Finance", "ISMEMBERFLG":"Y", "MEMBEROPTIONSLST":"CTR,DCL,DOC,TCL", "JOINDATE":"11/1/2017", "TERMINATIONDATE":"8/31/2017", "CUSTOMERTYPE":"Prospect", "STATUSSTT":"Current", "UPDATETMS":"1/20/2022 5:53:53 PM" }
Login Redirects
In ClearVantage, the login service allows configuration for redirecting the logged-in user back to the CMS website using the 'redirecturl' option. To ensure website security, only internal redirects are permitted. To achieve this, a configuration setting is applied to explicitly specify the domain name used for the redirect.
In the [DEFAULT] section of 'cvweb.cvcfg', the 'REDIRECTDOMAIN' setting is utilized to set the redirect domain. The login URL should include the following setting to redirect the user back to the CMS website: 'redirecturl=REDIRECTDOMAIN/path_to_page_on_website'.
For those requiring support for multiple redirect domains, additional configuration options are available. You can find more details in the documentation here: Login Redirects Documentation.
Example REDIRECTDOMAIN Link:
https://www.domain.com/cv5/cgi-bin/logindll.dll/IndLogin&webuserid=USERNAME&webuserpassword=PASSWORD&redirecturl=REDIRECTDOMAIN/home
If the CMS software sets the session cookies they can destroy the session cookies when the user logs out of the CMS software. If ClearVantage is setting the cookies, a call to the https://domain.com/cv5/cgi-bin/logindll.dll/IndLogoff webservice will destroy the cookies created by ClearVantage.
As noted above the cookies are configured to be session based. If you are providing an option to set a longer cookie time we have a second paramater that can be passed using an ALTCOOKIETIME configuration setting. The specified cookie expiration time when used in conjuncton with when REMEMBERFLG=Y passed to the LoginDLL/indlogin action will set the cookie time based on the ALTCOOKIE time configuration setting.
More configuration options can be found on the Webservice Login documentation link.