All Collections
Developer Documentation
Making requests to the Novi OpenID Connect/OAuth2 SSO
Making requests to the Novi OpenID Connect/OAuth2 SSO

Documentation for 3rd party developers who would like to create an OpenID connect 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.

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.

Summary/Endpoint URLs

If you are already familiar with OpenID Connect or are just looking to configure it in a system that supports the standard, you'll likely just need to know the following. All URLs are based off the root URL of the Novi site you are using -

  • Configuration Endpoint - {url}/.well-known/openid-configuration

  • Authorization Endpoint - {url}/oauth/authorize

  • Token Endpoint - {url}/oauth/token

  • User Info Endpoint - {url}/oauth/userinfo

  • Log Out URL - {url}/log-out

If you are setting up SSO on a 3rd party solution that supports OpenID Connect out of the box, this information combined with the client id/client secret from your SSO Client configuration is likely what you'll need to start.

If you are not familiar with OpenID Connect and/or OAuth2 but are looking to build an SSO against our platform, keep reading below. We suggest 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".

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://{your-novi-site-here}/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

  • prompt - If set to "none", we won't redirect the user to the login screen, we'll simply return authorize response to you with "login_required" as the error type

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.

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.

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://{your-novi-site-here}/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 you included in your authorization code request. (Note: Must be a URL that is present in the Valid Redirect URLs on your configured SSO client AND it must match the redirect_uri from the initial authorization code request)

  • 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.

User Info Endpoint

Once you've received an access token, you can also make requests to the user info endpoint to get a copy of the same claims as are returned in the id token. This endpoint is implemented to be compliant with the OAuth spec, but is not recommended for use over the id token because there are no additional claims available.

The user info endpoint is the base url for the Novi AMS website you are authenticating against, followed by "/oauth/userinfo".

Useful Tools:

Did this answer your question?