Skip to main content

Single Sign-On - SSO SAML Authenticator Integration Service

ZenPacks.zenoss.SAMLAuthenticator

This ZenPack provides SAML authentication support for Virtana. See the list of tested SAML identity providers to find your identity provider.

Support

This ZenPack is developed and supported by Virtana. Enterprise support is available to Virtana customers with an active subscription or support agreement. ZenPacks are available at delivery.zenoss.com. To request more information about this or any other ZenPack, contact Virtana.

This ZenPack is a subscription-based Virtana Professional Services engagement. Our Integration Services are offered as subscriptions in order to provide initial setup, configuration assistance, training, and ongoing compatibility and maintenance. All standard packages are renewable every 12 months from the date of purchase. Contact Virtana to request more information regarding this or any other ZenPacks.

Latest Release

1.6.0

Prerequisites

Prerequisite

Restriction

Product

Zenoss 6.x or higher

Required ZenPacks

ZenPack.zenoss.PS.Util >= 1.1.0

Other dependencies

xmlsec1 and xmlsec1-openssl

SAML IdP Requirements

  1. Metadata must contain:

    1. HTTP-Redirect SingleSignonService URL.

    2. X509 key for verifying SAMLResponse messages.

  2. SAMLResponse messages must be signed, but not encrypted.

  3. Accept signed, unsigned, and unencrypted AuthnRequest messages.

Installation

  1. Install xmlsec1 and xmlsec1-openssl RPMs. Virtana v.5.0 and higher requires installing in a container, for example:

    serviced service shell -s xmlsecinstall -i Zope yum install -y
        xmlsec1 xmlsec1-openssl
    serviced snapshot commit xmlsecinstall
    serviced service restart Zope
  2. Install ZenPacks.zenoss.SAMLAuthenticator-\*-py2.7.egg.

  3. Restart Zope.

Note

Later versions of Zenoss might have different Zope instances for reporting, API, and other features. These features might requies a restart as well as any user-interface services, such as Zauth, zenjobs, and zenjsserver.

Configuration

  1. Log in to Virtana Service Dynamics as a user with ZenManager or Manager role

  2. Navigate to Advanced > SAML Authentication.

  3. Enter a value in EntityID. As a best practice, set this value in your IdP so Virtana can use it to identify itself in SAML AuthnRequests. As a SAML best practice, use a URI syntax up to 1024 characters in length. As a best practice for a system entity, use a URL containing its own domain name to identify itself, such as machine.domain.com.

  4. Enter Paste SAML IdP entity identifier and metadata. For example:

    <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" validUntil="2028-07-20T19:51:52Z" entityID="zenoss5.ip-10-111-4-79.zenoss.loc">
        <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>MIIDizCCAnOgAwIBAgIJAJ0GCSqGSIb3DQEBCwUAMFwxCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJujdjUWDEPMA0GA1UEBwZW5vc3MxETAPBgNVBAsMCFNlcnZpY2VzMQswCQYDVQQDDAJQUzAeFw0xODA3MjMxOVTMQswCQYDVQQIDAJUWDEPMA0GA1UEBwwGQXVzdGluMQ8wDQYDVQQKDAZaZW5vc3MxETAPBgNVBAsMCFNlcnZpY2VzMQswCQYDVQQDDAJQUzCCASIwDQYJKoZIhvcNAQEDOXVUdshdtHq8Isf1UXRNe2V9Avnj048rdpJHlnAURMBPyExNLEMT399I2/NnuNugSz8CAwEAAA1UdIwQYMBaAFGWi9ztbPbHr0r5fgDEJBp1+7Bb3FMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEqSmh79qb4Rb3JtNWEG6YiRNnNy49DWtAtStZ6N+O6RRDw9uzrwTmb6c2J3AKTj4a2UsXzcGmbU5+cXCQ7ZrQ77ZMWh98Re3hdm6pKZi6p0vkDghd1WCE97/eWuPupwmvhSkmLu4Zq1DdX9iI/o=</ds:X509Certificate>
                    </ds:X509Data>
                </ds:KeyInfo>
            </md:KeyDescriptor>
            <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:persistent</md:NameIDFormat>
            <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://zenoss5.ip-10-111-4-79.zenoss.loc/zport/SSOLogin"/>
        </md:IDPSSODescriptor>
    </md:EntityDescriptor>
  5. Optionally, specify an alternative XPath expression for determining login. Ex: *//saml:Attribute[@Name='uid']/saml:AttributeValue/text()

  6. Optionally, specify Name ID Policy format. Different IdPs want different values, so you can configure Virtana based on what the IdP wants in the AuthnRequest. This value has no effect on Virtana SAML.

  7. If your IdP requires signed AuthnRequests, select Sign AuthN request. You can obtain private key and certificate with the Generate Self Signed Key/Cert.

Usage

Any users attempting to access Virtana are redirected to the configured IdP URL. To bypass SAML authentication, navigate to Virtana with a query string of saml=0:

https://<zenoss-host>/zport/dmd?saml=0

Note

If you logged in using the IdP then the bypass won't work. To resolve, log out of the IdP and wait for your Virtana session to expire. Optionally, use a different browser or remove the Virtana session cookie.

Note

If you logged in using the SAML bypass, clicking the logout link redirect you to the configured IdP URL. You can bypass this URL with the the path logoutUser.

https://<zenoss-host>/zport/dmd/logoutUser

Logs

SAML errors are logged in Zope's /opt/zenoss/log/event.log.

Tested SAML Identify Providers

  • ADFS

  • Azure AD

  • Okta

  • OneLogin

  • OpenAM

  • Ping Identity

  • SalesForce

  • SimpleSAMLphp

  • SSO Circle

Implementation Details

Overview

When a user attempts to access a resource requiring authorization, such as permission zenoss.View, the SAMLAuthenticator issues a challenge that redirects the user to the configured SAML IdP. When the IdP has authenticated the user, the browser is then directed to post a hidden form using JavaScript that contains a Base64-encoded SAMLResponse which is POSTed to Virtana.

The SAMLAuthenticator plugin decodes the response using its authenticateCredentials and attempts to validate its signature using the configured IdP's certificate. If the SAMLResponse is valid, the username is extracted and stored as a session variable.

When a user attempts to access a resource requiring authorization after their Virtana session has expired, they are again redirected to the configured SAML IdP.

Click the Show SP Metadata button to show the SP metadata. The settings in your IdP configuration require this information. It provides the SSO URLs you need for redirection, for example, https://machine.domain.com/zport/acl_users/samlAuthenticator/consume.

Tracking Initial URL

The SAMLAuthenticator sends the initial URL to the IdP using RelayState. It is expected that the IdP will return RelayState unmodified.

Change Log

1.4.1

  • Features

    • Expose ability to logout and be directed to the Zenoss login page (NOT be forwarded to the IdP)

  • Bug fixes

    • When logged in through SAML remove prompt for password on the Settings and User Settings page

1.4.0

  • Features

    • Support for Single Logout (SLO) added

    • Improved integration with Virtana Analytics

    • Use RelayState to persist original url request rather than session

1.5.0

  • Features

    • Support for signed AuthNRequest

    • Add possibility to configure SLO Response Redirect URL

    • move common code to PS.util ZenPack

1.6.0

  • Features

    • Add config entry for user ID field

  • Bug fixes

    • Fix hardcoded NameIDFormat for service provider metadata