Documentation
¶
Overview ¶
Package credentials handles the authentication of users using username-password pairs. Each user is stored as a userEntry in a local database. The database columns are defined by the userEntry struct, so they appear as seen below:
+----+-------+----------+---------------+------+---------------+-------------+ | ID | Email | Username | Password Hash | Salt | Hash Function | Permissions | +----+-------+----------+---------------+------+---------------+-------------+
Two main authentication functions are provided in RegisterUser() and ValidateUserCred(), with supporting functions ChangeUserPassword() and ChangeUserPermissions() to alter the data of already-existing users in the database.
credentials exports the User type, which contains the same data as userEntry with private data (password hash, salt, hash func, internal ID) removed. ValidateUserCred() returns one, so that when the authentication API is called, it returns back information about the user in a format that can easily pass back to the application servers or converted into a token without exposing important data.
Index ¶
- func ChangeUserPassword(username, password string, newPassword string) error
- func ChangeUserPermissions(username string, newPermissions map[string]bool) error
- func Entries() int
- func OpenDB(path string) error
- func RegisterUser(email, username string, password string, permissions map[string]bool) error
- type User
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ChangeUserPassword ¶
Validate a user's current credentials, then change their password if they could be validated.
Input:
- username, password string: User credentials. See ValidateUserCred.
- newPassword string: New password to set IF the above credentials can be validated.
Output:
- error: Any error that occurs when changing user password, including: failure to validate, user doesn't exist, failure to hash password
func ChangeUserPermissions ¶
Change user permissions for a given user. This action is generally initiated by an admin or the application server, and not a user; as a result, no password is required for the user.
Input:
- username string: Username to alter.
- newPermissions map[string]bool: Full list of new permissions. Overwrites any permissions with the same name.
Output:
- error: Any error that occurs while changing permissions, including: user does not exist, failure to marshal permissions
func Entries ¶
func Entries() int
Get the current number of entries in the database. It's not likely that this has significant use outside of noticing if the user is initializing a new database; to preserve security in this case, the user should be asked to create the first account as an admin account before opening to a network.
Output:
- int: Number of entries in the current database
func OpenDB ¶
Open the database. This MUST be called before any authcred operations take place, and if the path is changed, a different DB will be opened; this is configured under DB.Path in config.yml, and should probably not change unless you have a testing database to use. Only one database can be open at a time.
Input:
- path string: Path to the database file
Output:
- error: Output if the open fails, or if the userEntry struct changes in a way that prevents migrating the DB. This most commonly occurs if the path does not exist; gorm can create a new file, but not directories.
func RegisterUser ¶
Register a user with the given credentials and permissions.
Input:
- email, username string: User email/username pair. Both of these values MUST be unique.
- password string: User password. To avoid conflicts with integration, auth imposes no password restrictions; it is expected that the application manage restrictions such as password length.
- permissions map[string]bool: User permissions. auth only takes advantage of the admin permission; all others are application-defined.
Output:
- error: Any errors that occur during the registration of a user, including: non-unique email/username, failure to generate password salt, failure to hash password. If an error is returned, no change is made to the database.
Types ¶
type User ¶
type User struct {
Email string `json:"email"`
Username string `json:"username"`
Permissions map[string]bool `json:"permissions"`
}
A User contains *public* information about a user. authcred functions that return user info MUST return this.
func FindUserByEmail ¶
Exported version of findUserEntryByEmail; returns public User instead of userEntry.
Input:
- email string: Email to find
Output:
- User: User data, or empty user if not found.
func FindUserByUsername ¶
Exported version of findUserEntryByUsername; returns public User instead of userEntry.
Input:
- username string: Username to find
Output:
- User: User data, or empty user if not found.
func ValidateUserCred ¶
Validate a user with username and password credentials.
Input:
- username, password string: User credentials. The username will be used to find the userEntry, and then the password will be hashed with that userEntry salt and hash function and compared to the userEntry password.
Output:
- bool: Is user valid?
- User: Public user credentials.
- error: Any errors that occur during user validation, including: failure to find user, failure to hash password, failure to validate user.
Source Files