Configuring SAML SSO for Commander and the Service Portal

In this topic:

Access through:

Configuration menu > Identity and Access > Authentication tab

Available to:

Commander Role of Superuser

Single sign-on (SSO) allows Commander and Service Portal users to authenticate once before accessing multiple service provider resources, including Commander and the Service Portal.

Commander also supports SSO for Windows Domain Users.

How it works

Commander uses the SAML 2.0 Web Browser SSO profile to provide single sign-on. Security Assertion Markup Language (SAML) is an XML-based, open-standard data format for exchanging authentication and authorization data between an identity provider (IdP) and a service provider.

The IdP is the service you provide that authenticates your users and can provide user identity information to Commander and the Service Portal.

As part of configuring SSO, you must establish trust between your IdP and Commander. This involves generating metadata for your IdP and providing it to Commander, and generating metadata for Commander and providing it to your IdP.

You can log in to both Commander and the Service Portal using SAML SSO. If SAML is misconfigured or malfunctioning, you can bypass SAML and log into Commander using Commander credentials. See Bypassing SAML for more information. No bypass is available for the Service Portal.

The SAML settings for Commander won’t be shared with the SAML settings for the Service Portal. You can set up Commander and the Service Portal separately and you can set up just Commander or just the Service Portal.

Notes:

  • Commander respects the session timeout configured for Commander and the Service Portal, rather than the IdP's session timeout.
  • You must configure the IdP's session timeout to work with Commander's session timeout. The IdP's session timeout should be significantly longer than the session timeout for Commander.
  • When using SAML SSO, the login speed is based on factors outside of Commander, such as the response time from your IdP and the speed of your infrastructure.
  • This capability also provides for multi-factor authentication (MFA), since many SAML SSO providers directly support MFA.

Prerequisites

  • A directory service (Active Directory or LDAP) must be integrated with Commander prior to configuring SAML SSO integration. Before proceeding with SAML integration, the Commander internal user database needs to be built by adding users or groups to Commander from the Active Directory or LDAP integration. These users must have a valid email address as that is the account property that will be exchanged between the Directory Service, IdP and Commander to authenticate users.
  • Commander must be installed with a valid signed certificate. See the Knowledge Base article Generating and Installing an SSL Certificate with Active Directory Certificate Services for more information.
  • The Commander Tomcat service requires a PKCS #12 keystore to sign SSO requests. A keystore contains a public/private key pair plus a certificate. As part of configuring SAML SSO in Commander, you must upload a PKCS #12 keystore and provide the following information:
    • the keystore password
    • the alias of the key pair in the uploaded keystore file
    • the key pair password
    • To learn how to prepare a keystore, see Preparing a keystore for SAML SSO.

  • You must have an operational IdP and generate metadata for that IdP. This task is performed outside Commander. Consult your IdP documentation more information.
  • If you have deployed Commander or the Service Portal behind a load balancer, you must enable session pinning on your load balancer. Session pinning enables the load balancer to bind a user's session to a specific instance, ensuring that all of the user's requests during the session are sent to the same instance. See the Commander High Availability Configuration Guide to learn more.

Preparing a keystore for SAML SSO

For both Commander and the Service Portal, the metadata that must be generated for your IdP requires your current keystore configuration. Any changes you make to the keystore configuration will require you to upload the new Commander SAML metadata file to your IdP server or otherwise make sure your IdP is accessing the correct URL for metadata.

The task of generating metadata for your IdP is performed outside Commander. Consult your IdP documentation for more information.

In the procedure below, the example command assumes the following about your original source keystore, which should be true when using the Embotics' defaults:

  • the keystore contains a key pair named tomcat
  • the keystore is protected with the password changeit. To learn how to change the default keystore password, see Changing the Default Keystore Password.
  • the key pair is not password protected

If you chose to use a different key pair or password for the source keystore, you must replace the -srcalias and -srcstorepass values in the procedure below. If you don't have the correct values, Embotics Technical Support won't be able to retrieve them for you.

As of vCommander 6.0, the SAML SSO configuration requires administrators to create a second keystore for the Tomcat webserver using a PKCS#12 file. This second keystore enhances the end-to-end security and protects user sessions.

In the example command, a second destination keystore is generated to validate for your IdP. It assumes the following about your "destination" keystore:

  • the keystore file name will be saml-keystore.p12
  • the keystore contains a key pair named saml
  • the keystore is protected with the password changeit. To learn how to change the default keystore password, see Changing the Default Keystore Password.

