.Dd January 28, 2020
.Dt app-sso 1
.Os macOS
.Sh NAME
.Nm app-sso
.Nd A tool used to control and get information about the Kerberos SSO extension.
.Sh SYNOPSIS
.Nm
.Op command
.Pp
Commands:
.Bl -inset -compact -offset indent
.It Fl a, Fl Fl authenticate Ar REALM Op Ar options Li "..."
.Bl -inset -compact -offset indent
.It Fl u, Fl Fl username Ar USERNAME
.It Fl f, Fl Fl force
.It Fl q, Fl Fl quiet
.El
.It Fl d, Fl Fl logout Ar REALM
.It Fl c, Fl Fl changepassword Ar REALM
.It Fl l, Fl Fl listrealms
.It Fl i, Fl Fl realminfo Ar REALM
.Bl -inset -compact -offset indent
.It Fl v, Fl Fl verbose
.El
.It Fl i, Fl Fl sitecode Ar REALM
.Bl -inset -compact -offset indent
.It Fl v, Fl Fl verbose
.El
.It Fl r, Fl Fl reset Ar REALM
.It Fl k, Fl Fl keychainoption Ar REALM
.It Fl j, Fl Fl json Ar REALM
.It Fl h, Fl Fl help Ar REALM
.El
.Sh DESCRIPTION
.Nm
is used to control and get information about the Kerberos Single Sign-on (SSO) 
extension via the command line. The Kerberos SSO extension simplifies using Kerberos
authentication with an Active Directory based Kerberos realm. It also allows the
user to use Active Directory specific functions such as password changes and password
expiration notifications.
.Pp
Note that
.Nm
cannot be used to completely configure the Kerberos SSO extension. Configuring
the Kerberos SSO extension requires a user approved MDM enrollment, as well
as an MDM solution that can build and deliver an appropriately configured
Extensible SSO configuration profile payload. See your MDM vendor's
documentation for additional information.
.Pp
.Sh COMMANDS
.Pp
.Bl -tag -width -indent 
.It Fl a, Fl Fl authenticate Ar REALM
Display the login dialog for the specified realm, or if the user has already
configured the Kerberos SSO extension, acquire a new credential. Returns success
upon acquiring a new credential or if the user already has a valid credential.
.Bl -tag -width -indent
.It Fl u, Fl Fl username
The username for authentication. The user will not be able to change this username
on the login screen.
.It Fl f, Fl Fl force
Display the login screen even if the user is already authenticated.
.It Fl q, Fl Fl quiet
Suppress the information that is normally printed after authentication.
.El
.It Fl d, Fl Fl logout Ar REALM
Logs out any user logged into the specified realm.
.It Fl c, Fl Fl changepassword Ar REALM
Displays the "Change Password" dialog for the specified realm.
.It Fl l, Fl Fl listrealms
Prints the list of configured realms.
.It Fl i, Fl Fl realminfo Ar REALM
Print information about the currently configured realm. This includes information
such as the current site code, network home directory and date the user's password expires.
.Bl -tag -width -indent
.It Fl v, Fl Fl verbose
Print the complete site code cache in the results.
.El
.It Fl s, Fl Fl sitecode Ar REALM
Perform a site lookup for the specified realm.
.Bl -tag -width -indent
.It Fl v, Fl Fl verbose
Print the complete site code cache in the results.
.El
.It Fl r, Fl Fl reset Op Ar REALM
Reset the cache for the specified realm. If a realm isn't specified, reset caches
for all realms.
.It Fl k, Fl Fl keychainoption Ar REALM
Resets the "login automatically" option for the specified realm.
.It Fl p, Fl Fl proceedusersetup Ar REALM
Allow user setup to proceed if you are using "delayUserSetup" in your configuration profile.
.It Fl t, Fl Fl sharedsettings Ar REALM
Prints the kerberos settings that are shared with other processes for the specified realm. For diagnostic purposes only, not intended for scripting.
.It Fl j, Fl Fl json
Format the output of this command as JSON instead of property list format.
.It Fl h, Fl Fl help
Print a synopsis of the above document.
.El
.Sh EXAMPLES
.Bl -tag -width -indent
.It Print infomation about the PRETENDCO.COM realm:
app-sso -i PRETENDCO.COM
.It Authenticate to the PRETENDCO.COM realm as jappleseed:
app-sso -a PRETENDCO.COM -u jappleseed
.El
.Sh Kerberos Extension UI Options
.Bl -tag -width "XXX"
.It startInSmartCardMode
The default behavior of the KerberosExtension is to start in the UI mode last used by the user.  To force it to start in SmartCard mode, run this defaults command:
.Pp
.Dl defaults write com.apple.AppSSOKerberos.KerberosExtension startInSmartCardMode -bool true
.El
.Bl -tag -width "XXX"
.It allowSmartCard
 The default behavior of the KerberosExtension is to show both password and SmartCard authentication in the UI.  To hide SmartCards, run this defaults command:
.Pp
.Dl defaults write com.apple.AppSSOKerberos.KerberosExtension allowSmartCard -bool false
.El
.Bl -tag -width "XXX"
.It allowPassword
 The default behavior of the KerberosExtension is to show both password and SmartCard authentication in the UI.  To hide passwords, run this defaults command:
.Pp
.Dl defaults write com.apple.AppSSOKerberos.KerberosExtension allowPassword -bool false
.El
.Bl -tag -width "XXX"
.It identityIssuerAutoSelectFilter
 The default behavior of the KerberosExtension is to auto select an available identity if one is available.  If more than one is available, then the identityIssuerAutoSelectFilter can be used to filter the issuer names.  If one is left, then it will be auto selected.  The value should include any wild cards.  To enable it, run this defaults command with the correct filter value:
.Pp
.Bd -literal -offset indent
defaults write com.apple.AppSSOKerberos.KerberosExtension identityIssuerAutoSelectFilter 'Apple CA*'
.Ed
.El