All of SSO configuration takes place through config files or command line interface. This chapter covers the config files.
There are two files involved:
File server.conf is used only to enable or disable SSO functionality as a whole whereas sso.conf deals with details of how SSO should work once enabled.
The files belong to Zato servers and they don't exist with other components, e.g. a Zato web-admin or scheduler do not have them.
Both of the files can be found in the config/repo sub-directory of each server.
For instance, if a path to server is /opt/zato/env/server1 then the files with be in:
sso of the component_enabled stanza in server.conf to True of False, for instance:--sync-internal option, which is used to re-populate an internal cache of built-in objects - however, this needs to be done only once after the flag is changed, using the option afterwards makes the servers boot up longer so it should not be anymore once the flag is changedFile sso.conf is the one where all the SSO configuration happens. Its default form is presented below for reference and what follows next is discussion about each config entry.
Note that after all changes to the file need to be applied in each Zato server and after each modification that server needs to be restarted.
[main]
encrypt_email=True
encrypt_password=True
smtp_conn=sso.notifications
[backend]
default=sql
[sql]
name=
[hash_secret]
rounds=100000
salt_size=64 # In bytes = 512 bits
[apps]
all=
signup_allowed=
login_allowed=
login_metadata_allowed=
inform_if_app_invalid=True
[login]
reject_if_not_listed=False
inform_if_locked=True
inform_if_not_confirmed=True
inform_if_not_approved=True
[password_reset]
valid_for=1440 # In minutes = 1 day
password_change_session_duration=1800 # In seconds = 30 minutes
user_search_by=username
email_title_en_GB=Password reset
email_title_en_US=Password reset
email_from=hello@example.com
[login_list]
[session]
expiry=60 # In minutes
[password]
expiry=730 # In days, 365 days * 2 years = 730 days
inform_if_expired=False
inform_if_about_to_expire=True
inform_if_must_be_changed=True
inform_if_invalid=True
about_to_expire_threshold=30 # In days
log_in_if_about_to_expire=True
min_length=8
max_length=256
reject_list = """
111111
123123
123321
123456
123qwe
1q2w3e
1q2w3e4r
1q2w3e4r5t
222222
333333
444444
555555
654321
666666
777777
888888
999999
987654321
google
letmein
mynoob
password
qwerty
zxcvbnm
"""
[signup]
inform_if_user_exists=False
inform_if_user_invalid=False
inform_if_email_exists=False
inform_if_email_invalid=False
email_required=True
max_length_username=128
max_length_email=128
password_allow_whitespace=True
always_return_confirm_token=True
is_email_required=True
is_approval_needed=True
[user_validation]
service=zato.sso.user.validate
reject_username=zato, admin, root, system, sso
reject_email=zato, admin, root, system, sso
main.encrypt_email
A boolean value indicating whether emails in the SSO database should be encrypted or not. If True, it will not be possible to look up users by emails. If False, user emails will be stored in clear text.
Default: True
main.encrypt_password
A boolean value indicating whether passwords in the SSO database should be encrypted or not. Encryption is an additional measure on top of password hashing which always takes place.
Default: True
backend.default
Which database backend to use to store information in. In current version it is fixed to 'sql' and cannot be changed.
Default: sql
sql.name
Name of an outgoing SQL connection to connect to the SSO database through. Should be left empty if Zato's own DB is to be used.
Default: (None)
hash_secret.rounds
How many rounds in the PBKDF2 algorithm to use for password hashing. It should be fine-tuned from for each environment separately.
Default: 120000
hash_secret.salt_size
How many bytes (not bits) of random data to use for the creation of salt in the password hash.
Default: 64
apps.all
A comma separated list of all application names that SSO should be aware of and which can be sent as current_app in API calls.
Default: (None)
apps.signup_allowed
A comma separated list of application names through which users may sign up. Signup requests sent from other applications will be rejected.
Default: (None)
apps.login_allowed
A comma separated list of application names from which users may log in. Login requests sent from other applications will be rejected.
Default: (None)
apps.login_metadata_allowed
A comma separated list of application names that may send login metadata to SSO. Login requests with metadata coming from other applications will be rejected.
Default: (None)
apps.inform_if_app_invalid
In API calls, whether to use a specific error code to indicate that input current_app does not exist in a given context or if a generic error code should be used. If True, the specific one will be returned.
Default: True
login.reject_if_not_listed
Whether login attempts should be rejected if input username is not explicitly white-listed in [user_address_list].
Default: False
login.inform_if_locked
If login credentials are correct but the account is locked, whether a specific error code to indicate this fact should be returned or a generic one.
Default: True
login.inform_if_not_confirmed
If login credentials are correct but the account has not been confirmed by user yet, whether a specific error code to indicate this fact should be returned or a generic one.
Default: True
login.inform_if_not_approved
If login credentials are correct but the account has not been approved by a super-user yet, whether a specific error code to indicate this fact should be returned or a generic one.
Default: True
The stanza is a white-list of usernames allowed and, optionally, what remote addresses they may log in from.
Default: (None)
session.expiry
What the expiration of a user session is, in minutes. Existing sessions are extended by that many minutes upon each successful interaction with SSO APIs.
Default: 60
password.expiry
After how many days a newly set password should be considered expired. Users with expired passwords will not be able to log in until the password is changed. Super-users may also change and reset passwords from command line.
Default: 730
password.inform_if_expired
If login credentials are correct but the password has already expired, whether a specific error code to indicate this fact should be returned or a generic one.
Default: False
password.inform_if_about_to_expire
If login credentials are correct but the password is about to expire soon, whether a specific error code to indicate this fact should be returned or a generic one.
Default: True
password.inform_if_must_be_changed
If login credentials are correct but the password must be changed by user yet a new one has not been sent, whether a specific error code to indicate this fact should be returned or a generic one.
Default: True
password.inform_if_invalid
If a password that user is trying to set is invalid (e.g. too short or too long), whether a specific error code to indicate this fact should be returned or a generic one.
Default: True
password.about_to_expire_threshold
How many days before the actual expiration the password should be construed as about to expire.
Default: 30
password.log_in_if_about_to_expire
If password is about to expire, whether the user should be allowed to log in nevertheless.
Default: True
password.min_length
Minimum password length in bytes.
Default: 8
password.max_length
Maximum password length in bytes.
Default: 256
password.reject_list
A multi-line list of strings that are not allowed in passwords, no matter if used as a prefix, suffix or in the middle of password. Checked case-insensitively.
Default: (None)
signup.inform_if_user_exists
When users sign up, should they be informed through a specific code that the username chosen already exists or if a generic error code should be returned.
Default: True
signup.inform_if_user_invalid
When users sign up, should they be informed through a specific code that the username chosen is invalid (e.g. has whitespace) or if a generic error code should be returned.
Default: True
signup.inform_if_email_exists
When users sign up, should they be informed through a specific code that the email chosen already exists or if a generic error code should be returned.
Default: True
signup.inform_if_email_invalid
When users sign up, should they be informed through a specific code that the email chosen is invalid (e.g. has whitespace) or if a generic error code should be returned.
Default: True
signup.email_required
Whether email is a required field when signing up.
Default: True
signup.max_length_username
signup.max_length_email
signup.password_allow_whitespace
signup.always_return_confirm_token
signup.is_email_required
signup.is_approval_needed
user_validation.service
A comma-separated list of services to validate users that are trying to sign up. Services are invoked in the order defined in this entry.
Default: zato.sso.user.validate
user_validation.reject_username
A comma-separated list of keywords that must not be part of username, otherwise a signup request is rejected.
Default: zato, admin, root, system, sso
user_validation.reject_email
A comma-separated list of keywords that must not be part of email, otherwise a signup request is rejected.
Default: zato, admin, root, system, sso