Single Sign-On Authentication

Document created by myles.bruggeling on Dec 5, 2018Last modified by jason.shaw on Nov 27, 2019
Version 11Show Document
  • View in full screen mode

 

If your company policy supports Single Sign-On (SSO) authentication, Turbonomic enables SSO authentication by using Security Assertion Markup Language (SAML) 2.0.


At a high-level, the process involves:

  • Creating external groups or at least one external user for SSO. See “Managing User Accounts” in the Turbonomic User Guide.
  • Configuring Turbonomic to connect to the SAML Identity Provider (IdP). See Configuring Single Sign-On


When SSO is enabled, use your SSO credentials to log in to your Turbonomic instance. Do not use your local or Active Directory (AD) credentials for the login. The Identity Provider (IdP) will perform the authentication.

NOTE: When you enable SSO, Turbonomic only accepts authentication from the IdP you configure. Remote requests via the Turbonomic REST API do not use SSO. For security reasons, those REST API requests will not execute while SSO is enabled. As a result, integrations which use the REST API will not work on the Turbonomic instance where SSO is enabled.  

***As of v6.4.4 of Turbonomic you have the option to enable both SSO and access the REST API, look at step 7 below for the details of how to do this.


Configuring Single Sign-On

 

To configure Single Sign-On, perform these steps:
1. (Required) Create external groups or at least one external user for SSO.

IMPORTANT: When SSO is enabled, Turbonomic only permits logins via the SSO IdP. Whenever you navigate to your Turbonomic installation, it redirects you to the SSO Identity Provider (IdP) for authentication before displaying the Turbonomic user interface.
Before you enable SSO for your Turbonomic installation, you must configure at least one SSO user with Turbo‐nomic administrator privileges. If you do not, then once you enable SSO you will not be able to configure any SSO users in Turbonomic.

 

To authorize an SSO user as an administrator, use EXTERNAL AUTHENTICATION to do one of the following:

  • Configure a single SSO user with administrator authorization.
    Add an external user. The username must match an account that is managed by the IdP.

  • Configure an SSO user group with administrator authorization.
    Add an external group. The group name must match a user group on the IdP, and that group must have at least one member.

    For information about creating external groups or external users for SSO, see “Managing User Accounts" theTurbonomic User Guide.


2. (Required) Ensure that the NTP server is configured and the system time on your Turbonomic instance is correct.

For instructions see Best Practices Synchronizing Time

 

3. Open an SSH terminal session to your Turbonomic instance.

 

4. Download the metadata from your IdP.

 

5. Examine your metadata.

Compare your metadata to the sample provided in Example of IdP Metadata
If your metadata includes optional attribute tags that are not listed in the example, remove those optional attribute tags since they are invalid.


6. Import the IdP metadata into the saml.xml file.

a)  Create the saml.xml file.

vi /srv/tomcat/data/config/saml.xml

b)  Copy the IdP metadata into the /srv/tomcat/data/config/saml.xml file.

c)  Save the file.


7. Modify the Tomcat configuration file.

a)  Open the Tomcat configuration file.

     vi /etc/tomcat/tomcat.conf

b)  Set the CATALINA_OPTS variable - for SSO login only (this will disable all REST API access into Turbonomic).

     CATALINA_OPTS="-Dadmin.policy.localusers=SAML_ONLY"

or you can set the CATALINA_OPTS variable - for SSO and REST API access use the value below instead of the one above.  NOTE: This is a new option that only works starting in v6.4.4 of Turbonomic and above.

     CATALINA_OPTS="-Dadmin.policy.localusers=SAML_ENABLE"

c)  Save the file.


8. Copy the properties file.

   cp /srv/tomcat/data/config/saml.template.properties /srv/tomcat/data/config/
   saml.properties

9. Modify the properties file.

a)  Open the saml.properties file.

     vi /srv/tomcat/data/config/saml.properties

b)  Set the IDP.entityId property to the same value as the IdP's Audience Restriction property.

For example: IDP.entityId=urn:test:turbo:markharm

c)  Set the Turbonomic public IP address.

For example: Turbonomic.Location=10.10.10.123

Another example: Turbonomic.Location=turbonomic.dns.entry.com

