A static class that provides access to the Myna Permissions System
The functions and classes in this library combined with the web application located at MynaRoot/myna/permissions/index.ejs form Myna’s permissions system. The purpose of the permissions system is to provide a standardized and centralized system for managing users and their rights in your applications.
| User | A “user” is a unique entity such as a human or software service that has certain rights to perform actions in your system. A user can have one or more “logins”. Users are a global resource and are not associated with any particular application. |
| Login | A “login” is a unique identifier with an authentication authority, such as a local database, a Microsoft Active Directory, LDAP, or Open ID. Myna knows how to authenticate against its own local database in myna_permissions. To use this functionality, save a user name and password, and set the type to “myna”. You can then compare a plain text password to the stored password via User.isCorrectPassword. |
| Right | A right is essentially just a name associated with an application (appname). Rights only have meaning when an application checks for them and grants or restricts access based on them. The easiest way to do this is to call User.hasRight to check if the logged-in user has a particular right. Myna has some built-in support for the right “edit_permissions” in any application. A user with “edit_permissions” for an application is allowed to edit the permissions for that application in MynaRoot/myna/permissions/index.ejs. The Myna Adminstrator can edit permissions for any application, so it is possible to create a user account and assign edit_permissions to it and then let that user handle any further changes for his or her application |
| User Group | User groups are where users and rights meet. Like rights, user groups are associated with an application (appname). User groups are intended to represent a role, such as “Adminstrators” or “HR Staff”. |
in this step your application needs to know how to authenticate a user. This can be internal Myna authentication via User.isCorrectPassword, or an external authentication mechanism such as LDAP or your HR database. Some organizations have multiple ways of authenticating and allow the user to choose which to use.
After authentication, look up user’s user_id from his/her login and type (Myna.Permissions.getUserByLogin) and call $cookie.setAuthUserId. This sets a cookie with the user’s id and refreshes that cookie everytime the user makes a request. This cookie is encrypted with the result of getAuthKey (“myna_auth_cookie”). There is no timeout for this cookie, but it will automatically expire when the user closes the browser. If you want the authentication token to have a timeout, store the user_id in the session instead.
You can confirm that a user has been authenticated by checking $cookie.getAuthUserId which will return null if the current user is not authenticated. Placing this check in your $application.onRequestStart function is an easy way to prevent unauthenticated access.
To see if the current user has the right to “foo”, call User.hasRight (“foo”). You can use the Myna Administrator to define as a many rights as your application needs
To logout, simply call $cookie.clearAuthUserId and/or $session.clear
The Myna Permissions application is primarily designed to be accessed through the Myna Administrator and used to set up users, logins, rights, and groups. It can also be used in a simplified form for a particular application, in which case it is limited to just group management. In this mode your application can connect to the Myna Permissions application via IFRAME element or window.open() by passing an authentication token generated by Myna.Permissions.getAuthToken, like this:
<!-- index.ejs -->
<a href="perms.ejs" target="perm_window">Edit Foo Permissions</a>
...
// perms.ejs
var token =Myna.Permissions.getAuthToken($cookie.getAuthUserId());
var url = $server.rootUrl + "myna/permissions/index.ejs?appname=foo&auth_token=" + token;
$res.metaRedirect(url);
As an aside, you can use the getAuthToken / consumeAuthToken functions to transfer authentication between any two Myna applications, even if they are on different servers, as long as they both use the same “myna_permissions” datasource. For example, Myna.WebService instances check $req.auth_token in addition to the HTTP Basic Auth header, and $cookie.get(“myna_auth_cookie”) for authentication
| Myna. Permissions | A static class that provides access to the Myna Permissions System |
| Functions | |
| addApp | Adds/updates an application, and returns an instance of <Myna.Permissions.App>. |
| getAppValues | returns an object containing the display name, description, and inactive_ts for the supplied appname, or null if not defined |
| addRight | adds a new right, and returns an instance of Myna.Permissions.Right |
| deleteRight | deletes a right |
| addUserGroup | adds a new user group, and returns an instance of <Myna.UserGroup> |
| deleteUserGroup | removes a user group |
| addUser | adds a new user, and returns an instance of Myna.Permissions.User |
| consumeAuthToken | returns associated user_id or null if invalid |
| getAuthAdapter | creates and configures and authentication adapter based on the auth type name provided |
| getAuthKey | retrieves a unique authKey from the crypt_keys table for the supplied name, or creates one if the name does not exist. |
| getAuthToken | creates stores and return a one-use authentication token for the supplied user_id |
| getAuthTypes | returns an array of valid auth type names for this system |
| getRightById | returns the right object that matches the supplied id or null |
| getRightByName | returns the right object that matches the supplied name and appname, or returns null |
| getRightsByAppname | returns a Myna.DataSet of all the rights associated with the supplied appname |
| getUserGroupsByAppname | returns a Myna.DataSet of all the user groups associated with the supplied appname |
| getUserGroupById | returns the user group object that matches the supplied id or null |
| getUserById | returns the User object that matches the supplied id or null |
| getUserByLogin | returns the User object that matches the supplied login or null |
| getUserByAuth | returns the User that matches the supplied username and password or null if no matches |
| Myna. Permissions.User | Provides access to user specific permissions. |
| Functions | |
| get_created | returns created |
| get_first_name | returns first_name |
| get_last_login | returns last_login |
| get_last_name | returns last_name |
| get_middle_name | returns middle_name |
| get_title | returns title |
| get_user_id | returns user_id |
| set_created | sets created |
| set_first_name | sets first_name |
| set_last_login | sets last_login |
| set_last_name | sets last_name |
| set_middle_name | sets middle_name |
| set_title | sets title |
| qryRights | returns query of rights associated with this user |
| inactivate | inactivates this user. |
| isActive | returns true if this user is active |
| reactivate | reactivates this user |
| hasRight | returns true if this user has been assigned the supplied appname and right name |
| hasAnyRight | returns true if this user has been assigned the supplied appname and any of the supplied right names |
| getLogins | returns an array of objects in the form of [{type,login}] of the logins associated with this user |
| getLoginList | returns a list of type/login pairs in the form of “type:login,type:login” of the logins associated with this user |
| setLogin | adds or updates an login for this user |
| isCorrectPassword | returns true if the supplied user login and plaintext password match the stored password hash. |
| Myna. Permissions. Right | Provides access to Right specific actions. |
| Functions | |
| get_appname | returns appname |
| get_description | returns description |
| get_name | returns name |
| get_right_id | returns right_id |
| set_appname | sets appname |
| set_description | sets description |
| set_name | sets name |
| Myna. Permissions. UserGroup | Provides access to user group specific actions. |
| Functions | |
| get_appname | returns appname |
| get_description | returns description |
| get_name | returns name |
| get_user_group_id | returns user_group_id |
| set_appname | sets appname |
| set_description | sets description |
| set_name | sets name |
| addUsers | adds one or more users to this group, if not already added |
| addRights | adds one or more rights to this group, if not already added |
| qryRights | returns query of rights associated with this group |
| removeRights | removes one or more rights from this group, if not already removed |
| removeUsers | removes one or more users from this group, if not already removed |
| qryUsers | returns a query of user information associated with this group |
addApp:function( options )
Adds/updates an application, and returns an instance of <Myna.Permissions.App>.
| options | An object containing the new application’s information. See “options” below |
| appname | appname of this application. Used programatically to refer to this applicaiton. Only lowercase letters, numbers, and “_” allowed. |
| display_name | *Optional, default appname * The name of the app as it should be displayed to to humans |
| description | Optional, default “” A short description of this application |
Creates a new application entry. Also creates a UserGroup called “Administrators” containing a right called “edit_permissions” both associated with this appname. Any users in a group containing this app’s “edit_permissions” right will be able to create groups and assign permissions for this app via the Myna permissions front-end. If the appname already exists it is updated with the display name and description.
getAppValues:function( appname )
returns an object containing the display name, description, and inactive_ts for the supplied appname, or null if not defined
| appname | appname of the application. |
addRight:function( options )
adds a new right, and returns an instance of Myna.Permissions.Right
| options | An object containing the new right’s information. See “options” below |
| name | Name of the right. Should be a single word. |
| appname | appname of application associated with this right |
| description | Optional, default “” A description of the ability this right confers |
addUserGroup:function( options )
adds a new user group, and returns an instance of <Myna.UserGroup>
| options | An object containing the new user group’s information. See “options” below |
| name | Name of the user group. Can be any string, but should be short |
| appname | appname of application associated with this right |
| description | Optional, default “” A description of types of users that should be associated with this group |
deleteUserGroup:function( user_group_id )
removes a user group
| user_group_id | id of group to delete |
addUser:function( options )
adds a new user, and returns an instance of Myna.Permissions.User
| options | An object containing the new user’s information. See “options” below |
| first_name | Optional, default “” User’s first name |
| middle_name | Optional, default “” User’s middle name |
| last_name | Optional, default “” User’s last name |
| Optional, default “” User’s email address | |
| title | Optional, default “” User’s title, e.g. Mr, Mrs, Sir, Dr |
consumeAuthToken:function( token )
returns associated user_id or null if invalid
| token | token to consume |
Consuming a token permenantly removes it.
See getAuthToken
getAuthAdapter:function( auth_type )
creates and configures and authentication adapter based on the auth type name provided
| auth_type | name of the configuration to use to create the adapter. This name should match a config file in /WEB-INF/myna/auth_types |
getAuthKey:function( name )
retrieves a unique authKey from the crypt_keys table for the supplied name, or creates one if the name does not exist.
| name | name of key to retrieve |
getAuthToken:function( user_id, timeout )
creates stores and return a one-use authentication token for the supplied user_id
| user_id | user_id of the user to be authenticated |
| timeout | Optional, default 10000 Time in milliseconds that this token will be accepted. This should be the smallest amount of time that the two systems can reliably process. Longer timeouts leave a larger window for replay attacks Detail: This function is intended to be used in conjunction with consumeAuthToken to allow an application to “pre-authenticate” a user to another application. This requires the source application to acquire an authentication token representing a user_id, and then send this to the target application, normally via a URL or FORM variable called “auth_token”. The receiving application will call consumeAuthToken and store the result with $cookie.setAuthUserId |
Authentication tokens are stored in the “myna_permissions” data source, so both sending and receiving applications must use the same database for “myna_permissions”.
The token itself does not contain any authentication information. It is a just a cryptographically unique key to lookup authentication information in a shared database. If these tokens are sent over
getRightById:function( id )
returns the right object that matches the supplied id or null
| id | right id to search |
getRightByName:function( name, appname )
returns the right object that matches the supplied name and appname, or returns null
| name | right name |
| appname | right appname |
getRightsByAppname:function( appname )
returns a Myna.DataSet of all the rights associated with the supplied appname
| appname | appname to filter by |
getUserGroupsByAppname:function( appname )
returns a Myna.DataSet of all the user groups associated with the supplied appname
| appname | appname to filter by |
getUserGroupById:function( id )
returns the user group object that matches the supplied id or null
| id | user group id to search |
getUserById:function( id )
returns the User object that matches the supplied id or null
| id | user id to search |
getUserByLogin:function( type, login )
returns the User object that matches the supplied login or null
| type | login type |
| login | login |
getUserByAuth:function( login, password, type )
returns the User that matches the supplied username and password or null if no matches
| login | login string (username) |
| password | user’s password |
| type | Optional, default null auth type to check, or all types if not defined. if more than one user matches this login and password an exception is thrown |
Provides access to user specific permissions. see Myna.Permissions for creation
| Functions | |
| get_created | returns created |
| get_first_name | returns first_name |
| get_last_login | returns last_login |
| get_last_name | returns last_name |
| get_middle_name | returns middle_name |
| get_title | returns title |
| get_user_id | returns user_id |
| set_created | sets created |
| set_first_name | sets first_name |
| set_last_login | sets last_login |
| set_last_name | sets last_name |
| set_middle_name | sets middle_name |
| set_title | sets title |
| qryRights | returns query of rights associated with this user |
| inactivate | inactivates this user. |
| isActive | returns true if this user is active |
| reactivate | reactivates this user |
| hasRight | returns true if this user has been assigned the supplied appname and right name |
| hasAnyRight | returns true if this user has been assigned the supplied appname and any of the supplied right names |
| getLogins | returns an array of objects in the form of [{type,login}] of the logins associated with this user |
| getLoginList | returns a list of type/login pairs in the form of “type:login,type:login” of the logins associated with this user |
| setLogin | adds or updates an login for this user |
| isCorrectPassword | returns true if the supplied user login and plaintext password match the stored password hash. |
Myna.Permissions.User.prototype.qryRights = function()
returns query of rights associated with this user
returns a Myna.Query object containing right_id, name, appname, and description columns for each right this user has been assigned
Myna.Permissions.User.prototype.inactivate = function()
inactivates this user. Inactivating a user also removes the user from all user groups and causes isCorrectPassword to fail even if the password is correct
Myna.Permissions.User.prototype.hasRight = function( appname, rightName )
returns true if this user has been assigned the supplied appname and right name
| appname | name appname of of application |
| right | right name |
Myna.Permissions.User.prototype.hasAnyRight = function( appname, right_list )
returns true if this user has been assigned the supplied appname and any of the supplied right names
| appname | name appname of of application |
| right | Optional, default all rights for _appname_ a comma separated list or right names |
Myna.Permissions.User.prototype.getLogins = function()
returns an array of objects in the form of [{type,login}] of the logins associated with this user
Myna.Permissions.User.prototype.getLoginList = function( delimiter, seperator )
returns a list of type/login pairs in the form of “type:login,type:login” of the logins associated with this user
| delimiter | Optional, default ‘,’ seperator between each type/login set |
| seperator | Optional, default ‘:’ seperator between each type and login in each login set |
Myna.Permissions.User.prototype.setLogin = function( options )
adds or updates an login for this user
| options | An object that conains the options for this login. see below |
| type | type of login. This is a hint for how to authenticate using this login. Suggested values: myna (for local password access), ldap, openid |
| login | the appropriate type of identifier, |
| password | optional default “” a plain text password to encrypt with this login |
Myna.Permissions.User.prototype.isCorrectPassword=function( login, password )
returns true if the supplied user login and plaintext password match the stored password hash. Only works for “myna” auth type. Will always return false for inactive users
| login | user login |
| password | a plain text password for comparison |
Provides access to Right specific actions. see Myna.Permissions for creation
| Functions | |
| get_appname | returns appname |
| get_description | returns description |
| get_name | returns name |
| get_right_id | returns right_id |
| set_appname | sets appname |
| set_description | sets description |
| set_name | sets name |
Provides access to user group specific actions. See Myna.Permissions for creation
| Functions | |
| get_appname | returns appname |
| get_description | returns description |
| get_name | returns name |
| get_user_group_id | returns user_group_id |
| set_appname | sets appname |
| set_description | sets description |
| set_name | sets name |
| addUsers | adds one or more users to this group, if not already added |
| addRights | adds one or more rights to this group, if not already added |
| qryRights | returns query of rights associated with this group |
| removeRights | removes one or more rights from this group, if not already removed |
| removeUsers | removes one or more users from this group, if not already removed |
| qryUsers | returns a query of user information associated with this group |
Myna.Permissions.UserGroup.prototype.addUsers = function( user_id_list )
adds one or more users to this group, if not already added
| user_id_list | array or list of user_ids to add |
Myna.Permissions.UserGroup.prototype.addRights = function( right_id_list )
adds one or more rights to this group, if not already added
| right_id_list | array or list of right_ids of rights to add |
Myna.Permissions.UserGroup.prototype.qryRights = function()
returns query of rights associated with this group
removes one or more rights from this group, if not already removed
| right_id_list | array or list of right_ids of user to add |
Adds/updates an application, and returns an instance of Myna.Permissions.App.
addApp:function( options )
returns an object containing the display name, description, and inactive_ts for the supplied appname, or null if not defined
getAppValues:function( appname )
adds a new right, and returns an instance of Myna.Permissions.Right
addRight:function( options )
deletes a right
deleteRight:function( right_id )
adds a new user group, and returns an instance of Myna.UserGroup
addUserGroup:function( options )
removes a user group
deleteUserGroup:function( user_group_id )
adds a new user, and returns an instance of Myna.Permissions.User
addUser:function( options )
returns associated user_id or null if invalid
consumeAuthToken:function( token )
creates and configures and authentication adapter based on the auth type name provided
getAuthAdapter:function( auth_type )
retrieves a unique authKey from the crypt_keys table for the supplied name, or creates one if the name does not exist.
getAuthKey:function( name )
creates stores and return a one-use authentication token for the supplied user_id
getAuthToken:function( user_id, timeout )
returns an array of valid auth type names for this system
getAuthTypes:function()
returns the right object that matches the supplied id or null
getRightById:function( id )
returns the right object that matches the supplied name and appname, or returns null
getRightByName:function( name, appname )
returns a Myna.DataSet of all the rights associated with the supplied appname
getRightsByAppname:function( appname )
returns a Myna.DataSet of all the user groups associated with the supplied appname
getUserGroupsByAppname:function( appname )
returns the user group object that matches the supplied id or null
getUserGroupById:function( id )
returns the User object that matches the supplied id or null
getUserById:function( id )
returns the User object that matches the supplied login or null
getUserByLogin:function( type, login )
returns the User that matches the supplied username and password or null if no matches
getUserByAuth:function( login, password, type )
returns query of rights associated with this user
Myna.Permissions.User.prototype.qryRights = function()
inactivates this user.
Myna.Permissions.User.prototype.inactivate = function()
returns true if this user is active
Myna.Permissions.User.prototype.isActive = function()
reactivates this user
Myna.Permissions.User.prototype.reactivate = function()
returns true if this user has been assigned the supplied appname and right name
Myna.Permissions.User.prototype.hasRight = function( appname, rightName )
returns true if this user has been assigned the supplied appname and any of the supplied right names
Myna.Permissions.User.prototype.hasAnyRight = function( appname, right_list )
returns an array of objects in the form of [{type,login}] of the logins associated with this user
Myna.Permissions.User.prototype.getLogins = function()
returns a list of type/login pairs in the form of “type:login,type:login” of the logins associated with this user
Myna.Permissions.User.prototype.getLoginList = function( delimiter, seperator )
adds or updates an login for this user
Myna.Permissions.User.prototype.setLogin = function( options )
returns true if the supplied user login and plaintext password match the stored password hash.
Myna.Permissions.User.prototype.isCorrectPassword=function( login, password )
adds one or more users to this group, if not already added
Myna.Permissions.UserGroup.prototype.addUsers = function( user_id_list )
adds one or more rights to this group, if not already added
Myna.Permissions.UserGroup.prototype.addRights = function( right_id_list )
returns query of rights associated with this group
Myna.Permissions.UserGroup.prototype.qryRights = function()
removes one or more users from this group, if not already removed
Myna.Permissions.UserGroup.prototype.removeUsers = function( user_id_list )
returns a query of user information associated with this group
Myna.Permissions.UserGroup.prototype.qryUsers = function()
sets a cookie that contains the supplied user_id and a timestamp
setAuthUserId:function( user_id )
Returns the user_id in “myna_auth_cookie”, or null if there is no cookie
getAuthUserId:function()
Called before processing a request, but after and parent onRequestStart functions.
onRequestStart:function()
Clears the “myna_auth_cookie”.
clearAuthUserId:function( name )
deletes a session.
clear:function()