If you chose to use a different key pair or password for the destination keystore, you must replace the -destalias and -deststorepass values in the procedure below. If you don't have the correct values, Embotics Technical Support won't be able to retrieve them for you.

To prepare a keystore:

  1. On the Commander application server, open a command prompt and browse to <INSTALL_DIRECTORY>\Embotics\vCommander\jre\bin\.
  2. Issue the following command:

    keytool -importkeystore -srckeystore ..\..\tomcat\conf\keystore -srcstoretype JKS -srcalias tomcat -srcstorepass changeit -destkeystore ..\..\tomcat\conf\saml-keystore.p12 -deststoretype PKCS12 -deststorepass changeit -destalias saml

    This command extracts a key pair named "tomcat" from the original keystore and places it into a file. Any used passwords will remain the same.

  3. Retrieve the file <INSTALL_DIRECTORY>\Embotics\vCommander\tomcat\conf\saml-keystore.p12, and store it in a secure location.

Configuring SAML SSO for Commander and Service Portal

The following procedure applies to configuring both Commander and the Service Portal SSO, with appropriate filepaths for each. The bypass instructions only apply to Commander.

To configure SAML SSO:

  1. In Commander, go to Configuration > Identity and Access, and select the Authentication tab.
  2. In the SAML Single Sign-On section for either Commander or the Service Portal, click Edit.
  3. In the SAML Single Sign-On dialog for either Commander or the Service Portal, select Enabled to enable SSO.
  4. If you want users to be logged out of the IdP and all other service providers when they log out, enable Global Logout.
  5. Provide the IdP metadata (see the Prerequisites above). In the Identity Provider area, do one of the following:
    • If your metadata is accessible online, select URL, then enter an accessible URL that isn't protected by a user name and password.
    • If you have a downloaded metadata file, click Add and browse to the file.

      To store the metadata: Using the following exact file name, copy your metadata directly to the following location on the Commander server:

      <Commander install dir>/tomcat/conf/sso-idp-metadata.xml

  6. In the SAML Key Pair section, provide a PKCS #12 keystore that Commander will use to sign SSO requests (see the Prerequisites above).

    saml-key-pair-values

    • Click Add and browse to a PKCS #12 file.
    • Enter the keystore password (default value: changeit). To learn how to change the default keystore password, see Changing the Default Keystore Password.
    • Enter the alias for the key pair in the selected keystore file (default value: saml).
    • Enter the password for the key pair (default value: changeit).
  7. In the Service Provider Metadata section, provide information that Commander will use to create metadata that you will then upload to your IdP.

    SAML vCommander metadata

    SAML Service Portal metadata

    • External URL — The Commander External URL or the Service Portal External URL field displays the Commander or the Service Portal URL by default. If Commander or the Service Portal is deployed behind a load balancer or proxy, enter the load balancer or proxy URL. Otherwise, leave the default URL.
    • Entity ID URI Override — In the Entity ID URI Override field, enter the override value for the entity ID that is in the SAML metadata generated by Commander or the Service Portal.
    • User ID Attribute — In the User ID Attribute field, enter the attribute in the SSO payload that will allow Commander to identify a Service Portal user account. The default attribute is mail.
    • Hash Algorithm — From the Hash Algorithm list, select the secure hash algorithm required by your IdP. The default is SHA1; SHA256, SHA384 and SHA512 are also supported.
    • Sign Metadata — By default, Commander metadata is signed. If you don't want the metadata to be signed, clear the Sign Metadata option.

      Caution: Using unsigned metadata in production environments is not recommended.

    • Logout URL — In the Logout URL field, enter the URL for the page where you want the Commander or Service Portal user to land after logout. The default URL for Commander is /saml-logout.html and the default URL for the Service Portal is /saml-logout.xhtml.
    • IdP Error URL — In the IdP Error URL field, enter the URL for the page where you want Commander or Service Portal users to land if an error occurs while logging in to the IdP. The default IdP Error URL for Commander is /saml-error.html and the default URL for the Service Portal is /saml-error.xhtml.
    • vCommander Error URL — In the vCommander Error URL field, enter the URL for the page where you want Commander or Service Portal users to land if an error occurs while logging in to Commander or the Service Portal. The default URL for Commander is /saml-error.html and the default URL for the Service Portal is /saml-error.xhtml.
  8. Click OK.
  9. If you need to upload a metadata file to your IdP, in the SAML Single Sign-On section of the Authentication tab for either Commander or the Service Portal, click Download.

    SAML Single Sign On vCommander

    SAML Single Sign On Service Portal

    If you need to provide a URL for accessing the metadata, use the following:

    For Service Portal: https://<Commander host>:<port>/service_portal_metadata.xml

    For Commander: https://<Commander host>:<port>/admin_portal_metadata.xml

  10. Configure your IdP to trust Commander. See below for an example using Active Directory Certificate Services (ADFS). Consult your IdP documentation for more information.
  11. Test your configuration by logging out of Commander and logging back in, or accessing the Service Portal login page.

    You will be redirected to a sign-in page on the IdP server.

  12. Log in as an existing Commander or Service Portal user. If you can't log in to Commander, you can bypass SAML and log into Commander using Commander credentials. See Bypassing SAML for more information. No bypass is available for the Service Portal.

    You are able to access Commander or the Service Portal without having to log in again.

