SAML and Active Directory

External Identity Provider Setup

The Intelligence Hub supports using an External Identity Provider (IDP) for user login.

In this setup the hub defines the roles available to users, with appropriate restrictions. The IDP then assigns users to one or more hub roles by using the role names. After a user logs in through the IDP, the IDP sends the hub the list of roles the user is assigned to. The hub then matches the provided roles with the roles defined in the hub by name and restricts the users access.

Role names are matched using case-sensitive strings. Assume all settings described below are case-sensitive, and always match case with what is returned by the IDP.

Identity Provider Settings

IDPs are configured using the intelligencehub-identityproviders.json file located in application data directory. This file must be created on initial setup, and can be used to enable one or more providers.

The examples below cover how to enable SAML and Active Directory IDPs.

Internal Authentication

Below is an example file that enables login using locally defined user accounts.

{
	"authentication": {
		"providers": ["internal"]
	}
}

SAML 2.0

Below is an example file that enables SAML and internal login. There are a number of SAML specific settings that are covered below.

The SAML response must return a custom attribute named ‘roles’ that contains the role names assigned to the user.

{
	"authentication": {
		"providers": ["saml2", "internal"],
		"saml2": {
			"sp.nameidformat":
			"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
			"sp.entityid": "Intelligence Hub entity id",
			"sp.assertion_consumer_service.url":
			"http(s)://host:port/config/login/idp",
			"idp.entityid": "IDP entity id",
			"idp.single_sign_on_service.url": "IDP login in URL",
			"idp.single_sign_on_service.binding":
			"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
			"idp.x509cert": "IDPCertificate",
			"security.signature_algorithm":
			"http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
			"security.digest_algorithm":
			"http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
			"security.requested_authncontext":
			"urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport",
			"security.want_assertions_signed": false,
			"security.authnrequest_signed": false,
			"security.want_assertions_encrypted": false
		}
	}
}

For more information on the settings, please see the following:

Active Directory

Below is an example file that enables Active Directory login. There are a number of AD specific settings that are covered below.

The AD response must include two key components. The attribute defined by the userRoleAttribute must define all the roles the user is assigned to. Each role is an object with many child attributes. The roleNameAttribute must define the child attribute that links to the hub role name. Both of these are required and are case sensitive.

{
	"authentication": {
		"providers": ["ad"],
		"ad": {
			"host": "localhost",
			"port": "389",
			"gatewayUsername": "User",
			"encryptGatewayPassword": "****",
			"domain": "domain.com",
			"ssl": false,
			"caAlias": "",
			"userFilter": "(&(objectClass=user)(!(objectClass=computer)))",
			"searchBase": "dc=domain,dc=com",
			"suffixGatewayUsername": true,
			"usernameAttribute": "sAMAccountName",
			"userRoleAttribute": "memberOf",
			"roleNameAttribute": "cn",
			"fullNameAttribute": "name",
			"phoneAttribute": "telephoneNumber",
			"emailAttribute": "mail",
			"smsAttribute": "mobile"
		}
	}
}

Troubleshooting

Errors with IDP authentication are logged to the event log for troubleshooting.

If the user does authenticate with the IDP and we fail to match any of the IDP roles with hub roles, the user will remain logged in but will have no access rights, and will see permission errors in the UI.

SAML2 Advanced Logging

SAML2 supports advanced debugging by enabling logging. To do this, create a logback.xml in the appData directory. Place the following in the file.

<configuration scan="true" scanPeriod="10 seconds">
    <appender name="FILE" class="ch.qos.logback.core.FileAppender">
        <file>out/runtime.debug.log</file>
        <append>false</append>
        <immediateFlush>true</immediateFlush>
        <encoder>
            <pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</pattern>
        </encoder>
    </appender>

    <root level="OFF">
        <appender-ref ref="FILE" />
    </root>

    <logger name="com.onelogin.saml2.authn" level="ALL">
        <appender-ref ref="FILE" />
    </logger>

</configuration>

Stop and restart the runtime with the following command added to the command line.

-Dlogback.configurationFile=logback.xml

The command can be added to the start script for the operating system.

// Example adding to start-windows.bat
java -Dlogback.configurationFile=logback.xml -cp "intelligencehub-runtime.jar;lib/*" com.highbyte.intelligencehub.runtime.Main start

Detailed SAML2 debug logs will be logged to a runtime/out/runtime.debug.log file.