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, Neon CRM can act as an OAuth 2.0 provider. This means that Neon CRM’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 Neon CRM system users or with authorization for access to resources in the Neon CRM API. This page describes how to authenticate an organization's constituents, not the organization's staff who may have admin access to Neon CRM. Authenticated constituents should not have the same access to account data in Neon CRM that system users would have. The access token received through this method is simply the user's Neon CRM account ID. It is up to you to determine what the constituent user logged into your app is authorized to see from Neon CRM.

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 Neon CRM.
  2. They are redirected to Neon CRM’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 Neon CRM 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 Neon CRM, 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 Neon CRM know the user is logging in from a third-party site with OAuth. The normal Neon CRM login URL will not work here.

To create the login link or button, you can either use Neon CRM'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 Neon CRM Org ID
  • {{client_id}} is the client ID from the OAuth Configuration page in Neon CRM
  • {{redirect_uri}} is the URI where the user should be redirected after a successful or failed login

 

(Option 2) Use the Neon CRM JavaScript Widget

On the OAuth Configuration page in Neon CRM, 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 Neon CRM, 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 Neon CRM 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 Neon CRM
  • {{client_secret}} is the client secret from the OAuth Configuration page in Neon CRM
  • {{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, Neon CRM will return a JSON response with the user’s access token.

{"access_token":"101177"}

This access token is simply the user’s Neon CRM account ID. With this ID, you can use Neon CRM’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 Neon CRM by directing them to Neon CRM’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 Neon CRM 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 Neon CRM. To resolve, log out of that session from Neon CRM 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 Neon CRM API used.