How do I configure single sign-on (using SAML)?

After following the steps in this tutorial, your users will be able to sign-in to the Vidbeo video CMS without having to provide a password to us. All authentication is handled by your identity provider. The only data we need to know about each user is their email address, since that is how our platform identifies them.

In this tutorial we are using Centrify’s ‘Identity Service’ to authenticate our users, however the process should be similar for the identity provider that you are using. SAML is a standard method of authentication and so much of the information asked for will be common to all providers.

However if you are using Windows Server’s Active Directory (AD & ADFS), we have written a separate guide explaining How do I configure single sign-on (using ADFS)? that you should read instead.

The aim

At the end of this process, your users will be able to sign-in to manage your private video hosting just like our example ‘SSO User’ can do in the following video (04:34):

Prerequisites

SAML server
You will need an identity provider that supports SAML 2.0. You can build an in-house SAML server, or use one of the commercially available solutions such as those from Centrify or PingIdentity

Provisioned users
Each of your users needs to have an email address attribute defined, since that is how our platform identifies them

EntityID (aka Issuer)
You will need to obtain this from your identity provider

Sign-in (aka Remote log-on) URL
You will need to obtain this from your identity provider

X509 Certificate
You will need to obtain this from your identity provider. It should be in PEM format

Notes

Your identity provider may need to know the hashing algorithm we use. It is SHA-1.

Get started

Start by signing in the Vidbeo online video platform using your current email address and password. If you have been tasked with configuring single sign-on then it is likely you already have been granted this access. You should see an option called ‘Account’ in the main menu. Click on that.

Click on ‘Single sign-on’.

You should now see a page that describes the data we need from you to configure single sign-on, and also the data you will need from us.

Now in order to provide that data, we suggest you now open your identity provider’s configuration page - in a different tab or web browser window - so that you can quickly and easily switch between the two. The SAML process relies on both providers knowing about the existence of the other, so it is helpful to configure the two simultaneously.

In this case, we are using Centrify’s Identity Service, so we have signed in to their admin page, clicked on ‘Apps’, then clicked on the ‘Add Web Apps’ button. We have then clicked on the ‘Custom’ tab within that panel to add a custom SAML app:

Custom web app in Centrify

We use SAML to identify a user, so please click on the ‘Add’ button next to ‘SAML’. You will see a confirmation a new app has been added, so click on ‘Close’ to proceed to enter its details:

SAML web app settings

Here you can see that the first button asks for our metadata: ‘Upload SP Metadata’ (your identity provider may not need this). Clicking on that button within the panel prompts you to enter a URL to the service provider’s metadata. You can see what that URL is if you now switch back to the tab/window containing the Vidbeo admin panel:

SAML web app metadata

Having entered that metadata’s URL, underneath that button in the identity provider’s interface is a box asking for the ‘Assertion Consumer Service URL’. This is the most important part of the settings you need to provide, since that is the URL that the identity provider’s response is sent to in order to authenticate the user. If you switch back to the Vidbeo admin panel, you can see the URL you will need to put in that box:

SAML web app ACS URL

Next, you will see that Centrify (the Identity Provider) provides their ‘Issuer’. This is also known as ‘EntityId’ (which is what our platform calls it). They provided a default value when the app was created, so we have edited their value slightly to end ‘VidbeoAdmin’. This EntityId needs to be a URL and it is used to identify the application that is sending the response to our authentication request:

SAML web app EntityId

… so now our platform needs to know what that value is (so that we can identify who the response that is sent to the Assertion Consumer Service URL has come from). So switch back to our admin panel, and copy that URL into the box we have provided for your ‘EntityId’:

SAML web app SP EntityId

If you now switch back to the Identity Provider’s screen and scroll down, you can see that they have provided their sign-in URL, their error URL, and their sign-in URL. Below those URLs can be found a link to download their metadata, and below that, a link to download their certificate:

SAML web app details

… so please now copy the ‘Sign-in URL’ to the Vidbeo admin panel, where you will be asked for enter it in the box we provide. The ‘Sign-out URL’ is optional. If you do provide that, it triggers a sign-out request to be sent to your identity provider when the user signs our of our platform:

SAML web app sign in URL

