SAML 2

What is SAML 2.0?

SAML 2.0 is a security standard dedicated to the exchange of authentication and authorization information. This protocol is based on the exploitation of information tokens to exchange data between a SAML "authority" (Identity Provider) and a SAML "consumer" (Service Provider).

Acronyms:

SAML: Security Assertion Markup Language
IDP: Identity Provider
SP: Service Provider

Prerequisites to group identities:

Compatibility with IDPs and SP initiated by SAML 2.0 connections.
Compatibility with HTTP POST requests and redirection links.
Compatibility with the HTTPS protocol.
Compatibility with SAML assertion requests.
IDP and SP metadata.

How to set up the SAML 2.0 authentification on your chatbot?

If the SAML protocol is activated on a chatbot, users have to authenticate themselves to receive messages from the chatbot. Unauthenticated users can send as many messages to the chatbot but they will not receive any answers. The cache duration last for 5 minutes

Note: once activated, the SAML authentification will apply to the API chat meaning all your chatbots, no matter the channels (website, Teams, Meta), will only answer to authenticated users.

By defaul, the SAML setup page does not show in the main menu. To make it visible, go to Preferences >Bot >General >Connection and check Enable SAML.

Then the SAML 2 setup page will appear in the main menu: Preferences > Api > Saml 2

Navigate to the Saml 2 page where you will see the following parameters:

Dydu Service Provider (SP): you can download the Service Provider metadata required by your Identity Provider.
Identity Provider (IDP): you need to upload here your IDP file (obtained via your IDP administration account).
Enable/Disable SAML 2.0 authentification: you can easily activate or deactivate the SAML 2.0 authentification on your chatbot.
Trusted hosts (separated by comma) - optional: to prevent users from being redirected to any malicious website during their authentification process, you can specify trusted URLs here so that users will only be redirected to these trusted URLs. In general, they would be the URL of your IDP and of a web page(s) where your chatbot will be deployed.
Login protocol: we recommend using the HTTP-POST protocol (selected by default) in priority.
Click Send. You will see a confirmation message that SAML authentification is effective on your chatbot.

The Current IDP info section will give you an overview of the IDP information. The IDP file you upload may contain errors that lead to bugs. In this case, you will need to repair the file.

The Test configuration section allows you to test if SAML 2.0 runs well on your chatbot. If so, after clicking on "Send auth request to IDP", you shoud be redirected to your IDP authentification page.

Use case: setting up SAML with Google as Identity Provider

In this section we will walk you through how to enable SAML authentication by using Google as the Identidy Provider.

1. Download Dydu Service Provider data from the BMS

Go to Preferences >APIS >SAML 2> dydu Service Provider (SP).
Click Download data.

2. Create a Google SAML application

Log in to https://admin.google.com
Go to Applications >SAML Applications then click +.
Then click Set up my custom application.
Use option #2 and download the IDP data.
Follow the procedure according to Service Provider Details.
Complete the following fields:
- ACS URL: https://xxxxx.doyoudreamup.com/servlet/api/saml2/post
- Entity ID: https://xxxxx.doyoudreamup.com/BOTID
- Example: https://xxxxx.doyoudreamup.com/8c39c889-2cbc-437e-b157-c8f23e5558d1
The format of the name ID: EMAIL.
Complete the procedure
The button allows you to enable the service for everyone.
The operation may take some time.

3. Enable SAML on your chatbot

Go to Preferences >APIS >SAML 2 in the BMS.
Import the IDP file in the IDP section.
Check the Enable / Disable SAML2 authentication box
Define your trusted URL if you wish.
Choose the HTTP-POST protocol then emailAddress as the name format protocol.
Finally, click send.

4. Test SAML authentification without a chatbot

Click Send auth request to IDP. You should be redirected to the Google authentication page.

5.1. Test SAML authentification on a the chatbot V4

Go to Integration >Web >Chatbox.
Click Create new configuration or select an existing configuration.
Click Show advanced view then go to the module.common.saml2.auth module.

Check both boxes in Configurations sub-menu (use-relay and redirect-top-window).
Deploy your configuration and test your chatbox.

5.2. Test SAML authentification on a the chatbot V5

First, you need to set the "SAML" value as "true" in the configuration.json file of your chatbot v5.

Then, lauch your chatbot and you should be redirected to the authentification page.

For more information, approach your Customer Success Manager.

Alert email for the expiration of a SAML certificate

An alert email is generated by DYDU every week starting one month before the expiration of your SP certificate generated by DYDU. This certificate has a validity period of 3 years.

Mail example :

This alert concerns only the SP certificate. There are two possible scenarios following this email:

Case 1: Only the SP certificate has expired -> Certificate deletion

-> No impact on the bot.

Case 2: Both the SP certificate and the IDP have expired -> Deletion of the SP certificate, then regeneration of the certificate for creating a new IDP to upload in the BMS

-> Impact on the bot, it will no longer be available when the IDP is expired.

How to check the validity of an SP certificate?

You can download the data of your SP certificate generated from your BMS, in the SAML 2 menu.

With the data, you can check the validity of the SP certificate by copying the certificate into a certificate decoder, for example: https://www.sslshopper.com/certificate-decoder.html

Example of an expired certificate result since June 12, 2021:

It is also possible to view the certificates on the /bo of your bot:

chatbox.auth.saml.IDP: IDP Certificate

chatbox.auth.saml.key.cert: SP Certificate