[Enterprise] How to Work with the AdvicePay SSO Integration

An SSO integration on AdvicePay is available to firms on our Enterprise plan.

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 two certs.

The cert will need to be in the Base64-encoded PEM x509 format. Also, please do not include your private key!

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.