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.

If you haven't already please start with the Novi SSO overview article - that article will walk you through setting up your SSO client id and give an overview of the claims. Once you've read that, come back here and we'll get you going the OpenID Connect details. If you are not familiar with OpenID Connect and/or OAuth2, we suggest you develop some familiarity before attempting to the use the Novi AMS SSO.

OpenId Connect Configuration

Our SSO is compliant with the basic OpenID Connect standard, and as such we have an available OpenId Connect Configuration endpoint that lists our endpoints and supported response types & claims. 

You can view the configuration endpoint at the base url for the Novi AMS website you are authenticating against, followed by "/.well-known/openid-configuration".

Ex: https://www.novitesting.com/.well-known/openid-configuration

Out of the Box SSO vs Custom

If you are setting up SSO on a 3rd party solution that supports OpenID Connect out of the box, this configuration endpoint is likely what you'll need to start. Just put in this configuration url along with the client id and secret from the overview article and you should be good to go.

If you aren't using an out of the box solution and are a developer building your own, read on.

Making an authentication request to Novi OpenID Connect SSO

After you've setup your SSO client id, the next step will be directing your users to a GET request on the Novi OpenID connect endpoint, including several pieces of information from the SSO client setup in the overview article. The URL for your request will be the base url for the Novi AMS website you are authenticating against, followed by "/oauth/authorize".

Ex: https://www.novitesting.com/oauth/authorize

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)
  • scope - The scope you are requesting, most commonly "openid" for SSO.
  • response_type - The response type you would like from the authorization endpoint (essentially which OAuth2 flow you'd like to follow). We highly recommend the authorization code flow unless your application is JavaScript or client side only.
  • state - A string value that will be passed back to your redirect endpoint to help secure against forged requests

A complete request would look something like this example - https://www.novitesting.com/oauth/authorize?client_id=1052B2B7-1207-4CFE-9728-AFE43BF6DD45&redirect_uri=http://www.test.com/signin-novi&scope=openid&response_type=code

Bad Requests

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

  • Using a Client ID that doesn't exist for the given Novi AMS website
  • Using an invalid response URL (using HTTP or not using a URL that is in the "valid redirect urls" list)
  • Requesting an unsupported scope or response type

Receive, handle, & verify an authorization 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 redirected back to your specified redirect_uri with your requested response type.

Authorization Code Flow (response type = code)

In the code flow, the redirect back to your site will include an authorization code that you can then use to hit our token endpoint to receive the JWT ID token and access token. This authorization code will be good for 60 seconds to exchange for tokens.

Ex: http://www.test.com/signin-novi?code={code-value}&state={state-value}

Implicit Flow (response type = token id_token)

In the implicit flow, the redirect back to your site will include the access token and the id token directly in the query string.

Ex: http://www.test.com/signin-novi?token={access-token}&id_token={jwt-id-token}&state={state-value}

Making an token exchange request

The token endpoint is the base url for the Novi AMS website you are authenticating against, followed by "/oauth/token". You'll make a POST request to this endpoint to exchange the authorization code for tokens.

Ex: https://www.novitesting.com/oauth/token

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

  • client_id - This is the unique GUID created when configuring the SSO client
  • client_secret - The secret key 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)
  • code- The code from the authorization endpoint
  • grant_type - Should be "authorization_code"

Parsing the token responses

In either flow, you'll receive two tokens - an access token and an id token. For now the access token is unused. The ID token is an encoded JWT token. 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?