CMS Login IAP/REST Service
In order to use IAP/REST or IAP/WS you first need to log into the SmartServer CMS using the IAP/REST Login request. All subsequent request use the CMS cookie. After logging in you can make IAP/REST or IAP/WS call.
IAP/REST provides authentication methods allowing you to login and logout of the CMS, as well as update user passwords.
You can login to the CMS using the same browser from which the web pages are served to, or by using the authentication method /iap/auth/login as shown below. To log in with the embedded CMS which is installed on Apollo use the following url:
- With SmartServer release 2.8 or higher: https://<Apollo_ip>/cms
- With SmartServer release prior to 2.8: https://<Apollo_ip>:8443/cms
To log into the CMS you will need to change the request header "Content-type" to "application/json".
The login process may work differently if you are using a signed or self-signed certificates. The SmartServer defaults to using self-signed certificate. When using a SmartServer that is configured for a self-signed certificate, the first time you access the SmartServer Web pages with a Web browser (like Chrome or Firefox) you are prompted with security prompt asking if you want to continue. You may see a similar issue with any external application that you write.
The login response header has a cmsSID cookie that is required for all subsequent IAP/REST or IAP/WS requests.
- This cookie is usually added automatically to a request header by a Web browser for any custom Web pages that you host on the SmartServer.
- If you are using the IAP/REST or IAP/WS in an Internal Device on the SmartServer you may need to add the cookie to the request header.
- If you are using a PC or server based application you most likely need to manually add this cookie to the request header.
The authentication methods are described in Authentication (Login/Logout) in the IAP/REST API Reference.
To Login:
| POST | /iap/auth/login |
| Request payload: {"username":"{userName}","password":"{password}"} |
- Requires the request header "Content-type" to be set to "application/json".
- Authenticates the user in the CMS and returns information about the user if the login operation was successful.
- Use the Response cmsSID cookie for all subsequent IAP/REST or IAP/WS requests.
- You don't need to do anything with the cmsSID Web pages hosted on the SmartServer
- All other application hosted on or off the SmartServer (like a cloud server or a SmartServer internal Device) need to use the login response cmsSID included in the 'set-cookie'.
- 'set-cookie' may have additional cookies that you don't need to worry about.
Example:
POST /iap/auth/login PAYLOAD: {"username":"mark","password":"5pa?HG!O"} Success Response: { "id": 45, |
To Logout:
| POST | /iap/auth/logout |
POST with no payload (empty payload). Logs out the current user from CMS.
To Reset Password:
| PUT | /iap/auth/resetPwd |
Request body: { "userName":"user", "email":"user@user.com" } |
Updates forgotten password and sends e-mail to the user.
To Get the Current User Session Timeout Period:
| GET | /iap/auth/sessionTimeout |
Returns timeout of the current user's session in milliseconds.
HTTP responses are described in the table below.
| HTTP Response | Description |
|---|---|
| Login Attempt | |
| 401 | Incorrect login or password |
| 429 | Too many failed attempts, body contains message - "Too many failed login attempts! Wait for {0} before the next try.", {0} - waiting time until the next attempt, example - 10 minutes 43 seconds |
| Correct Login and Password | |
| 428 | The user has been deactivated. |
| 423 | The password expired. It is necessary to add the newPassword field to the payload where a new password needs to be specified. Request payload: {"username":"{userName}","password":"{password},"newPassword":"{newpassword}"} |
| 423 | The password has been reset and is set to temporary. It is necessary to add the newPassword field to the payload where a new password needs to be specified. |
| 406 | The password does not meet the requirements. The UI displays the message: Enhanced Security is enabled. Your current password does not meet the Enhanced Security requirements for a strong password. Click here to enter a new strong password. If prompted, enter your current apollo user credentials. Once you have changed your password, click the CMS tab at the top of the Configuration page to return to the CMS, and then log in with your new password. |
| Other | |
| 500 | Database error. |
You cannot change the password for apollo in the Local CMS. Instead, use the SmartServer System Configuration page. In the case of Remote CMS (and Local CMS if enhanced security is enabled), password requirements are as follows:
The password must be at least 14 characters long and must include each of the following: an uppercase letter ( A-Z ), a lowercase letter ( a-z ), a number ( 0,1, 2, 3, 4, 5, 6, 7, 8, 9 ), and a special character ( ! # $ % & ( ) * + , - . / : ; < = > ? @ [ ] ^ _ ` { | } ~ ).
- Single quote ( ' ), double quote ( “ ), spaces, and tabs are not allowed.
- Systematic characters (e.g., 1234 ) are not allowed.
- The New Password and Confirm New Password entires must match.
- Enabling the Show Password checkbox displays the disguised password characters.
- A setting that enforces password history requires that the number of unique, new passwords that are associated with the username is 5, prior to allowing an old password to be reused
Most errors contain a message field that describes the reason for any failure.