How to get Duo 2FA and SuiteCRM SAML SSO auth to play nice with each other

There are a few less documented, or shall we say obscure, config parameters to get this working. I’ll outline what worked for me.

1. Install/Upgrade to the latest version of SuiteCRM. I’m using 7.10.10. This version will include the SAML integrated library to help make this easier.
2. Setup your Duo Access Gateway. (Edit 3/2023 — Duo has deprecated the Access Gateway, you can now use Duo SSO directly, or “Generic SAML Service Provider — Single Sign-On” as they call it)
3. Setup your Duo Application via your Duo Dashboard. In Duo, go to Applications, click “Protect an Application” button, then search on keyword “Generic”. You should find the “SAML — Service Provider”

4. Set a Service provider name of your choice

5. Set your Entity ID as

https://suitecrm.yourdomain.com/index.php?action=Login&module=Users

6. Set your Assertion Consumer Service as

https://suitecrm.yourdomain.com/index.php?action=Login&module=Users

7. Set your Default Relay State as

https://suitecrm.yourdomain.com

8. Set your NameID format

urn:oasis:names:tc:SAML:1.1:name-id-format:emailAddress

9. Set your NameID attribute as

mail

10. Set your Send attributes to “All”

11. Signature algorithm to SHA-265

12. Sign response = checked

13. Sign assertion = checked

Now save your Duo Application config using the first Save Button. Once saved, download your Duo application config file using the link at the top of your application config page. We’ll use this file to upload to your Duo Access Gateway.

14. Log into your Duo Access Gateway (DAG), go to Applications, and upload the .json file you downloaded from your Duo Dashboard. Once the Application has been created copy down your SSO URL and Logout URL from the bottom of the DAG Application page, and also download the certificate from that same page.

Now lets configure SuiteCRM

15. Log into your SuiteCRM instances, go to Admin > Password Management

16. Under SAML Authentication, check the box to enable it.

17. For the “Login URL” paste in the DAG SSO URL you copied down.

18. For the “SLO URL” paste in the DAG Logout URL you copied down.

19. And for the X509 Certificate, just view that certificate in Notepad, and copy/paste it here.

20. Save your settings, but make sure to not log out yet.

21. Now, before you try to login with an SSO user, you MUST setup the users in SuiteCRM first. Create your user in SuiteCRM, make sure to use that users’ email address as their login name, give them a random password (SuiteCRM wont use it, so don’t worry about remembering it), assign a role to the user, now the important part, hit the advanced tab for the user, and select the check box for “SAML2Authenticate”.

22. Then manually edit the config_override.php file in the root of your SuiteCRM installation with your favorite text editor, and add the following line, using the domain of your Duo Access Gateway:

$sugar_config['http_referer']['list'][0] = 'dag.yourdomain.com';

And you should now be working!