Quickstart

To implement SSO, you will need to host a session transfer endpoint on your server. This endpoint will need to identify the user from your system of which you want to SSO, call the SSO SDK to get an authenticated URL for the service provider the user requested a resource from, and redirect the user to that URL.

This document applies to Vendasta Partners only. If you are a Vendor integrating a product into the Marketplace the Vendor documentation is located here.

SSO as described in this document is currently in beta. Beta is described as working, production-quality software, but may lack some documentation and open configuration. It is currently necessary to start a conversation with support@vendasta.com to complete your integration end-to-end. Support will put you directly in contact with the team responsible for SSO integrations, to ensure your integration is succesful.

Prerequisites

  1. The SSO SDK for your programming language:
  2. A service account to authenticate the SDK calls. See Service Accounts.
  3. To be replaced with self-serve configuration after beta – reach out to support@vendasta.com to set your SSO configuration. You must provide:
    • The service account email that you provisioned in step 2
    • The absolute URL of your intended session transfer endpoint. Example: https://my-authentication-service.com/session-transfer
    • Whether or not you want to use JiT identity management (see JiT Identity Management section here.

Session Transfer Implementation

  1. Create a blank-functionality session transfer HTTP endpoint, ideally on the same server as your login/logout endpoints, since you will have to re-use the user’s session cookie or other method of authentication. Example: https://my-authentication-service.com/session-transfer
  2. Add in your authentication logic and/or middleware.
    • If the user is not authenticated, redirect them to login.
    • After the user logs in, redirect the user back to your session transfer endpoint. It is important to maintain the original session transfer query parameters through these redirects.
  3. At this point, you know who the user is, and you know where they want to go (encoded in the query params).
    • If you are not choosing to use the JiT identity management, skip to step 4.
    • If you are choosing to use JiT identity management, then at this point you must do access checks, to make sure that the user you have identified should actually have access to the resource they requested. See the JiT Identity Management - Access Check section.
  4. Call the GetEntryURLWithCode SDK function (may be snake case depending on which SDK you are using)
    • NOTE: It is HIGHLY recommended to reuse a singleton of the client instance. Each client instantiation opens a new connection.
    • GetEntryURLWithCode offers inputs to customize the navigation bar of an application. backUrl and backUrlText allow the caller to have custom text for the back button in the navigation bar, as well as a custom url that the link will take the user to.
  5. Redirect the user to the the entry URL from the previous step. The session transfer is complete.

JiT Identity Management – Access Check

When you are using just-in-time identity management, users and account associations are created on the fly for you as a side effect of the SSO flow. With this configuration, if the identity provider does not run an access check, it would result in new users being created or accounts being associated to an existing user just by initiating SSO, obviously something that should not happen. Therefore, you must know on your end which users you want to be created and which accounts they should only have access to, and deny all other requests.

On the session transfer endpoint, you are provided two query params to help you do this:

  • serviceProviderId: The ID of the service provider the user is trying to access
  • serviceContext: A base64-encoded JSON string describing the resource that the user is trying to access.

There are two different types of service contexts of which you will want to inspect closer for the access check, defined by the _type field:

  • partner: this context means the user requested a resource that is not tied to any particular account, but is still scoped to a partner. For example, this could be a user profile screen, a notification settings screen, etc. For this context, validate that the partner_id matches your partner ID, if it does not, deny access by returning a 403.
  • account: the user requested an account resource. For this context, validate that the user should have access to the account_id field. This may require you to do a lookup on the account to find your customer_id in order to determine whether the user has access or not. If it does not, deny access by returning a 403.
  • For all other encountered context types, deny access. As Vendasta adds more SSO service providers, there may be new context types that will become relevant to third party identity providers. However, the default must be to deny access.

All SDK’s provide a helper function to decode and parse the serviceContext for you. In some SDK’s, this is done by using the constructor of a ServiceContext class, and checking the Partner and Account fields for null. In others, this might be a helper function. TODO: provide SDK specific code examples.

Providing Service Provider Links from your Dashboard

If you know that the URL you are intending on sending the user to in the service provider (the app/product) is a permalink, you can hardcode the link in your dashboard directly (keep in mind that all service provider URL’s must be contextual containing the Vendasta account ID, you will not be able to hardcode one link for everyone, but rather one per account).

However, if you want more peace of mind that you are always sending the user to the service provider’s entry URL, you can use the GetEntryURL SDK function.

Start selling your solution through our marketplace!

Start selling your solution through our marketplace!

Put your solutions in front of 400,000 local businesses, leverage over 5000 sales professionals and deliver a seamless customer experience.  Fill out the form and we'll be in touch shortly with credentials to Developer Central!

You have Successfully Subscribed!

Start selling your solution through our marketplace!

Start selling your solution through our marketplace!

Put your solutions in front of 400,000 local businesses, leverage over 5000 sales professionals and deliver a seamless customer experience.  Fill out the form and we'll be in touch shortly with credentials to Developer Central!

You have Successfully Subscribed!

Push your data to us in an instant

Push your data to us in an instant

Put your solutions in front of 400,000 local businesses, leverage over 5000 sales professionals and deliver a seamless customer experience.  Fill out the form and we'll be in touch shortly!

You have Successfully Subscribed!

Something missing?

Something missing?

Are you working on something that needs to be explained further or looking for help with your solution?  Drop us a line!

You have Successfully Subscribed!