Single sign-on allows Service Portal users to authenticate once at a specified web page before accessing the Service Portal and any other integrated resources. Embotics® vCommander® also supports SSO for Windows Domain Users.
How it works
vCommander uses the SAML 2.0 Web Browser SSO profile to provide single sign-on (SSO). SAML, or Security Assertion Markup Language, is an XML-based, open-standard data format for exchanging authentication and authorization data between parties, in particular, between an identity provider and a service provider. Web Browser SSO is a thin policy layer on top of widely deployed and trusted protocols such as HTTPS and TLS client certificate authentication.
The Identity Provider, or IdP, is the service you provide which authenticates your users and which can provide user identity information to the Service Portal. The Service Provider is the vCommander Service Portal. As part of configuring SSO, you must establish trust between your IdP and vCommander. This involves generating IdP metadata and providing it to vCommander, and generating metadata for vCommander and providing it to your IdP.
- vCommander respects the session timeout configured for the Service Portal, rather than the IdP's session timeout.
- When using SAML SSO, the login speed is based on factors determined outside of vCommander, such as the response time from your IdP and the speed of your infrastructure.
- vCommander must be installed with a valid signed certificate. See the Knowledge Base articles Generating and Installing an SSL Certificate and Generating and Installing an SSL Certificate with Active Directory Certificate Services for more information.
- The vCommander 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 vCommander, 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, and the password for the key pair. Refer to the next section for guidance on retrieving this information.
- You must have an operational Identity Provider (IdP).
- If you have deployed the Service Portal behind a load balancer, you must enable session pinning on your load balancer (also known as session fixation, session stickiness or session affinity). Session pinning enables the load balancer to bind a user's session to a specific instance, ensuring that all requests from the user during the session are sent to the same instance. See the vCommander High Availability Configuration Guide to learn more.
Preparing a Keystore for SAML Single Sign On
You must generate metadata for your IdP. This task is performed outside vCommander. Consult the documentation for your IdP for more information.
As of vCommander 6.0, the SAML Single Sign On configuration requires administrators to create a second keystore for the tomcat webserver using a p12 file. We've made this change to enhance the end-to-end security that protects your user sessions.
The procedure below assumes the following about your original "source" keystore, which should be true if you followed Embotics' defaults:
- keystore contains a key pair named tomcat
- keystore is protected with the password changeit
- key pair is not password protected
Please note that if you chose to use a different key pair or password, you must replace the -srcalias and -srcstorepass values in the procedure below. If you do not have the correct values, Embotics Technical Support will not be able to retrieve them for you.
In completing this procedure, you will generate a second keystore to provide validation for your Idp. The steps below will yield the following details for the new "destination" keystore:
- keystore file name will be saml-keystore.p12
- keystore contains a key pair named saml
- keystore is protected with the password changeit2
Please note that if you chose to use a different key pair or password, you must replace the -destalias and -deststorepass values in the procedure below. If you do not have the correct values, Embotics Technical Support will not be able to retrieve them for you.
- On the vCommander application server, open a command prompt and browse to <INSTALL_DIRECTORY>\Embotics\vCommander\jre\bin\.
- Issue the command keytool -importkeystore -srckeystore ..\..\tomcat\conf\keystore -srcstoretype JKS -srcalias tomcat -srcstorepass changeit -destkeystore ..\..\tomcat\conf\saml-keystore.p12 -deststoretype PKCS12 -deststorepass changeit2 -destalias saml
This command extracts a key pair named tomcat from the original keystore and places it into a file. Passwords remain the same, if any were used.
Retrieve the file <INSTALL_DIRECTORY>\Embotics\vCommander\tomcat\conf\saml-keystore.p12 and store in a secure location.
Configuring vCommander for SSO
- In vCommander, go to Configuration > System Configuration and select the Authentication tab.
- Under SAML Single Sign On, click Edit.
- In the SAML Single Sign On dialog, select Enabled.
- Enable Global Logout if you want users to be logged out of the IdP and all other service providers when they log out of the Service Portal.
- Provide the IdP metadata. You can do this in any of the following ways:
- Select URL and enter a URL, if your metadata is accessible online. The URL must be publicly accessible and not protected by a user name and password.
- Select File and click Add to upload a file.
- Copy your metadata directly to the following location on the vCommander server, using the following exact file name: <vCommander install dir>/tomcat/conf/sso-idp-metadata.xml
- Provide a PKCS #12 keystore that vCommander uses to sign SSO requests.
- In the SAML Key Pair section, click Add and browse to a PKCS #12 keystore file. "saml-keystore.p12"
- Enter the keystore password. "changeit2"
- Enter the alias for the key pair in the selected keystore file. "saml"
- Enter the password for the key pair. "changeit"
- Provide information that vCommander will use to create metadata that you will then upload to your IdP.
- The Service Portal External URL field displays the Service Portal URL by default. If the Service Portal is deployed behind a load balancer or proxy, enter the load balancer or proxy URL. Otherwise, leave the default URL.
- In the Credential Attribute field, enter the attribute in the SSO payload that will allow vCommander to identify a Service Portal user account. The default attribute is mail.
- In the Hash Algorithm drop-down list, select the secure hash algorithm required by your IdP. The default is SHA1; SHA256, SHA384 and SHA512 are also supported.
- By default, vCommander metadata is signed. If you do not want the metadata to be signed, disable the Sign Metadata option. Caution: Using unsigned metadata in production environments is not recommended.
- In the Logout URL field, enter the URL for the page where you want the Service Portal user to land after logout. The default URL is /saml-logout.xhtml.
- In the IdP Error URL field, enter the URL for the page where you want Service Portal users to land if an error occurs while logging in to the IdP. The default URL is /sso-error.xhtml.
- In the vCommander Error URL field, enter the URL for the page where you want Service Portal users to land if an error occurs while logging in to the Service Portal. The default URL is /sso-error.xhtml.
- Click OK.
- If you need to upload a metadata file to your IdP, download the generated metadata by clicking Download in the SAML Single Sign On pane.
If you need to provide a URL for accessing the metadata, use the following: https://<vCommander host>:<port>/vCommander-sp-metadata.xml
- Configure your IdP to trust vCommander. Consult your IdP documentation for more information.
- Test your configuration by accessing the Service Portal login page. You are redirected to a sign-in page on the IdP server.
- Log in as an existing Service Portal user. You access the Service Portal without having to log in again.
While testing the 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 the metadata has been uploaded correctly, consult the vCommander.log file inside the Support Diagnostics package for errors, or send the package to Embotics Technical Support for review.
Any changes you make to the configuration will require you to upload the new vCommander SAML metadata file to your IdP server or otherwise make sure your IdP is accessing the correct URL for metadata.