All Collections
Developer Documentation
Making requests to the Novi JWT SSO
Making requests to the Novi JWT SSO

Documentation for 3rd party developers who would like to create an JWT based SSO using the Novi AMS platform.

Pete Zimek, CAE avatar
Written by Pete Zimek, CAE
Updated over a week ago

The Novi SSO feature of the Novi AMS platform can allow you to leverage the Novi AMS user database for authentication to your application. There are two different supported options for single sign on - One based on OAuth2/OpenID Connect, and one legacy option based on the JSON Web Token (JWT) standard.

Note: We recommend the OAuth2/OpenID Connect approach for new connections as it provides better security for your users. 

If you haven't already please start with the Novi SSO overview article - this will walk you through setting up your SSO client id and give an overview of the claims.

Making an authentication request to Novi JWT SSO

After you've setup your SSO client id, the next step will be directing your users to a GET request on the Novi JWT SSO endpoint, including several pieces of information from the client setup in the overview article. The URL for your request will be the base url for the Novi AMS tenant you are authenticating against, followed by "/sso/auth"
​
​Example: https://ci.novitesting.com/sso/auth, https://www.aago.org/sso/auth
​
​Note: All requests must be made over HTTPS, as HTTP connections will be refused.

Your well-formed request should come with the following query string parameters - 

  • client_id - This is the unique GUID created when configuring the SSO client

  • redirect_uri - This is the URL that our Novi SSO endpoint will redirect the user back to once they are authenticated. (Note: Must be a URL that is present in the Valid Redirect URLs on your configured SSO client)

A complete request would look something like this example - https://ci.novistaging.com/sso/auth?client_id=1052B2B7-1207-4CFE-9728-AFE43BF6DD45&redirect_uri=http://www.test.com/signin-novi

Bad Requests

If you submit an invalid request to the Novi SSO endpoint, then users will receive a 400 bad request response. Invalid requests include the following: 

  • Using a Client ID that doesn't exist for the given Novi AMS tenant

  • Using an invalid response URL (using HTTP or not using a URL that is in the "valid redirect urls" list)

2. Receive, handle, & verify a response

If the user is not currently logged into Novi AMS when your authentication request is received, then they will first be redirected to the Novi AMS login screen. Once they have authenticated with our system, they'll be sent back to the Novi SSO endpoint which will then assemble a JWT with the logged in user's information before redirecting the user back to your specified redirect_uri.

The response to your redirect_uri will include a "token" query-string parameter which will be the encoded JWT (Example - http://www.test.com/signin-novi?token={token-value}. Once decoded, the token will give you the JWT claims that are specified in our SSO overview article.

Once you've received and decoded the token, you can then use the claims to identify the Novi user within your own system. It is also recommended that you use the secret key from the SSO client to verify the signature of the JWT, ensuring that your response request came directly from Novi SSO and not from via a bad actor.

Useful Tools:

Did this answer your question?