Chapter 8. Kerberos Support Through GSS API
8.1. Kerberos and Red Hat JBoss Data Virtualization
8.1.1. Introduction to Kerberos Authentication on Red Hat JBoss Data Virtualization
Red Hat JBoss Data Virtualization supports Kerberos authentication using the GSS API for single sign-on applications. This service ticket negotiation-based authentication is supported through remote JDBC/ODBC drivers and LocalConnections. The client has to be configured differently for each variant.
8.1.1.1. Local Connection Overview
For a local connection, set the JDBC URL property PassthroughAuthentication to true and use JBoss Negotiation to authenticate your web-application with Kerberos. When the web application is authenticated with the provided Kerberos token, it can be used in Red Hat JBoss Data Virtualization. For details about how to configure this, please refer to the JBoss Negotiation documentation.
8.1.1.2. Remote Connections (JDBC/ODBC)
Open the standalone.xml file in your text editor.
Go to the "security-domains" section and add the following, customizing where necessary for your system.
Note
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">
<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"/> <!-- service principal -->
<module-option name="keyTab" value="/path/to/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 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.
Note
The name of security-domain must match that of the realm.
<security-domain name="MY_REALM">
<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="requisite">
<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>
8.1.1.3. User Roles and Groups
Kerberos does not assign any user roles to the authenticated subject. Therefore, you need to configure a separate role-mapping module to do this work. In the example above, the "UserRoles" login-module was added.
To assign groups, you must edit the "spnego-roles.properties" file and add them using this syntax: user@MY_REALM=my-group
Please refer to the Red Hat JBoss EAP documentation for more information about how to do this.
The SPENGO security-domain delegates the calls relating to Kerberos to the Kerberos server based on the "serverSecurityDomain" property.
To customise it, add the following to the SPENGO security domain:
<module-option name="usernamePasswordDomain" value="{user-name-based-auth}"/>
Once your security domains have been defined, you need to associate them with Red Hat JBoss Data Virtualization’s transport configuration or virtual database configuration. To define a default JDBC transport configuration, add this code:
<transport name="jdbc" protocol="teiid" socket-binding="teiid-jdbc"/>
<authentication security-domain="MY_REALM" type="GSS"/>
</transport>
For an ODBC transport, add this code:
<transport name="odbc" protocol="pg" socket-binding="teiid-odbc"/>
<authentication security-domain="MY_REALM" type="GSS"/>
</transport>
| Value | Description |
|---|---|
| USERPASSWORD | This only allows you to create username and password-based authentication. |
| GSS | This allows you to create GSS API-based authentications using Kerberos5. |
To define a VDB-based authentication, add a combination of the optional following properties to the vdb.xml file:
<property name="security-domain" value="MY_REALM" />
<property name="gss-pattern" value="{regex}" />
<property name="password-pattern" value="{regex}" />
<property name="authentication-type" value="GSS or USERPASSWORD" />
| Property | Description |
|---|---|
| security-domain | Use this to define VDB-based security. |
| authentication-type | This allows you to enforce single authentication. |
| gss-pattern | This allows you to use GSS. |
| password-pattern | This allows you to use USERPASSWORD. |
During the connection, these regular expressions are matched against the connecting user’s name to the user’s preferred authentication method. Here is an example:
<property name="security-domain" value="MY_REALM" /> <property name="gss-pattern" value="logasgss" />
In this case, if "user=logasgss" is passed in the connection string, then GSS authentication will be used to authenticate the user. If there is no match, then the default transport’s authentication method is selected.
You can configure different security-domains for different virtual databases and authentication will no longer be dependent upon the underlying transport.
For instance, if you wish make GSS the permanent default, use this code:
<property name="security-domain" value="MY_REALM" /> <property name="authentication-type" value="GSS" />
Open the {jboss-as}/bin/standalone.conf file in your text editor 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"
Alternatively, you can use this.
JAVA_OPTS = "$JAVA_OPTS -Djava.security.krb5.conf=/path/to/krb5.conf -Djava.security.krb5.debug=false -Djavax.security.auth.useSubjectCredsOnly=false"
Another way of doing this is to add these properties to the standalone.xml file, after the extensions section:
<system-properties>
<property name="java.security.krb5.conf" value="/pth/to/krb5.conf"/>
<property name="java.security.krb5.debug" value="false"/>
<property name="javax.security.auth.useSubjectCredsOnly" value="false"/>
</system-properties>
Restart the server. There should be no errors.
8.1.1.4. JDBC Client Configuration
You must configure your JDBC Client workstation so that it authenticates using the GSS API.
The workstation on which the JDBC Client exists must have been authenticated using GSS API against Active Directory or Enterprise directory server. Go to this website for information on this: http://spnego.sourceforge.net
You must now add a JAAS configuration for Kerberos authentication to your virtual machine. Here is a sample client.conf file:
Teiid {
com.sun.security.auth.module.Krb5LoginModule required
useTicketCache=true
storeKey=true
useKeyTab=true
keyTab="/path/to/krb5.keytab"
doNotPrompt=true
debug=false
principal="user@EXAMPLE.COM";
};
Check that you have configured the "keytab" properly. For information on how to do this for Microsoft Windows environments, go to this website: http://spnego.sourceforge.net
For information on how to do this for Red Hat Enterprise Linux go to this site: https://access.redhat.com/site/solutions/208173
Add the following JVM options to your client’s initialization script, customizing the realm and KDC information for your environment This first sample is based on the krb5.conf file:
-Djava.security.krb5.conf=/path/to/krb5.conf -Djava.security.auth.login.config=/path/to/client.conf -Djavax.security.auth.useSubjectCredsOnly=false -Dsun.security.krb5.debug=false
This alternative version is based on the KDC and Realm file:
-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 the Red Hat JBoss Data Virtualization JDBC connection string along with the URL property:
jaasName=Teiid;user={pattern};kerberosServicePrincipleName=host/testserver@MY_REALM
Note
When you configure it to use Kerberos, you need to configure the "user" property as required by the "gss-pattern" or define the "authentication-type" property on the VDB or transport. However, after successful login into security-domain, the user name from the GSS login context is used instead.
| Value | Description |
|---|---|
| jaasName | This defines the JAAS configuration name in the client.conf file's java.security.auth.login.config property. This property is optional. If it is omitted, "Teiid" is used by default. |
| kerberosServicePrincipleName | This defines service principle that is requested on behalf of the service to which you are connecting. If this property is omitted, the default principle used is TEIID/hostname" and hostname is derived from the JDBC connection URL. |
8.1.1.5. ODBC Client Configuration
Create a DSN for the virtual database on the client machine using the PostgreSQL ODBC driver. In order to participate in Kerberos based authentication you need to configure the "user" property as required by "gss-pattern" or define the "authentication-type" property on the VDB or transport.
No additional configuration is needed as part of this, except that your workstation where the ODBC DSN exists must have been authenticated using GSS API against Active Directory or other Enterprise directory server. For more details on this, see http://spnego.sourceforge.net
8.1.1.6. OData Client
By default, the OData client is configured to use HTTP Basic authentication.
To convert this authentication method into kerberos, clone or copy the maven project from https://github.com/teiid/teiid-web-security. You must update this to the version used in the product (featuring the redhat-x extension) before running Maven.
Edit the web.xml and jboss-web.xml files and then replace the MY_REALM property with that of your security domain.
Once the properties are updated, create a WAR file by running this command:
mvn clean install
Copy the WAR file from the odata-kerberos/target directory to replace the original OData WAR file with same name.
