OAuth 2

NeonCRM can act as an OAuth 2.0 provider. This means that NeonCRM’s existing login system can be used to authenticate constituent user access to a third-party website or service as a single sign-on. OAuth is not a method for API session authentication (use Login instead). Once properly implemented, a user experiences this workflow:

Workflow

  1. A user clicks the Sign in with NeonCRM button on a third-party website.
  2. They are redirected to NeonCRM’s login page, where they type in their user name and password.
  3. If successful, they are immediately redirected back to the third-party website where they are granted appropriate access.

Setup

Setting up an integration requires three steps:

  1. Set up the Sign-in Widget
  2. Capture the Authorization Code
  3. Obtain Access Token

Once the third-party website or service has obtained an access token, they can make further requests to obtain information about this user by taking advantage of NeonCRM’s API.

1. Set up the Sign-in Widget

The first step is to obtain the widget code and keys from your system settings. Log in to your NeonCRM system and navigate to System Settings > Home/Dashboard > OAuth Configuration. If this section is not visible, please contact projects [at] z2systems.com to request that we enable the feature for your system.

Get the Widget Code Snippet

Copy the JavaScript widget code and embed it into your application inside the HTML <body> tag. This code will render a sign-in widget in the location where the code snippet resides. This code will not work when inside the <head> or inside another <script> tag.

Set the redirect URI

You must set the redirect_uri parameter. The only part of this code that should be modified is the redirect_uri parameter. Here, you must include the URI of the callback page, where users are redirected after authenticating with NeonCRM. http and https are both acceptable. If neither are specified, then http is the default value. If you do not specify this parameter, users will be shown the error Invalid redirect_uri parameter value.

Embed the Widget

Once your widget is embedded, the sign-in button will display on your webpage. When a user clicks this button, they will be directed to a NeonCRM sign-in page.

  • This login page works for constituent account credentials only.
  • If you attempt to access this page while already logged in as a system user, you will receive the error “Logged in as system user not supported”.
  • If you attempt to log in to this page using a system user account, you will be logged in to NeonCRM as a system user instead of being redirected to the originating application.

2. Capture the Authorization Code

After a user has successfully authenticated with NeonCRM, they will be redirected to the URI specified in the JavaScript widget. An authorization code is passed to this page as a URL parameter. This code expires 10 minutes after it is generated.

3. Obtain Access Token

Request

The final step is to make an HTTP request to NeonCRM to request the user token (account ID). Your HTTP request must be set up with the specific parameters.

  • POST Request – Must be a POST request.
  • HTTP Headers – Header must include Content-Type: application/x-www-form-urlencoded
  • URL -The request must be sent to https://www.z2systems.com/np/oauth/token
  • Parameters – Your request must include the following parameters, which must be URL encoded:
    • client_id – found in NeonCRM OAuth Settings
    • client_secret – found in NeonCRM OAuth Settings
    • redirect_uri – must be the same as the value specified in the widget
    • code – retrieved from the URL parameter. This is already URL encoded.
    • grant_type – fixed value, must be authorization_code
HTTP Headers:
Content-Type: application/x-www-form-urlencoded

URL:
https://www.z2systems.com/np/oauth/token

Body:
client_id=[client id]&
client_secret=[client secret]&
redirect_uri[redirect uri]&
code=[code]&
grant_type=authorization_code

Response

The server response, if successful, will return JSON of the user’s access token.

{"access_token":"101177"}

This access token is simply the user’s NeonCRM account ID. With this data, you can use NeonCRM’s API to request further information about this user. Identifying specific use cases is beyond the scope of this article, but a good place to start would be the retrieveIndividualAccount method.

Logging Users Out

You may terminate a user’s session with NeonCRM by directing them to NeonCRM’s logout page. You may pass a URL to the targetUrl parameter to immediately redirect a user to the destination of your choice.

https://www.z2systems.com/np/logout.do?targetUrl=http://mysite.org

PHP Example

This is a basic example of the script on your callback page to retrieve the access code and then make an authentication request to NeonCRM. This is just an example and should not be used as-is in a production environment.

/* Build array for HTTP request POST parameters */
$parameters = array();

if ( isset( $_GET['code'] ) ) {
    $parameters['client_id']     = 'Bmc2jfZK6qqXoFzFasdSFDSSDFDPr1lBS8LdAnK7ekWRLNvFHx2b9r7RbAmF'; // Found in NeonCRM System Settings
    $parameters['client_secret'] = '00000000-1111-bbbb-cccc-222222222222'; // Found in NeonCRM System Settings
    $parameters['redirect_uri']  = '127.0.0.1/oauth/auth.php'; // Use the same value specified in the widget
    $parameters['code']          = $_GET['code']; // Get code from URL Parameter
    $parameters['grant_type']    = 'authorization_code'; // required, fixed value

    // Convert the parameters array to URLEncoded string
    $parameters = http_build_query($parameters);

    /* HTTP POST request to NeonCRM */
    $url = 'https://www.z2systems.com/np/oauth/token'; // Always use this URL
    $ch = curl_init();
    curl_setopt($ch,CURLOPT_URL, $url);
    curl_setopt($ch,CURLOPT_POST, TRUE);
    curl_setopt($ch,CURLOPT_POSTFIELDS, $parameters);
    curl_setopt($ch,CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($ch,CURLOPT_HTTPHEADER,array('Content-Type: application/x-www-form-urlencoded')); // Must specify content type in header
    $result = curl_exec($ch);
    curl_close($ch);

    echo $result; // print the server response
}

Errors and Troubleshooting

Logged in as system user not supported

This error appears when a user has an active system user session with NeonCRM. To resolve, log out of that session from NeonCRM and try logging in with a constituent user account instead of a system user account.

Invalid redirect_uri parameter

This error is triggered when the URI specified in the redirect_uri parameter is not a valid URL. Check the syntax of your URL. If you are developing on a local or virual web server and redirecting to a URI located on that server, try specifying your host name as 127.0.0.1 instead of localhost.

Invalid Request: Authorization code invalid

The authorization code has either been altered, or it has expired. Authorization codes expire automatically 10 minutes after they are created.

I send my HTTP request to the server, but I receive no response or access token.

Ensure you have properly specified the Content Type in your request header: Content-Type: application/x-www-form-urlencoded.