Kerberos

This how-to guide shows how to configure Kerberos authentication in vScope using Generic Security Services (GSS). For protocol background, see Kerberos authentication overview in Windows Server (Microsoft).

Note

By default, Kerberos is not configured in vScope. If Kerberos is required in your environment, you must configure it.

Before you begin

Have these prerequisites in place:

• Kerberos is configured on the vScope server.
  • Windows: domain-joined host with working Kerberos in the OS.
  • Linux: krb5.conf installed and valid for your realm.
• DNS resolution works for domain controllers and service names (A/AAAA and SRV records).
• The vScope server time matches domain controllers (time skew can block Kerberos).
• You can set Java system properties in vScope, including sun.security.jgss.native and java.security.krb5.conf.
• You have credentials ready for your chosen method (domain account, ticket cache, or keytab).

Case sensitivity

Kerberos is strict about names. Realm names must be UPPERCASE, and principals must match exactly what’s in the keytab.

Choose a GSS implementation

Pick the option that matches how vScope runs and how you want to supply credentials.

Option	Best when	Requirements	Limitations
OS native GSS	vScope runs as a domain account on a domain-joined server and should use the OS ticket cache	Domain-joined host, OS Kerberos configured, service account is a domain account	No alternate credentials or keytabs; uses the service account ticket cache only
Java GSS	You need explicit principals, keytabs, or non-domain accounts	krb5.conf / krb5.ini, JAAS config, credentials available to vScope	More setup; non-domain hosts must be configured manually

Configure OS native GSS

Use OS native GSS when vScope should use the service account’s OS ticket cache.

1. Join the vScope server to the domain.
2. Run the vScope service as a domain account (for example, DOMAIN\svc_vscope).
3. Confirm Kerberos is configured in the OS.
4. Set sun.security.jgss.native=true.
5. Restart the vScope service to apply the change.

Note

If you need to load credentials from a non-default ticket cache, provide a JAAS configuration that points to that cache.

Not available for non-domain accounts or LOCAL_SYSTEM.

Configure Java GSS

Use Java GSS when you need explicit principals, keytabs, or non-domain accounts.

1. Set sun.security.jgss.native=false (this is the vScope default).
2. Create a Kerberos config file (krb5.conf on Linux, krb5.ini on Windows).
3. Set java.security.krb5.conf to the path of the Kerberos config file.
4. Create a JAAS configuration file and point vScope to it.
5. Choose one authentication method below and configure the JAAS stanza.
6. Restart the vScope service to apply the changes.

Ticket cache

Use ticket cache authentication when the vScope service account already has valid Kerberos tickets. To enable use of the ticket cache, the JAAS configuration must include useTicketCache=true.

Native ticket cache The native ticket cache is always used as a fallback with useTicketCache=true.

Note

Java GSS cannot access native ticket cache unless HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\Parameters\AllowTGTSessionKey is set to 1 in the registry.

Custom ticket cache Use a custom cache when the service account cannot access the OS cache. Java will look for the custom ticket cache in the following locations:

• On Windows: {user.home}{file.separator}krb5cc_{user.name}.
  If no ticket is found in the file-based cache, Java will attempt to retrieve the TGT from the Local Security Authority (LSA) API.

• On Linux: /tmp/krb5cc_uid (where uid is the numeric user identifier).
  If no ticket cache is available here, Java will also check {user.home}{file.separator}krb5cc_{user.name}.

You may override the location by configuring ticketCache=c:\\myticketcache in the JAAS configuration.

Keytab

A keytab contains principals and keys to use for Kerberos authentication. Use this when vScope cannot access a usable ticket cache or when you need a dedicated service identity.

Generate on a domain controller for svc_vscope@ISL.LOCAL: To generate a keytab for the user svc_vscope@ISL.LOCAL, run the following on a domain controller as a domain admin. Replace the password and output path to match your environment.