Troubleshooting SSO configuration

While testing Commander or Service Portal access with SSO, if you receive a 403 error, make sure the metadata has been uploaded properly to your IdP server. If you have confirmed that the metadata has been uploaded correctly, review the vCommander.log file for errors, or open a ticket with Embotics Customer Support, being sure to include a diagnostics package.

If you make configuration changes, you must upload the new Commander SAML metadata file to your IdP server or make sure your IdP is accessing the correct URL for metadata.

Bypassing SAML

In case of SAML misconfiguration or malfunction, you can bypass SAML in Commander but not in the Service Portal.

When SAML is enabled, an audit event is generated of each login (successful or unsuccessful) to Commander using the SAML bypass mechanism. See Monitoring Your Infrastructure with Tasks, Alerts and Events.

To log in to Commander using Commander credentials instead of through SAML, enter the following bypass URL:

https://<Commander host>:<port>?defaultLogin.

Example: Configuring IdP for SSO using ADFS

The following example shows how to configure an IdP for SAML 2.0 SSO, using Active Directory Federation Services (ADFS) as an example. This example is for SAML SSO with the Service Portal and not SAML SSO for Commander. You can also configure SAML SSO for Commander.

Prerequisites for this example

Configuring ADFS servers for SSO

  1. On the ADFS Server, launch the ADFS Management Console.
  2. Right-click the tree and select Add Relying Party Trust.
  3. On the Select Data Source page of the Add Relying Party Trust Wizard, select Import data about the relying party from a file.

    sso-adfs-import-data

  4. Click Browse and navigate to the service_portal_metadata.xml file you generated in the previous procedure, then click Next.
  5. On the Specify Display Name page, give the trust configuration an identifying name, such as "Commander Service Portal SSO", then click Next.
  6. On the Choose Issuance Authorization Rules page, select Permit all users to access this relying party, then click Next.

    In a production environment, we don't recommend allowing access to all users.

  7. On the Ready to Add Trust page, review your settings, then click Next.
  8. On the Finish page, select Open the Edit Claims Rules Dialog for this relying party trust when the wizard closes, then click Close.
  9. In the Edit Claim Rules window, go to the Issuance Transform Rules tab and click Add Rule.

    sso-adfs-edit-claim-rules

  10. On the Select Rule Template page of the Add Transform Claim Rule wizard, from the Claim Rule Template list, select Send LDAP Attributes as Claims, then click Next.

    sso-adfs-add-xform-claim

  11. On the Configure Rule page, configure the rule to map User-Principal-Name to mail.

    The mapped attribute must match the Credential Attribute configured above.

    sso-adfs-config-claim-rule

  12. Click Finish.
  13. On the Select Rule Template page of the Add Transform Claim Rule Wizard, add another rule to transform an incoming claim and give the rule a name, then click Next.

    sso-adfs-add-xform-incoming-claim

  14. On the Configure Rule page, configure the rule to map the Windows account name to the Windows-formatted Name ID, then click Finish.

    sso-adfs-config-xform-rule

  15. Verify your settings and click OK.

    sso-adfs-verify-rules

Testing the configuration

  1. Go to https://<Commander host>:<port>/portal.

    You are redirected to a sign-in page on the ADFS server.

  2. In the same browser session, log in as a preconfigured Service Portal user.

    You are able to access the Service Portal without having to log in again.