Page tree
Skip to end of metadata
Go to start of metadata


The USxS Redesign projects have a default authentication system based on user profiles stored in the application database.  The user profile in the application provides both Authentication (auth-n) and Authorization (auth-z).

 The application user profile has the following features:

  • Auth-n:
    • username
    • password stored using one-way encryption
    • account status (enabled/disabled)
    • account expiration
    • password lifetime/expiration
    • account locking
    • external authentication
    • password change tracking
    • last login timestamp
  • Auth-z:
    • Profile contains a list of district defined "Roles"
    • Each Role has a list of application defined "Permissions"


In security terminology, "auth-n" is part of the system where the user proves "who they are" by: "something they know" (a password), "something they have" (a key card), or "something they are" (fingerprint), etc. Given their identity, the "auth-z" system determines what they are allowed to do within the application. The Redesign applications permit you to externalize the auth-n system, but not auth-z. That is, every user must have a user profile in the application to gain permissions in the application.


Event System

USxS application contains an event system including a Rules Engine which allows the behavior of the applications to be extended and customized by the SSDT, ITC's or individual school districts.  The Authentication system participates in the event processing by publishing authentication success and failure events, password change events, etc.  

By default, the following features are implemented by rules:

  • Break-in/intruder detection and evasion
  • Basic password complexity requirements

The rules engine allows the authentication system to be extended without changes to the software.  For example, using rules, a district could implement "time of day" restrictions for logins by role or custom field.

External Authentication

USxS are distributed with optional modules supporting external authentication by Windows ADS Domain or LDAP authentication, or both. For details see:

A user who is externally authenticated must have a user profile in the application database.  The roles granted to the user will be taken from the application profile, not the external directory. Further, the application profile must also be active (enabled and non-expired).  Therefore, a user who has a valid account in the external system can be denied access by the USxS application.  

A user who is externally authenticated will not, normally, have a password in the application profile.  However, if the local profile does have a password, then the user could authenticate with either the external password or the local password.  This is an intentional behavior which allows an external user to be converted to a local user simply by setting a password in the application.

Authentication Process

The authentication process checks each configured provider in the following order:

  • Intrusion Prevention Authenticator
  • Windows ADS Authenticators (up to three)
  • LDAP Authenticators (one or two)
  • Local Application Authenticator

The "Intrusion Prevention Authenticator" is not a true authenticator.  Rather, it consults the intrusion prevention system to determine if the login name or source has been marked as an "intruder".  If an intruder is detected, the login attempt fails and the remaining authenticators are not consulted.  This results in a generic "Bad credentials" response is returned to the user.  No indication that the system is in evasion mode is provided to the possible attacker.

The first authenticator which responds with an affirmative response is treated as the authoritative response.  The remaining authenticators are not consulted. If none of the providers respond successfully, then the attempt is treated as a "Bad credentials"  authentication failure.

After a successful authentication, the user's application profile is checked.  If the profile is inactive, expired or locked, then the login attempt will fail.  In this case, the external system would have granted access but the local application blocked the login.  In this case, the user is returned an error message indicating the nature of the failure.

Any of the authenticators may return a "password expired" response.  In this case, the authentication process will stop and the user provided an appropriate message.  The users who are locally authenticated may use the application to reset their password from the login screen. Externally authenticated users must use the external system to change their password.

Finally, after a successful authentication, an "Authentication Success Event" is published to the event handlers. Rules defined in the rules engine may veto the login attempt by recording one or more error messages.  The authentication will be converted to a failure and the messages reported to the user.


The USxS authorization system is based on a "Permissions and Roles" model.   Permissions are defined by the application and control the low-level actions a user can perform.  Due to the fine-grained nature of permissions, each application creates a large, perhaps daunting, number of permissions.  Furthermore, the list of permissions varies by application and the modules installed.  Therefore, the permissions available vary by district.

