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
A complete request would look something like this example - https://{your-novi-site-here}/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.
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://{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:
https://jwt.io/ - Tool for parsing and verifying JWT