Single Sign-On (SSO)
Vendasta allows the ability to sign into the products in our Marketplace through the use of Single Sign-On (SSO). This is accomplished through a simple technical integration of a session transfer endpoint on your authentication server.
- Service Provider: any application or service provided by, or through, Vendasta, which supports SSO.
- Identity Provider: the application that owns user authentication. This is likely to be your existing dashboard where your customers currently sign into.
- Identity Discovery Provider: a standalone service offered by Vendasta to help facilitate the SSO process. Stores or proxies the configuration and artifacts necessary to allow service providers to redirect to identity providers, and identity providers to be able to SSO into service providers.
SSO into service providers is accomplished via 2-legged OAuth. The identity discovery provider takes care of the actual OAuth exchange for the identity provider, to make the integration as simple as possible.
SSO Authentication requires the identity provider to implement a session transfer HTTP endpoint on their server. The sequence diagram looks like this:
- A user, via their browser request a resource (any protected URL a service provider owns, for which it requires an access check). In this example, the user does not have an active session, therefore the service provider initiates the session transfer process. This is known as “service-provider initiated SSO”.
- The service provider does not directly know which identity provider to serve for a particular account. Therefore, it asks the identity provider discovery service for the session transfer URL to send the user to. The service provider appends the requested resource as the next URL to the session transfer URL, so that the user can be redirected back to the originally requested URL after authentication.
- The service provider redirects the user to the session transfer URL.
- The identity provider receives the session transfer request.
- If the user does not have an active session with the identity provider, at this point the identity provider redirects the user to login before continuing with the session transfer.
- The identity provider requests an “entry URL with code” from the identity provider discovery service, in exchange for the required identity information. The entry URL is an endpoint on the service provider capable of exchanging a code (an identity token) for a session.
- The identity provider discovery service creates a JWT representation of the identity information, and requests the code from the service provider. The identity provider discovery service appends this code as a query parameter to the service provider entry URL.
- This is potentially where just-in-time identity and access management could occur. See the Identity and Access Management section.
- The identity provider redirects the user to the entry URL, which at this point contains the code for authentication, as well as the next URL for their originally requested resource.
- The browser makes the redirect request, creates a session, and redirects the user back to the originally requested resource.
- At this point, since the user has been identified, the service provider can run resource access checks. If the user does not have access to the resource, the user will be shown a denied access screen.
Identity and Access Management
Currently, session transfer relies on identity federation – that is, your users must be created/mirrored in the Vendasta platform for the session transfer to occur. This requirement may change in the future, which would entrust the identity provider as the sole owner of the identity, and (possibly) the access attributes.
There are three ways to manage the identity federation:
- Through Partner Center user management screens
- Via API
- Via a side effect of the SSO process
The first two ways are classified as ahead-of-time (AoT), while the third is classified as just-in-time (JiT).
Ahead-of-time (AoT) is managed by creating and managing users in the Vendasta platform before an attempt at a session transfer can be successful. AoT IAM is done through one of two ways: through the Partner Center user management screens, or via API.
It is important to note that when using AoT IAM, the identity provider should omit implementing any access checks. As the identity provider, for a session transfer to occur, your sole responsibility is to identify the user, regardless as to whether or not they have access to the resource they are requesting. It is important to allow the session transfer to occur regardless of access for two reasons:
- The service providers must do the access checks on every request, regardless of whether a session transfer is occurring or not. If access checks were not on every request, a user could simply request another resource after the session transfer occurred. Since the service providers must do the access check anyway, access checks implemented by the identity provider would be redundant.
- Allowing the session transfer to occur regardless of access gives the service provider the control over what to show the user when access is denied. In the simplest scenario, this could result in an “Access Denied” screen, ideally with some context and a link back to where they came. However, a much better user experience is to present the user with the option to “request access”. This would allow a resource owner to make the decision of whether or not to grant another user permissions as a result of the request.
AoT IAM is the default and recommended integration.
JiT IAM is an option to allow creating and managing users during the session transfer, without any additional API calls needed.
There are currently two levels of configuration for JiT available:
- JiT identity creation – allows creating the identity on the fly
- JiT account association – allows associating the user to the requested account on the fly.
The JiT IAM option is very useful for legacy SSO integrations; whom are used to previous versions of SSO being account-based, as opposed to the current identity-based SSO described in this document. These partners are not used to having to provide identities to get into accounts, therefore JiT creates a low-friction upgrade option with automated identity creation happening lazily during the session transfer.
While a JiT IAM integration sounds appealing, it comes with several tradeoffs to weigh. The first tradeoff is speed: due to the extra overhead of checking the identity exists, access to the account exists, and possibly having to create the user and/or the account association, the speed of the session transfer itself is dramatically slower. The second tradeoff is the complexity of the session transfer integration itself goes up, due to the burden placed on the identity provider of having to implement resource access checks. If the identity provider does not do adequate resource access checks on their end, then it could result in users acquiring access to resources that they should not otherwise have access to, just by initiating the session transfer process. Therefore, the responsibility is shifted from the service providers (who also still have to run access checks, therefore making the overall process even slower) to the identity provider to ensure that a user can only access appropriate accounts.
A safer middleground that could be appropriate, especially for the freemium products and services, is to enable JiT user creation, but leave JiT account association turned off. This allows the session transfer to create users which have access to no accounts initially, but they could optionally add their own accounts once they have a user.
Software Development Kits
Software Development Kits (SDKs) streamline and simplify the integration process by taking care of authentication, serialization/deserialization, and other development details. SDKs provide an idiomatic interface for the developer to use, provide documentation hints for all common languages, and provide built-in retry and re-authentication for a much more robust integration overall.
Currently, SDKs are available (some currently only available upon request) in five languages: Go, Python, Java, PHP, and C#, with plans to add other common languages upon request.
All SDKs default to using GRPC for the transport layer. However, in some languages, GRPC can be difficult to install, or cannot be supported. In these languages, the SDK will fallback to using JSON as a transport.
Due to the complexity of authentication and the robustness features the SDK’s offer, directly integrating against the GRPC RPC’s or the JSON endpoints is not currently supported or recommended.
The Marketplace product navigation bar allows the user to quickly navigate between all of the purchased products, as well as provides easy access to settings, logout, and navigate back to the user’s dashboard.
The navigation bar features several areas of customization to seamlessly integrate the identity provider with the SSO service providers:
- The top left portion of the navigation bar is reserved for the identity provider (the dashboard application and/or the application where your users login). The text and link can be customized. To customize the text and url the values can be passed to the “get entry url with code” function.
- The product dropdown features all of the service providers your user has access to. This list can be augmented with your own products, even if they are not integrated in the Marketplace, via the “Custom Products” feature. Many of the products in this list can have a whitelabelled name.
- The logout URL can be customized to the identity provider logout URL, which will in turn trigger logging out of all service providers which were accessed during a session.
Visit the Quickstart guide for implementation details.