Contacts
IBSurgeon

GSSAPI/SSPI authentication (gssauth)

← HQbird server features

Using Windows Active Directory services to authenticate users in a Firebird database.

Firebird already supported Windows trusted authentication on Windows. That ability was implemented in the Win_SSPI plugin for client and server. It uses the Windows SSPI API and the NTLM security provider and works on Windows only.

Windows Active Directory is widely supported by modern Linux systems, so its services can also authenticate users on Linux.

Firebird implements that support in the gssauth security plugin. As the name implies, it uses the GSS API to talk to Active Directory. It is available on both Windows and Linux, for both the Firebird client and the Firebird server. In most cases it can replace Win_SSPI, but that is not required — both plugins can run on the same Firebird server.

Installation

Some preparation is required to use Active Directory. A Windows host that runs the Firebird server must be a member of a Windows domain. A Linux host that runs the Firebird server must be joined to Active Directory. A domain user account is required to run the Firebird service on Windows. Service Principal Names (SPNs) must be assigned to that domain account so a Firebird client can authenticate the Firebird server via Active Directory. Below is a brief guide for preparing Windows and Linux servers from the Firebird side.

Firebird server on Windows host

  1. Create a domain account to run the Firebird service. Set these properties:

    • User cannot change password
    • Password never expires

  2. Install Firebird and run it under that domain account. Use instsvc with -login, or change the “Log on as” property of an already installed service.

  3. Add two Service Principal Names for that account. The service name is FirebirdSQL. One SPN must use the short host name; the other must use the FQDN. If the Firebird service was created with instsvc, it also registers those two SPNs. Otherwise use the Windows setspn utility:

setspn -U -S FirebirdSQL/hostname account
setspn -U -S FirebirdSQL/hostname.domain account

For example, if the domain is example.com, the host is winfb, and the account is fbsvc:

setspn -U -S FirebirdSQL/winfb fbsvc
setspn -U -S FirebirdSQL/winfb.example.com fbsvc
  1. Add gssauth to firebird.conf (AuthServer):
AuthServer = Srp256, gssauth

  1. Set (or check) file-system permissions for the domain account:

    • Read access: firebird.conf and other .conf files
    • Full access: folders with databases; security5.fdb; firebird.log and other .log files

  2. Add a firewall rule for Firebird.

Firebird server on Linux host

  1. Create a domain account on a Windows host. Set these properties:

    • User cannot change password
    • Password never expires

  2. Add two Service Principal Names for that account. The service name is FirebirdSQL. One SPN must use the short host name; the other must use the FQDN. Use the Windows setspn utility:

setspn -U -S FirebirdSQL/hostname account
setspn -U -S FirebirdSQL/hostname.domain account

For example, if the domain is example.com, the host is linuxfb, and the account is fbsvc:

setspn -U -S FirebirdSQL/linuxfb fbsvc
setspn -U -S FirebirdSQL/linuxfb.example.com fbsvc
  1. Create a Kerberos key table file for the Linux server with the Windows ktpass utility:
ktpass
  /out firebird.keytab
  /princ FirebirdSQL/[email protected]
  /mapuser [email protected]
  /pass <password of fbsvc account>
  -setpass
  /ptype KRB5_NT_PRINCIPAL
  /crypto all

Notes:

  • The /princ argument is case-sensitive; it must match what the Linux host that will run Firebird sees.
  • -setpass is used so the account password is not changed.
  • /crypto can be changed to avoid legacy encryption algorithms.
  • Full documentation for ktpass: Microsoft ktpass.

  1. Make sure libgssapi_krb5.so is installed.

  2. Install Firebird.

  3. Stop the Firebird service.

  4. Add gssauth to firebird.conf (AuthServer):

AuthServer = Srp256, gssauth

  1. Copy firebird.keytab from the Windows host to /opt/firebird (or the folder where firebird.conf lives on your distro). Set owner to firebird:firebird and permissions so only the user and group can read it.

  2. Start the Firebird service.

Note: use the KRB5_TRACE environment variable to set a Kerberos trace file name for troubleshooting.

Usage

On Windows, the gssauth plugin is built into fbclient.dll, so no special client deployment is needed. On Linux, gssauth is a separate libgssauth.so module and must be deployed with the other binaries when necessary.

The Firebird server must include gssauth in the AuthServer plugin list. The Firebird client includes gssauth in AuthClient by default.

Firebird tools such as isql, gbak, and others now support the -trusted command-line switch on Linux, as they have on Windows for a long time.

Create a mapping in the user database or the security database to map domain users to Firebird users. Note: gssauth reports only full names of users and groups (including the domain prefix), while Win_SSPI reports two forms for every group (with and without domain) — account for that when creating mappings. Also, on Linux, domain user/group names can appear in a slightly different form than in Active Directory (lower case, no domain prefix, and so on). Check the exact representation with Linux commands such as id and groups.

Mapping examples

Map every user as is:

CREATE GLOBAL MAPPING GSS_USERS
  USING PLUGIN GSSAUTH
  FROM ANY USER
  TO USER;

Map domain admins as RDB$ADMIN on a Linux server:

CREATE GLOBAL MAPPING GSS_ADMINS
  USING PLUGIN GSSAUTH
  FROM GROUP 'domain admins'
  TO ROLE RDB$ADMIN;

Map domain admins as RDB$ADMIN on a Windows server:

CREATE GLOBAL MAPPING GSS_ADMINS
  USING PLUGIN GSSAUTH
  FROM GROUP 'EXAMPLE\Domain Admins'
  TO ROLE RDB$ADMIN;