Cleito IWAAC Installation Guide for G Suite

Overview

IWAAC for G Suite

Atlassian Crowd ships with a Connector that allows users to log into G Suite (formerly Google Apps) with their Crowd credentials. When such a user requests a G Suite application, he is redirected to a login form hosted on the Crowd server. Once authenticated with his Crowd credentials, the user is redirected back to the G Suite application that he initially requested along with a SAML assertion that proves his identity to G Suite.

In such a user flow, Cleito IWAAC allows Windows domain users to bypass the Crowd authentication form, what means that such users can access to their company's G Suite without entering a password or any other credential (including 2-step verification codes). As a matter of fact, Cleito IWAAC is a simple plugin that can be installed on any Tomcat instance running a web application relying upon Atlassian Crowd for user management, including the Crowd application itself. The installation consists in adding a JAR file to the Tomcat lib directory of your Crowd server along with other configuration files.

Prerequisites

  1. The very first prerequisite before installing and configuring IWAAC for G Suite is to make sure that you have already setup G Suite to redirect your users to your Crowd Server for authentication. Please go to the Atlassian Crowd documentation for more details about this setup.

  2. Please also check that the usernames in G Suite are identical to the Windows usernames. For instance, if John Doe's AD logon name is john_doe@YOURDOMAIN.COM, then his username in G Suite has to be john_doe (or jOhn_Doe as it is not case-sensitive). This is a most-likely case since you probably linked the google-apps application to an Active Directory / LDAP Directory Connector in Crowd's console. If you did not and configured an Internal, Delegated Authentication, Remote Crowd or Custom Directory Connector instead, you might want to configure IWAAC properties so that the plugin automatically creates authenticated Active Directory domain users in the corresponding Crowd directory (if those users do not already exist in this very directory).

System requirements

IWAAC

  • Cleito IWAAC 1.0 and later

End-user computer

  • Any computer running Microsoft Windows (XP, Vista, 7, 8, 8.1, 10) or Mac OS[1] (10.10 and later) and belonging to your enterprise Windows Domain
  • Microsoft Internet Explorer, Microsoft Edge, Mozilla Firefox, Google Chrome and Apple Safari are supported web browsers
1. Please follow these instructions to add a Mac to an Active Directory domain.

Windows domain

  • Active Directory Domain Services for Windows Server (2008 R2, 2012 R2, 2016, 2019)

Crowd server

  • Atlassian Crowd 2.1 and later (up to v4.2)
  • Apache Tomcat 7.0.39 and later
  • JDK 7, JDK 8 (except JDK 1.8.0_40 and 1.8.0_45), JDK 11
  • Windows, Linux and Mac OS are supported Operating Systems
  • For testing purposes, do not install Crowd on your end-user client computer as in such a case your browser might use the unsupported NTLM protocol instead of Kerberos

Firewall rules

Your Crowd server must be able to connect to at least one of your Active Directory Domain Controllers (TCP/UDP on port 88 for Kerberos, TCP/UDP on ports 389 and 636 for LDAP and LDAPS connections)

