Setting Up SAML authentication

Security Assertion Markup Language (SAML) is an XML-based open standard for exchanging authentication and authorization data between parties. To configure Turbonomic to authenticate via SAML, complete the following steps.

(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 Turbonomic 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.
(Required) Ensure that chrony is configured and the system time on your Turbonomic instance is correct.

For instructions, see Synchronizing Time.
Obtain the metadata from your IdP.

You will use this metadata to configure SSO in the Turbonomic CR file located at:
```
/opt/turbonomic/kubernetes/operator/deploy/crds/charts_v1alpha1_xl_cr.yaml
```
To get the metadata:
1. Contact your security administrator to obtain the metadata from IdP.
2. Save the metadata file in a directory on your local machine.
```
/tmp/MySamlMetadata.txt
```
3. Compare your metadata to the example IdP metadata.
  
  If your metadata includes optional attribute tags that are not listed in the example, remove those optional attribute tags since they are not supported.
Obtain a certificate from IdP.

Contact your security administrator to obtain a certificate from IdP.

Update the CR file with your SAML configuration.

Edit the cr.yaml file that configures your Turbonomic node, and then deploy or restart the node.

Display the contents of your downloaded SAML metadata.

For example, assuming you saved the file to this location on your local machine, run the command:
```
cat /tmp/MySamlMetadata.txt
```
Open the CR file for editing.

In a shell, cd to the deploy/crds directory in the Turbonomic VM.
```
cd /opt/turbonomic/kubernetes/operator/deploy/crds
```
Open the CR file for editing. For example, to open the file in VI:
```
vi charts_v1alpha1_xl_cr.yaml
```
As you edit this file, refer to the metadata that you obtained from your IdP.
In the CR file, search for or scroll to the entry for the API component.
```
apiVersion: charts.helm.k8s.io/v1alpha1
```
Turn on the SAML feature.

For the first API property under spec:properties:api:, set the following:
```
samlEnabled: true
```
Set the SSO endpoint.

In the SAML metadata, find the entry for md:SingleSignOnService. Within that element, find the Location attribute. The value of Location is the SSO endpoint. Using the sample metadata, make the following setting in your CR file:
```
samlWebSsoEndpoint: https://dev-771202.oktapreview.com/app/ibmdev771202_turbo2_1/exkexl6xc9MhzqiC30h7/sso/saml
```
Set the SAML entity ID.

In the SAML metadata, find the entry for md:EntityDescriptor. Within that element, find the entityID attribute. Using the sample metadata, make the following setting in your CR file:
```
samlEntityId: http://www.okta.com/exkexl6xc9MhzqiC30h7
```
Set the SAML registration.
```
samlRegistrationId: simplesamlphp
```
Set the SAML SP entity ID.
```
samlSpEntityId: turbo
```
Enter the SAML certificate.

In the metadata that you got from your IdP, find the entry for <ds:X509Certificate>. Copy the characters between <ds:X509Certificate> and </ds:X509Certificate>.

Create an entry for the certificate in the API properties section of the CR file. On a new line, enter:
```
samlIdpCertificate: |
```
Open a new line after the entry you just created, and paste the certificate content that you copied from your metadata file.

The finished API section of the CR file is similar to the following example:

apiVersion: charts.helm.k8s.io/v1alpha1
kind: Xl
metadata:
  name: xl-release
spec:
  properties:
    api:
      samlEnabled: true
      samlWebSsoEndpoint: https://dev-771202.oktapreview.com/app/ibmdev771202_turbo2_1/exkexl6xc9MhzqiC30h7/sso/saml
      samlEntityId: http://www.okta.com/exkfdsn6oy5xywqCO0h7
      samlRegistrationId: simplesamlphp
      samlSpEntityId: turbo
      samlIdpCertificate: |
        -----BEGIN CERTIFICATE----- 
        MIIDpDCCAoygAwIBAgIGAWMnhv7cMA0GCSqGSIb3DQEBCwUAMIGSMQswCQYDVQQGEwJVUzETMBEG
        A1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU
        MBIGA1UECwwLU1NPUHJvdmlkZXIxEzARBgNVBAMMCmRldi03NzEyMDIxHDAaBgkqhkiG9w0BCQEW
        DWluZm9Ab2t0YS5jb20wHhcNMTgwNTAzMTk0MTI4WhcNMjgwNTAzMTk0MjI4WjCBkjELMAkGA1UE
        BhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xDTALBgNV
        BAoMBE9rdGExFDASBgNVBAsMC1NTT1Byb3ZpZGVyMRMwEQYDVQQDDApkZXYtNzcxMjAyMRwwGgYJ
        KoZIhvcNAQkBFg1pbmZvQG9rdGEuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA
        ugxQGqHAXpjVQZwsO9n8l8bFCoEevH3AZbz7568XuQm6MK6h7/O9wB4C5oUYddemt5t2Kc8GRhf3
        BDXX5MVZ8G9AUpG1MSqe1CLV2J96rMnwMIJsKeRXr01LYxv/J4kjnktpOC389wmcy2fE4RbPoJne
        P4u2b32c2/V7xsJ7UEjPPSD4i8l2QG6qsUkkx3AyNsjo89PekMfm+Iu/dFKXkdjwXZXPxaL0HrNW
        PTpzek8NS5M5rvF8yaD+eE1zS0I/HicHbPOVvLal0JZyN/f4bp0XJkxZJz6jF5DvBkwIs8/Lz5GK
        nn4XW9Cqjk3equSCJPo5o1Msj8vlLrJYVarqhwIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQC26kYe
        LgqjIkF5rvxB2QzTgcd0LVzXOuiVVTZr8Sh57l4jJqbDoIgvaQQrxRSQzD/X+hcmhuwdp9s8zPHS
        JagtUJXiypwNtrzbf6M7ltrWB9sdNrqc99d1gOVRr0Kt5pLTaLe5kkq7dRaQoOIVIJhX9wgynaAK
        HF/SL3mHUytjXggs88AAQa8JH9hEpwG2srN8EsizX6xwQ/p92hM2oLvK5CSMwTx4VBuGod70EOwp
        6Ta1uRLQh6jCCOCWRuZbbz2T3/sOX+sibC4rLIlwfyTkcUopF/bTSdWwknoRskK4dBekFcvN9N+C
        p/qaHYcQd6i2vyor888DLHDPXhSKWhpG
        -----END CERTIFICATE-----

Save your changes to the CR file.

Apply the modified cr.yaml file.

kubectl apply -f /opt/turbonomic/kubernetes/operator/deploy/crds/charts_v1alpha1_xl_cr.yaml

Restart the API component to load the new spec.
1. Open an SSH terminal session to your Turbonomic instance.
2. Restart the API component.
```
kubectl delete pod api-<API_POD_ID>
```
  To auto-fill the pod ID, type api- and then press TAB.
Verify that the configuration is successful.
1. Navigate to the Turbonomic User Interface.
  
  You are automatically redirected to your IdP for authentication.
2. Log in with the username that is a member of the external group or external user that you previously configured.
3. 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.
4. If the configuration is not successful, look for an HTTP Status 500 exception in the product log. If this exception exists, review your CR file for invalid entries.

Example of IdP metadata

The following example of IdP metadata 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 not supported.

    <?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>
         MIIDpDCCAoygAwIBAgIGAWMnhv7cMA0GCSqGSIb3DQEBCwUAMIGSMQswCQYDVQQGEwJVUzETMBEG
         A1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU
         MBIGA1UECwwLU1NPUHJvdmlkZXIxEzARBgNVBAMMCmRldi03NzEyMDIxHDAaBgkqhkiG9w0BCQEW
         DWluZm9Ab2t0YS5jb20wHhcNMTgwNTAzMTk0MTI4WhcNMjgwNTAzMTk0MjI4WjCBkjELMAkGA1UE
         BhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xDTALBgNV
         BAoMBE9rdGExFDASBgNVBAsMC1NTT1Byb3ZpZGVyMRMwEQYDVQQDDApkZXYtNzcxMjAyMRwwGgYJ
         KoZIhvcNAQkBFg1pbmZvQG9rdGEuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA
         ugxQGqHAXpjVQZwsO9n8l8bFCoEevH3AZbz7568XuQm6MK6h7/O9wB4C5oUYddemt5t2Kc8GRhf3
         BDXX5MVZ8G9AUpG1MSqe1CLV2J96rMnwMIJsKeRXr01LYxv/J4kjnktpOC389wmcy2fE4RbPoJne
         P4u2b32c2/V7xsJ7UEjPPSD4i8l2QG6qsUkkx3AyNsjo89PekMfm+Iu/dFKXkdjwXZXPxaL0HrNW
         PTpzek8NS5M5rvF8yaD+eE1zS0I/HicHbPOVvLal0JZyN/f4bp0XJkxZJz6jF5DvBkwIs8/Lz5GK
         nn4XW9Cqjk3equSCJPo5o1Msj8vlLrJYVarqhwIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQC26kYe
         LgqjIkF5rvxB2QzTgcd0LVzXOuiVVTZr8Sh57l4jJqbDoIgvaQQrxRSQzD/X+hcmhuwdp9s8zPHS
         JagtUJXiypwNtrzbf6M7ltrWB9sdNrqc99d1gOVRr0Kt5pLTaLe5kkq7dRaQoOIVIJhX9wgynaAK
         HF/SL3mHUytjXggs88AAQa8JH9hEpwG2srN8EsizX6xwQ/p92hM2oLvK5CSMwTx4VBuGod70EOwp
         6Ta1uRLQh6jCCOCWRuZbbz2T3/sOX+sibC4rLIlwfyTkcUopF/bTSdWwknoRskK4dBekFcvN9N+C
         p/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>