Configuring ADFS SSO with Apache CloudStack/CloudPlatform using SAML

Apache CloudStack supports SAML2 integration. This can be used to enable SSO using ADFS.

Prerequisites:

1. ADFS server running with https enabled (lets call this sso.example.com) (This is called Identity Provider or IdP in SAML terminology)

2. Management Server with https enabled (lets call this cloud.example.com/client) (This is called Service Provider or SP in SAML terminology)

3. ADFS and MS should be able to talk to each using domain names and https

Installing ADFS on windows server 2k12 R2

1. Keep a verified certificate PFX file and password handy
2. Go to server manager, Manage -> Add roles and Features, select Domain services and install.
3. Once installed, configure it and promote it to domain server 
4. Go to server manager, Manage -> Add roles and Features, select Federation Services and install
5. Once installed, configure it. During the configuration it asks for certificate provide the required certificates and install

Reference: https://www.virtuallyboring.com/how-to-setup-microsoft-active-directory-federation-services-adfs/

Enabling SSL on CloudStack Management server

In /etc/cloudstack/management/server.xml uncomment ssl connector

    <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"

               maxThreads="150" scheme="https" secure="true"

               clientAuth="false" sslProtocol="TLS" sslEnabledProtocols="TLSv1.2,TLSv1.1"

               keystoreType="PKCS12"

               keystoreFile="location to PFX file"

               keystorePass="password of the PFX file"

               />

enable port 8443 in iptables and optionally redirect 443 to 8443

• iptables -I INPUT 1 -p tcp -m tcp --dport 8443 -j ACCEPT
• iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -j REDIRECT --to-port 8443

restart cloudstack management server

Configuring Relying party trust for the MS on ADFS

1. make sure that ADFS is working properly by accessing https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml 
2. on ADFS server(I used Microsoft Windows Server 2k12 R2), go to ServerManager -> Tools -> AD FS Management
3. On the AD FS Management window, go to AD FS ->  Trust Relationships -> Relying Party Trusts -> Add Relying Party Trust
4. On the wizard, on clicking start, it will ask for SP metadata url. give https://cloud.example.com/client/api?command=getSPMetadata click next,next and do the configuration (check screenshots below)
5. right click on the newly configured trust, properties, advanced and set the algorithm to SHA1 (check screenshots below)
6. Enable form based authentication in AD FS -> Authentication policies -> Edit global Authentication policies(check screenshots below)

At this stage, ADFS is ready to be receive requests from CloudStack

Configuring ADFS on CloudStack MS

Go to global settings and search for SAML. Configure all the required attributes. Here is the list of sample configuration that worked for me

mysql> select name, value from configuration where name like '%saml%';

+-------------------------+--------------------------------------------------------------------------+

| name                    | value                                                                    |

+-------------------------+--------------------------------------------------------------------------+

| saml2.append.idpdomain  | true                                                                     |

| saml2.default.idpid     | http://sso.example.com/adfs/services/trust                                |

| saml2.enabled           | true                                                                     |

| saml2.idp.metadata.url  | https://sso.example.com/federationmetadata/2007-06/federationmetadata.xml |

| saml2.redirect.url      | https://cloud.example.com/client/                                         |

| saml2.sigalg            | SHA1                                                                     |

| saml2.sp.contact.email  | dev@cloud.example.com                                                     |

| saml2.sp.contact.person | Example Admin                                                             |

| saml2.sp.id             | com.example.cloud                                                         |

| saml2.sp.org.name       | Example Cloud                                                             |

| saml2.sp.org.url        | http://example.com                                                        |

| saml2.sp.slo.url        | https://cloud.example.com/client/api?command=samlSlO                      |

| saml2.sp.sso.url        | https://cloud.example.com/client/api?command=samlSsO                      |

| saml2.timeout           | 3600                                                                     |

| saml2.user.attribute    | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn                |

+-------------------------+--------------------------------------------------------------------------+

15 rows in set (0.00 sec)

There is no automatic creation of users in CloudStack. Admin should add users to CloudStack and authorize them against the specific IdP using authorizeSamlSso API (or from UI in Users page) before they can single signon.

SSO FLOW

SSO is SP initiated. IdP cannot initiate SSO. This means, users need to start the SSO process from CloudStack UI. Multiple IdP servers are supported. On login screen, users will be able to select the list of IdP registered from a dropdown and continue with SSO.


User is redirected to IdP site and redirected back on authentication. CloudStack SAML2 plugin checks if the authentication is successful and user with username exists in ACP and is allowed to proceed. (Else, error message is shown.)


In case of more than one allowed SAML users with same username in different CloudStack domains, authenticated user will be allowed to use any of the available account in any domain (through a dropdown in UI)