[Account Owner] How to Work with the AdvicePay SSO Integration

Single sign-on (SSO) allows you to give your users one login for the systems your business uses. If you have an AdvicePay Enterprise account and have SSO set up for your business, you can require users to log in to AdvicePay using their SSO credentials.

For single sign-on, AdvicePay currently supports an IdP-initiated SAML2 flow. The instructions below will guide you through the process of setting up an SSO integration with us!

Types of SSO Configurations

Users provisioned with direct login enabled will have AdvicePay login credentials and can access their account directly via SSO and AdvicePay's website. To disallow advisors from accessing their AdvicePay account via our website, please ensure direct login access is disabled. You can indicate your preference by:

• Adding advisors via the API:
  • On the Create an Advisor endpoint, if disableDirectLogin is set to true, the advisor will only be able to login using SSO. If set to false, they can login using SSO and AdvicePay's site.
• Adding advisors via the Advisor Import CSV file via the UI:
  • If the field Disable Direct Login (optional) is set to true, the advisor will only be able to login using SSO. If set to false, they can login using SSO and AdvicePay's site.

Preparing for the Integration

Before you can load your certificates, we'll need to provide you with a SSO Source that you'll send along in the URL when you make your requests. Please email your relationship manager at enterprise@advicepay.com to provide you with your SSO Source.

We’ll need some information from you so we can set things up on our side! Most-importantly, we’ll need the certificate that we can use to verify your signed SAML responses. (In the Demo environment, this can be a self-signed cert, but you’ll need to provide a valid CA cert in your live or "Production" site.) 

Providing this cert can be done securely once your firm is set up on the AdvicePay system, we have enabled your account with Developer capabilities, and you have added a Developer user in the same way you add an Admin/Analyst user.

The Developer user can then log in to their account and select Single Sign On > Add Certificate. You can upload up to five certs. 

Finally, you'll want to go ahead and add some users that have SSO IDs associated with them. Users can be created using the advisors endpoint on our API (see https://docs.advicepay.com) or within the AdvicePay UI by your account owner. 

If you need any help with this part, please let your AdvicePay Relationship Manager know at enterprise@advicepay.com -- we'll be glad to lend a hand!

AdvicePay Endpoints

https://demo.advicepay.com/auth/sso?source=YourAdvicePayProvidedSSOSourceHere

https://app.advicepay.com/auth/sso?source=YourAdvicePayProvidedSSOSourceHere

We recommend doing all of your development against the Demo environment so you can work out any kinks before moving over to Production.

Tips for Successful Configuration

• SSO IDs are case sensitive. If the SSO ID is configured as enterprise@advicepay.com, but you pass in Enterprise@advicepay.com, the user will not be able to SSO.
• Access (either disabled direct login or direct login) cannot currently be changed within the UI.

The SSO request

Your system will need to display a link, a button, or some other method that your users use to initiate the SSO flow. This will need to perform an HTTP POST to the desired AdvicePay SSO endpoint. 

The body of the POST should contain a field named SAMLResponse containing the signed SAML Response. By default, the piece of the response we care most about is the Name ID since we use that to associate the request with users in the AdvicePay system, although we can customize the response parsing to meet your needs. 

When testing, we like to use https://capriza.github.io/samling/samling.html to generate responses, which allows us to ensure that things are set up correctly on the AdvicePay side. It also generates a nice example of a valid SAML response if you need it. The body of the POST can also contain a field named RelayState containing the URL of the page you’d like the user redirected to after a successful SSO. This can be useful for scenarios like deep-linking into an invoice record so the user doesn’t need to navigate there on their own.

Updating Certificates

As needed your Developer user(s) can provide updated certs securely via their login.

When logged in the Developer will select  Single Sign On > Add Certificate.

You can upload up to two certs.

If you need any help with this part, please let your AdvicePay Relationship Manager know at enterprise@advicepay.com -- we'll be glad to lend a hand!

Firm Settings for SSO in AdvicePay

If your firm is using SSO with AdvicePay, there are two locations for setting these to disable direct login for Advisors and Admins independently.

Settings for Advisors is located under Firm Settings, Advisors, under General Settings.

You can require SSO IDs and require Advisors to log in with SSO by selecting Always require SSO.

• This will not allow direct login into AdvicePay at all.

Other options for the setting are to Always Enable Direct Login or Allow Either.

• These options allow direct login and/or disabled direct login per individual as needed. If the individual setting on their profile is set to Direct Disable Login "on" (toggles green) they cannot log in directly and an SSO ID is required.

On Advisors profiles, you can see the Disable Direct Login and whether it is on or off. The above restricts or allows this and must be changed at the Firm settings:

Admin users can be controlled with the SSO function under Firm Settings, Admins, Under General Settings:

Admin(s) can also have an SSO ID required, Always Require SSO, Always Enable Direct Login, or Allow Either. The same options for Advisors explained above.

Admin(s) setting for Disable Direct Login can be viewed in their profile as well but is overall controlled by the above setting (Firm Settings), the same as the advisors are: