Help Center
Guides
IPS Connect
Guide added by Charles Warner, Nov 08 2012 11:55 AM (Updated Apr 16 2013 03:40 PM)
IPS Connect provides a simple solution for any application to to implement single sign-on (SSO) with other IPS Connect compatible applications.
In an IPS Connect network, there will be one "master" application and any number of "slave" applications.
The IPS Community Suite (versions 3.4 and above), can serve as either a master or a slave in an IPS Connect network.
This article will show you how to connect two IPS Community Suite installations using IPS Connect.
Before you set up, you will need to decide which installation will be the master, and which will be the slave.
Generally speaking, when setting up an IPS Connect network, the "new" installation (which does not have any existing user data) should be the slave. If you are connecting two installations which both have existing user data, it doesn't matter which is the master and which is the slave.
Important Information about Single Sign-On
In order for Single Sign-On to work properly, the slave application(s) need to read cookies set by the master application.
Since cookies cannot be read across domains, this means that your slave application needs to be on the same domain or a subdomain of the domain that the master application is on.
For example, your master application might be mysite.com, and the slave application might be something.mysite.com.
It will not work if the master application is on mysite.com and the slave application is on somethingelse.com.
Obtaining the URL and Key from the Master
Once you have decided which will be the master, you will need to obtain two pieces of information from it - the IPS Connect URL, and the IPS Connect Key.
This information can be obtained from Admin CP --> System --> Log In Management.
Setting up the slave
To set up your IPS Connect network, you simply need to input this information into the Admin CP on your slave installation.
To do this:
If your slave application does not already have member data, you can disable the "IPB Internal" method completely - this is the recommended set up if possible in your circumstances.
To do this, simply disable the "IPB Internal" method in the same way that you enabled the "IPS Connect" method.
If you are not sure which installation to make the master and which the slave, or are not sure if you can disable the IPB Internal method, or have any problems setting up IPS Connect, please contact technical support.
Troubleshooting
If your IPS Connect integration doesn't seem to be working, your cookie settings are probably in conflict.
For each community in the network, go to Admin CP --> System --> System Settings --> Server Environment and fill in a value for the "Cookie Prefix" setting.
Information for Developers
IPS Connect provides a simple solution for any application to to implement single sign-on with other IPS Connect compatible applications.
In an IPS Connect network, there will be one "master" application and any number of "slave" applications.
The IPS Community Suite (versions 3.4 and above), can serve as either a master or a slave in an IPS Connect network.
To make your application IPS Connect compatible, you first need to decide if you will make it the master or the slave.
Generally speaking, when setting up an IPS Connect network, the "new" application (which does not have any existing user data) should be the slave.
If you are connecting two applications which both have existing user data, it is usually best to make the IPS Community Suite the slave and your custom application the master, as the IPS Community Suite already has support for local fallbacks.
Developers: Creating a Master
This article will take you through the coding necessary to make any 3rd party website or application IPS Connect compatible as a master application.
An example website which is ready to serve as a master application is attached below - see the readme.txt file within for instructions to set up.
master.zip 35.61K
217 downloads
Introduction
As a master application, you will create a public API for slave applications to handle logins, log outs, registrations and account changes. This will all be done through a single file calls ipsconnect.php.
In order for slave applications to use this API, they will need to know the URL to this file and a secret key which is known only to your application (the key can be anything you want, but it must be unique to your master installation).
It is important that your application does not ever reveal the key publicly.
You can start with this sample structure for your ipsconnect.php file:
ipsconnect.php 10.95K
236 downloads
Before you get started
You will notice in the sample ipsconnect.php file that there are two places where a cookie is set - when the user logs in and logs out.
You must ensure that wherever your application handles local log ins and log outs that this cookie is set.
The cookie name is "ipsconnect_" followed by an md5 hash of the Master URL. For example, if the Master URL was http://www.example.com/ipsconnect.php - you'd be setting a cookie with the name "ipsconnect_43fff52f2fc1ae40d522dcfd9bc51b40".
When the user successfully logs into your application, you should set this cookie to the value "1", and when they log out, set it to "0".
Make sure you set the cookie to be available to the whole domain, not a subdomain or to a particular path.
Accommodating existing logins
When a user visits one of your slave applications, if the ipsconnect_xxxx cookie is set, the slave application will contact your application to verify if the user can be automatically logged in.
You will accommodate this using the "cookies" method in your ipsconnect.php file.
The parameters the method receives and the expected output are documented in the example ipsconnect.php. For a working example, see the sample application.
Note: the same application does not handle validating accounts. If your application has a concept of waiting for email validating, or the account was created by a "register" call which set the "revalidateurl" parameter, you should return "VALIDATING" for "connect_status" and the URL where the user can resend the validation email for "connect_revalidate_url".
Accommodating new logins
When a user logs into a slave application having not been previously logged into the IPS Connect network, an API call and/or direct POST request will be made to your ipsconnect.php file which needs to validate the user's credentials and log them in as necessary.
You will accommodate this using the "login" method in your ipsconnect.php file.
The parameters the method receives and the expected output are documented in the example ipsconnect.php. For a working example, see the sample application.
Note: It is recommended that brute-force protection is used as this is a public API. The example application does not do this. For an example of working brute-force protection, see the ipsconnect.php file in the IPS Community Suite (located under /interface/ipsconnect/).
Note: the same application does not handle validating accounts. If your application has a concept of waiting for email validating, or the account was created by a "register" call which set the "revalidateurl" parameter, you should return "VALIDATING" for "connect_status" and the URL where the user can resend the validation email for "connect_revalidate_url".
Accommodating Logouts
When a user logs out on a slave application, a direct POST request will be made to your ipsconnect.php file which needs to log the user out.
You will accommodate this using the "logout" method in your ipsconnect.php file.
The parameters the method receives and the expected output are documented in the example ipsconnect.php. For a working example, see the sample application.
Accommodating Registrations
When a user registers an account on a slave application, 2 API calls will be made to your ipsconnect.php file - one to check that the requested username/email address is available, and one to register the account.
You will accommodate this using the "check" and "register" methods in your ipsconnect.php file.
The parameters the methods receive and the expected output are documented in the example ipsconnect.php. For a working example, see the sample application.
Note: the sample application does not facilitate validating accounts. If the "revalidateurl" parameter is sent, you should save this as it will be needed in your responses to the "login" and "cookie" functions.
Accommodating Account Changes
When a user updates their username, displayname, email address or password on slave application, an API call and/or direct POST request will be made to your ipsconnect.php file which needs to update it's database as necessary.
You will accommodate this using the "change" method in your ipsconnect.php file.
The parameters the method receives and the expected output are documented in the example ipsconnect.php. For a working example, see the sample application.
Accommodating Validations
Some applications (including the IPS Community Suite) have a concept of accounts which are pending validation. If so, the registration includes the "revalidateurl" parameter.
When an account is validated, an API call will be made to your ipsconnect.php file which needs to update it's database as necessary.
You will accommodate this using the "validate" method in your ipsconnect.php file.
The parameters the method receives and the expected output are documented in the example ipsconnect.php.
Accommodating Deletes
When an account is deleted, an API call will be made to your ipsconnect.php file which needs to update it's database as necessary.
You will accommodate this using the "delete" method in your ipsconnect.php file.
The parameters the method receives and the expected output are documented in the example ipsconnect.php.
Developers: Creating a Slave
This article will take you through the coding necessary to make any 3rd party website or application IPS Connect compatible as a slave application.
An example website which is ready to serve as a slave application is attached below - see the readme.txt file within for instructions to set up.
slave.zip 33.75K
215 downloads
Introduction
As a slave application, you will be relying on the master application to handle logins, log outs, registrations and account changes.
While you will maintain a local database, all these actions will go through the IPS Connect master application.
You will also use the IPS Connect master application to automatically log users in. In order to do this, you need to be able to read cookies set by the IPS Connect master application.
Since cookies cannot be read across domains, this means the two applications must be on the same domain, or your slave application must be on a subdomain of the domain the master application is on.
If this is not possible, you can still use IPS Connect, but automatic login will not be available.
Before you start, you need two pieces of information from the IPS Connect master application.
Firstly, a URL to the ipsconnect.php file - this is the file you will call for all callbacks to the master.
Secondly, you need the installation's IPS Connect key.
If your master application is an IPS Community Suite installation, both the URL and the key can be obtained from Admin CP --> System --> Log In Management.
It is important that your application does not ever reveal the IPS Connect key publicly.
Checking for existing logins
When a user visits your application, you should examine their cookie data to see if they have an IPS Connect login and handle this appropriately.
Look for a cookie with the name "ipsconnect_" followed by an md5 hash of the Master URL. For example, if the Master URL was "http://www.example.com/ipsconnect.php" - you'd be looking for a cookie with the name "ipsconnect_43fff52f2fc1ae40d522dcfd9bc51b40".
If this cookie is set and has the value of "0" - this means that the user has expressly logged out of the IPS Connect network, and you should ensure that they are not logged in to your application.
If the cookie is not set, or it's value is "1" you should do your normal local checks to verify if the user is logged in (that is, examine your local cookies).
If you cannot validate the user as being logged in, look at the "ipsconnect_xxxx" cookie again - if it's value is "1", this means that the user is logged into the IPS Connect network, and so you need to check with the IPS Connect network to see what account is logged in.
To do this, send a HTTP GET request to the master application's ipsconnect.php file with the following parameters:
You should ensure that you only call the IPS Connect master application once per session, so make sure you set whatever local cookies necessary for the user to be logged in automatically without this API call on future page loads.
Here's an example of what the flow will look like - see the example application for a working example:
Special Note Regarding Passwords
The passwords in IP.Board and IPS Connect are run through the IP.Board input cleansing routines, meaning certain characters have been replaced with HTML entities. If your external application does not do the same thing, this may mean passwords with special characters will fail if you do not account for this. The special characters that IP.Board will replace are:
If a user is not already logged into the IPS Connect Network, logging in through your application needs to log them into the entire network.
To do this, once the user has submitted the login, send a HTTP GET request to the master application's ipsconnect.php file with the following parameters:
If you cannot locate a user locally, send the request with either the username or email address.
The IPS Connect master application will respond with a JSON object with the following parameters:
If connect_status is SUCCESS, you should first do the same as you do for the cookie check - create or update the account as necessary.
Then redirect the user to the master application's ipsconnect.php file with the same parameters you sent in the request, plus two additional parameters:
When the master application passes the user back, it will add the same parameters that it initially responded with to the GET data of the redirect URL. To stop it doing this, pass the additional parameter 'noparams' with a value of '1'.
Here's an example of what the flow will look like - see the example application for a working example:
Handling Logouts
When a user logs out of your application, you should redirect them tothe master application's ipsconnect.php file with the following parameters:
In practice, it is better to destroy your local cookies before redirecting the master application.
Handling Registrations
When a user creates an account on your application, you need to inform the IPS Connect master application to create the user locally.
Before you accept a registration you must first check with the IPS Connect master application that the requested username/email address is available.
To do this, send a HTTP GET request to the master application's ipsconnect.php file with the following parameters:
If your application has a concept of validating accounts (i.e. the user must click a link in an email before their account is "activated"), you must send an additional HTTP GET request to the master application's ipsconnect.php file when the user validates their account. Send the following parameters:
Handling Account Changes
Whenever the user changes their username, display name, email address or password on your local application, that you contact the master application to update it's database.
To do this, send a HTTP GET request to the master application's ipsconnect.php file with the following parameters:
The IPS Connect master application will respond with a JSON object with a single property - 'status'. This property will have one of the following values:
Handling Deletions
Finally, whenever an account is deleted in your local application, that you contact the master application to update it's database.
To do this, send a HTTP GET request to the master application's ipsconnect.php file with the following parameters:
In an IPS Connect network, there will be one "master" application and any number of "slave" applications.
The IPS Community Suite (versions 3.4 and above), can serve as either a master or a slave in an IPS Connect network.
This article will show you how to connect two IPS Community Suite installations using IPS Connect.
Before you set up, you will need to decide which installation will be the master, and which will be the slave.
Generally speaking, when setting up an IPS Connect network, the "new" installation (which does not have any existing user data) should be the slave. If you are connecting two installations which both have existing user data, it doesn't matter which is the master and which is the slave.
Important Information about Single Sign-On
In order for Single Sign-On to work properly, the slave application(s) need to read cookies set by the master application.
Since cookies cannot be read across domains, this means that your slave application needs to be on the same domain or a subdomain of the domain that the master application is on.
For example, your master application might be mysite.com, and the slave application might be something.mysite.com.
It will not work if the master application is on mysite.com and the slave application is on somethingelse.com.
Obtaining the URL and Key from the Master
Once you have decided which will be the master, you will need to obtain two pieces of information from it - the IPS Connect URL, and the IPS Connect Key.
This information can be obtained from Admin CP --> System --> Log In Management.
Setting up the slave
To set up your IPS Connect network, you simply need to input this information into the Admin CP on your slave installation.
To do this:
- Go to Admin CP --> System --> Log In Management on your slave application.
- You will see a module called "IPS Connect" - click the pencil icon to edit it, and toggle the "Log In Enabled" setting to "Yes".
- Now click the icon next to the pencil icon for "IPS Connect", which looks like a cog - copy and paste the IPS Connect URL and Key which you obtained from your master application and.
If your slave application does not already have member data, you can disable the "IPB Internal" method completely - this is the recommended set up if possible in your circumstances.
To do this, simply disable the "IPB Internal" method in the same way that you enabled the "IPS Connect" method.
If you are not sure which installation to make the master and which the slave, or are not sure if you can disable the IPB Internal method, or have any problems setting up IPS Connect, please contact technical support.
Troubleshooting
If your IPS Connect integration doesn't seem to be working, your cookie settings are probably in conflict.
For each community in the network, go to Admin CP --> System --> System Settings --> Server Environment and fill in a value for the "Cookie Prefix" setting.
Information for Developers
IPS Connect provides a simple solution for any application to to implement single sign-on with other IPS Connect compatible applications.
In an IPS Connect network, there will be one "master" application and any number of "slave" applications.
The IPS Community Suite (versions 3.4 and above), can serve as either a master or a slave in an IPS Connect network.
To make your application IPS Connect compatible, you first need to decide if you will make it the master or the slave.
Generally speaking, when setting up an IPS Connect network, the "new" application (which does not have any existing user data) should be the slave.
If you are connecting two applications which both have existing user data, it is usually best to make the IPS Community Suite the slave and your custom application the master, as the IPS Community Suite already has support for local fallbacks.
Developers: Creating a Master
This article will take you through the coding necessary to make any 3rd party website or application IPS Connect compatible as a master application.
An example website which is ready to serve as a master application is attached below - see the readme.txt file within for instructions to set up.
master.zip 35.61K
217 downloads
Introduction
As a master application, you will create a public API for slave applications to handle logins, log outs, registrations and account changes. This will all be done through a single file calls ipsconnect.php.
In order for slave applications to use this API, they will need to know the URL to this file and a secret key which is known only to your application (the key can be anything you want, but it must be unique to your master installation).
It is important that your application does not ever reveal the key publicly.
You can start with this sample structure for your ipsconnect.php file:
ipsconnect.php 10.95K
236 downloads
Before you get started
You will notice in the sample ipsconnect.php file that there are two places where a cookie is set - when the user logs in and logs out.
You must ensure that wherever your application handles local log ins and log outs that this cookie is set.
The cookie name is "ipsconnect_" followed by an md5 hash of the Master URL. For example, if the Master URL was http://www.example.com/ipsconnect.php - you'd be setting a cookie with the name "ipsconnect_43fff52f2fc1ae40d522dcfd9bc51b40".
When the user successfully logs into your application, you should set this cookie to the value "1", and when they log out, set it to "0".
Make sure you set the cookie to be available to the whole domain, not a subdomain or to a particular path.
Accommodating existing logins
When a user visits one of your slave applications, if the ipsconnect_xxxx cookie is set, the slave application will contact your application to verify if the user can be automatically logged in.
You will accommodate this using the "cookies" method in your ipsconnect.php file.
The parameters the method receives and the expected output are documented in the example ipsconnect.php. For a working example, see the sample application.
Note: the same application does not handle validating accounts. If your application has a concept of waiting for email validating, or the account was created by a "register" call which set the "revalidateurl" parameter, you should return "VALIDATING" for "connect_status" and the URL where the user can resend the validation email for "connect_revalidate_url".
Accommodating new logins
When a user logs into a slave application having not been previously logged into the IPS Connect network, an API call and/or direct POST request will be made to your ipsconnect.php file which needs to validate the user's credentials and log them in as necessary.
You will accommodate this using the "login" method in your ipsconnect.php file.
The parameters the method receives and the expected output are documented in the example ipsconnect.php. For a working example, see the sample application.
Note: It is recommended that brute-force protection is used as this is a public API. The example application does not do this. For an example of working brute-force protection, see the ipsconnect.php file in the IPS Community Suite (located under /interface/ipsconnect/).
Note: the same application does not handle validating accounts. If your application has a concept of waiting for email validating, or the account was created by a "register" call which set the "revalidateurl" parameter, you should return "VALIDATING" for "connect_status" and the URL where the user can resend the validation email for "connect_revalidate_url".
Accommodating Logouts
When a user logs out on a slave application, a direct POST request will be made to your ipsconnect.php file which needs to log the user out.
You will accommodate this using the "logout" method in your ipsconnect.php file.
The parameters the method receives and the expected output are documented in the example ipsconnect.php. For a working example, see the sample application.
Accommodating Registrations
When a user registers an account on a slave application, 2 API calls will be made to your ipsconnect.php file - one to check that the requested username/email address is available, and one to register the account.
You will accommodate this using the "check" and "register" methods in your ipsconnect.php file.
The parameters the methods receive and the expected output are documented in the example ipsconnect.php. For a working example, see the sample application.
Note: the sample application does not facilitate validating accounts. If the "revalidateurl" parameter is sent, you should save this as it will be needed in your responses to the "login" and "cookie" functions.
Accommodating Account Changes
When a user updates their username, displayname, email address or password on slave application, an API call and/or direct POST request will be made to your ipsconnect.php file which needs to update it's database as necessary.
You will accommodate this using the "change" method in your ipsconnect.php file.
The parameters the method receives and the expected output are documented in the example ipsconnect.php. For a working example, see the sample application.
Accommodating Validations
Some applications (including the IPS Community Suite) have a concept of accounts which are pending validation. If so, the registration includes the "revalidateurl" parameter.
When an account is validated, an API call will be made to your ipsconnect.php file which needs to update it's database as necessary.
You will accommodate this using the "validate" method in your ipsconnect.php file.
The parameters the method receives and the expected output are documented in the example ipsconnect.php.
Accommodating Deletes
When an account is deleted, an API call will be made to your ipsconnect.php file which needs to update it's database as necessary.
You will accommodate this using the "delete" method in your ipsconnect.php file.
The parameters the method receives and the expected output are documented in the example ipsconnect.php.
Developers: Creating a Slave
This article will take you through the coding necessary to make any 3rd party website or application IPS Connect compatible as a slave application.
An example website which is ready to serve as a slave application is attached below - see the readme.txt file within for instructions to set up.
slave.zip 33.75K
215 downloads
Introduction
As a slave application, you will be relying on the master application to handle logins, log outs, registrations and account changes.
While you will maintain a local database, all these actions will go through the IPS Connect master application.
You will also use the IPS Connect master application to automatically log users in. In order to do this, you need to be able to read cookies set by the IPS Connect master application.
Since cookies cannot be read across domains, this means the two applications must be on the same domain, or your slave application must be on a subdomain of the domain the master application is on.
If this is not possible, you can still use IPS Connect, but automatic login will not be available.
Before you start, you need two pieces of information from the IPS Connect master application.
Firstly, a URL to the ipsconnect.php file - this is the file you will call for all callbacks to the master.
Secondly, you need the installation's IPS Connect key.
If your master application is an IPS Community Suite installation, both the URL and the key can be obtained from Admin CP --> System --> Log In Management.
It is important that your application does not ever reveal the IPS Connect key publicly.
Checking for existing logins
When a user visits your application, you should examine their cookie data to see if they have an IPS Connect login and handle this appropriately.
Look for a cookie with the name "ipsconnect_" followed by an md5 hash of the Master URL. For example, if the Master URL was "http://www.example.com/ipsconnect.php" - you'd be looking for a cookie with the name "ipsconnect_43fff52f2fc1ae40d522dcfd9bc51b40".
If this cookie is set and has the value of "0" - this means that the user has expressly logged out of the IPS Connect network, and you should ensure that they are not logged in to your application.
If the cookie is not set, or it's value is "1" you should do your normal local checks to verify if the user is logged in (that is, examine your local cookies).
If you cannot validate the user as being logged in, look at the "ipsconnect_xxxx" cookie again - if it's value is "1", this means that the user is logged into the IPS Connect network, and so you need to check with the IPS Connect network to see what account is logged in.
To do this, send a HTTP GET request to the master application's ipsconnect.php file with the following parameters:
- act - the value "cookies"
- data - a JSON-encoded array of the user's cookie data. In PHP code this would be
json_encode( $_COOKIE )
- connect_status - one of the following values:
- "SUCCESS" - check was successful
- "VALIDATING" - check was successful, but the account hasn't been validated yet. Do not process login
- "FAIL" - check was unsuccessful
- connect_id - IPS Connect master application's ID number for the user that is logged in
- connect_username - the username of the user that is logged in
- connect_displayname - the displayname of the user that is logged in
- connect_email - the email address of the user that is logged in
- connect_revalidate_url - will be provided if connect_status is 'VALIDATING'. Is a URL where you can direct the user to resend the validation email.
You should ensure that you only call the IPS Connect master application once per session, so make sure you set whatever local cookies necessary for the user to be logged in automatically without this API call on future page loads.
Here's an example of what the flow will look like - see the example application for a working example:
$loggedIn = 0;
// Only do this if the user has not expressly logged out of the IPS Connect Network
if ( !isset( $_COOKIE[ 'ipsconnect_' . md5( $masterUrl ) ] ) or $_COOKIE[ 'ipsconnect_' . md5( $masterUrl ) ] )
{
// Check local cookies
if ( /* ... */ )
{
$loggedIn = /* */;
}
// Check IPS Connect
elseif ( isset( $_COOKIE[ 'ipsconnect_' . md5( $masterUrl ) ] ) and $_COOKIE[ 'ipsconnect_' . md5( $masterUrl ) ] )
{
$check = file_get_contents( $masterUrl . '?' . http_build_query( array( 'act' => 'cookies', 'data' => json_encode( $_COOKIE ) ) ) );
if ( $check = @json_decode( $check, TRUE ) and $check['connect_status'] == 'SUCCESS' )
{
// Load local member
if ( /* $member = SELECT * FROM members WHERE ips_connect_id={$check['connect_id']} */ )
{
// Update local member
if ( $member['username'] != $check['connect_username'] )
{
// UPDATE members SET username={$check['connect_username']} WHERE ips_connect_id={$check['ips_connect_id']};
}
if ( $member['displayname'] != $check['connect_displayname'] )
{
// UPDATE members SET displayname={$check['connect_displayname']} WHERE ips_connect_id={$check['ips_connect_id']};
}
if ( $member['email'] != $check['connect_email'] )
{
// UPDATE members SET email={$check['connect_email']} WHERE ips_connect_id={$check['ips_connect_id']};
}
}
else
{
// Create local member
// $member = INSERT INTO members ( username, displayname, email, ips_connect_id ) VALUES ( {$check['connect_username']}, {$check['connect_displayname']}, {$check['connect_email']}, {$check['ips_connect_id']} )
}
// Log in
$loggedIn = $member['ips_connect_id'];
/* Set local cookies so we don't need to do this API call again */
}
}
}
Special Note Regarding Passwords
The passwords in IP.Board and IPS Connect are run through the IP.Board input cleansing routines, meaning certain characters have been replaced with HTML entities. If your external application does not do the same thing, this may mean passwords with special characters will fail if you do not account for this. The special characters that IP.Board will replace are:
& to & (do this first so that you don't double convert any others below) \ to \ ; ( no space between 2 and ; ) ! to ! $ to $ " to " < to < > to > ' to 'Handing Logins
If a user is not already logged into the IPS Connect Network, logging in through your application needs to log them into the entire network.
To do this, once the user has submitted the login, send a HTTP GET request to the master application's ipsconnect.php file with the following parameters:
- act - the value "login"
- idType - either "username", if providing a username, "email" if providing an email address or "id" if providing the master application's ID number for the account.
- id - either the username, email address or ID, as per idType.
- password - the password, md5 encoded.
If you cannot locate a user locally, send the request with either the username or email address.
The IPS Connect master application will respond with a JSON object with the following parameters:
- connect_status - one of the following values:
- SUCCESS - the login was successful
- WRONG_AUTH - the password was incorrect
- NO_USER - could not locate a user based on the ID given.
- MISSING_DATA - you did not provide all the required data
- ACCOUNT_LOCKED - Account has been locked by brute-force prevention
- VALIDATING - The login was successful, but the account hasn't been validated yet. Do not process login.
- connect_id - IPS Connect master application's ID number for the user that is logged in
- connect_username - the username of the user that is logged in
- connect_displayname - the displayname of the user that is logged in
- connect_email - the email address of the user that is logged in
- connect_unlock - If the account is locked, the number of seconds until it unlocks
- connect_revalidate_url - will be provided if connect_status is 'VALIDATING'. Is a URL where you can direct the user to resend the validation email.
If connect_status is SUCCESS, you should first do the same as you do for the cookie check - create or update the account as necessary.
Then redirect the user to the master application's ipsconnect.php file with the same parameters you sent in the request, plus two additional parameters:
- key - an md5 hash of the IPS Connect key for the master application concatenated with the value you sent for the "id" parameter - i.e.:
md5( $masterKey . $id )
- redirect - the URL that the master application should redirect the user back to, bas64 encoded.
- redirectHash - an md5 hash of the IPS Connect key for the master application concatenated with the value you sent for the "redirect" parameter (as it is, base64 encoded) - i.e.:
md5( $masterKey . $redirect )
When the master application passes the user back, it will add the same parameters that it initially responded with to the GET data of the redirect URL. To stop it doing this, pass the additional parameter 'noparams' with a value of '1'.
Here's an example of what the flow will look like - see the example application for a working example:
$idType = 'username';
$id = $_POST['username'];
$_member = NULL;
if ( /* $_member = SELECT * FROM members WHERE username={$_POST['username']} */ )
{
$idType = 'id';
$id = $_member['ips_connect_id'];
}
$login = file_get_contents( $masterUrl . '?' . http_build_query( array( 'act' => 'login', 'idType' => $idType, 'id' => $id, 'password' => md5( $_POST['password'] ) ) ) );
if ( $login = @json_decode( $login, TRUE ) )
{
switch ( $login['connect_status'] )
{
case 'SUCCESS':
// Load local member
/* $member = SELECT * FROM members WHERE ips_connect_id={$login['connect_id']} */
// If we can't load based of the connect ID, but we already loaded off the username, update the connect ID
if ( isset( $_member['id'] ) and !isset( $member['id'] ) )
{
$member = $_member;
// UPDATE members SET ips_connect_id={$login['ips_connect_id']} WHERE id={$_member['id']};
}
// If we don't have a member, create one
if ( !isset( $member['id'] ) )
{
// $member = INSERT INTO members ( username, displayname, email, password, ips_connect_id ) VALUES ( {$login['connect_username']}, {$login['connect_displayname']}, {$login['connect_email']}, md5($_POST['password']), {$login['ips_connect_id']} )
}
// Or update our existing one
else
{
if ( $member['username'] != $login['connect_username'] )
{
// UPDATE members SET username={$login['connect_username']} WHERE id={$member['id']};
}
if ( $member['displayname'] != $login['connect_displayname'] )
{
// UPDATE members SET displayname={$login['connect_displayname']} WHERE id={$member['id']};
}
if ( $member['email'] != $login['connect_email'] )
{
// UPDATE members SET email={$login['connect_email']} WHERE id={$member['id']};
}
// Also update the password, just for consistency
// UPDATE members SET password=md5($_POST['password']) WHERE id={$member['id']};
}
/*
Log the user in ....
setcookie( ... )
*/
header( 'Location: ' . $masterUrl . '?' . http_build_query( array( 'act' => 'login', 'idType' => $idType, 'id' => $id, 'password' => md5( $_POST['password'] ), 'key' => md5( $masterKey . $id ), 'redirect' => base64_encode( $_SERVER['HTTP_ORIGIN'] . $_SERVER['PHP_SELF'] ), 'redirectHash' => md5( $masterKey . base64_encode( $_SERVER['HTTP_ORIGIN'] . $_SERVER['PHP_SELF'] ) ), 'noparams' => '1' ) ) );
exit;
case 'WRONG_AUTH':
$error = "Password incorrect.";
break;
case 'NO_USER':
$error = "Could not locate a user with that username.";
break;
case 'ACCOUNT_LOCKED':
$minutes = ceil( $login['connect_unlock'] / 60 );
$error = "Your account is locked. Please try again in {$minutes} minutes.";
break;
case 'MISSING_DATA':
default:
$error = "We could not log you in. Please try again later.";
break;
}
}
else
{
$error = "We could not log you in. Please try again later.";
} Handling Logouts
When a user logs out of your application, you should redirect them tothe master application's ipsconnect.php file with the following parameters:
- act - the value "logout"
- id - the master application's ID number for the user that is logged in
- key - an MD5 hash of the IPS Connect key for the master application concatenated with the IPS Connect master application's ID number for the user that is logged in - i.e.:
md5( $masterKey . $member['ips_connect_id'] )
- redirect - the URL, base64 encoded, that the user should be redirected to after the logout is completed.
- redirectHash - an md5 hash of the IPS Connect key for the master application concatenated with the value you sent for the "redirect" parameter (as it is, base64 encoded) - i.e.:
md5( $masterKey . $redirect )
In practice, it is better to destroy your local cookies before redirecting the master application.
Handling Registrations
When a user creates an account on your application, you need to inform the IPS Connect master application to create the user locally.
Before you accept a registration you must first check with the IPS Connect master application that the requested username/email address is available.
To do this, send a HTTP GET request to the master application's ipsconnect.php file with the following parameters:
- act - the value "check"
- key - the IPS Connect key for the master application
- username - the account username (i.e. what the user logs in with) - this value is optional if you are not checking it at this stage
- displayname - the account display name (i.e. the user's public username. Send the same as username if your application does not distinguish) - this value is optional if you are not checking it at this stage
- email - the account email address - this value is optional if you are not checking it at this stage
- status - will be "SUCCESS" if the check was successful, or "BAD_KEY" if the key provided was incorrect.
- username - will be a boolean value (1 or 0) indicating if the username provided is okay. If no username was provided, the value will be 0.
- displayname - will be a boolean value (1 or 0) indicating if the display name provided is okay. If no username was provided, the value will be 0.
- email - will be a boolean value (1 or 0) indicating if the email address provided is okay. If no username was provided, the value will be 0.
- act - the value "register"
- key - the IPS Connect key for the master application
- username - the account username (i.e. what the user logs in with)
- displayname - the account display name (i.e. the user's public username. Send the same as username if your application does not distinguish)
- email - the account email address
- password - the account password, MD5 encoded
- revalidateurl - if your application has a concept of validating accounts (i.e. the user must click a link in an email before their account is "activated"), you should pass a value here, otherwise leave it blank. If passing a value, it should be a URL that the user can be directed to in order to resend that email.
- status - one of the following values:
- "BAD_KEY" - the key provided was incorrect.
- "SUCCESS" - the account was created successfully
- "EMAIL_IN_USE" - the email address provided is in use
- "USERNAME_IN_USE" - the username provided is in use
- "MISSING_DATA" - you did not provide all the required data
- "FAIL" - the account could not be created due to an internal error.
- id - the IPS Connect master application's ID number for this account. You must save this ID locally as it will be required in later API calls.
If your application has a concept of validating accounts (i.e. the user must click a link in an email before their account is "activated"), you must send an additional HTTP GET request to the master application's ipsconnect.php file when the user validates their account. Send the following parameters:
- act - the value "validate"
- key - an md5 hash of the IPS Connect key for the master application concatenated with the IPS Connect master application's ID number for the account, i.e.:
md5( $masterKey . $member['ips_connect_id'] )
- id -the IPS Connect master application's ID number for the account.
- "BAD_KEY" - the key provided was incorrect.
- "NO_USER" - the ID number was invalid.
- "SUCCESS" - the request was received successfully.
Handling Account Changes
Whenever the user changes their username, display name, email address or password on your local application, that you contact the master application to update it's database.
To do this, send a HTTP GET request to the master application's ipsconnect.php file with the following parameters:
- act - the value "change"
- id - the master application's ID number for the user that is logged in
- key - an MD5 hash of the IPS Connect key for the master application concatenated with the IPS Connect master application's ID number for the user that is logged in - i.e.:
md5( $masterKey . $member['ips_connect_id'] )
- username - if changing the username, provide the new username. If not provided or blank, the username will not be changed.
- displayname - if changing the display name, provide the new display name. If not provided or blank, the display name will not be changed.
- email - if changing the email address, provide the new email address. If not provided or blank, the email address will not be changed.
- password - if changing the email address, provide the new password, md5 encoded. If not provided or blank, the password will not be changed.
- redirect - you will probably leave this blank, however, if you would prefer to send a POST request directly to the master application, you can use this parameter to provide the URL, base64 encoded, to pass the user back to after the information has been updated.
- redirectHash - an md5 hash of the IPS Connect key for the master application concatenated with the value you sent for the "redirect" parameter (as it is, base64 encoded) - i.e.:
md5( $masterKey . $redirect )
The IPS Connect master application will respond with a JSON object with a single property - 'status'. This property will have one of the following values:
- "BAD_KEY" - the key provided was invalid
- "NO_USER" - the ID number did not match any account
- "SUCCESS" - The information was changed successfully
- "EMAIL_IN_USE" - the email address provided is in use
- "USERNAME_IN_USE" - the username provided is in use
- "DISPLAYNAME_IN_USE" - the display name provided is in use
- "MISSING_DATA" - you did not provide anything that was necessary to update
Handling Deletions
Finally, whenever an account is deleted in your local application, that you contact the master application to update it's database.
To do this, send a HTTP GET request to the master application's ipsconnect.php file with the following parameters:
- act - the value "delete"
- ids - an array of the IDs in the master application's ID number(s) to be deleted
- key - an MD5 hash of the IPS Connect key for the master application concatenated with a JSON-encoded array of the IPS Connect master application's ID number(s) for the accounts to be deleted - i.e.:
md5( $masterKey . json_encode( $ids ) )
- "BAD_KEY" - the key provided was invalid
- "SUCCESS" - The request was received successfully