Setting up IWAAC Kerberos SSO

  1. First of all, you must ask an AD domain administrator to create a user account for your Crowd server in Active Directory, for instance crowdsvc@YOURDOMAIN.COM

    Crowd service account creation in AD - Step 1
    Crowd service account creation in AD - Step 2
    Crowd service account creation in AD - Step 3
    Crowd service account creation in AD - Step 4
  2. Then ask your AD domain administrator to set a Service Principal Name (SPN) for your Crowd server. The Fully Qualified Domain Name (FQDN) to be used MUST be the Host (A) record of your Crowd server in Active Directory DNS.

    setspn -A HTTP/<crowd_server_fqdn> <crowd_server_username>

    For instance:
    setspn -A HTTP/crowd-macos-srv.cleito.com crowdsvc

    Crowd setspn in AD - Step 5
  3. Finally ask your AD domain administrator to generate a keytab file for your Crowd server. A keytab file is a piece of cryptographic information that will enable the IWAAC plugin to validate responses to Kerberos authentication challenges. Please be careful while typing this command as it is case sensitive.
    ktpass /out <keytab_filename> /mapuser <crowd_server_username>@<YOURDOMAIN.COM> /princ HTTP/<crowd_server_fqdn>@<YOURDOMAIN.COM> /pass <crowd_server_userpassword> /kvno 0 /ptype KRB5_NT_PRINCIPAL

    For instance:
    ktpass /out crowd.keytab /mapuser crowdsvc@CLEITO.COM /princ HTTP/crowd-macos-srv.cleito.com@CLEITO.COM /pass crowdServerUserPassword /kvno 0 /ptype KRB5_NT_PRINCIPAL

    Keytab generation with ktpass
  4. (Optional) If you did not link the google-apps application to an Active Directory / LDAP Directory Connector in Crowd and if you plan to enable automatic user creation, you will have to perform this extra step. Go to the delegation tab of the Windows user you created for your Crowd server and click on Trust this user for delegation to specified services only and then click on Use Kerberos only. Then click on Add. Then click on Users or Computers, type the name of your AD domain controller and click on Check Names. Then select the ldap service and click on OK. Finally click on Apply and then on OK.

    Crowd service account in AD - Delegation
    Still in the case where you did not link the google-apps application to an Active Directory / LDAP Directory Connector in Crowd and you plan to enable automatic user creation, you will also have to add the [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\NTDS\Parameters\LdapEnforceChannelBinding] registry key on your Active Directory Domain Controller and set its value to 1 as detailed in Microsoft's documentation.

    LdapEnforceChannelBinding Windows registry - Active Directory Domain Controller
    LdapEnforceChannelBinding DWORD entry - Active Directory Domain Controller
  5. Now, download and unzip the CLEITO IWAAC archive somewhere on your Crowd server.

  6. Copy the content of the conf directory to the apache-tomcat/conf directory of your Crowd instance

  7. Copy the CLEITO-IWAAC-2.2.0.jar file to the apache-tomcat/lib directory of your Crowd instance

    Copy files
  8. Copy the keytab file that was previously generated by your Windows domain administrator to the apache-tomcat/conf/IWAAC directory of your Crowd instance

  9. Then in the apache-tomcat/conf/IWAAC directory of your Crowd instance, run setup_generic.sh (Linux, Mac OS) or setup_generic.bat (Windows) in a shell or terminal window:

    IWAAC Kerberos SSO Setup
    ------------------------
    [Java Version] 1.8.0_111
    [Kerberos] Enter your Windows Domain Name (e.g. DOMAIN.LOCAL): <YOURDOMAIN.COM>
    [Kerberos] Enter the Fully Qualified Domain Name (FQDN) of your Active Directory Domain Controller (e.g. dcsrv.domain.local): <ad_domain_controller_fqdn>
    [Kerberos] Enter the Fully Qualified Domain Name (FQDN) of the server hosting your application. This FQDN MUST be the A record of the server in Active Directory DNS (e.g. linuxsrv001.domain.local): <crowd_server_fqdn>
    [Kerberos][INFO] Setting Service Principal Name: HTTP/<crowd_server_fqdn>@<YOURDOMAIN.COM>
    [Kerberos] Enter Kerberos keytab filename (e.g. mykeytab.keytab): <keytab_file_name>
    [Crowd] Enter Crowd Server URL (e.g. http://crowdsrv.domain.local:8095/crowd): <crowd_server_url>
    [Crowd] Enter application name as defined in Crowd administration console (e.g. jirasdk): <application_name>
    [Crowd] Enter application password as defined in Crowd administration console (e.g. ********): <application_password>

    IWAAC Kerberos SSO Setup completed without an error

    For instance:

    IWAAC Kerberos SSO Setup
    ------------------------
    [Java Version] 1.8.0_111
    [Kerberos] Enter your Windows Domain Name (e.g. DOMAIN.LOCAL): CLEITO.COM
    [Kerberos] Enter the Fully Qualified Domain Name (FQDN) of your Active Directory Domain Controller (e.g. dcsrv.domain.local): win-2f2rum1cpin.cleito.com
    [Kerberos] Enter the Fully Qualified Domain Name (FQDN) of the server hosting your application. This FQDN MUST be the A record of the server in Active Directory DNS (e.g. linuxsrv001.domain.local): crowd-macos-srv.cleito.com
    [Kerberos][INFO] Setting Service Principal Name: HTTP/crowd-macos-srv.cleito.com@CLEITO.COM
    [Kerberos] Enter Kerberos keytab filename (e.g. mykeytab.keytab): crowd.keytab
    [Crowd] Enter Crowd Server URL (e.g. http://crowdsrv.domain.local:8095/crowd): http://crowd.cleito.com:8095/crowd
    [Crowd] Enter application name as defined in Crowd administration console (e.g. jirasdk): crowd
    [Crowd] Enter application password as defined in Crowd administration console (e.g. ********): ********

    IWAAC Kerberos SSO Setup completed without an error

  10. The setup_generic script has generated four configuration files

    • jaas.conf: This file is used by IWAAC for Kerberos implementation. In most cases, it should not be edited.

    • krb5.conf: This file is also used by IWAAC for Kerberos implementation. In most cases, it should not be edited.

    • crowd.properties: This file is used by IWAAC to connect to the Crowd server. There are several options available that are detailed in the Configuration options section.

    • iwaac.properties: This file is used by IWAAC to restrict its functions to specific user agents, ip addresses, users or URLs. In the case of IWAAC integration for G Suite, we will restrict Integrated Windows Authentication to the Crowd login form users are redirected to:

      iwaac.uri.include.only /console/plugin/secure/saml/samlauth.action
      The other options are detailed in the Configuration options section.

  11. Finally we need to tell Crowd to load IWAAC at startup. That setup MUST be done in the <Host> configuration of Crowd which is available in the global apache-tomcat/conf/server.xml configuration file.

    For instance, in Atlassian Crowd 2.12.0, edit apache-tomcat/conf/server.xml:

    <Engine defaultHost="localhost" name="Catalina">
       <Host appBase="webapps" autoDeploy="true" name="localhost" unpackWARs="true">
          <Valve className="com.cleito.iwaac.tomcat.TomcatValve" asyncSupported="true"/>
       </Host>
    </Engine>
  12. Restart Crowd and follow the browser configuration instructions to complete the installation

  13. Now open your web browser and enter your G Suite application URL, e.g. http://mail.google.com/a/cleito.net.

    Congratulations, you are already authenticated!

    Already authenticated in G Suite

    If this installation procedure does not seem to work in your environment, please check the troubleshooting section.

Browser configuration

The browsers of your Active Directory domain users must be configured so as to automatically respond to Kerberos authentication challenges. In the next section, we describe how to manually configure some of the most popular corporate web browsers. This manual configuration can be automated by your Active Directory domain administrator with a Group Policy Object.

Windows clients

Microsoft Internet Explorer

  1. Open Internet Explorer, then click Tools > Internet options > Security > Local intranet > Sites and click Advanced

  2. Add your domain extension to the Local intranet zone, for instance http://*.yourdomain.com and/or https://*.yourdomain.com

    Internet Explorer configuration

Mozilla Firefox

  1. Open Firefox, then type about:config in the adress bar and click I'll be careful, I promise!

  2. Type network.negotiate-auth.trusted-uris in the filter bar and set this setting to .yourdomain.com

    Firefox configuration
  3. (Optional) If you did not link your application to an Active Directory / LDAP Directory Connector in Crowd and if you plan to enable automatic user creation, you will also have to set the network.negotiate-auth.delegation-uris property to .yourdomain.com

Google Chrome

Google Chrome's support for Kerberos authentication relies on Internet Explorer's configuration. Please follow configuration instructions for Internet Explorer and then start Google Chrome.

If Internet Explorer does not seem to be installed on your workstation, click Start Menu > Control Panel > Network and Internet > Internet Options > Security > Local intranet > Sites > Advanced. Then add your domain extension to the Local intranet zone, for instance http://*.yourdomain.com

(Optional) If you did not link your application to an Active Directory / LDAP Directory Connector in Crowd and if you plan to enable automatic user creation, you will also have to edit the [HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome\AuthNegotiateDelegateWhitelist] registry key on your workstation and set its value to *.yourdomain.com

Kerberos delegation for Chrome
If you cannot find that registry key, please follow these steps:
  1. Download the policy templates from https://dl.google.com/dl/edgedl/chrome/policy/policy_templates.zip
  2. Run gpedit.msc to open the local group policy management
  3. Go to Local Computer Policy > Computer Configuration > Administrative Templates and right click on Administrative Templates
  4. Click Add/Remove Templates, then click the Add button and select windows/adm/en-US/chrome.adm from the unzipped policy_templates archive you previously downloaded
  5. Go to Local Computer Policy > Computer Configuration > Administrative Templates > Classic Administrative Templates (ADM) > Google > Google Chrome > Policies for HTTP Authentication > Kerberos delegation server whitelist
  6. On the Kerberos delegation server whitelist window, click Enabled and enter *.yourdomain.com in the field named Kerberos delegation server whitelist
  7. Then restart Chrome and type chrome://policy in the address bar
  8. Check that you now see the AuthNegotiateDelegateWhitelist key in Windows registry editor

Microsoft Edge

Microsoft Edge's support for Kerberos authentication relies on Internet Explorer's configuration. Please follow configuration instructions for Internet Explorer and then start Microsoft Edge.

If Internet Explorer does not seem to be installed on your workstation, click Start Menu > Control Panel > Network and Internet > Internet Options > Security > Local intranet > Sites > Advanced. Then add your domain extension to the Local intranet zone, for instance http://*.yourdomain.com

Mac OS clients

Apple Safari

Cleito IWAAC works out of the box on Safari and does not require any further configuration.

Mozilla Firefox

  1. Open Firefox, then type about:config in the adress bar and click I'll be careful, I promise!

  2. Type network.negotiate-auth.trusted-uris in the filter bar and set this setting to .yourdomain.com

    Firefox configuration on a Mac
  3. (Optional) If you did not link your application to an Active Directory / LDAP Directory Connector in Crowd and if you plan to enable automatic user creation, you will also have to set the network.negotiate-auth.delegation-uris property to .yourdomain.com

Google Chrome

In a terminal, go to your user's Library/Preferences folder and set the AuthServerWhitelist property to *.yourdomain.com
defaults write com.google.Chrome AuthServerWhitelist *.yourdomain.com
(Optional) If you did not link your application to an Active Directory / LDAP Directory Connector in Crowd and if you plan to enable automatic user creation, you will also have to set the AuthNegotiateDelegateWhitelist property to *.yourdomain.com
defaults write com.google.Chrome AuthNegotiateDelegateWhitelist *.yourdomain.com
Chrome configuration on a Mac

Microsoft Edge

In a terminal, go to your user's Library/Preferences folder and set the AuthServerAllowlist property to *.yourdomain.com
defaults write com.microsoft.Edge AuthServerAllowlist *.yourdomain.com
(Optional) If you did not link your application to an Active Directory / LDAP Directory Connector in Crowd and if you plan to enable automatic user creation, you will also have to set the AuthNegotiateDelegateAllowlist property to *.yourdomain.com
defaults write com.microsoft.Edge AuthNegotiateDelegateAllowlist *.yourdomain.com
Edge configuration on a Mac

Configuration options

crowd.properties

This file is used by IWAAC to connect to the Crowd server.

Attributes of the IWAAC crowd.properties file

Attribute Description Default Value
application.name The name of your application as specified in the Crowd server (it should always be crowd)
application.password The password of your application as specified in the Crowd server
crowd.base.url The URL of the Crowd server, e.g. http://localhost:8095/crowd
cookie.domain Set this property to override the SSO Domain set in the Crowd server, e.g. .internal.cleito.com
cookie.tokenkey The SSO cookie name for this application
validation_factor.remote_address Defines whether the client's or latest proxy's IP address will be used as a validation factor for Crowd SSO tokens true
validation_factor.x-forwarded-for Defines whether the real client's IP address will be used as a validation factor for Crowd SSO tokens true
http.proxy.host The FQDN of the proxy server used to transport REST traffic to the Crowd server, e.g. internal-proxy.cleito.com
http.proxy.port The port of the proxy server used to transport REST traffic to the Crowd server, e.g. 3128
http.proxy.username The username used to authenticate with the proxy server
http.proxy.password The password used to authenticate with the proxy server
http.max.connections The maximum number of HTTP connections in the connection pool for communication with the Crowd server 20
http.timeout The HTTP connection timeout (milliseconds) used for communication with the Crowd server. A value of zero indicates that there is no connection timeout 5000

iwaac.properties

This file is used by IWAAC to restrict its functions to specific user agents, ip addresses, users or URLs, and to enable fallback to basic authentication.

Attributes of the iwaac.properties file

Attribute Description Available since version
iwaac.agent.include.only A list of comma separated user agent substrings, e.g. Windows NT, MSIE 11

If this property is not null, then Integrated Windows Authentication will only apply to Active Directory domain users connecting from browsers whose user agent contains at least one of the substrings in the specified list.		 1.1
iwaac.agent.exclude A list of comma separated user agent substrings, e.g. iPad, Android

If this property is not null, then Integrated Windows Authentication will not apply to Active Directory domain users connecting from browsers whose user agent contains at least one of the substrings in the specified list.		 1.1
iwaac.ip.include.only A list of comma separated IP addresses or IPv4 CIDR notations, e.g. 10.211.55.8,10.211.55.22,10.211.54.0/24

If this property is not null, then Integrated Windows Authentication will only apply to Active Directory domain users connecting from the computers, proxy servers or subnetworks in the specified list.		 1.2
iwaac.ip.exclude A list of comma separated IP addresses or IPv4 CIDR notations, e.g. 10.211.55.8,10.211.55.22,10.211.54.0/24

If this property is not null, then Integrated Windows Authentication will not apply to Active Directory domain users connecting from the computers, proxy servers or subnetworks in the specified list.

This is especially useful in a reverse-proxy architecture where internet users have to access to your Crowd server.		 1.2
iwaac.uri.include.only A list of comma separated URI, e.g. /console,/secure

If this property is not null, then Integrated Windows Authentication will only occur when the Active Directory domain users hit the URI in the specified list.		 1.0
iwaac.uri.exclude A list of comma separated URI, e.g. /rest,/api

If this property is not null, then Integrated Windows Authentication will not occur when the Active Directory domain users hit the URI in the specified list. This is especially useful for URI requested by REST or SOAP clients.

Please note that you must not include the context path or your application in the specified values. For instance, if your application base url is http://yourdomain.com/crowd, do not set the iwaac.uri.exclude property to /crowd/rest but to /rest.		 1.0
iwaac.user.include.only A list of comma separated Active Directory usernames, e.g. john_doe,jane_doe

If this property is not null, then Integrated Windows Authentication will only apply to the Active Directory users in the specified list. This is especially useful for testing, as you might want to test IWAAC on a limited set of users before going live.		 1.0
iwaac.user.exclude A list of comma separated Active Directory usernames, e.g. john_doe,jane_doe

If this property is not null, then Integrated Windows Authentication will not occur for Active Directory users in the specified list. This is especially useful for administrators who often log onto web applications using different usernames.		 1.0
iwaac.add.user.to.groups A list of comma separated Crowd groups, e.g. google-apps-users,google-apps-administrators

If this property is not null, then Active Directory domain users will automatically be added to these groups after a successful Kerberos authentication.		 1.4
iwaac.fallback.basic.enabled Either true or false

When set to true, users connecting from computers outside of the Active Directory domain will be able to enter their Active Directory credentials in a Basic Authentication pop up window.

Please note that you must also complete the 4 next options.		 1.1
iwaac.fallback.basic.dc.hostname The fully qualified domain name of your Active Directory Domain Controller, e.g. dc1.cleito.com

It is used by IWAAC to verify users credentials with the LDAP protocol in the case of basic authentication fallback.		 1.1
iwaac.fallback.basic.dc.ssl Either true or false

When set to true, IWAAC will use LDAPS to verify users credentials in the case of basic authentication fallback.		 1.1
iwaac.fallback.basic.dc.port The LDAP or LDAPS port on your Active Directory Domain Controller, e.g. 389 or 636

Used by IWAAC only in the case of basic authentication fallback.		 1.1
iwaac.fallback.basic.windows.domain Your Windows domain name, e.g. CLEITO.COM

Used by IWAAC only in the case of basic authentication fallback.		 1.1
iwaac.fallback.basic.dc.timeout The connection timeout (in milliseconds) to your Active Directory Controller, e.g. 1000

Used by IWAAC only in the case of basic authentication fallback.		 1.4
iwaac.auto.create.user.in.crowd.enabled Either true or false

When set to true, IWAAC will automatically create successfully authenticated Active Directory domain users in the Crowd directory to which the application is linked. You do not need to use this option if your application is linked to an Active Directory / LDAP Directory connector in Crowd as in such a case, Active Directory domain users already exist in Crowd.

Please note that you must also complete the 3 next options if you wish to enable automatic user creation.		 1.4
iwaac.auto.create.user.in.crowd.dc.hostname The fully qualified domain name of your Active Directory Domain Controller, e.g. dc1.cleito.com

It is used by IWAAC to get the Active Directory domain user's details (first name, last name, email address) that are required to create the user account in the application's directory in Crowd.		 1.4
iwaac.auto.create.user.in.crowd.dc.ssl Either true or false

When set to true, IWAAC will use LDAPS to get the Active Directory domain user's details (first name, last name, email address) that are required to create the user account in the application's directory in Crowd.		 1.4
iwaac.auto.create.user.in.crowd.dc.port The LDAP or LDAPS port on your Active Directory Domain Controller, e.g. 389 or 636

Used by IWAAC to get the Active Directory domain user's details (first name, last name, email address) that are required to create the user account in the application's directory in Crowd.		 1.4
iwaac.auto.create.user.in.crowd.timeout The connection timeout (in milliseconds) to your Active Directory Controller, e.g. 1000

Used by IWAAC to get the Active Directory domain user's details (first name, last name, email address) that are required to create the user account in the application's directory in Crowd.		 1.4
iwaac.auto.create.user.in.crowd.password.min.length The minimum length for the random password of the user account to be created in the application's directory in Crowd, e.g. 8

Used by IWAAC only in the case of automatic user creation.		 1.4
iwaac.auto.create.user.in.crowd.password.max.length The maximum length for the random password of the user account to be created in the application's directory in Crowd, e.g. 16

Used by IWAAC only in the case of automatic user creation.		 1.4
iwaac.auto.create.user.in.crowd.password.min.upper.alpha The minimum number of uppercase alphabetic characters for the random password of the user account to be created in the application's directory in Crowd, e.g. 1

Used by IWAAC only in the case of automatic user creation.		 1.4
iwaac.auto.create.user.in.crowd.password.min.lower.alpha The minimum number of lowercase alphabetic characters for the random password of the user account to be created in the application's directory in Crowd, e.g. 1

Used by IWAAC only in the case of automatic user creation.		 1.4
iwaac.auto.create.user.in.crowd.password.min.numeric The minimum number of numeric characters for the random password of the user account to be created in the application's directory in Crowd, e.g. 1

Used by IWAAC only in the case of automatic user creation.		 1.4
iwaac.auto.create.user.in.crowd.password.min.special The minimum number of special characters for the random password of the user account to be created in the application's directory in Crowd, e.g. 1

Used by IWAAC only in the case of automatic user creation.		 1.4

Failover

Cleito IWAAC can be configured so as to provide your applications with a failover mechanism when your main Active Directory Domain Controller is down.

Edit krb5.conf in the apache-tomcat/conf/IWAAC directory of your Crowd server and add another kdc property:
[realms]
  YOURDOMAIN.COM = {
  kdc = dc1.yourdomain.com:88
 kdc = dc2.yourdomain.com:88
  default_domain = .yourdomain.com
  }
Also edit iwaac.properties and add domain controllers as a list of comma separated values:
iwaac.fallback.basic.dc.hostname                     dc1.yourdomain.com, dc2.yourdomain.com
iwaac.auto.create.user.in.crowd.dc.hostname   dc1.yourdomain.com, dc2.yourdomain.com

Upgrading

  • If you need to upgrade Cleito IWAAC, replace CLEITO-IWAAC-1.x.jar with CLEITO-IWAAC-2.2.0.jar in Crowd's lib directory, then restart Crowd.
  • If you need to upgrade Crowd, please follow the steps below.
    1. Copy CLEITO-IWAAC-2.2.0.jar to the lib directory of the new Crowd server.
    2. Copy the content of the apache-tomcat/conf/IWAAC directory of the current Crowd server to the apache-tomcat/conf/IWAAC directory of the new Crowd server.
    3. On the new Crowd server, edit apache-tomcat/conf/IWAAC/jaas.conf and change the keyTab location.
    4. Finally edit the apache-tomcat/conf/server.xml configuration file of the new Crowd server and add the <Valve className="com.cleito.iwaac.tomcat.TomcatValve" asyncSupported="true"/> element in the <Host> section.

Entering license key

  1. Go to the apache-tomcat/conf/IWAAC directory of your Crowd instance and copy/paste your license key into the iwaac.license file

  2. Restart Crowd

Troubleshooting and problem resolution

Whatever your problem, please turn on FINE logging in the apache-tomcat/conf/logging.properties file of your Crowd instance. Insert the following line at the end of the file:
com.cleito.iwaac.level = FINE
IWAAC events will be logged into the apache-tomcat/logs/catalina.out file of your Crowd instance. They are all prefixed by the [IWAAC] string so you can easily parse the generated log file.

When you have solved your problem, you can turn logging to the INFO level.

You can also turn on debug logging for Kerberos specific events.

Edit jaas.conf in the apache-tomcat/conf/IWAAC directory of your Crowd server:
debug=true;
Also edit bin/setenv.sh (Linux, Mac OS) or bin/setenv.bat (Windows) and insert the following line at the beginning of the file. Then restart Crowd.

On Linux or Mac OS:
JAVA_OPTS="-Dsun.security.krb5.debug=true $JAVA_OPTS"
On Windows:
set JAVA_OPTS=%JAVA_OPTS% -Dsun.security.krb5.debug=true
Kerberos debug logs will appear in the apache-tomcat/logs/catalina.out file of your Crowd instance. Please note that they are not prefixed by the [IWAAC] string.

Common problems

A Basic Authentication popup appears

Most likely cause: your web browser has not been configured for automatic Kerberos authentication or you did not use the A record of your Crowd server throughout the installation process.
Resolution: follow the browser configuration instructions or start the configuration again with the A record of your Crowd server.

DEBUG: [IWAAC] No valid credentials provided(Mechanism level: Attempt to obtain new ACCEPT credentials failed!)
Caused by: javax.security.auth.login.LoginException: Message stream modified (41)

Most likely cause: a change in the OpenJDK Kerberos client has been introduced in OpenJDK 1.8.0_242 and above, which requires to set a specific system property if you face that error message.
Resolution: edit bin/setenv.sh (Linux, Mac OS) or bin/setenv.bat (Windows) and insert the following line at the beginning of the file. Then restart Crowd.

On Linux or Mac OS:
JAVA_OPTS="-Dsun.security.krb5.disableReferrals=true $JAVA_OPTS"
On Windows:
set JAVA_OPTS=%JAVA_OPTS% -Dsun.security.krb5.disableReferrals=true

SEVERE: [IWAAC] GSSContext Target Name (service ticket) is null

Most likely cause: there is a known bug in JDK 1.8.0_40 and JDK 1.8.0_45 that prevents Kerberos authentication to succeed on Linux and Mac OS environments. This may also happen if you are trying to access to your application from the server or workstation on which it is installed.
Resolution: upgrade your JDK version or connect to Crowd from another computer.

SEVERE: [IWAAC] Service ticket could not be decrypted, exception is: Failure unspecified at GSS-API level (Mechanism level: Clock skew too great (37))

Most likely cause: there is a time desynchronization between your Crowd server and the Active Directory controller.
Resolution: time synch your servers with NTP.

INFO: org.apache.coyote.http11.AbstractHttp11Processor.process Error parsing HTTP request header

Most likely cause: the Kerberos ticket that is sent by the Active Directory domain user's browser is too large for Tomcat's HTTP headers buffer.
Resolution: edit apache-tomcat/conf/server.xml and extend the maxHttpHeaderSize attribute of Tomcat's HTTP Connector to a higher value (e.g. 64 KB), then restart Tomcat.
maxHttpHeaderSize="65536"

SEVERE: org.apache.coyote.http11.Http11Processor.service Error processing request
java.lang.IllegalArgumentException: An invalid domain [.yourdomain.com] was specified for this cookie

Most likely cause: Some versions of Tomcat embed a Cookie Processor Component that is not fully compliant with RFC 6265 and throws an exception when the IWAAC plugin tries to set a Crowd SSO cookie on a domain whose name starts with "." (e.g. .yourdomain.com)
Resolution: remove the leading "." character from the SSO domain value in the Administration > General Options of your Crowd server. For instance yourdomain.com instead of .yourdomain.com. Then, restart your Crowd server.

Other issues