The penultimate value you need to provide us with is the certificate your identity provider uses to sign its requests. This is like an electronic signature. In Centrify’s case, we can obtain the certificate by simply clicking on the blue link you will have seen in the previous image - where it provided the option to ‘Download Signing Certificate’.

That certificate looks like a long series of letters and numbers, starting with ‘—–BEGIN CERTIFICATE—-’. You will need to open that certificate (it is just like a text file, so open it in something like Notepad) and copy and paste the entire certificate into the box we provide in our form:

SAML web app certificate

Finally, the last option in our form asks whether you would like to ‘Permit Unknown Users’ to sign in. This is up to you (the default is ‘No’). Essentially setting it to ‘No’ means that you have more control over the users, at the expense of having to do more user management. If set as ‘No’, the Vidbeo platform will only process their request to sign-in if they are already known within our platform (ie their email address is linked to an existing user). You can see who your account’s users currently are by clicking on ‘Users’ within the main menu. This allows you to enter their name, preferences (such as their home page) and define a role for them in advance of them signing in, too.

Setting ‘Permit Unknown Users’ to ‘Yes’ means that our platform will let a user sign-in to the admin panel simply upon receiving a successful authentication from your identity provider. If they are not already known to the platform, a new user account will be created for them and your account’s default role will be assigned to them. Since our platform has no way of knowing their name, it will simply call them ‘SSO User’.

So that is all of the information needed at our end, so go ahead and click ‘Save Changes’ at the bottom of the page in the Vidbeo admin panel. If that has all worked correctly, you should see a tick and at that point single sign-on has been configured.

Finishing touches

It is likely you will need to do a bit more work to configure things at your identity provider’s end. If you now switch back to the tab/window with Centrify open, you will see that while all of the ‘Application Settings’ have now been entered, we still need to do a little more configuration. Click on ‘Description’ and you will see this new app has had a generic title and description provided. So you will need to change those to something that describes what this app does. We can provide you with a logo file should you want one too:

SAML web app title and description

The next option is called ‘User Access’. Here we can specify which users are allowed to use this app. For this demonstration, we’ll just let everyone use it (although, as mentioned above, a sign-in request from just anyone won’t work unless they are already a known user within the Vidbeo platform):

SAML web app user access

Finally, we need to specify the attribute that will identify the user. We need their email address. In Centrify, you can leave this as ‘userprincipalname’:

SAML web app account mapping

… and that is all we need to configure. We now have an app that will allow users of our identity service to be able to sign-in to the Vidbeo admin panel, simply by clicking on the app’s icon. So we can click ‘Save’ … and that should return us to the ‘Apps’ page:

SAML web apps

So now that has all been configured, if one of your users wishes to sign-in to the Vidbeo admin panel, they simply need to click on the app in their own ‘Apps’ page. Our system will then be able to identify them by checking against your identity provider’s database, and if they are signed in to that, they will be seamlessly signed in to our platform too.

Alternative method

If a user has access to an ‘Apps’ page, they can simply click on that app in order to sign-in directly. However your identity provider may not have an equivalent page that your users can access.

Therefore we provide another way users can initiate a single sign-on request. If they visit our normal sign-in form they would normally need to enter an email address and a password. However when you create each user within the ‘Users’ page of your admin panel, you can specify that they are authenticated using ‘Single sign-on’ (instead of the usual ‘Password’). This means our system knows they do not need to enter a password. So if they simply type in their email address (and leave the password box empty) …

Alternative sign-in

… when they click on ‘Sign in’, our system recognises they need to be authenticated using an external service - and forwards them on to your identity provider’s sign-in URL.

If they are already signed in, your identity provider then immediately forwards them on to our admin panel, and so they are immediately and seamlessly signed in without having to provide us with their password.

Alternatively, if they are not already signed in to your identity provider, they will be prompted to sign in to it:

Alternative sign-in at identity provider

… and upon entering their email address and password, rather than be taken to their ‘Apps’ page (or your identity provider’s default home page), they are instead taken directly to our admin panel, as they have now been authenticated.

As you can see, the process of configuring single sign-on does take quite a long time, however once it is done it is much more convenient for your users and gives you far greater control over their access to our system.

As ever, if you have any questions about this, or any other aspect of our enterprise video hosting, please don’t hesitate to email support@vidbeo.com

Go back to the questions about users