ktpass /princ svc_vscope@ISL.LOCAL /mapuser ISL\svc_vscope /pass MYPASSWORD /out C:\svc_vscope.keytab /crypto all /ptype KRB5_NT_PRINCIPAL /mapop set

Heads up!

ktpass updates the mapped account’s password - only use with accounts dedicated to vScope.

If your environment requires SPNs instead of UPNs, generate the keytab with the service SPN (for example, ldap/dc.domain.com@DOMAIN.COM) and make sure it matches the account you map with ktpass.

Copy C:\svc_vscope.keytab to the vScope server. In your JAAS configuration, set useKeyTab=true, set keyTab to the file path, and set principal to the principal used when the keytab was generated. The principal must match exactly what is in the keytab, including casing. A mismatch in case (for example, svc_vscope@isl.local instead of svc_vscope@ISL.LOCAL) can cause key lookups to fail silently.

Note

Store keytabs securely and limit file access to the vScope service account.

Configure in JAAS: Below is a basic keytab configuration for principal svc_vscope@ISL.LOCAL.

useKeyTab=true
keyTab="C:\svc_vscope.keytab"
principal="svc_vscope@ISL.LOCAL"

Kerberos configuration file

Set the Java system property java.security.krb5.conf to the path of the Kerberos configuration file. The file is usually named krb5.conf on Linux and krb5.ini on Windows. Java does not depend on the file suffix. Below is a minimal Kerberos configuration for the domain isl.local.

Example (krb5.conf for domain isl.local):

[libdefaults]
  default_realm = ISL.LOCAL
  dns_lookup_kdc = false
  dns_lookup_realm = false
  forwardable = true

[realms]
  ISL.LOCAL = {
      kdc = ad.isl.local
      admin_server = ad.isl.local
  }

[domain_realm]
  .isl.local = ISL.LOCAL
  isl.local = ISL.LOCAL

---

JAAS Configuration File

Example configuration for principal svc_vscope@ISL.LOCAL using keytab and ticket cache:

ldapnetworkconnection {
  com.sun.security.auth.module.Krb5LoginModule required
    useKeyTab=true
    keyTab="C:\svc_vscope.keytab"
    principal="svc_vscope@ISL.LOCAL"
    useTicketCache=true
    refreshKrb5Config=true
    doNotPrompt=true
    debug=true;
};

Key fields:

• useKeyTab - Enables keytab authentication.
• keyTab - Path to keytab file.
• principal - Principal for authentication (case-sensitive).
• useTicketCache - Enables ticket cache use.
• doNotPrompt - Prevents interactive prompts (must be true without username and password).

Use Kerberos in vScope

Active Directory integration

1. Open your AD integration settings.
2. Set the bind method to SASL GSSAPI.
3. Clear any stored username and password so Kerberos can use the configured credentials.

Windows (PowerShell) discovery

Select “No Credential” in the Windows Credential settings. For details, see Windows Discovery settings.

Troubleshooting

If authentication fails, check the following areas.

Registry settings

Some Kerberos-related behaviors in Windows are controlled by registry keys:

Purpose	Registry Path	Value
Allow Java GSS to access Windows LSA ticket cache	HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\Parameters\AllowTGTSessionKey	1 = allow, 0 = deny
Control LDAP channel binding enforcement (AD DS)	HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\NTDS\Parameters\LdapEnforceChannelBinding	0 = none, 1 = relaxed, 2 = strict
Control LDAP channel binding enforcement (AD LDS)	HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\<LDS-instance-name>\Parameters\LdapEnforceChannelBinding	Same as above

Channel binding and LDAPS/StartTLS

LDAPS/StartTLS binds can fail if channel binding tokens are enforced (LdapEnforceChannelBinding=2). If you see bind failures after enabling channel binding, use plain binds or switch to Java GSS.

Other common causes

• Principal or realm casing does not match the keytab.
• Time skew between the vScope server and domain controllers.
• Java cannot access the Windows ticket cache (AllowTGTSessionKey not set).