Kerberos authentication#
BDV can be configured to enable Kerberos authentication over HTTPS for clients, such as the MDACA Data Storage Explorer, or the JDBC and ODBC drivers.
To enable Kerberos authentication for BDV, configuration changes are made on the BDV coordinator. No changes are required to the worker configuration. The worker nodes continue to connect to the coordinator over unauthenticated HTTP. However, if you want to secure the communication between BDV nodes with SSL/TLS, configure Secure internal communication.
Environment configuration#
Kerberos services#
You will need a Kerberos KDC running on a node that the BDV coordinator can reach over the network. The KDC is responsible for authenticating principals and issuing session keys that can be used with Kerberos-enabled services. KDCs typically run on port 88, which is the IANA-assigned port for Kerberos.
MIT Kerberos configuration#
Kerberos needs to be configured on the BDV coordinator. At a minimum, there needs
to be a kdc entry in the [realms] section of the /etc/krb5.conf
file. You may also want to include an admin_server entry and ensure that
the BDV coordinator can reach the Kerberos admin server on port 749.
[realms]
BDV.EXAMPLE.COM = {
kdc = kdc.example.com
admin_server = kdc.example.com
}
[domain_realm]
.bdv.example.com = BDV.EXAMPLE.COM
bdv.example.com = BDV.EXAMPLE.COM
The complete documentation
for krb5.conf is hosted by the MIT Kerberos Project. If you are using a
different implementation of the Kerberos protocol, you will need to adapt the
configuration to your environment.
Kerberos principals and keytab files#
The BDV coordinator needs a Kerberos principal, as do users who are going to connect to the BDV coordinator. You need to create these users in Kerberos using kadmin.
In addition, the BDV coordinator needs a keytab file. After you create the principal, you can create the keytab file using kadmin
kadmin
> addprinc -randkey bdv@EXAMPLE.COM
> addprinc -randkey bdv/bdv-coordinator.example.com@EXAMPLE.COM
> ktadd -k /etc/bdv/bdv.keytab bdv@EXAMPLE.COM
> ktadd -k /etc/bdv/bdv.keytab bdv/bdv-coordinator.example.com@EXAMPLE.COM
Note
Running ktadd randomizes the principal’s keys. If you have just
created the principal, this does not matter. If the principal already exists,
and if existing users or services rely on being able to authenticate using a
password or a keytab, use the -norandkey option to ktadd.
Configuration for TLS#
When using Kerberos authentication, access to the BDV coordinator must be through HTTPS and TLS.
System access control plugin#
A BDV coordinator with Kerberos enabled typically needs a system access control plugin to achieve the desired level of security. Please contact SpinSys customer service for additional information on enabling Kerberos with the BDV coordinator.
BDV coordinator node configuration#
You must make the above changes to the environment prior to configuring the BDV coordinator to use Kerberos authentication and HTTPS. After making the following environment changes, you can make the changes to the BDV configuration files.
config.properties#
Kerberos authentication is configured in the coordinator node’s
config.properties file. The entries that need to be added are listed below.
http-server.authentication.type=KERBEROS
http-server.authentication.krb5.service-name=bdv
http-server.authentication.krb5.principal-hostname=bdv.example.com
http-server.authentication.krb5.keytab=/etc/bdv/bdv.keytab
http.authentication.krb5.config=/etc/krb5.conf
http-server.https.enabled=true
http-server.https.port=7778
http-server.https.keystore.path=/etc/bdv/keystore.jks
http-server.https.keystore.key=keystore_password
node.internal-address-source=FQDN
Property |
Description |
|---|---|
|
Authentication type for the BDV
coordinator. Must be set to |
|
The Kerberos service name for the BDV coordinator. Must match the Kerberos principal. |
|
The Kerberos hostname for the BDV coordinator. Must match the Kerberos principal. This parameter is optional. If included, BDV uses this value in the host part of the Kerberos principal instead of the machine’s hostname. |
|
The location of the keytab that can be used to authenticate the Kerberos principal. |
|
The location of the Kerberos configuration file. |
|
Enables HTTPS access for the BDV coordinator.
Should be set to |
|
HTTPS server port. |
|
The location of the Java Keystore file that is used to secure TLS. |
|
The password for the keystore. This must match the password you specified when creating the keystore. |
|
Regex to match against user. If matched, user will be
replaced with first regex group. If not matched,
authentication is denied. Default is |
|
File containing rules for mapping user. See User mapping for more information. |
|
Kerberos is typically sensitive to DNS names. Setting
this property to use |
See Standards supported for a discussion of the supported TLS versions and cipher suites.
access-controls.properties#
At a minimum, an access-control.properties file must contain an
access-control.name property. All other configuration is specific
for the implementation being configured.
User mapping#
After authenticating with Kerberos, the BDV server receives the user’s principal which is typically similar to
an email address. For example, when alice logs in BDV might receive alice@example.com. By default,
BDV will use the full Kerberos principal name, but this can be mapped to a shorter name using a user-mapping
pattern. For simple mapping rules, the http-server.authentication.krb5.user-mapping.pattern configuration
property can be set to a Java regular expression, and BDV will use the value of the first matcher group. If the
regular expression does not match, the authentication is denied. For more complex user-mapping rules, see
User mapping.
Troubleshooting#
Getting Kerberos authentication working can be challenging. You can independently verify some of the configuration outside of BDV, to help narrow your focus when trying to solve a problem.
Kerberos verification#
Ensure that you can connect to the KDC from the BDV coordinator using telnet.
$ telnet kdc.example.com 88
Verify that the keytab file can be used to successfully obtain a ticket using kinit and klist
$ kinit -kt /etc/bdv/bdv.keytab bdv@EXAMPLE.COM
$ klist
Java keystore file verification#
Verify the password for a keystore file and view its contents using Inspect and validate keystore
Additional Kerberos debugging information#
You can enable additional Kerberos debugging information for the BDV
coordinator process by adding the following lines to the BDV jvm.config
file
-Dsun.security.krb5.debug=true
-Dlog.enable-console=true
-Dsun.security.krb5.debug=true enables Kerberos debugging output from the
JRE Kerberos libraries. The debugging output goes to stdout, which BDV
redirects to the logging system. -Dlog.enable-console=true enables output
to stdout to appear in the logs.
The amount and usefulness of the information the Kerberos debugging output sends to the logs varies depending on where the authentication is failing. Exception messages and stack traces can provide useful clues about the nature of the problem.
Additional resources#
Common Kerberos Error Messages (A-M)