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 firstname.lastname@example.org 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.
- The SSO SDK for your programming language:
- A service account to authenticate the SDK calls. See Service Accounts.
- To be replaced with self-serve configuration after beta – reach out to email@example.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
- 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
- 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.
- 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 Checksection.
- Call the
GetEntryURLWithCodeSDK 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.
GetEntryURLWithCodeoffers inputs to customize the navigation bar of an application.
backUrlTextallow 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.
- 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
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_idmatches 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_idfield. This may require you to do a lookup on the account to find your
customer_idin 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
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.