'\" t
.\"     Title: sssd-krb5
.\"    Author: The SSSD upstream - http://fedorahosted.org/sssd
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 02/04/2017
.\"    Manual: File Formats and Conventions
.\"    Source: SSSD
.\"  Language: English
.\"
.TH "SSSD\-KRB5" "5" "02/04/2017" "SSSD" "File Formats and Conventions"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
sssd-krb5 \- SSSD Kerberos provider
.SH "DESCRIPTION"
.PP
This manual page describes the configuration of the Kerberos 5 authentication backend for
\fBsssd\fR(8)\&. For a detailed syntax reference, please refer to the
\(lqFILE FORMAT\(rq
section of the
\fBsssd.conf\fR(5)
manual page\&.
.PP
The Kerberos 5 authentication backend contains auth and chpass providers\&. It must be paired with an identity provider in order to function properly (for example, id_provider = ldap)\&. Some information required by the Kerberos 5 authentication backend must be provided by the identity provider, such as the user\*(Aqs Kerberos Principal Name (UPN)\&. The configuration of the identity provider should have an entry to specify the UPN\&. Please refer to the man page for the applicable identity provider for details on how to configure this\&.
.PP
This backend also provides access control based on the \&.k5login file in the home directory of the user\&. See
\fB.k5login\fR(5)
for more details\&. Please note that an empty \&.k5login file will deny all access to this user\&. To activate this feature, use \*(Aqaccess_provider = krb5\*(Aq in your SSSD configuration\&.
.PP
In the case where the UPN is not available in the identity backend,
\fBsssd\fR
will construct a UPN using the format
\fIusername\fR@\fIkrb5_realm\fR\&.
.SH "CONFIGURATION OPTIONS"
.PP
If the auth\-module krb5 is used in an SSSD domain, the following options must be used\&. See the
\fBsssd.conf\fR(5)
manual page, section
\(lqDOMAIN SECTIONS\(rq, for details on the configuration of an SSSD domain\&.
.PP
krb5_server, krb5_backup_server (string)
.RS 4
Specifies the comma\-separated list of IP addresses or hostnames of the Kerberos servers to which SSSD should connect, in the order of preference\&. For more information on failover and server redundancy, see the
\(lqFAILOVER\(rq
section\&. An optional port number (preceded by a colon) may be appended to the addresses or hostnames\&. If empty, service discovery is enabled; for more information, refer to the
\(lqSERVICE DISCOVERY\(rq
section\&.
.sp
When using service discovery for KDC or kpasswd servers, SSSD first searches for DNS entries that specify _udp as the protocol and falls back to _tcp if none are found\&.
.sp
This option was named
\(lqkrb5_kdcip\(rq
in earlier releases of SSSD\&. While the legacy name is recognized for the time being, users are advised to migrate their config files to use
\(lqkrb5_server\(rq
instead\&.
.RE
.PP
krb5_realm (string)
.RS 4
The name of the Kerberos realm\&. This option is required and must be specified\&.
.RE
.PP
krb5_kpasswd, krb5_backup_kpasswd (string)
.RS 4
If the change password service is not running on the KDC, alternative servers can be defined here\&. An optional port number (preceded by a colon) may be appended to the addresses or hostnames\&.
.sp
For more information on failover and server redundancy, see the
\(lqFAILOVER\(rq
section\&. NOTE: Even if there are no more kpasswd servers to try, the backend is not switched to operate offline if authentication against the KDC is still possible\&.
.sp
Default: Use the KDC
.RE
.PP
krb5_ccachedir (string)
.RS 4
Directory to store credential caches\&. All the substitution sequences of krb5_ccname_template can be used here, too, except %d and %P\&. The directory is created as private and owned by the user, with permissions set to 0700\&.
.sp
Default: /tmp
.RE
.PP
krb5_ccname_template (string)
.RS 4
Location of the user\*(Aqs credential cache\&. Three credential cache types are currently supported:
\(lqFILE\(rq,
\(lqDIR\(rq
and
\(lqKEYRING:persistent\(rq\&. The cache can be specified either as
\fITYPE:RESIDUAL\fR, or as an absolute path, which implies the
\(lqFILE\(rq
type\&. In the template, the following sequences are substituted:
.PP
%u
.RS 4
login name
.RE
.PP
%U
.RS 4
login UID
.RE
.PP
%p
.RS 4
principal name
.RE
.PP
%r
.RS 4
realm name
.RE
.PP
%h
.RS 4
home directory
.RE
.PP
%d
.RS 4
value of krb5_ccachedir
.RE
.PP
%P
.RS 4
the process ID of the SSSD client
.RE
.PP
%%
.RS 4
a literal \*(Aq%\*(Aq
.RE
.sp
If the template ends with \*(AqXXXXXX\*(Aq mkstemp(3) is used to create a unique filename in a safe way\&.
.sp
When using KEYRING types, the only supported mechanism is
\(lqKEYRING:persistent:%U\(rq, which uses the Linux kernel keyring to store credentials on a per\-UID basis\&. This is also the recommended choice, as it is the most secure and predictable method\&.
.sp
The default value for the credential cache name is sourced from the profile stored in the system wide krb5\&.conf configuration file in the [libdefaults] section\&. The option name is default_ccache_name\&. See krb5\&.conf(5)\*(Aqs PARAMETER EXPANSION paragraph for additional information on the expansion format defined by krb5\&.conf\&.
.sp
NOTE: Please be aware that libkrb5 ccache expansion template from
\fBkrb5.conf\fR(5)
uses different expansion sequences than SSSD\&.
.sp
Default: (from libkrb5)
.RE
.PP
krb5_auth_timeout (integer)
.RS 4
Timeout in seconds after an online authentication request or change password request is aborted\&. If possible, the authentication request is continued offline\&.
.sp
Default: 6
.RE
.PP
krb5_validate (boolean)
.RS 4
Verify with the help of krb5_keytab that the TGT obtained has not been spoofed\&. The keytab is checked for entries sequentially, and the first entry with a matching realm is used for validation\&. If no entry matches the realm, the last entry in the keytab is used\&. This process can be used to validate environments using cross\-realm trust by placing the appropriate keytab entry as the last entry or the only entry in the keytab file\&.
.sp
Default: false
.RE
.PP
krb5_keytab (string)
.RS 4
The location of the keytab to use when validating credentials obtained from KDCs\&.
.sp
Default: /etc/krb5\&.keytab
.RE
.PP
krb5_store_password_if_offline (boolean)
.RS 4
Store the password of the user if the provider is offline and use it to request a TGT when the provider comes online again\&.
.sp
NOTE: this feature is only available on Linux\&. Passwords stored in this way are kept in plaintext in the kernel keyring and are potentially accessible by the root user (with difficulty)\&.
.sp
Default: false
.RE
.PP
krb5_renewable_lifetime (string)
.RS 4
Request a renewable ticket with a total lifetime, given as an integer immediately followed by a time unit:
.sp
\fIs\fR
for seconds
.sp
\fIm\fR
for minutes
.sp
\fIh\fR
for hours
.sp
\fId\fR
for days\&.
.sp
If there is no unit given,
\fIs\fR
is assumed\&.
.sp
NOTE: It is not possible to mix units\&. To set the renewable lifetime to one and a half hours, use \*(Aq90m\*(Aq instead of \*(Aq1h30m\*(Aq\&.
.sp
Default: not set, i\&.e\&. the TGT is not renewable
.RE
.PP
krb5_lifetime (string)
.RS 4
Request ticket with a lifetime, given as an integer immediately followed by a time unit:
.sp
\fIs\fR
for seconds
.sp
\fIm\fR
for minutes
.sp
\fIh\fR
for hours
.sp
\fId\fR
for days\&.
.sp
If there is no unit given
\fIs\fR
is assumed\&.
.sp
NOTE: It is not possible to mix units\&. To set the lifetime to one and a half hours please use \*(Aq90m\*(Aq instead of \*(Aq1h30m\*(Aq\&.
.sp
Default: not set, i\&.e\&. the default ticket lifetime configured on the KDC\&.
.RE
.PP
krb5_renew_interval (string)
.RS 4
The time in seconds between two checks if the TGT should be renewed\&. TGTs are renewed if about half of their lifetime is exceeded, given as an integer immediately followed by a time unit:
.sp
\fIs\fR
for seconds
.sp
\fIm\fR
for minutes
.sp
\fIh\fR
for hours
.sp
\fId\fR
for days\&.
.sp
If there is no unit given,
\fIs\fR
is assumed\&.
.sp
NOTE: It is not possible to mix units\&. To set the renewable lifetime to one and a half hours, use \*(Aq90m\*(Aq instead of \*(Aq1h30m\*(Aq\&.
.sp
If this option is not set or is 0 the automatic renewal is disabled\&.
.sp
Default: not set
.RE
.PP
krb5_use_fast (string)
.RS 4
Enables flexible authentication secure tunneling (FAST) for Kerberos pre\-authentication\&. The following options are supported:
.sp
\fInever\fR
use FAST\&. This is equivalent to not setting this option at all\&.
.sp
\fItry\fR
to use FAST\&. If the server does not support FAST, continue the authentication without it\&.
.sp
\fIdemand\fR
to use FAST\&. The authentication fails if the server does not require fast\&.
.sp
Default: not set, i\&.e\&. FAST is not used\&.
.sp
NOTE: a keytab is required to use FAST\&.
.sp
NOTE: SSSD supports FAST only with MIT Kerberos version 1\&.8 and later\&. If SSSD is used with an older version of MIT Kerberos, using this option is a configuration error\&.
.RE
.PP
krb5_fast_principal (string)
.RS 4
Specifies the server principal to use for FAST\&.
.RE
.PP
krb5_canonicalize (boolean)
.RS 4
Specifies if the host and user principal should be canonicalized\&. This feature is available with MIT Kerberos 1\&.7 and later versions\&.
.sp
Default: false
.RE
.PP
krb5_use_kdcinfo (boolean)
.RS 4
Specifies if the SSSD should instruct the Kerberos libraries what realm and which KDCs to use\&. This option is on by default, if you disable it, you need to configure the Kerberos library using the
\fBkrb5.conf\fR(5)
configuration file\&.
.sp
See the
\fBsssd_krb5_locator_plugin\fR(8)
manual page for more information on the locator plugin\&.
.sp
Default: true
.RE
.PP
krb5_use_enterprise_principal (boolean)
.RS 4
Specifies if the user principal should be treated as enterprise principal\&. See section 5 of RFC 6806 for more details about enterprise principals\&.
.sp
Default: false (AD provider: true)
.sp
The IPA provider will set to option to \*(Aqtrue\*(Aq if it detects that the server is capable of handling enterprise principals and the option is not set explicitly in the config file\&.
.RE
.PP
krb5_map_user (string)
.RS 4
The list of mappings is given as a comma\-separated list of pairs
\(lqusername:primary\(rq
where
\(lqusername\(rq
is a UNIX user name and
\(lqprimary\(rq
is a user part of a kerberos principal\&. This mapping is used when user is authenticating using
\(lqauth_provider = krb5\(rq\&.
.sp
example:
.sp
.if n \{\
.RS 4
.\}
.nf
krb5_realm = REALM
krb5_map_user = joe:juser,dick:richard
.fi
.if n \{\
.RE
.\}
.sp
\(lqjoe\(rq
and
\(lqdick\(rq
are UNIX user names and
\(lqjuser\(rq
and
\(lqrichard\(rq
are primaries of kerberos principals\&. For user
\(lqjoe\(rq
resp\&.
\(lqdick\(rq
SSSD will try to kinit as
\(lqjuser@REALM\(rq
resp\&.
\(lqrichard@REALM\(rq\&.
.sp
Default: not set
.RE
.SH "FAILOVER"
.PP
The failover feature allows back ends to automatically switch to a different server if the current server fails\&.
.SS "Failover Syntax"
.PP
The list of servers is given as a comma\-separated list; any number of spaces is allowed around the comma\&. The servers are listed in order of preference\&. The list can contain any number of servers\&.
.PP
For each failover\-enabled config option, two variants exist:
\fIprimary\fR
and
\fIbackup\fR\&. The idea is that servers in the primary list are preferred and backup servers are only searched if no primary servers can be reached\&. If a backup server is selected, a timeout of 31 seconds is set\&. After this timeout SSSD will periodically try to reconnect to one of the primary servers\&. If it succeeds, it will replace the current active (backup) server\&.
.SS "The Failover Mechanism"
.PP
The failover mechanism distinguishes between a machine and a service\&. The back end first tries to resolve the hostname of a given machine; if this resolution attempt fails, the machine is considered offline\&. No further attempts are made to connect to this machine for any other service\&. If the resolution attempt succeeds, the back end tries to connect to a service on this machine\&. If the service connection attempt fails, then only this particular service is considered offline and the back end automatically switches over to the next service\&. The machine is still considered online and might still be tried for another service\&.
.PP
Further connection attempts are made to machines or services marked as offline after a specified period of time; this is currently hard coded to 30 seconds\&.
.PP
If there are no more machines to try, the back end as a whole switches to offline mode, and then attempts to reconnect every 30 seconds\&.
.SH "SERVICE DISCOVERY"
.PP
The service discovery feature allows back ends to automatically find the appropriate servers to connect to using a special DNS query\&. This feature is not supported for backup servers\&.
.SS "Configuration"
.PP
If no servers are specified, the back end automatically uses service discovery to try to find a server\&. Optionally, the user may choose to use both fixed server addresses and service discovery by inserting a special keyword,
\(lq_srv_\(rq, in the list of servers\&. The order of preference is maintained\&. This feature is useful if, for example, the user prefers to use service discovery whenever possible, and fall back to a specific server when no servers can be discovered using DNS\&.
.SS "The domain name"
.PP
Please refer to the
\(lqdns_discovery_domain\(rq
parameter in the
\fBsssd.conf\fR(5)
manual page for more details\&.
.SS "The protocol"
.PP
The queries usually specify _tcp as the protocol\&. Exceptions are documented in respective option description\&.
.SS "See Also"
.PP
For more information on the service discovery mechanism, refer to RFC 2782\&.
.SH "EXAMPLE"
.PP
The following example assumes that SSSD is correctly configured and FOO is one of the domains in the
\fI[sssd]\fR
section\&. This example shows only configuration of Kerberos authentication; it does not include any identity provider\&.
.PP
.if n \{\
.RS 4
.\}
.nf
[domain/FOO]
auth_provider = krb5
krb5_server = 192\&.168\&.1\&.1
krb5_realm = EXAMPLE\&.COM
.fi
.if n \{\
.RE
.\}
.sp
.SH "SEE ALSO"
.PP
\fBsssd\fR(8),
\fBsssd.conf\fR(5),
\fBsssd-ldap\fR(5),
\fBsssd-krb5\fR(5),
\fBsssd-simple\fR(5),
\fBsssd-ipa\fR(5),
\fBsssd-ad\fR(5),
\fBsssd-sudo\fR(5),
\fBsss_cache\fR(8),
\fBsss_debuglevel\fR(8),
\fBsss_groupadd\fR(8),
\fBsss_groupdel\fR(8),
\fBsss_groupshow\fR(8),
\fBsss_groupmod\fR(8),
\fBsss_useradd\fR(8),
\fBsss_userdel\fR(8),
\fBsss_usermod\fR(8),
\fBsss_obfuscate\fR(8),
\fBsss_seed\fR(8),
\fBsssd_krb5_locator_plugin\fR(8),
\fBsss_ssh_authorizedkeys\fR(8), \fBsss_ssh_knownhostsproxy\fR(8),
\fBsssd-ifp\fR(5),
\fBpam_sss\fR(8)\&.
\fBsss_rpcidmapd\fR(5)
.SH "AUTHORS"
.PP
\fBThe SSSD upstream \- http://fedorahosted\&.org/sssd\fR