SAML, OIDC, 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 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.

Hub role names cannot contain dashes or spaces, but external group and role names often do (for example, an Active Directory group named Plant-Ops). To match these, add one or more aliases to a hub role. When a role has aliases, the IDP value is matched only against those aliases instead of the role name. See Role Aliases for how to configure them and the full matching rules.

Identity Provider Settings

IDPs are configured using the intelligencehub-identityproviders.json file located in application data directory. This file must be manually created before configuring or using any external IDP for user login.

The examples below cover how to configure the intelligencehub-identityproviders.json to enable SAML, OIDC, 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,
			"custom.roleNameAttribute" : "roles"
		}
	}
}

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

OpenID Connect (OIDC)

The Intelligence Hub uses the OIDC authorization code flow with PKCE. When a user picks Login with OIDC on the sign in screen, the hub redirects the browser to the identity provider. After the user authenticates, the provider redirects back to the hub’s redirectUri, and the hub exchanges the authorization code for tokens and validates the returned id token.

Below is an example file that enables OIDC and internal login.

{
	"authentication": {
		"providers": ["oidc", "internal"],
		"oidc": {
			"issuer": "https://idp.example.com/realms/intelligencehub",
			"clientId": "intelligence-hub",
			"encryptClientSecret": "****",
			"redirectUri": "http(s)://host:port/config/login/oidc",
			"usernameClaim": "preferred_username",
			"rolesClaim": "groups",
			"scopes": ["openid", "profile", "email"]
		}
	}
}

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. For advanced debugging, enable the Debug Logging .

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.