SSO configuration

All of SSO configuration takes place through config files or command line interface. This chapter covers the config files.

There are two files involved:

server.conf
sso.conf

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:

/opt/zato/env/server1/config/repo/server.conf
/opt/zato/env/server1/config/repo/sso.conf

Enabling or disabling SSO

To enable or disable SSO set key sso of the component_enabled stanza in server.conf to True of False, for instance:

  [component_enabled]
  ..
  sso=True
  ..

The change needs to be applied to all servers and all of them need to restart for the change to become effective
Note that after changing the flag to True or False from its previous value, all of the servers need to be started with the --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 changed

$ zato start /path/to/server --sync-internal

sso.conf

File 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]

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

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

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

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

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

user_address_list

The stanza is a white-list of usernames allowed and, optionally, what remote addresses they may log in from.
Default: (None)

session

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

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

Default: 128

signup.max_length_email

Default: 128

signup.password_allow_whitespace

Default: True

signup.always_return_confirm_token

Default: True

signup.is_email_required

Default: True

signup.is_approval_needed

Default: True

user_validation

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