Single Sign-On with Vimeo OTT using SAML (General Instructions)

OTT sellers using this integration must agree to provide their own viewer support. Information on how support works can be found in this guide.

You can manage user logins outside of Vimeo OTT by configuring third-party authentication services (single sign-on / SSO) for your OTT site. When you have SSO enabled, all Customers will be redirected to the third-party identity provider to authenticate their accounts before they can watch content. If your site contains multiple destinations, SSO will allow your Customers to use the same login across them all. 

The following instructions provide a step-by-step walkthrough on how to configure your Identity Provider and your OTT Site to leverage SSO authentication using the SAML protocol.

If you are unfamiliar with Single Sign-On, please read our introductory article first.

In this article

• Configuring Identity Provider with SAML

• Configuring Vimeo OTT with SAML

• Customer Migrations

• Testing SSO

Configuring Identity Provider with SAML

Before you begin 

There are many different Identity Providers available. As long as your IdP is capable of providing authentication through a SAML interface (most are), the following instructions will help to guide you through the connection process.

To begin, make sure you have an account already registered with your Identity Provider. Vimeo OTT can not troubleshoot your account nor provide technical support on populating your Identity Provider with user information.

Summary of Requirements

• Persistent NameID: a unique and immutable ID for a given user
• Email NameID: the email address for the given user
• (Optional) fullName: pass along SAML Assertion with First and Last Name

You may also want to refer to our specific onboarding instructions if you use the following services:

• Okta
• Auth0
• Azure AD

The following is a broad overview of the steps to configure your IdP. Note that your Identity Provider may have a very specific interface for setting this up. 

1. Create a new Service Provider.
   
   
2. Choose SAML as the primary type for your connection.
   
   
3. In the new SP settings, give your App a name (such as “Vimeo OTT.")
   
   
4. In the SAML Settings for your SP, provide the following information:
   1. Add your Service Provider SAML Consumer URL:
      
      • You will find this URL in your OTT Site Settings under Single Sign-On in the left rail.
      • Copy the link from SAML Consumer URL and paste it into this block.
        
        
   2. Add your Service Provider URI:
      
      • You will find this URL in your OTT Site Settings under Single Sign-On in the left rail.
      • Copy the link from SP Entity ID and paste it into this block.
        
        
   3. Configure a Subject for a NameID that contains the User’s ID:
      
      • The format should be persistent.
        
        
   4. Configure a Subject for a NameID that contains the User’s Email:
      
      • The format should be emailAddress.
        
        
   5. (Optional) Configure an Attribute Statement for your Customer’s Name:
      
      • Create a new Attribute Statement.
        
      • In the Name field, enter the key fullName.
        
      • In the Format field, choose Unspecified.
        
      • In the Value field, enter the value pass along the properties for your Customers name (this may be something like `user.firstName + " " + user.lastName`)
        
        
   6. The Application is now created and ready to be added to your Vimeo OTT account. Leave this tab open and follow the instructions for updating your Vimeo OTT Settings in another window.

If prompted for a Default RelayState, you may leave this field blank.

Use your "SAML consumer URL" and "SAML service provider metadata URL" found in your OTT SSO Settings to configure the following items. Please note, if you are not using a custom domain, this will point to a vhx.tv subdomain. If you are using a custom domain, this will point to the custom domain.

SAML Response Destination 
No Custom Domain: https://yoursite.vhx.tv/saml/consume
Custom Domain: https://yoursite.com/saml/consume

SAML SubjectConfirmationData Recipient
No Custom Domain: https://yoursite.vhx.tv/saml/consume
Custom Domain: https://yoursite.com/saml/consume

SAML AudienceRestriction
No Custom Domain: https://yoursite.vhx.tv/saml/metadata
Custom Domain: https://yoursite.com/saml/metadata

Configuring Vimeo OTT with SAML

To configure your Vimeo OTT site for Single Sign-On you will use the information provided from your Site Settings under Single Sign-On in the left rail. If you do not already have this page open, do so to begin.

⚠️Note: When an Identity Provider is enabled, all authentication for your OTT Site will be sent to your IdP. This means if you have any existing Customers on OTT before enabling the integration that is not also in your IdP, they will need to be migrated. Vimeo OTT can not provide support for this migration but we do provide tools for exporting Customers to CSV.

1. In your Single Sign-On settings, give your integration a SAML Service Name. This does not have to match the Application name you provided in your IdP but it is a recommended practice to do so.
   
   
2. Provide “Login button text” - this is generally a generic message along the lines of “Sign In with [Your Site]”
   
   • In most cases, your Customers will never see a button in order to sign in but in certain cases where this need surfaces, we will use the text you have provided.
     
     
3. If your IdP provides a metadata URL to retrieve your SP configuration, choose the Metadata URL option, paste the link, and click Retrieve. If your IdP does not provide a metadata URL for your SP configuration, you will need to copy and paste the SAML Certificate settings into your OTT Account before enabling the Integration.
   • In your IdP, copy the Identity Provider Single Sign-On URL. Paste this into OTT under the Single sign-on endpoint.
     
   • In your IdP, copy the entire X.509 Certificate including the "Begin Certificate---" all the way down through "---End Certificate." Paste this into OTT under Certificate.
     
     
4. Under Remote Account Registration URL, provide a URL to the page where your Customers should sign in. (This is most likely your IdP URL.)
   
   
5. Under Remote Settings Page URL, provide a URL to the page where your Customers can manage their settings. As Vimeo OTT is no longer the source of truth for authentication, this will be handled on your service.
   
   
6. Under Support Email, provide an email address where Customers can contact your Support team to help troubleshoot signing in. As Vimeo OTT is no longer the source of truth for authentication, your team must provide this information.
   
   
7. (Optional): Under Default Products, choose from your list of Active products that you wish to grant Entitlements to Customers who first authenticate successfully. If your integration with Vimeo OTT requires more granular Entitlements than a default product, please leverage the OTT API to add Products to your Customers. 

When you are ready, choose Enable SSO and save again. As soon as this option is selected and saved, your Customers will start to be redirected to your Identity Provider.

Customer Migrations

Before you enable Single Sign-On, please ensure that all of your Customers exist within your IdP beforehand. If you are enabling SSO for your Site and have not migrated your Customers to your IdP they will suffer service interruption. 

Use the Customers export tool in your OTT CMS to retrieve the latest list of your Customers.

Testing SSO

If you wish to test your SSO configuration before you enable it, simply enter in all of the requested information as noted above, save your work and point your browser to "https://yoursite.vhx.tv/saml/login" (where "yoursite" is your OTT subdomain). This will enforce the SSO settings for your site regardless of them being enabled, allowing you to test the integration.