d)  Save the file.


10. Generate the SAML configuration file.
Run the config_saml.sh script to parse the values in the properties file and transfer them to the SAML configuration file, saml-security.xml.

a) Change to the directory for the SAML configuration script.

cd /srv/tomcat/script/appliance/

b) Execute the SAML configuration script and chmod commands below

./config_saml.sh
cd /srv/tomcat/data/config
chmod 644 saml*


11. Add a trusted custom IdP certificate.
The public domain default key store only trusts two public IdPs, Okta and SSO Circle. If you are using a proprietary IdP or other public IdPs, contact your security administrator to add the IdP certificates to the default key store. Default key store location: 

/srv/tomcat/webapps/vmturbo/WEB-INF/security/samlKeystore.jks
Key store password: nalle123

Run the commands below to import the custom IdP certificate:

vi /tmp/cert_name.crt

-paste contents of the IdP certificate into the file and save it

cd /srv/tomcat/webapps/vmturbo/WEB-INF/security/

keytool -importcert -alias <alias_name> -file /tmp/cert_name.crt -keystore samlKeystore.jks

-type key store password above

-type yes to confirm

keytool -list -keystore samlKeystore.jks (this will confirm the new certificate is in the keystore)

-type key store password above

 

12. Restart the Tomcat service.

   service tomcat stop
   service tomcat start

13. Verify that the configuration is successful.

a)  Navigate to the Turbonomic User Interface.
You will be automatically redirected to your IdP for authentication.

b)  Log in with the username that is a member of the external group or external user previously configured.

c)  Verify that the system time on your Turbonomic instance is correct.

If the time is not synchronized, this might cause an HTTP Status 401 -authentication failed exception in the browser.

d)  If the configuration is not successful, look for an HTTP Status 500 exception in the /var/log/ tomcat/catalina.out log file. If this exception exists, review your metadata for invalid optional attribute tags.

 

Example of IdP Metadata

This section provides an example of IdP metadata which may be useful when you are examining the optional attributes in your metadata.

 

If your metadata includes optional attribute tags that are not listed in the example, remove those optional attribute tags since they are invalid.

 

<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="http://www.okta.com/exkexl6xc9MhzqiC30h7"> <md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"> <md:KeyDescriptor use="signing">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate>
MIIDpDCCAoygAwIBAgIGAWMnhv7cMA0GCSqGSIb3DQEBCwUAMIGSMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEUMBIGA1UECwwLU1NPUHJvdmlkZXIxEzARBgNVBAMMCmRldi03NzEyMDIxHDAaBgkqhkiG9w0BCQEWDWluZm9Ab2t0YS5jb20wHhcNMTgwNTAzMTk0MTI4WhcNMjgwNTAzMTk0MjI4WjCBkjELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xDTALBgNVBAoMBE9rdGExFDASBgNVBAsMC1NTT1Byb3ZpZGVyMRMwEQYDVQQDDApkZXYtNzcxMjAyMRwwGgYJKoZIhvcNAQkBFg1pbmZvQG9rdGEuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAugxQGqHAXpjVQZwsO9n8l8bFCoEevH3AZbz7568XuQm6MK6h7/O9wB4C5oUYddemt5t2Kc8GRhf3BDXX5MVZ8G9AUpG1MSqe1CLV2J96rMnwMIJsKeRXr01LYxv/J4kjnktpOC389wmcy2fE4RbPoJne P4u2b32c2/V7xsJ7UEjPPSD4i8l2QG6qsUkkx3AyNsjo89PekMfm+Iu/dFKXkdjwXZXPxaL0HrNWPTpzek8NS5M5rvF8yaD+eE1zS0I/HicHbPOVvLal0JZyN/f4bp0XJkxZJz6jF5DvBkwIs8/Lz5GKnn4XW9Cqjk3equSCJPo5o1Msj8vlLrJYVarqhwIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQC26kYeLgqjIkF5rvxB2QzTgcd0LVzXOuiVVTZr8Sh57l4jJqbDoIgvaQQrxRSQzD/X+hcmhuwdp9s8zPHSJagtUJXiypwNtrzbf6M7ltrWB9sdNrqc99d1gOVRr0Kt5pLTaLe5kkq7dRaQoOIVIJhX9wgynaAKHF/SL3mHUytjXggs88AAQa8JH9hEpwG2srN8EsizX6xwQ/p92hM2oLvK5CSMwTx4VBuGod70EOwp6Ta1uRLQh6jCCOCWRuZbbz2T3/sOX+sibC4rLIlwfyTkcUopF/bTSdWwknoRskK4dBekFcvN9N+Cp/qaHYcQd6i2vyor888DLHDPXhSKWhpG
</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>
<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat
<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://dev-771202.oktapreview.com/app/ibmdev771202_turbo2_1/exkexl6xc9MhzqiC30h7/sso/saml"/>
<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://dev-771202.oktapreview.com/app/ibmdev771202_turbo2_1/exkexl6xc9MhzqiC30h7/sso/saml"/>
</md:IDPSSODescriptor>
</md:EntityDescriptor>

 

