IPS Connect is a cross-domain single sign on and single point of authentication system that allows login credentials to be shared across multiple web applications. Furthermore, basic member management is also shared across those separate installations allowing you to manage users in one website and have those changes propagate to all of your other websites. While the IPS Community Suite natively supports IPS Connect with minimal configuration from the administrator, developers can also add IPS Connect integration capabilities to their own web applications as well. This document outlines how to use IPS Connect within the Community Suite, as well as how to develop both "master" and "slave" IPS Connect applications.
While all changes propagate to all installations that are connected with IPS Connect, one installation will always act as the "master" and all of the remaining installations in the network act as the "slave". When any requests that are a part of IPS Connect are made by a slave application, they are always sent to the master application. The master application is then responsible for calling to all of the slave installations to notify them of any changes they need to be aware of (which means the master application must maintain a database of all slave applications that are connected). If you have an established site and a new site, the established site should be the master installation, and the new site should be the slave.
Requests that are propagated with IPS Connect include:
Logging in: login requests are processed by the master application and credentials are shared across all sites in the network.
Single sign on: when a user signs in to one application they will be signed in to all other applications, even if those other applications live on different domains.
Logging out: When you log out of one application you are logged out of all applications.
Registering: When a new user account is added, it is added to all sites in the network.
Changing usernames, email addresses and passwords: These requests are propagated to all sites in the network. (Note: you can disable username changes from being shared amongst sites in the Community Suite - see below for details).
Banning users: When you ban a user on one site, the user is banned on all sites.
Account validation: If a user has registered and you require account validation, that user will be required to validate their account before they can access any site in the network as a fully registered user.
Account deletion: If a user is deleted, they will be deleted on all sites across the network.
Account merges: If two user accounts are merged, the merge will be copied to all sites in the network.
TIP: You can disable username changes from propagating to all sites within a network. This can be useful when you want to share login credentials amongst all of your sites, but want user accounts to otherwise appear to be separate. To do this with the Community Suite you must create a file called constants.php in your root directory (where index.php is), or edit the existing one if it already exists. Paste the following code into the constants.php file (if you are editing an existing file, omit the opening <?php tag):
Warning
Be aware that IPS Connect in IP.Board 3.x and IPS Connect in the 4.0 Community Suite are not compatible. While we strived to make the upgrade process painless, the need to expand and improve IPS Connect meant that the 3.x API calls could no longer be processed while adding multiple new features to the set of existing features.
Using IPS Connect in the IPS Community Suite
To use IPS Connect with two or more IPS Community Suite installations, you must first choose which installation will be the master and which installation(s) will be the slave(s). Visit the Admin Control Panel of the master application and navigate to the System tab -> Login Handlers. At the top of the page you will see a notice that tells you credentials you must use in order to notify other IPS Community Suite installations that this is the master.
There is no "setup" required to make a Community Suite installation the master IPS Connect installation.
To set up slave applications in the network, visit the Admin Control Panel of each slave individually and navigate to the same area (System -> Login Handlers). Next to the IPS Connect login method, click on the pencil icon. Here you will be asked for the Master IPS Connect URL and Master IPS Connect Key that you will have retrieved from the master installation previously. You will also be asked if you wish to accept display names or email addresses for the login identifier, or both, and if you want to allow IPS Connect authentications to provide access to the admin control panel if the local user account is marked as an administrator.
After providing the required information and saving this form, you should click the "Disabled" badge in order to enable the IPS Connect login handler, and then you should drag-n-drop the IPS Connect handler to the top of the list to make it the primary login method. This ensures that IPS Connect is checked first before the Community Suite falls back to the local database to validate a login attempt.
Setting up IPS Connect with your Community Suite is complete at this point. You can repeat the above steps on any other installations you wish to connect to your network.
Creating "master" IPS Connect applications
Your master IPS Connect application will be required to accept API calls from slave IPS Connect applications and respond to them accordingly, and to then propagate changes from those calls to any other slaves in the network. You must supply a unique key for your master application (which can be anything you want but must be unique to this installation) and the URL to the gateway API file that you will create to all slave applications. The master application secret key should be kept private and never be made public.
You must create a gateway file that slave applications will call to. These applications will send requests to your gateway file and will expect a response in JSON format to those requests (except for certain requests which result in redirection as outlined later in this document). Your master application will need to implement the API requests outlined below, accepting the expected GET parameters and responding with the outlined Response status code and parameters. Finally, the master application will also need to propagate the requests to all slave applications in its network (and thus needs to maintain a database of all slave applications that have connected with it).
The IPS Community Suite when acting as a master IPS connect application implements a queue system for requests to slave applications. If a request that should be propagated to a slave fails, it is inserted into a queue and reattempted at a later time. Any repeated failures are reported to the administrator via an ACP dashboard plugin. The requests will be automatically reattempted, or you can manually reattempt the requests from the dashboard.
While this system is not necessary in a master application, it can help to ensure data consistency across an IPS Connect network. If the master application ignores failures to a slave application, then email changes, name changes, password changes and more may not be propagated if a temporary error occurs.
Note that as the IPS Connect API is a public API, while the master key is required to communicate with it, you may wish to implement brute force protection against multiple subsequent login requests. This can help protect against brute force attempts made against slave applications that do not natively support such protection.
If a slave application no longer wishes to communicate with a master application, it should respond with a status of DISABLED when a request is propagated to it. If this happens, the master application should disassociate the slave application and cease sending further requests to it.
Creating "slave" IPS Connect applications
Slave IPS Connect applications will need to send requests for specific actions via an HTTP REST API call to the IPS Connect master installation. This means that you will need to obtain the URL and API key from your IPS Connect master installation and supply this to your slave application, and then when a user attempts to perform one of the actions outlined at the top of this article your login routines should make API calls to the master application in order to perform and validate those actions. Be aware: Some requests result in redirecting the user to one or more websites before returning the user to a URL you supply. See the crossLogin method outlined below for an example. For most requests, however, you will receive a JSON response which will need to be decoded and examined.
If you issue a login request, for instance, you will receive a response with a status code and then some additional information such as the email address, username and unique ID on the network. Most slave applications will then create a local user record with this data if the user account does not exist, or update the local user record if the account does exist (using the unique ID to match up user accounts if possible, or falling back to matching accounts by email address). This is not, however, a requirement.
Note: After making a login request to the master installation, an IPS Connect slave should then call the crossLogin request at the master installation in order to ensure the user is logged in to all websites in the IPS Connect network. This method will result in the user being redirected to all installations in the network, and then finally back to a URL supplied by the local slave application.
All account changes must be sent to the master installation to ensure data consistency across the network. If a user changes their email address and this account change is not sent to the master application, for instance, the user will no longer be able to login correctly on other sites in the network.
Additionally, all slave applications must accept the same requests and respond accordingly just as the master would, as the master application must propagate requests to each slave in the network. For instance, consider the following work flow:
User changes their email address on SLAVE 1. SLAVE 1 sends this request to the MASTER. The MASTER, in turn, sends the request to SLAVE 2 and then to SLAVE 3. In this case, even though SLAVE 2 and SLAVE 3 are slave applications, they must accept the same requests the master accepted in order to allow them to update their local databases.
API Request Details
Master IPS Connect applications will need to accept the following requests and respond accordingly with the response parameters outlined for each request. It will also need to propagate the requests to each slave in its network, differentiating the requests with a "slaveCall=1" request parameter. Slave IPS Connect applications will need to call the following API endpoints against the master IPS Connect installation it is communicating with, and additionally accept the same API request calls (differentiated with a slaveCall=1) in order to accept and make changes to the local database when changes are made at a remote website in the Connect network.
The following GET request parameters will always be included:
do: This is the action to perform, as outlined below.
key: This is the secure key and should be validated to ensure it matches the secure key supplied to the slave application.
url: This is the URL to the slave application.
Other GET request parameters will be sent and will vary depending upon the request. All requests from the master installation to slave installations will also include
slaveCall: Always set to '1', this allows the slave application to know that the request is coming from a master application and is intended to result in the local database being updated.
Important Note: If 'id' is passed in the request to make a change to a specific user account, the 'key' value will be an MD5 hash of the master application's key concatenated with the id. For instance
All responses will include a 'status' key in the JSON response. Some responses may include additional information. You should verify the 'status' response is SUCCESS to ensure the action completed successfully. Invalid requests will have a status of INVALID_ACTION. Slave applications that no longer wish to be a part of the network (i.e. if IPS Connect is disabled at this installation) should respond with a status of DISABLED.
Example:
Method: verifySettings
This method is intended to allow a slave application to verify the settings of the master (i.e. when the master key is first provided) and to "register" with the master installation. This allows the master installation to propagate requests to slave applications later.
GET parameters:
ourKey: [Required] This is a unique key associated with the slave
Response status codes:
SUCCESS
Response parameters: None
Method: fetchSalt
Call this method in order to fetch a user's password salt - necessary for allowing the local application to hash the user's credentials properly before sending them to the master.
GET parameters:
idType: [Required] What type of ID is being passed (a value of 1 indicates the id is a display name, a value of 2 indicates the id is an email address and a value of 3 indicates the value could be either a display name OR an email address)
id: [Required] The user ID
Response status codes:
SUCCESS
REQUEST_MISSING_DATA: This indicates either idType or id was not provided
ACCOUNT_NOT_FOUND: No account was found based on the supplied value
Response parameters:
pass_salt: The salt applied to the password when hashing it
Method: login
This method authenticates a user and logs the user into all applications on the IPS Connect network.
GET parameters:
idType: [Required] What type of ID is being passed (a value of 1 indicates the id is a display name, a value of 2 indicates the id is an email address and a value of 3 indicates the value could be either a display name OR an email address)
id: [Required] The user ID
password: [Required] The encrypted password
NOTE:
The 'password' parameter must be encrypted in the same manner as the IPS Community Suite. A request should first be sent to fetch the user's salt (see fetchSalt above), and then the password should be hashed in the following manner:
$2a$13$ refers to the salt prefix and a pre-determined cost factor that should not be altered.
Response status codes:
SUCCESS
REQUEST_MISSING_DATA: This indicates either idType or id was not provided
WRONG_AUTH: This indicates that the provided credentials could not be authenticated. This may mean that no account exists with the id provided or that the password is not valid.
Response parameters:
connect_status: VALIDATING if the account is still validating or SUCCESS otherwise
email: The member's email address
name: The member's display name
connect_id: The member's unique integer ID on the master installation
connect_revalidate_url: If the member is VALIDATING, the URL that any slave application's should send the user to in order to complete their validation
Method: crossLogin
When a user logs in to a slave application successfully, they will be redirected to the crossLogin method of the master application in order to be logged in to it and all other slave applications on the network. This is necessary to work around cross-domain cookie restrictions. The master install will need to redirect the user to each slave's crossLogin method, and will also need to log the user in to the master application, before returning the user to the originating URL (the original slave application the user logged in to).
GET parameters:
id: The member's unique integer ID on the master installation
returnTo: a URL to return the user to once the user has been logged on.
NOTE:
When the master application redirects the user to slave applications to log the user on, the returnTo URL should be compared to the url parameter in order to ensure the user is not sent to the originating slave. When sending the user to another slave in the network, the returnTo parameter should be set to the master URL. Further, the master application should set a 'slaveCall' parameter to 1 when calling slave applications to prevent them from performing extra work (this allows slave applications to know that the request is from the master and to perform specific duties).
Response status codes: None, the user will be redirected to the returnTo URL
Response parameters: None
Method: logout
API calls to the logout method are designed to log the user out of the master application as well as all of the slave installations.
GET parameters:
returnTo: The URL to return the user to once they have been logged out
id: The member's unique integer ID on the master installation
NOTE:
Much like the crossLogin method, the logout method should redirect the user to all slave applications to log the user out and then log the user out of the master application before returning the user to the originating installation. slaveCall is passed in the URL when the master calls slave applications to differentiate requests between master and slave applications.
Response status codes: None, the user will be redirected to the returnTo URL
Response parameters: None
Method: register
Register the user on all installations in the Connect network
GET parameters:
name: The member's name
email: The member's email address
pass_hash: The member's password hash
pass_salt: The member's password salt
revalidateUrl: The URL to send the user to if they are validating and attempt to login to any other site in the connect network
NOTE:
The 'pass_hash' parameter must be encrypted in the same manner as the IPS Community Suite. The password should be hashed in the following manner:
Response status codes:
SUCCESS
REQUEST_MISSING_DATA: This indicates email, name, pass_salt or pass_hash was not passed
Response parameters:
connect_id: The member's unique integer ID on the connect network
Method: validate
Call this method in order to mark a user's account as validated. If a user account is marked as awaiting validation and the user validates, this should be called to ensure the user account is marked as validated across the entire network.
GET parameters:
id: [Required] The unique user ID of the user account
Response status codes:
SUCCESS
Response parameters: None
Method: delete
Call this method in order to delete a user account. THERE IS NO UNDOING THIS ACTION.
GET parameters:
id: [Required] The unique user ID of the user account
Response status codes:
SUCCESS
Response parameters: None
Method: ban
Call this method in order to ban or unban a user account
GET parameters:
id: [Required] The unique user ID of the user account
status: [Required] A value of 1 will ban the user account while a value of 0 will unban the user account
Response status codes:
SUCCESS
Response parameters: None
Method: merge
Call this method in order to merge two distinct user accounts into one. THERE IS NO UNDOING THIS ACTION.
GET parameters:
id: [Required] The unique user ID of the account you wish to keep
remote: [Required] The unique user ID of the account you wish to remove
Response status codes:
SUCCESS
Response parameters: None
Method: checkEmail
Call this method in order to check if an email exists at the master application. This can be useful to prevent a user who has already registered elsewhere on the Connect network from registering again on a local site, when they should instead login.
GET parameters:
email: [Required] The email address to check
Response status codes:
SUCCESS
Response parameters:
used: 1 if the email address is in use or 0 if not
Method: checkName
Call this method in order to check if a username exists at the master application. This can be useful to prevent a user who has already registered elsewhere on the Connect network from registering again on a local site, when they should instead login. It is not necessary to enforce uniqueness of display names in your application if your application has a need to allow multiple user accounts with the same display name to exist, however you should never allow logging in by 'display name' if this is the case.
GET parameters:
name: [Required] The name to check
Response status codes:
SUCCESS
Response parameters:
used: 1 if the name is in use or 0 if not
Method: changeEmail
This method is called when an existing user's email address should be updated to a new value.
GET parameters:
email: [Required] The new email address to use
id: [Required] Unique user ID provided by the master application to a previous login or registration call
Response status codes:
SUCCESS
REQUEST_MISSING_DATA: The new email address to use was not supplied
EMAIL_IN_USE: The new email address is already being used by another account
Response parameters: None
Method: changePassword
This method is called when a user has updated their password
GET parameters:
pass_salt: [Required] Password salt
pass_hash: [Required] Password hash
id: [Required] Unique user ID provided by the master application to a previous login or registration call
NOTE:
The 'pass_hash' parameter must be encrypted in the same manner as the IPS Community Suite. The password should be hashed in the following manner:
Response status codes:
SUCCESS
REQUEST_MISSING_DATA: The password salt or password hash was not supplied
Response parameters: None
Method: changeName
This method is called when an existing user has changed their display name at a local installation
TIP: You can disable username changes from propagating to all sites within a network. This can be useful when you want to share login credentials amongst all of your sites, but want user accounts to otherwise appear to be separate. To do this with the Community Suite you must create a file called constants.php in your root directory (where index.php is), or edit the existing one if it already exists. Paste the following code into the constants.php file (if you are editing an existing file, omit the opening <?php tag):
If this is done on a slave IPS Community Suite application, that slave (only) will ignore username change requests and will not send username changes to the master application. If the above constant is set on a master IPS Community Suite application, username change requests will not be propagated to any slaves in the network. You should carefully consider your intentions if you decide to make the change above.
GET parameters:
name: [Required] The new name to use
id: [Required] Unique user ID provided by the master application to a previous login or registration call
Response status codes:
SUCCESS
REQUEST_MISSING_DATA: The new name to use was not supplied
USERNAME_IN_USE: The new name is already being used by another account
Response parameters: None
Plugging in to your existing master application
If you are using IPS Community Suite as a master application and wish to extend or change its functionality, you can easily do so without having to edit any PHP files, ensuring your customizations are retained through future upgrades. The master IPS Connect gateway with the IPS Community Suite is found at /applications/core/interface/ipsconnect/ipsconnect.php. You can create a new file in this same location called "custom.php" with a class inside this file called ipsConnect_custom, extending ipsConnect. This file will be automatically loaded if it exists, and the ipsConnect_custom class will be instantiated instead of ipsConnect. From there, you can override any methods you need to.
As an extension to this, the following methods can be defined which will be called automatically:
_postCrossLogin(): Because cross login requests result in redirection instead of returning a response to output in JSON format, this method is supported which allows you to perform any custom actions you require before the redirection occurs.
_postCrossLogout(): Because logout requests result in redirection instead of returning a response to output in JSON format, this method is supported which allows you to perform any custom actions you require before the redirection occurs.
Example: