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.
1. Setting Up a Novi SSO Client
Before you can begin using Novi SSO, you'll need to have a Novi SSO client setup with the Novi AMS tenant that you wish to use for authentication. This can be set up by going to the "SSO Clients" in the admin section of Novi AMS.
When adding a Novi SSO client, you will be asked for the following information -
Name - A description to help you recognize this particular client
Valid Redirect URLs - A list of the possible URLs that Novi SSO will send users back to for your application's authentication (HTTPS only, comma separated)
Permitted Groups - To limit the single sign-on access to specific members, use this field to select the group(s) that should have access to this SSO client. If no groups are selected and the field is left blank, all members will have access (regardless of membership status). If you need to create a new group, follow the steps here.
Once you fill in the above information and click Save, the following generated values will be generated for the new client -
Client ID - A generated GUID you'll use to uniquely identify your requests
Secret Key - A generated HMAC-SHA256 key you'll use to verify the final JWT and will be passed with OAuth2 token requests
2. Making an authentication request to Novi SSO
The next steps will vary based on which SSO option you are using. For more information check out the detail articles below for each SSO type -
JWT SSO Details (Not recommended unless you can't support OAuth2)
3. Parse your ID Token Response
In either SSO option, you will receive a token that will be the encoded JWT. Once decoded, the token will give you the following claims values -
sub - A unique identifier of the user/member from Novi AMS [Type : GUID converted to string]
legacy_id - A unique identifier of the user/member from the tenant's old AMS system (Optional) [Type: string]
parent_id - A unique identifier of the member's parent from Novi AMS [Type : GUID converted to string]
email - The user's email address [Type: string]
email_verified - A flag for whether the user/member has verified their email [Type: Boolean converted to string]
name - The user/member's full display/preferred name [Type: string]
firstname and given_name - The user/member's first name (could vary from display name) [Type: string]
lastname and family_name - The user/member's last name (could vary from display name) [Type: string]
iss - The issuer of the JWT, usually the root URL of the Novi AMS tenant
exp - The expiration date of the JWT, usually 1 day after issue [Type: NumericDate (Unix style Date/Time, seconds since epoch) to conform to the JWT standard]
aud - The audience of the JWT. For OpenID Connect this will be the client id, while for the JWT based this will be your redirect URL.
nonce - A specific one-time use value used to prevent theft of tokens [Type: string]
iat - Identifies the time that the JWT was issued [Type: NumericDate (Unix style Date/Time, seconds since epoch) to conform to the JWT standard]
locale - The DateTime locale for the token [Type: string]
member_type - A unique identifier for the user/member's member type, if they have one. [Type: GUID converted to a string]
member_status - The user/member's member status [Type: string]
member_sub_status - The user/member's member sub status, if they have one [Type: string]
For more information about Novi AMS data values see Novi AMS API Docs.
Once you've received and decoded the token, you can then use the above claims to identify the Novi user within your own system. If you have Novi AMS API access, you can also use the "sub" value above to query the full member details of a given user from the API. Please review the Getting Started Developing with the Novi API guide for more information.
Testing Environment
If you are collaborating with the Novi AMS team on implementing a Novi SSO use case for one of our clients, your best bet may be to work in the staging environment we already have for that client. This will give you access to a copy of their data and user set (usually several months old). That tenant may not be connected to a QuickBooks sandbox environment - but a connection should not be required for testing of Novi SSO.
If you have questions about the SSO, need help with your integration, or have ideas that could make your development easier, feel free to reach out to our team by clicking the "blue bubble" in the bottom right of this article and sending us a message via Intercom.