Roles are district defined roles which grant access to zero or more permissions.  Roles may be treated as a "group" in other systems, or may be used to identify roles by job function.   

One or more roles may be assigned to each user.  If a user has multiple roles, the permissions from each role are merged to provide a complete set of permissions.

Permission Structure

Permissions are hierarchical in the general format: {prefix}_{functionArea}_{operation}.  Each underscore marks a point in the hierarchy.  "prefix" represents a major application area such as "ADMIN", "USAS","USPS", and "MODULE". The latter is the prefix for modules shared between USAS and USPS. The "functionArea" indicates the area or object the permission applies to.  The "operation" is the specific application function being controlled.  

Operations are, in general, one of the following:

  • VIEW (query and view)
  • REPORT (create and generate reports)

Using USAS as an example, the Vendor object defines the following permissions:

USAS_VENDOR_CREATEAbility to create new vendors
USAS_VENDOR_UPDATEAbility to update existing vendors
USAS_VENDOR_DELETEAbility to delete existing vendors
USAS_VENDOR_VIEWAbility to view vendors in the UI
USAS_VENDOR_REPORTAbility to generate reports of vendors



and all other permissions starting with USAS 

Notice that USAS_VENDOR grants access to all of it's children.  Therefore, to grant a role full access to Vendors, it is sufficient to grant USAS_VENDOR.  Likewise, granting the USAS permission grants access to all permissions starting with "USAS".  The nature of the permissions makes it possible to create non-sensical combinations of permissions which the applications do not prevent.  For example, granting a user "DELETE" without the corresponding "VIEW" would have no effect because the user could not query for a record in the UI to delete it.  

The permissions, although they appear to refer to "data types", should not be thought of as ACLs which control access to underlying database tables.  Rather, they control access to functions in the software.  For example, in USAS, if a user holds "USAS_PURCHASEORDER_CREATE" they will have access to the Purchase Order user interface.  The Purchase Order UI allows the user to query for Vendors to assign to the purchase order.  By definition, a user must be able to search for and select vendors to create a PO, even if they do not hold the "USAS_VENDOR_VIEW" permission.


Roles are district defined roles which can be granted zero or more permissions.  Any combination of permissions may be granted to a role.  Roles can be defined by job function, group membership or organizational unit. A user may be granted multiple roles.  If a user has multiple roles, the permissions from each role are merged (cumulative) to create the users final permissions.  It is not possible for a role to remove a permission granted by another role.

Administrators Role

The applications define one special role named "ADMINISTRATORS". This role is guaranteed to be assigned all top-level permissions defined in the application and is automatically assigned to the "admin" user name.   The state of the admin profile and ADMINISTRATORS role is checked, and updated if necessary, during application startup.  Therefore, if a districts admin roles become corrupted or accidentally damaged (e.g. a district revokes their own admin rights), then restarting the application will reset the role.

Admin Password

By default, the special "admin" user profile will be created automatically the first time the application is started.  The admin user will be assigned the well-known password of "99admin00".  It is strongly recommended that this password be changed before any production data is entered or imported into the system.

The initial default password may be changed by defining the following environment variable in the usXsapp section of the docker-compose.yml or docker-compose.override.yml

    - APPLICATION_ADMIN_PASSWORD=desiredpassword


On subsequent application startups, the admin user will be checked to ensure it is active, unlocked and holds at least the ADMINISTRATORS role.  This username must also have a password set. However, the default password will only be applied on the initial bootstrap of the application.  Subsequent restarts of the application will not change the password.

If the admin password is lost, it may be recovered by defining the following variables in docker-compose.yml or docker-compose.override.yml of the application container:

    - APPLICATION_ADMIN_PASSWORD=desiredpassword

When the APPLICATION_ADMIN_RESET property is true, the admin password will be reset to the APPLICATION_ADMIN_PASSWORD value on the next application startup.  If this property is used to recover access to the application, it is strongly recommended it be removed immediately after the next startup.



  • No labels