# How to create a Kerberos realm for single sign-on running on NetBSD

You want to organize your users and services into a
[[Kerberos|kerberos]] realm to enable
[[single sign-on|tutorials/kerberos_client]] to your
[[web sites and other services|tutorials/kerberos_services]] at
hostnames under example.com.
How do you set it up?

1. Pick a realm name.
   This is normally the uppercase version of your organization's domain
   name in the DNS, EXAMPLE.COM.

   _Note:_ Unlike DNS domain names, Kerberos realm names are
   case-sensitive.

1. Pick a host to run the Kerberos Key Distribution Center, say
   kdc.example.com.

   Make sure TCP and/or UDP traffic to kdc.example.com goes to the
   host, in case it is behind a NAT or firewall or similar.

1. To make it easier for users, create DNS records in the
   example.com. zone:

       ; name           ttl     class   type    rrdata
       _kerberos        300     IN      TXT     "EXAMPLE.COM"
       _kerberos._tcp   300     IN      SRV     1 0 88 kdc
       _kerberos._udp   300     IN      SRV     1 0 88 kdc

   For access to services under `example.com`, clients will consult
   `_kerberos.example.com` TXT records to find the realm name
   (see `dns_lookup_realm` in
   [[!template id=man name="krb5.conf" section="5"]])

   To find the KDC for the realm EXAMPLE.COM, clients and services will
   consult `_kerberos._tcp.example.com` or `_kerberos._udp.example.com`
   SRV records
   (see `dns_lookup_kdc` in
   [[!template id=man name="krb5.conf" section="5"]]).

   If you don't set this up, you will need to distribute
   [[!template id=man name="krb5.conf" section="5"]] files to all users
   with the realm name and domain-to-realm mapping; see the
   `[domain_realm]` and `[realms]` sections in the
   [[!template id=man name="krb5.conf" section="5"]] man page for
   details.

1. On kdc.example.com, create /etc/krb5.conf with the following content:

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

   Check it by running:

       # verify_krb5_conf /etc/krb5.conf

1. Initialize the KDC:

       # kadmin -l init EXAMPLE.COM
       Realm max ticket life [unlimited]:
       Realm max renewable ticket life [unlimited]:

   Hit return when prompted to use the defaults.

   This will create the database at the default location under
   `/var/heimdal`.

1. Create a user principal and an admin principal.
   We'll call the user `jruser` for J. Random User.

       # kadmin -l add --use-defaults jruser
       jruser@EXAMPLE.COM's Password: 
       Verifying - jruser@EXAMPLE.COM's Password: 
       # kadmin -l add --use-defaults jruser/admin
       jruser/admin@EXAMPLE.COM's Password: 
       Verifying - jruser/admin@EXAMPLE.COM's Password: 

   The admin principal `jruser/admin@EXAMPLE.COM` has no intrinsic
   connection to `jruser@EXAMPLE.COM` but by convention is chosen to be
   authorized like a [[!template id=man name="su" section="1"]]-style
   superuser version of `jruser` for administrative tasks with the help
   of [[!template id=man name="kadmind" section="8"]].

Now you can do `kinit jruser@EXAMPLE.COM` for
[[client-side single sign-on|tutorials/kerberos_client]], and set up
[[kerberized services|tutorials/kerberos_services]]!