All authentication/authorisation errors are logged in the /var/log/audit/audit.log file


Disabling Single Sign-On

If for some reason you no longer want to use SSO, you can disable it for your Turbonomic installation. To disable Single Sign-On, perform these steps:

 

1. Open an SSH terminal session to your Turbonomic instance.

 

2. Modify the Tomcat configuration file to disable the CATALINA_OPTS variable.

a)  Open the Tomcat configuration file.

     vi /etc/tomcat/tomcat.conf

b)  Insert a comment character or delete the line for the CATALINA_OPTS variable.
For example:#
CATALINA_OPTS="-Dadmin.policy.localusers=SAML_ONLY"

c)  Save the file.


3. Navigate to the Tomcat configuration directory on your local machine.
The directory is: /srv/tomcat/data/config

4. Remove files from the Tomcat configuration directory.
Delete:

  • The metadata file: /srv/tomcat/data/config/saml.xml

  • The SAML configuration file: /srv/tomcat/data/config/saml-security.xml

  • The SAML properties file: /srv/tomcat/data/config/saml.properties


5. Restart the Tomcat service.

   service tomcat stop
   service tomcat start

6. Verify that the configuration is successful.

 

a)  Navigate to the Turbonomic User Interface.
You will no longer be redirected to your IdP for authentication. You will be redirected to the default Turbo- nomic login screen.
b)  Log in with a local account or an Active Directory (AD) account.

 

Support for Single Logout

 

If you are using the SSO feature, Turbonomic supports the Single Logout feature provided by Security Assertion Markup Language (SAML) 2.0. When you click Logout in the Turbonomic session that has SSO enabled, the SAML 2.0 Single Logout feature terminates the Turbonomic session, the browser session, the Identity Provider (IdP) session, and sessions at other Service Providers (SP) connected to the same IdP session.


If you want to use this feature, contact your security administrator to configure it.

 

The following are the requirements:

  • The Single Logout setting must be enabled on the IdP.
  • The IdP needs to trust the Turbonomic SAML key store certificate.


If the IdP does not enable or support Single Logout, you need to manually log out from the IdP to fully log out from Turbonomic.

 

If you close the browser without clicking Logout or if your browser session times out, you can log in again provided the Turbonomic or the IDP session is valid.

 

Managing User Accounts


As an administrator, you specify accounts that grant users specific access to Turbonomic. User accounts determine the following for a given user login:

  • User Authentication

To configure an account, you set the type of authentication the account will use:

  • Local User – Configure the username and password and save those credentials on the Turbonomic server.
  • External User – Single user accounts that authenticate through Single Sign-on (SSO) or through Microsoft Active Directory (AD).
  • External Group – User group accounts that authenticate through SSO or AD.   

 

  • User AuthorizationProperties that determine the range of access and features for a given user:
  • Role – Access to specific Turbonomic features
  • Type – Dedicated user or tenant on a virtual datacenter Scope – How much of the environment this user can manage
  • Scope – How much of the environment this user can manage
As you configure user accounts, you can set up access to specific clusters in your environment. You can even set up accounts for tenant customers, and only show them the virtual workloads they own in their specific virtual datacenters.

 

3 people found this helpful

Attachments

    Outcomes