Kerberos support through GSSAPI

Teiid supports kerberos authentication using GSSAPI for single sign-on applications. This service ticket negotiation based authentication is supported through remote JDBC/ODBC drivers and LocalConnections. Client configuration is different for each client type.

LocalConnection

Set the JDBC URL property PassthroughAuthentication as true and use JBoss Negotiation for authentication of your web-application with kerberos. When the web application authenticates with the provided kerberos token, the same subject authenticated will be used in Teiid. For details about configuration, check the JBoss Negotiation documentation.

Remote Connections

On the server, edit the <jboss-install>/standalone/configuration/standalone-teiid.xml under "security-domains" subsystem add the following. Make necessary changes related to your configuration in terms of key tab locations, service principal etc. You need to configure two separate security domains.

Configure one security domain to represent the identity of the server.

The first security domain authenticates the container itself to the directory service. It needs to use a login module which accepts some type of static login mechanism, because a real user is not involved. This example uses a static principal and references a keytab file which contains the credential.

<security-domain name="host" cache-type="default">
   <authentication>
      <login-module code="Kerberos" flag="required">
         <module-option name="storeKey" value="true"/>
         <module-option name="useKeyTab" value="true"/>
         <module-option name="principal" value="host/testserver@MY_REALM"/>
         <module-option name="keyTab" value="/home/username/service.keytab"/>
         <module-option name="doNotPrompt" value="true"/>
         <module-option name="debug" value="false"/>
      </login-module>
   </authentication>
</security-domain>	

Configure a second security domain to secure the Teiid application.

The second security domain is used to authenticate the individual user to the Kerberos server. You need at least one login module to authenticate the user, and another to search for the roles to apply to the user. The following XML code shows an example SPNEGO security domain. It includes an authorization module to map roles to individual users. You can also use a module which searches for the roles on the authentication server itself.

<security-domain name="teiid-spengo" cache-type="default">
   <authentication>
      <!-- Check the username and password -->
      <login-module code="SPNEGO"  flag="requisite">
         <module-option name="password-stacking" value="useFirstPass"/>
         <module-option name="serverSecurityDomain" value="host"/>
      </login-module>
      <!-- Search for roles -->
      <login-module code="UserRoles" flag="required">
         <module-option name="password-stacking" value="useFirstPass" />
         <module-option name="usersProperties" value="spnego-users.properties" />
         <module-option name="rolesProperties" value="spnego-roles.properties" />
      </login-module> 
   </authentication>
</security-domain>

SPENGO security-domain delegates the calls relating to Kerberos to Kerberos server based on "serverSecurityDomain" property set. If you also want to support a additional security-domain like "UsernamePassword" in case, if you would like configure the choice of logging into Kerberos or other, you can supply property

   <module-option name="usernamePasswordDomain" value="userNameBasedAuth"/>

under SPENGO security-domain. Selecting which domain "kerberos" or "userNameBasedAuth" to for Teiid's authentication is defined below.

The above configured the domains, however usage of these domains in Teiid for authentication purposes can be configured in two different ways.

Defining a "default" authentication based on transport

User can define a "default" authentication per transport as below that can be used for all the VDBs system wide.

For JDBC:

<transport name="jdbc" protocol="teiid" socket-binding="teiid-jdbc"/>
        <authentication security-domain="teiid-spengo" type="GSS"/>
</transport>

For ODBC:

<transport name="odbc" protocol="pg" socket-binding="teiid-odbc"/>
        <authentication security-domain="teiid-spengo" type="GSS"/>
</transport>

"What is the value of Type" The "type" attribute above defined the type of authentication that needs to be enforced on the configured security domain on a given transport. The allowed values for type are USERPASSWORD - only allow user name/password based authentications GSS - only allow GSS API based authrntication. (kerberos) ANY - Allow both GSS or USERPASSWORD based. To use this option your "teiid-spengo" must define the "usernamePasswordDomain" module-option as defined above. Not defining "type" value defaults to "ANY" value. Unless, you support both GSS and UserPassword based domains, it is recommended to set value to this attribute.

This configuration replaces the default Teiid login configuration, and you should change the principal and key tab locations accordingly to your runtime environment.

Defining VDB based authentication

You can add a VDB property in the vdb.xml file as below

    <property name="security-domain" value="teiid-spengo/USERPASSWORD" />

the value is in the form "security-domain/type", and all the "type" values from above apply here also in enforcing the authentication requirements. Type value is optional, however in case if it is not specified, it is treated as "ANY" value as default. Using this model you can configure, different security-domains for different VDBS, they are no longer dependent upon what is enforced by a underlying transport.

Edit the "standalone.conf" file in the "${jboss-as}/bin" directory and add the following JVM options (changing the realm and KDC settings according to your environment)

JAVA_OPTS = "$JAVA_OPTS -Djava.security.krb5.realm=EXAMPLE.COM -Djava.security.krb5.kdc=kerberos.example.com -Djavax.security.auth.useSubjectCredsOnly=false"

This finishes the configuration on the server side, restart the server and make sure that there were no errors during start up.

JDBC Client Configuration

In you client VM the JAAS configuration for kerberos authentication needs to be written. A sample configuration file (client.conf) is show below

Client {
    com.sun.security.auth.module.Krb5LoginModule required
    useTicketCache=true
    storeKey=true
    useKeyTab=true 
    keyTab="/path/to/krb5.keytab" 
    doNotPrompt=true 
    debug=false
    principal="demo@EXAMPLE.COM";
};

before you do make sure you have configured the "keytab". You can check this website for making sure you have access to KDC server and instructions on how to create keytabs especially on windows environments http://spnego.sourceforge.net, for Redhat Linux see https://access.redhat.com/site/solutions/208173

Add the following JVM options to your client's startup script - change Realm and KDC settings according to your environment

-Djava.security.krb5.conf=/path/to/krb5.conf (on Linux /etc/krb5.conf)
-Djava.security.auth.login.config=/path/to/client.conf
-Djavax.security.auth.useSubjectCredsOnly=false
-Dsun.security.krb5.debug=false

or

-Djava.security.krb5.realm=EXAMPLE.COM
-Djava.security.krb5.kdc=kerberos.example.com
-Djavax.security.auth.useSubjectCredsOnly=false
-Dsun.security.krb5.debug=false
-Djava.security.auth.login.config=/path/to/client.conf

Add the following additional URL connection properties to Teiid JDBC connection string along with URL etc. Note that when configured with Kerberos you do not need to provide "user" or "password" properties. The user name is derived automatically from GSS login context.

jaasName=Client;

ODBC Client Configuration

No additional configuration is needed as part of this, except that your workstation where the ODBC DSN is created is already authenticated using GSS API against Active Directory or Enterprise directory server. See this website http://spnego.sourceforge.net on instructions as to how to verify your system is logging into enterprise domain. Contact your company's operations team if you have any questions.

How to choose authentication type when type is set to "ANY"

As mentioned above the "teiid-spengo" security domain can be configured with both a Kerberos domain, and also UserPassword domain. The authentication type can be influenced by "user" connection property in JDBC and ODBC. If "user" name is defined as "GSS" it notified the Teiid server, that user prefers to login using the GSS, if "user" name is anything else it indicates that user prefers to use UsernamePassword Domain. Note that the authentication type must be "empty" or "ANY" in transport's type attribute Or on VDB, the "security-domain" property it must be ANY or not specified.

The below table defines the behavior of the system with different settings

* When VDB based security-domain is defined, the transport based settings are no longer consulted.