.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 kerberos|platform
.Op command
.Pp
Kerberos Commands (default mode):
.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
.Pp
Platform SSO Commands:
.Bl -inset -compact -offset indent
.It Fl m, Fl Fl messages
.It Fl s, Fl Fl state
.El
.Sh DESCRIPTION
.Nm
is used to control and get information about both the Kerberos Single Sign-on (SSO)
extension and Platform SSO via the command line.
.Pp
In Kerberos mode (default), the tool controls the Kerberos SSO extension which 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
In Platform SSO mode, the tool provides diagnostic information about the current
Platform SSO state and configuration, and can display sample messages using the
current configuration.
.Pp
Note that
.Nm
cannot be used to completely configure either the Kerberos SSO extension or Platform SSO.
Configuration 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
.Pp
.Sh PLATFORM SSO COMMANDS
.Pp
.Bl -tag -width -indent
.It Fl m, Fl Fl messages
Display sample messages using the current Platform SSO configuration. This command
is useful for testing and diagnostic purposes to verify that Platform SSO is
properly configured and can generate authentication messages.
.It Fl s, Fl Fl state
Display the current Platform SSO state and configuration. This includes information
about device configuration, login configuration, user configuration, and SSO token
status including received and expiration dates. For diagnostic purposes only, not
intended for scripting.
.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
.It Display Platform SSO state and configuration:
app-sso platform -s
.It Display Platform SSO test messages:
app-sso platform -m
.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