# How to use Kerberos for single sign-on in a NetBSD client

Your organization has a [[Kerberos|kerberos]] realm EXAMPLE.COM.
You have a login password for the principal jruser@EXAMPLE.COM.
How do you log in and authenticate to services?

1. Create a directory ~/.krb5 and a file ~/.krb5/config with the
   following content to enable Kerberos on the client side:

       [libdefaults]
               name_canon_rules = as-is:

1. Get a ticket:

       $ kinit jruser@EXAMPLE.COM
       jruser@EXAMPLE.COM's Password: 

Now any kerberized applications such as ssh and Firefox can
authenticate as jruser@EXAMPLE.COM on your behalf to services!

[[!toc startlevel=2 levels=1]]

##### Notes

- If your realm isn't set up for Kerberos DNS autoconfiguration, you
  may need to specify the KDC address in the `[realms]` section of
  ~/.krb5/config, and a domain to realm mapping in the `[domain_realm]`
  section.
  Consult your realm administrator for details.

- Some realms are set up to require DNS canonicalization, which is
  traditional but also a
  [security vulnerability](https://github.com/heimdal/heimdal/issues/1130).
  For such realms, add another `name_canon_rules` in the
  `[libdefaults]` section of ~/.krb5/config matching the EXAMPLE.COM
  realm:

      [libdefaults]
              name_canon_rules = nss:match_realm=EXAMPLE.COM

  See [[!template id=man name="krb5.conf" section="5"]] for more
  information about the syntax of ~/.krb5/config.

- If you are using Kerberos to log into multiple independent realms for
  different purposes at once, you can ensure that services in one realm
  can't spoof services in the other in any of several ways:

  1. Use the `[domain_realm]` section in ~/.krb5/config to assign
     different domains to different realms, and disable DNS
     name-to-realm mapping:

         [libdefaults]
                 dns_lookup_realm = false

         [domain_realm]
                 example.com = EXAMPLE.COM
                 .example.com = EXAMPLE.COM
                 evil.net = EVIL.NET
                 .evil.net = EVIL.NET

     The entry for example.com matches just example.com directly, and
     the entry for .example.com matches any subdomain one level under
     example.com such as foo.example.com but not foo.bar.example.com.

  1. Create separate config files ~/.krb5/config.example and
     ~/.krb5/config.evil, and run programs with the KRB5_CONFIG
     environment variable set to whichever one you want to use for that
     program:

         $ KRB5_CONFIG=$HOME/.krb5/config.example firefox &
         $ KRB5_CONFIG=$HOME/.krb5/config.evil ssh foo.evil.net

     Make sure to set `[libdefaults] dns_lookup_realm = false` in each
     config file too in this case.

## ssh

To enable [[!template id=man name="ssh" section="1"]] to use Kerberos
authentication when logging into any host under *.example.com, add the
following stanza to the end of ~/.ssh/config
([[!template id=man name="ssh_config" section="5"]]):

    Match host *.example.com
            GSSAPIAuthentication yes

Now log in to foo.example.com without a password!

If you trust the remote host to act on your behalf, and you need to
authenticate to kerberized applications on the remote host, you can
also forward your Kerberos tickets with:

    Match host *.example.com
            GSSAPIAuthentication yes
            GSSAPIDelegateCredentials yes

Now run kerberized applications on foo.example.com through ssh without
a password!

## Firefox

To log into kerberized web sites at `https://*.example.com/`:

1. Go to `about:config`.
1. Search for `negotiate-auth`.
1. Set `network.negotiate-auth.trusted-uris` to the string
   `.example.com`.
   (Note: Not `network.negotiate-auth.delegation-uris`.)
1. If you need more sites like `https://*.example.org/` too, set it to
   a comma-separated string like `.example.com, .example.org`.

Now go to a page that requires kerberized login!

##### Notes

- This applies to web sites that use SPNEGO-based
  `WWW-Authenticate: Negotiate` authentication in
  [RFC 4559](https://datatracker.ietf.org/doc/html/rfc4559).

- This is restricted to HTTPS, and will not work with HTTP sites.

## Kerberos for local login

To use Kerberos for local logins, e.g. at the console or in a display
manager such as [[!template id=man name="xdm" section="8"]], when your
local login name matches your Kerberos principal name in the realm:

1. Get a keytab from your realm administrator at /etc/krb5.keytab.

1. Create a system-wide /etc/krb5.conf file
   ([[!template id=man name="krb5.conf" section="5"]])
   with the following content:

       [libdefaults]
               default_realm = EXAMPLE.COM
               name_canon_rules = as-is:

1. Uncomment the pam_krb5.so lines
   ([[!template id=man name="pam_krb5" section="8"]]) in
   /etc/pam.d/display_manager.

Now log out and log back in again as jruser@EXAMPLE.COM, and see with
[[!template id=man name="klist" section="1"]] that you automatically
got tickets!

##### Notes

- The keytab is required for local login security.
  If you are willing to rely only on physical security of the machine,
  and use local login strictly as a convenience to get tickets for
  yourself without actually authenticating whoever is typing on the
  keyboard, you can skip the keytab and set the `allow_kdc_spoof`
  option on the pam_krb5.so line in /etc/pam.d/display_manager.
  See [[!template id=man name="pam.conf" section="5"]] and
  [[!template id=man name="pam_krb5" section="8"]] for more
  information.

- If your local login name does not match your Kerberos principal name
  in the realm, you can configure `auth_to_local` mappings in
  /etc/krb5.conf, and control which principals are allowed to log in as
  your local login name by adding them one per line in ~/.k5login.
  See [[!template id=man name="krb5.conf" section="5"]] for more
  information.