Authenticating Constituents with OAuth 2.0

For certain applications, your integration may need to authenticate an organization's constituents in order to grant access to parts of your app. For this scenario, 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.

Do not confuse constituent authentication with authentication for NeonCRM system users or with authorization for access to resources in the NeonCRM API. This page describes how to authenticate an organization's constituents, not the organization's staff who may have admin access to NeonCRM. Authenticated constituents should not have the same access to account data in NeonCRM that system users would have. The access token received through this method is simply the user's NeonCRM account ID. It is up to you to determine what the constituent user logged into your app is authorized to see from NeonCRM.

Typical User Flow

Below is an example of a typical constituent experience when signing in with OAuth:

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

Setup

Setting up OAuth with NeonCRM requires three steps:

  1. Create the login URL
  2. Capture the authorization code
  3. Retrieve the access token

You will need access to the organization's OAuth credentials in order to complete this setup. In NeonCRM, go to the Settings cog > Global Settings > OAuth Configuration.

 

Create the login URL

To log in with OAuth, users must navigate to a special login URL with parameters to let NeonCRM know the user is logging in from a third-party site with OAuth. The normal NeonCRM login URL will not work here.

To create the login link or button, you can either use NeonCRM's JavaScript widget, which will generate the login link for you, or construct the URL yourself with information from the organization's OAuth credentials.

(Option 1) Construct the URL manually

You can construct the OAuth login with the following format:

https://{{org_id}}.z2systems.com/np/oauth/auth?response_type=code&client_id={{client_id}}&redirect_uri={{redirect_uri}}
  • {{org_id}} is the organization's NeonCRM Org ID
  • {{client_id}} is the client ID from the OAuth Configuration page in NeonCRM
  • {{redirect_uri}} is the URI where the user should be redirected after a successful or failed login

 

(Option 2) Use the NeonCRM JavaScript Widget

On the OAuth Configuration page in NeonCRM, copy the JavaScript widget code and embed it into your application inside the HTML <body> tag where you want the login link to appear. Inside the code snippet, replace the text your redirect_uri here with the URI where the user should be redirected after a successful or failed login. This code snippet will not work when placed inside the <head> or another <script> tag.

 

Capture the Authorization Code

After a user has successfully authenticated with NeonCRM, they will be redirected to the redirect_uri that you specify. An authorization code is passed to this page as in the URL parameter code. You must capture this code in order to receive the access token in the next step.

Authorization codes expire 10 minutes after they are generated.

 

Retrieve the Access Token

The final step is to make an HTTP request to NeonCRM to request the constituent access token.

HTTP Request:

POST /np/oauth/token

Hostname:

https://www.z2systems.com

HTTP Headers:

Content-Type: application/x-www-form-urlencoded

Request Body:

client_id={{client_id}}&client_secret={{client_secret}}&redirect_uri={{redirect_uri}}&code={{authorization_code}}&grant_type=authorization_code
  • {{client_id}} is the client ID from the OAuth Configuration page in NeonCRM
  • {{client_secret}} is the client secret from the OAuth Configuration page in NeonCRM
  • {{redirect_uri}} is the URL where the user is redirected after a successful or failed login
  • {{authorization_code}} is the authorization code from the redirect URL parameter

 

Access Token Response

If the request is successful, NeonCRM will return a JSON response with the user’s access token.

{"access_token":"101177"}

This access token is simply the user’s NeonCRM account ID. With this ID, you can use NeonCRM’s API to request further information about this user.

Learn more about working with the Accounts API.

 

Logging Out

You 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://{{org_id}}.z2systems.com/np/logout.do?targetUrl={{targetUrl}}
  • {{org_id}} is the organization's NeonCRM Org ID
  • {{targetUrl}} is the URL where the user should be redirected after logout

 

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 virtual 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 constructed your HTTP request. Make sure the request method is POST and you have specified the Content-Type in your request header: Content-Type: application/x-www-form-urlencoded

API Reference

There is no API reference material for this topic. The implementation of OAuth 2.0 for authenticating constituents is agnostic to the version of the NeonCRM API used.