Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

The CAST dashboards have various authentication modes available for use:

  • CAST recommends using Standard LDAP because this avoids having to manually manage individual usernames and passwords via the Default authentication mode.
  • Only one mode can be active at a time
    Mode
    Description
    Notes
    Default authenticationThis mode is active by default and relies on simple username/password authentication defined in the application-security-default.xml configuration file within the web application..
    Standard LDAP

    This mode is inactive by default and allows users to authenticate with a standard LDAP server. For example:

    • Basic Active Directory domain controllers
    • Other members of the Active Directory family such as ADAM / AD LDS
    • Non-Microsoft directories such as Apache, Oracle, Novell etc.
    Info

    Note that the configuration of Standard LDAP mode requires detailed knowledge of your environment's LDAP implementation - i.e. an LDAP administrator should help with this.


    SAML

    This mode is inactive by default and allows users to authenticate via SAML.

    Info

    Note that the configuration of SAML mode requires detailed knowledge of your environment - i.e. SAML administrator should help with this.



    Info
    • CAST recommends using Standard LDAP because this avoids having to manually manage individual usernames and passwords via the Default authentication mode.
    • Only one mode can be active at a time.


    Authentication mode activation

    ...

    <!-- Define basic information regarding WEBI as a Service Provider --> <bean id="metadataGenerator" class="org.springframework.security.saml.metadata.MetadataGenerator"> <property name="entityId" value="https://my_server/saml/metadata"/> <property name="extendedMetadata" ref="extendedMetadata"/> <property name="includeDiscoveryExtension" value="false"/> <property name="keyManager" ref="keyManager"/> </bean>

    Some examples for the "value" parameter are given below:

    Expand

    This mode is not enabled by default "out of the box".

    Prerequisites

    Before you can configure your CAST AIP web applications to use SAML authentication, the following prerequisites must already be in place:

    CAST AIP web applications deployed and functioningThe CAST AIP web applications must be deployed and functioning before you can proceed. In particular you must ensure that any roles and data authorizations are already configured.
    Apache Tomcat / standalone ZIP configured for HTTPS

    The Apache Tomcat host server / standalone ZIP deployments must be configured to use the HTTPS protocol. See:

    FederationMetadata.xmlThis file must be provided by your IT administrators before you can proceed.
    Key pair generation

    A public/private key pair must be generated on the Apache Tomcat host server in a dedicated keystore to allow encrypted communication with the Active Directory Federation Server (ADFS). See backend identity provider. See below for more information.

    Note: Dashboard supports the SAML Keystore file, which is generated using the SHA256 algorithm. 

    Supported versions of SAML

    VersionSupported
    2.0(tick)
    1.1(error)
    1.0(error)

    Configuration process

    Request FederationMetadata.xml

    You must request the FederationMetadata.xml file from your IT administrators. When you have received the file, you should store it in a location that can be accessed from thew eb the web application, for example, within the Apache Tomcat installation location or within the unpacked ZIP. For example:

    Code Block
    languagetext
    Windows: D:/apache-tomcat/conf/FederationMetadata.xml
    Linux: file:/opt/apache-tomcat/conf/FederationMetadata.xml

    Key pair generation

    A public/private key pair must be generated on the Apache Tomcat host server in a dedicated keystore to allow encrypted communication with the Active Directory Federation Server (ADFS)backend identity provider. This keystore should be specific to the SAML configuration. To do so, you need to use the keytool command line utility ( provided with the JRE - see (see for example https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html for more information about how to use this tool (this link refers to Oracle's Java implementation, and other JRE providers will have their own instructions, which you should use)) on the workstation on which the web application server is running. For example:

    Code Block
    languagetext
    %JAVA_HOME%\keytool -genkeypair -alias <some-alias> -keyalg RSA -sigalg SHA256withRSA -keysize 2048 -validity 3650 -keypass <keypass> -keystore <samlKeystore.jks> -storepass <storepass>

    Where:

    This configured a password that is used to
    -aliasChoose an alias that is specific to the key pair.
    -keyalg, -sigalg, -keysize, -validityChoose these options according to your own requirements requirements (see  for example https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html for more information ).-keypassabout how to use this tool (this link refers to Oracle's Java implementation, and other JRE providers will have their own instructions, which you should use))
    -keypass

    This configured a password that is used to protect the private key of the generated key pair. The value must be at least 6 characters.

    -keystore

    Choose a keystore location in which to store the key pair, for example:

    Code Block
    languagetext
    Windows: D:/keystore/samlKeystore.jks
    Linux: /opt/apache-tomcat/conf/samlKeystore.jks


    -storepassChoose a password to protect the keystore.

    Activate and configure the authentication mode in the web application

    Activation and configuration of the SAML authentication mode is governed by a .properties configuration file within the web application:

    Code Block
    languagetext
    WAR 1.x
    CATALINA_HOME\webapps\<dashboard>\WEB-INF\security.properties
    
    WAR ≥ 2.x
    CATALINA_HOME\webapps\<dashboard>\WEB-INF\classes\application.properties
    
    ZIP ≥ 2.x
    <unpacked_zip>\configurations\application.properties

    To activate the SAML authentication mode, change the following line. For example, to change from the Default authentication security mode to SAML, do as follows. Change:

    Code Block
    languagetext
    security.mode=default

    to:

    Code Block
    languagetext
    security.mode=saml

    Save the security.properties file.

    Configure SAML authentication

    Find the SAML parameters section in the .properties configuration file and modify each uncommented line to match the items you have already configured. Save the .properties file when complete.

    Code Block
    languagetext
    WAR 1.x
    
    # Parameters for saml mode
    # ------------------------
    # idp metadata file
    security.saml.idp.metadata.location=file:/opt/apache-tomcat/conf/FederationMetadata.xml
    # attribute name for group in saml response
    security.saml.idp.metadata.group.attribute.name=http://schemas.xmlsoap.org/claims/Group
    # Key store path
    security.saml.keystore.path=file:/opt/apache-tomcat/conf/myKeystore.jks
    # key store password
    security.saml.keystore.password=changeit
    # Key alias
    security.saml.key.alias=somealias
    # Key password
    security.saml.key.password=changeit
    # is Single Logout implemented in the customer IDP ?
    security.saml.single.logout=true
    
    WAR and ZIP ≥ 2.x
    
    ## SPRING SECURITY SAML CONFIG
    # or a classpath resource using "classpath:myMetadataFile.xml" for example
    # NB : when using an HTTPS metadata source, you must first add the public certificate to the keystore
    security.saml.metadata.source=
    # Specify the filename of the keystore to use for the SAML certificates
    # The file must be placed inside the security.config.folder
    security.saml.keystore.filename=sample.keystore
    # Specify the default alias in the keystore for the certificate
    security.saml.keystore.default-alias=somealias
    # Specify the keystore and alias password
    security.saml.keystore.password=changeit
    # The XML attribute containing the user's name
    # If this attribute is missing or empty, the user ID will be used
    security.saml.attribute.username=
    # The XML attribute containing the user's group in the SAML response
    security.saml.attribute.group=
    # is Single Logout implemented in the customer IDP ?
    security.saml.single.logout=true


    1.x = security.saml.idp.metadata.location

    2.x = security.saml.metadata.source

    Location of the FederationMetadata.xml file
    For example: 

    Windows: D:/apache-tomcat/conf/FederationMetadata.xml

    Linux: /opt/apache-tomcat/conf/FederationMetadata.xml

    1.x = security.saml.idp.metadata.group.attribute.name

    2.x = security.saml.attribute.username

    2.x = security.saml.attribute.group

    Name of the username and/or group attribute (please discuss with your IT administrators about this option).

    1.x = security.saml.keystore.path

    2.x = security.saml.keystore.filename

    Location of the keystore you created previously.

    security.saml.keystore.password

    The keystore password you created previously (corresponds to the -storepass option for keytool)

    1.x = security.saml.key.alias

    2.x = security.saml.keystore.default-alias

    The keystore alias you created previously.

    1.x = security.saml.key.password

    2.x = security.saml.keystore.password

    The key password you created previously (corresponds to the -keypass option for keytool).

    security.saml.single.logout

    If SAML authentication is in operation, but no Single Logout service is provided in the IdP, you can force the dashboard to handle this situation gracefully and display a message explaining what to do by setting the option to true (default):

    Restart Apache Tomcat / ZIP file

    Now restart your Apache Tomcat server or the web application ZIP file so that the changes you made are taken into account.

    Modify application-security-saml.xml file - only required in 2.x releases

    If you are using CAST Dashboards ≥ 2.0, please ensure that you modify the application-security-saml.xml file to match the location of your Dashboard deployment. This file is located located here:

    Code Block
    languagetext
    WAR ≥ 2.x
    CATALINA_HOME\webapps\<dashboard><deployed_war>\WEB-INF\classes\security
    
    ZIP ≥ 2.x
    <unpacked_zip>\configurations\security

    First you need to update the "metadataGenerator" to match the location of your Dashboard deployment. Locate the following section:

    Code Block
    <!-- Define basic information regarding WEBI as a Service Provider -->
    <bean id="metadataGenerator" class="org.springframework.security.saml.metadata.MetadataGenerator">
    	<property name="entityId" value="https://localhost:8080/saml/metadata"/>
    	<property name="extendedMetadata" ref="extendedMetadata"/>
    	<property name="includeDiscoveryExtension" value="false"/>
    	<property name="keyManager" ref="keyManager"/>
    </bean>

    Change the host name and port in the line <property name="entityId" value="https://localhost:8080/saml/metadata"/> to match your own deployment. In the following example, the URL has been changed to https://my_myserver

    Code Block
    Code Block
    <property name="entityId" value="https://<my_server_dns_name>/saml/metadata"/>
    <property name="entityId" value="https://<my_server_dns_name>/<deployed_war>/saml/metadata"/>
    <property name="entityId" value="https://<my_server_dns_name><:custom_ssl_port>/<deployed_war>/saml/metadata"/>
    <property name="entityId" value="https://<my_server_ip_address>/saml/metadata"/>
    <property name="entityId" value="https://<my_server_ip_address>/<deployed_war>/saml/metadata"/>
    <property name="entityId" value="https://<my_server_ip_address><:custom_ssl_port>/<deployed_war>/saml/metadata"/>

    Next update the successRedirectHandler to configure the redirect after a successful login. Locate the following section:

    Code Block
    <bean id="successRedirectHandler"
    	class="org.springframework.security.web.authentication.SavedRequestAwareAuthenticationSuccessHandler">
    	<property name="alwaysUseDefaultTargetUrl" value="true"/>
    	<!-- the default landing url after login successful -->
    	<property name="defaultTargetUrl" value="/engineering/index.html"/>
    </bean>

    Change the line <property name="defaultTargetUrl" value="/engineering/index.html"/> to match your own deployment. For example:

    Code Block
    Engineering Dashboard: <property name="defaultTargetUrl" value="/engineering/index.html"/>
    Health Dashboard: <property name="defaultTargetUrl" value="/portal/index.html"/>
    Combined Health/Engineering: <property name="defaultTargetUrl" value="/welcome.html"/>

    Save the file and restart your Apache Tomcat server or the web application ZIP file so that the changes you made are taken into account.

    Generate spring_metadata

    Now browse to the following URL to generate the spring_metadata:

    Code Block
    languagetext
    WAR file deployment:
    https://tomcat/<deployed_war_file>war>/saml/metadata
    
    ZIP fil deployment:
    https://localhost/saml/metadata

    This will download a file called spring_saml_metadata.xml. Send this file to your IT administrators who will then register it in the ADFS allowing users to login to the web application.

    Tips

    • Attempting to use the login button in the static/default.html page in the CAST Health Dashboard, Engineering Dashboard and the RestAPI will fail when SAML mode is configured: this button is only configured to use basic authentication. If you need to use any of the options provided in the static/default.html page (which all require a login), you must ensure that you login to the dashboard in the conventional way, and THEN access the static/default.html page in your browser.
    • ADFS are very sensitive: if badly set, authentication will fail.
    • By default, the log mechanism is not configured to provide any logging information to debug SAML authentication issues - if you have encountered issues activating SAML authentication, please enable DEBUG mode as described in Configuring the Log and Audit Trail.

    Notes about Groups

    • SAML groups can also be used for authorization assignments (for example, a set of users can be assigned to a group and that group can then be authorized to view the required data instead of having to authorize individual users) and for role assignments. In SAML mode, Groups are retrieved directly from the SAML directory.
    • Nested groups are supported, both for authorization assignments and for role assignments. For instance, if user jdoe is member of groupA, which is member of groupB which is used to define an authorization or role, then jdoe will be attributed the groupB authorizations/roles.

    ...