Partner SSO Guide
note* This Guide is for Partner Integrations – For Vendor Marketplace App SSO see the Vendor Docs
Vendasta offers a sandbox environment for initial development work with new partners that will be integrating with Vendasta via API and/or SSO. This environment pulls in live data and is an excellent way to perform integration testing. We require that you perform your initial integration work in this environment, and we are here to answer any of your questions as you go through testing in this sandbox environment. We will ensure you’re comfortable before migrating to the production environment.
Note that the sandbox environment is separated from the production environment in every way. There is separate domains and credentials laid out below that will be required for interacting with this testing environment, and when you shift your code to production, you will need to make changes to these. You could set your system up so it can switch back and forth, or better for long term testing of new features, have separate code bases instead of changing over.
Please contact email@example.com to get your sandbox environment set up, and your sandbox access granted.
The Sandbox Environment does not change the General SSO Flow at all. However, the urls of the product pages being accessed to trigger the SSO handshake will be different:
Reputation Management: http://partnerId.steprep-demo.com/overview/?sso_token=XXXXXXXX
Presence Builder: http://partnerId.mobilesiteplatform-demo.com/edit/account/AG-XXXXXXXX/overview/?sso_token=MS-XXXXXXXX
Social Marketing: http://partnerId.socmktg-demo.appspot.com/account/AG-XXXXXXXX/posts/recent/?sso_token=AC-XXXXXXXX
- How to store and manage user to product associations, i.e where to store the sso_tokens on your end for when you need to look them up to determine what permissions a user has.
- What happens when a user has access to multiple accounts? The Vendasta Business Center has an ‘Account selector’ dropdown also with a searchbox for those with access to larger amounts of accounts.
- What happens when a client requests unauthenticated access? Unauthenticated access is when a product url is accessed without an sso_token entered as a query param? This could be from someone who has bookmarked the product, or who is accessing it via a notification email. Once they have been redirected to your login page, do you send them back to their product/account selection page, or directly into the product that was initially requested?
- Once you have gone through the documentation, and set up the base functionality for your authorization and validation handler urls. Contact support, and provide the authorization and validation urls you intend to use in the sandbox environment for testing your integration. We will configure these on our end so that you can commence with testing, revising, and expanding functionality.
- When you are ready to change over to Production, you will need to:
- Contact support, and indicate you are wanting to change, and provide a timeline on when you want to do so
- Provide the production urls for the authorization and validation handlers.
- Ensure your production environment is using production credentials, and domains for accessing the products.
- Ensure your sso_tokens are being sourced from the production environment, as accounts created in the sandbox will not be accessible from production.
As a concrete example, let’s call the system integrating with Vendasta products (your system) PartnerSystem and the Vendasta product you wish to sign-on to SM (Vendasta’s Social Marketing product).
The user must first log in to PartnerSystem using PartnerSystem’s standard authentication mechanism. We will assume HTTP Basic Authorization. After the user is logged in and using PartnerSystem you may present that user with a URL to SM at any point during your desired workflow. When the user clicks on this URL the SSO process will begin and transparently log the user in to the SM product.
High Level Example
The basic premise of SSO with Vendasta is that a unique token and ticket are used to identify that HTTP requests are coming from an authenticated system. To achieve this, a unique SSO token and ticket pair will be generated at the appropriate time during the SSO procedure.
In our concrete example of integrating with Vendasta’s Social Marketing product, the user’s browser will request a URL of the form
<partner-whitelabel-social-marketing-domain>/account/ within PartnerSystem. If the user is not currently authenticated with SM, an SSO Authorization URL and SSO Validation URL provided by the PartnerSystem will be used to identify that this request to access SM is coming from an authenticated user. PartnerSystem will have to implement the following two URL handlers as detailed below.
SSO Authorization URL
The first handler that PartnerSystem will have to implement is an SSO Authorization URL. SM will redirect the user to this URL with a product identifier (SM), and a next url. PartnerSystem will verify that the product identifier is valid and check that the user session is currently authorized with their system. If these checks pass PartnerSystem will generate a unique token and ticket signifying that the user is authorized with PartnerSystem and redirect to the next url provided in the original request with this token and ticket attached as query parameters. The SSO token should correspond to the account-specific identifier that you are trying to access. The SSO ticket should be a random identifier. The ticket must be single-use and short-lived, it should expire after 60 seconds or once it has been validated.
SSO Validation URL
For SM to validate that the token and ticket are correct the PartnerSystem will have to implement an SSO Validation URL. SM will directly query this URL with the SSO token, SSO ticket, and the product id as request parameters. PartnerSystem will verify that the SSO token and ticket combination are valid and that this combination was used to attempt access to the SM product. If this information is correct PartnerSystem will return an HTTP response with a status code of 200. If SM receives this HTTP response it will create a login session and at this point the SSO process is complete.
This query is the only direct system-to-system interaction and is made independently of the current user session. This may have implications on your systems firewall or other architecture configuration.
If the SSO token and SSO ticket are not valid the user agent will be redirected back to the SSO Authorization URL with no query parameters. Your system can then attempt to re-authenticate the user before trying. This redirection occurs whenever a non-200 response is received from the SSO Validation URL.
Your system must implement two URL handlers and provide these URLs to Vendasta. These URLs will be stored with Vendasta Business Center and used by Vendasta to communicate with your system.
SSO Authorization URL
Once the user clicks on a URL directed to a Vendasta product the user agent is directed to our system. Our system will redirect the user agent to the SSO Authorization URL to confirm access to the Vendasta products. This URL will be called with the following request syntax.
|product_id||string||A Vendasta product code.
|next||string||The next URL to redirect to after successfully authorizing the user. The generated SSO ticket will be appended to this URL as a query argument.|
(max 200 characters)
|This is the token to use for single sign-on mechanics, if applicable. May be the same as partner defined product specific account id. It must be unique per product. If the original request to Vendasta included an sso_token parameter that parameter will be kept intact during future requests. If this token is present you may use it. If the token is not present you will need to append your own token.|
RESPONSE (302 Redirect)
In the case that the
sso_token is not present your system will append an SSO token to the redirect location for the current product. Your system will also verify that the current user is logged in and authorized with your system for this session.
Your system will then generate and store an SSO ticket and append this ticket to the URL provided in the next parameter as valid query arguments. The SSO ticket should be single use and short-lived (60 seconds) and expire after this time period has elapsed.
The resulting URL must be well formed and valid. The user agent should be redirected to this URL. Please make sure that you decode the next URL add sso_token and sso_ticket to the query params and re-encode the URL validating that it is still a valid URL.
The Location value of the redirect should look similar to this
SSO Validation URL
The SSO Validation URL will be called directly by Vendasta, server-to-server, to verify that a provided SSO token and SSO ticket are valid and are being made by an authorized user. This URL will be called with the following request syntax.
|product_id||string||A Vendasta product code.
(max 200 characters)
|This is the token to use for single sign-on mechanics, if applicable. May be the same as partner defined product specific account id. It must be unique per product.|
|sso_ticket||string||An SSO ticket generated by your system. Your system will expire the SSO ticket immediately after it has been validated or after 60 seconds, whichever event occurs first.|
Your system will verify that the sso_token, sso_ticket, and product_id are valid values. If the values are valid your system will return an HTTP response with a status code of 200. Upon receiving this HTTP 200 response Vendasta will create an authorized session for the user and redirect the user to the Vendasta product URL given during the first redirection to our system. Your system will expire the SSO ticket immediately after it has been validated or after 60 seconds, whichever event occurs first.
This section details a full example of the URL call sequence when integrating with Vendasta’s Social Marketing product. All query parameters are assumed to be properly URL encoded before being transmitted. The example below shows the data when it has been URL encoded.
It is assumed that the Partner has configured the following SSO URLs with Vendasta.
|SSO Authorization URL||partner.com/sso/authorization/|
|SSO Validation URL||partner.com/sso/validation/|
It is also assumed that the Social Marketing is hosted on the domain http://socmktg.com
User clicks on a link that accesses Social Marketing Account
SM-12345 in PartnerSystem. The sso_token parameter is optional. The
sso_token will be kept intact throughout the SSO process if specified. This is useful if the current logged in user has more than one accounts in given Vendasta product.
Redirects the user agent to the SSO Authorization URL provided by the Partner. The next URL is properly URL encoded before transmission.
Ensures the current user is authorized and generates an SSO ticket of
9876543210. This ticket and the SSO token is appended to the next URL provided. The
next URL must be properly URL decoded before appending the
sso_ticket. The user agent is redirected to this new URL.
sso_token parameter was provided the Partner system will retrieve the correct SSO token for this users account and append it to the URL.
Processes the redirect request and calls the SSO Validation URL to determine that the request is valid. This is a server-to-server call (not a redirection) and may have an impact on firewalls or other system configurations.
Ensures the tuple (SSO ticket, SSO token, product id) is valid. If the tuple is valid the SSO ticket should expire immediately. The SSO ticket should also expire 60 seconds after creation if it hasn’t been used by that time. The system should respond to the request with an HTTP 200 response to signify successful validation. Any other response will be interpreted as a failure to authenticate.
Upon receipt of an HTTP 200 response a user session is created and the user is now logged in to the Vendasta product.