Rename to AccountHub and add a lot of docs
parent
2138778af2
commit
51682ed9fc
@ -0,0 +1,37 @@
|
||||
# API Introduction
|
||||
|
||||
The AccountHub API is extremely simple to use. Requests can be sent via GET or POST, and responses are sent in JSON. POST requests are strongly recommended over GET for security reasons (i.e. GET request data, including API keys and plaintext passwords, is saved in server logs and browser history with little to no protection). You should only use GET requests for debugging purposes or if (for some awful reason) it is not possible to use POST for your use case.
|
||||
|
||||
# Request Structure
|
||||
|
||||
The API is typically located at `http(s)://accounthub-url/api.php`.
|
||||
|
||||
All requests to the API must include a `key` argument containing a valid API key. They must also include an `action`. The `action` specifies the type of request. Other arguments may or may not be needed, depending on the `action` specified. See the table below for valid actions and parameters.
|
||||
|
||||
# Response Structure
|
||||
|
||||
Responses to well-formed requests will have a `status` field containing the string `OK` or `ERROR`.
|
||||
If `status` is `ERROR`, there will also be a field named `msg` containing a human-readable localized error message suitable for display to the user.
|
||||
If `status` is `OK`, there may or may not be additional fields sent, depending on the `action`.
|
||||
|
||||
If the request is not well-formed (missing required arguments, invalid API key, or invalid `action`), the API will send a 4xx HTTP code and a JSON string, such as `"400 Bad Request"`, `"403 Unauthorized"`, or `"404 Not Found: the requested action is not available."`.
|
||||
|
||||
# Actions
|
||||
|
||||
| Action | Additional Arguments | Description
|
||||
| ------------- | --------------------------------------- | -----------
|
||||
| `ping` | None | Used to check if the server is online and responding. Responds with `{"status":"OK"}`.
|
||||
| `auth` | `username`, `password` | Returns a status of `OK` if the user/pass combination are valid and allowed to login, otherwise returns `ERROR`. Also includes a `msg` with an error or success message.
|
||||
| `userinfo` | `username` or `uid` | If the username or UID exist in the system, returns the user's profile data in the `data` field. <br>Response format:<br> <code>"data":{<br> "uid": "123",<br> "username": "jdoe",<br> "name": "John Doe",<br> "email": "jdoe@example.com",<br> "phone":{<br> 1: "1234567890",<br> 2: ""<br> }<br>}</code>
|
||||
| `userexists` | `username` | Returns a field `exists` which is true if the username exists or false if it does not. <br>Example response: `{"status":"OK", "exists":true}`
|
||||
| `hastotp` | `username` | Returns a field `otp` which is true if the user has 2-factor authentication setup or false if the user does not.
|
||||
| `verifytotp` | `username`, `code` | Checks if the given TOTP code is valid for the given user at the current time. Returns with `{"status":"OK","valid":true}` or `{"status":"ERROR","msg":"<error message>","valid":false}`.
|
||||
| `acctstatus` | `username` | Returns the account status in field `account` for the given username. Statuses are `NORMAL`, `LOCKED_OR_DISABLED`, `CHANGE_PASSWORD` (if password expired), `TERMINATED`, or `ALERT_ON_ACCESS` (like `NORMAL` except an alert email is sent to the system admin on successful login).
|
||||
| `login` | `username`, `password` | Simulates a system login, processing the account status, sending login alerts if needed, and noting a successful login in the security log. Returns a `status` of `OK` if it worked (with `"alert": true` if an admin alert was sent), or a `status` of `ERROR` if anything prevented a successful login.
|
||||
| `ismanagerof` | `manager`, `employee`, `uid` (optional) | Returns a boolean `managerof` which is true if `manager` is a manager of `employee` or false otherwise. If argument `uid` is present and equal to `1`, `manager` and `employee` will be treated as UIDs, else as usernames.
|
||||
| `getmanaged` | `uid` or `username` | Returns an array of UIDs in `employees` corresponding to the users the given account is a manager of.
|
||||
| `getmanagers` | `uid` or `username` | Returns an array of UIDs in `managers` corresponding to the users the given account is managed by.
|
||||
| `usersearch` | `search` | Searches for users with names or usernames containing the `search`. Returns them in `result` as an indexed array. <br>Response format:<br> <code>"result":[<br> {<br> "uid":"123",<br> "username":"jdoe",<br> "name":"John Doe"<br> },<br> {<br> "uid":"124",<br> "username":"jadoe",<br> "name":"Jane Doe"<br> }<br>]</code> <br>If `search` is less than three characters long, a search will not be attempted and `result` will be an empty array (`[]`). The `result` is also `[]` if no results are found.
|
||||
| `permission` | `uid` or `username`, `code` | Returns boolean `has_permission` if the given user has the given permission code. A list of valid permission codes are found in the database table `permissions`. Note: if a user has the `ADMIN` permission, this will always return true no matter what code is requested, because the user in question should have enough system access to give themselves the permission if so desired.
|
||||
|`mobileenabled`| None | Returns a boolean `mobile` to indicate the value of the config setting `MOBILE_ENABLED`.
|
||||
| `mobilevalid` | `username`, `code` | Returns a boolean `valid` to indicate if the supplied username and mobile code are valid.
|
||||
@ -0,0 +1,71 @@
|
||||
# System Requirements
|
||||
|
||||
Portal is tested and officially supported on the following configurations. Other systems may be supported at our discretion, possibly with an additional support fee. AccountHub and the other business apps should work on any sane Linux/PHP/SQL based web stack.
|
||||
|
||||
## Server
|
||||
|
||||
### Minimum Hardware
|
||||
|
||||
The Business Apps are very lightweight on server resources. The minimum supported hardware is a $35 Rasperry Pi 3 (1.2 GHz quad-core ARM CPU, 1GB RAM, 100Mbps Ethernet). Cloud VPS servers with as little as 512 MB RAM are fine too.
|
||||
|
||||
### Software and Operating System
|
||||
|
||||
* Server Operating System
|
||||
* Ubuntu 16.04
|
||||
* PHP
|
||||
* 7.0
|
||||
* 7.1
|
||||
* Database
|
||||
* MySQL 5.7+
|
||||
* MariaDB 10.0/10.1
|
||||
* Web Server
|
||||
* Apache 2.4
|
||||
|
||||
### Recommended Software
|
||||
For best performance, security, and ease of administration, we recommend installing the following on your server:
|
||||
|
||||
* Google's ModPageSpeed Apache module (on-the-fly caching and bandwidth optimization)
|
||||
* PHP's opcache (cached compiled PHP code for faster execution)
|
||||
* Fail2ban (if using SSH or other remote administration methods)
|
||||
* PHPMyAdmin (web-based MySQL/MariaDB server administration)
|
||||
* LetsEncrypt (automatic free SSL encryption setup)
|
||||
|
||||
## Client
|
||||
|
||||
The Business Apps are web-based and built with modern technologies. This means any machine capable of running a standards-compliant, modern, up-to-date web browser will run the Business Apps just fine.
|
||||
|
||||
### Officially Supported Operating Systems
|
||||
Note: This list is incomplete, as any OS capable of running one of the browsers from the list below will suffice.
|
||||
|
||||
* Linux
|
||||
* Ubuntu Linux 14.04, 16.04, and supported non-LTS releases
|
||||
* Ubuntu Derivatives (such as Linux Mint)
|
||||
* Debian 8 or 9
|
||||
* Android
|
||||
* 5.0 - 7.0 with Chrome, or
|
||||
* Any supported by Firefox, or
|
||||
* Any supported by the Business Apps for Mobile client
|
||||
|
||||
### Supported Operating Systems
|
||||
Any other operating system running a supported browser is also supported, but we may not provide support for issues not directly related to the Business Apps.
|
||||
|
||||
### Supported Screen Resolutions
|
||||
All screens with a viewport (the portion of the screen showing the app, in contrast to window borders, status bars, etc) having a resolution greater than 300x400 pixels will work, assuming use of a supported browser.
|
||||
|
||||
### Supported Web Browsers
|
||||
* Mozilla Firefox (54+)
|
||||
* Chrome/Chromium (latest and latest-1)
|
||||
* Android WebView (Android 5+)
|
||||
|
||||
### Unsupported Web Browsers
|
||||
While we do not support the following browsers, they will likely still work. You won't break anything by trying.
|
||||
|
||||
* Edge
|
||||
* Safari
|
||||
* Opera
|
||||
|
||||
### Known Incompatable Browsers
|
||||
These browsers are known to lack support for CSS rules, JavaScript APIs, and other technology required to run the Business Apps.
|
||||
|
||||
* Opera Mini
|
||||
* Internet Explorer
|
||||
@ -0,0 +1,73 @@
|
||||
# User Documentation
|
||||
|
||||
## Logging In
|
||||
|
||||
1. Go to the address of the AccountHub server in your web browser (Firefox, Chrome, etc.). This address will be supplied by your IT staff or Netsyms Business Support.
|
||||
2. Enter your username and password.
|
||||
* Do not enter your email address.
|
||||
* Passwords are case-sensitive.
|
||||
3. If you have setup a 2-factor authentication app, AccountHub will ask you for a code. Open the app on your phone or other device and type the displayed code.
|
||||
* The code changes every 30 seconds. If you don't submit the code in that time window, it will be considered incorrect and you will have to go back to step 2.
|
||||
4. You are now logged in.
|
||||
|
||||
### Login Troubleshooting
|
||||
There are some common error messages you may see while logging in. Here's what they mean annd what you can do about them.
|
||||
|
||||
* __Login incorrect.__
|
||||
This means you have entered an incorrect username or password. Try again.
|
||||
* __Authentication code incorrect.__
|
||||
The 2-factor authentication code you entered was either wrong or expired. Log in and try again.
|
||||
* __This account has been disabled. Contact technical support.__
|
||||
Your account has been marked as disabled by your IT staff. Contact them to resolve the issue.
|
||||
* __Account terminated. Access denied.__
|
||||
The user account has been closed by your IT staff. Contact them to resolve the issue.
|
||||
* __Your account state is not stable. Log out, restart your browser, and try again.__
|
||||
Your account is not syncronized between the Portal server and the Active Directory domain controller. Log out (if you are logged in), close your web browser, and start over. If you continue to see this error, try clearing your cookies and cache or contact your IT department.
|
||||
* __You must change your password before continuing.__
|
||||
Your password has been marked by IT staff or an automatic process as requiring a reset before you can log in.
|
||||
|
||||
### Changing your Password during Login
|
||||
If your password has expired, you will need to change it before logging in. Type your current password and new password where prompted on the screen. You will need to type your new password twice. Press Continue. If your current password is correct, you entered the new password correctly, and your new password meets the security requirements, your password will be updated and you will be able to login as usual.
|
||||
|
||||
## Home Page (Dashboard)
|
||||
The dashboard, or home page, is what you will see after logging in. It shows you a brief overview of your account, with information taken from all the different Business Apps.
|
||||
|
||||
### Using the Dashboard
|
||||
|
||||
There are various "widgets" on the dashboard. They display relevant information from the other Business Apps. You can use them to quickly view important information or perform common tasks, such as viewing assigned tasks from TaskFloor or punching in or out with QwikClock.
|
||||
|
||||
### Navigating between apps
|
||||
|
||||
Near the top of the dashboard, you will see a row of icons. You can click on these icons to go to other apps. To return to the dashboard from the other apps, click your name in the bar near the top of the screen.
|
||||
|
||||
## Account Options
|
||||
|
||||
To manage account options, click on Account Options in the top bar of AccountHub.
|
||||
|
||||
### Sync Mobile App
|
||||
|
||||
If you wish to access the Business Apps from your smartphone or tablet, you can download Business Apps for Mobile on your device. The first time you open the app, you will be told to scan a sync code.
|
||||
|
||||
#### Pairing the Mobile App
|
||||
To generate a sync code, go to Account Options in AccountHub, and press `Create new sync code` under `Sync Mobile App`. Follow the instructions on your smartphone or tablet to scan the code and finish the setup process. If you cannot scan the code for whatever reason, press `Manual Setup` on your phone and type the details shown below the sync code in AccountHub.
|
||||
|
||||
#### Unpairing the Mobile App
|
||||
From your Account Options in AccountHub, press the red trash can icon next to the sync key. The mobile app will no longer work until it is re-paired with a new key.
|
||||
|
||||
If your phone or tablet was lost or stolen, you should also change your password, because the password is stored on the phone or tablet to facilitate automatic login. If your phone or tablet was not lost or stolen, you should open the settings in Business Apps for Mobile and clear all saved data.
|
||||
|
||||
#### Updating your Password
|
||||
The mobile app saves your password so you don't have to type it every time. If you change your password, you will need to tell the mobile app the new password. Open the app settings, press the proper button, and enter your new password.
|
||||
|
||||
### Change Password
|
||||
Type your current password and new password where prompted on the screen. You will need to type your new password twice. Press `Change password`. If your current password is correct, you entered the new password correctly, and your new password meets the security requirements, your password will be updated.
|
||||
|
||||
### Setup 2-factor authentication
|
||||
|
||||
2-factor authentication, or 2FA, is the security practice of using a continually-changing code to make it much harder to hack in to an account. The Business Apps support TOTP, a common 2FA method. With 2FA enabled, you will be asked for a six-digit code in addition to your password. This code will be shown on an app on your phone or other device, and changes every 30 seconds.
|
||||
|
||||
#### Enable 2FA
|
||||
To setup TOTP 2-factor authentication, download an app such as Google Authenticator on your phone. In AccountHub, press `Enable 2-factor authentication`, add the barcode with your mobile authenticator app, and press `Finish setup` in AccountHub.
|
||||
|
||||
#### Disable 2FA
|
||||
To disable 2FA, press `Disable 2-factor authentication` from the Account options in AccountHub. If you are unable to log in due to not having a 2FA code, tech support can remove 2FA from your account for you.
|
||||
@ -1,14 +1,20 @@
|
||||
# Portal
|
||||
# <img src="http://cdn.netsyms.com/images/products/accounthub/logo.svg" style="width: 100px; max-width: 50%; border: 1px solid grey; border-radius: 20%; padding: 3px;" /> AccountHub
|
||||
|
||||
Portal is a web application enabling secure self-serve account management. Employees can change their password and manage other web apps they have access to with the dashboard.
|
||||
AccountHub is a web application enabling secure self-serve account management. Employees can change their password and manage other web apps they have access to with the dashboard.
|
||||
|
||||
## Features
|
||||
|
||||
* __Active Directory integration__
|
||||
* Transparently manages LDAP and local accounts simultaneously.
|
||||
* Transparently manages AD and local accounts simultaneously and transparently.
|
||||
* __2-factor authentication__
|
||||
* Use both a password and a device to add an extra layer of security.
|
||||
* Allows users to setup both a password and an authentication device to add an extra layer of security.
|
||||
* __reCAPTCHA integration__
|
||||
* Prevents automated brute-force and dictionary attacks while legitimate users simply check a box while logging in.
|
||||
* __Detailed security logs__
|
||||
* Records every login attempt, password change, invalid CAPTCHA, or other security-related activity, tracking client IP address and activity timestamp.
|
||||
* __Easily-extendable dashboard__
|
||||
* Add additional dashboard widgets with as little as five lines of code, for easy access to and overviews of other applications
|
||||
* Add additional dashboard widgets with as little as five lines of code, for easy access to and overviews of other applications.
|
||||
* __Modern__
|
||||
* Portal uses the latest open web technology to provide a seamless, uniform user experience on phones, tablets, desktops, and laptops, from anywhere in the world.
|
||||
* AccountHub uses the latest open web technology to provide a seamless, uniform user experience on phones, tablets, desktops, and laptops, from anywhere in the world.
|
||||
* __For users and IT__
|
||||
* Users will appreciate how easy it is to manage their accounts, while tech support won't have as many login-related tickets to deal with.
|
||||
@ -1,14 +0,0 @@
|
||||
# System Requirements
|
||||
|
||||
Portal is tested and officially supported on the following configurations. Other systems may be supported at our discretion, possibly with a support fee. Portal should work on any sane PHP/SQL based web stack.
|
||||
|
||||
* Server Operating System
|
||||
* Ubuntu 16.04
|
||||
* PHP
|
||||
* 7.0
|
||||
* 7.1
|
||||
* Database
|
||||
* MySQL 5.7+
|
||||
* MariaDB 10.0/10.1
|
||||
* Web Server
|
||||
* Apache 2.4
|
||||
@ -1,25 +0,0 @@
|
||||
# Logging In
|
||||
|
||||
1. Go to the address of the Portal server in your web browser (Firefox, Chrome, etc.). This address should be supplied by your IT staff.
|
||||
2. Enter your username and password.
|
||||
* Do not enter your email address.
|
||||
* Passwords are case-sensitive.
|
||||
3. If you have setup a 2-factor authentication app, Portal will ask you for a code. Open the app on your phone or other device and type the displayed code.
|
||||
* The code changes every 30 seconds. If you don't submit the code in that time window, it will be considered incorrect and you will have to go back to step 2.
|
||||
4. You are now logged in.
|
||||
|
||||
# Login Troubleshooting
|
||||
There are some common error messages you may see while logging in. Here's what they mean annd what you can do about them.
|
||||
|
||||
* __Login incorrect.__
|
||||
This means you have entered an incorrect username or password. Try again.
|
||||
* __Authentication code incorrect.__
|
||||
The 2-factor authentication code you entered was either wrong or expired. Log in and try again.
|
||||
* __This account has been disabled. Contact technical support.__
|
||||
Your account has been marked as disabled by your IT staff. Contact them to resolve the issue.
|
||||
* __Account terminated. Access denied.__
|
||||
The user account has been closed by your IT staff. Contact them to resolve the issue.
|
||||
* __Your account state is not stable. Log out, restart your browser, and try again.__
|
||||
Your account is not syncronized between the Portal server and the Active Directory domain controller. Log out (if you are logged in), close your web browser, and start over. If you continue to see this error, try clearing your cookies and cache or contact your IT department.
|
||||
* __You must change your password before continuing.__
|
||||
Your password has been marked by IT staff as requiring a reset before you can log in.
|
||||
@ -1,2 +1,4 @@
|
||||
site_name: Portal Docs
|
||||
site_name: AccountHub Docs
|
||||
theme: 'readthedocs'
|
||||
site_author: Netsyms Technologies
|
||||
copyright: Copyright © 2017 Netsyms Technologies. All rights reserved. Copying is allowed for instructional purposes (such as creating an internal user help document) as long as credit is given and this copyright notice is included. For other purposes, or if you are selling a product containing copied material, please <a href="https://netsyms.com/contact" target="_BLANK">contact us</a> for permission.
|
||||
|
||||
Loading…
Reference in New Issue