This document will attempt to outline the authentication and authorization features currently available. UBMoD 2.0 (0.2.4) is the first version to integrate authentication and authorization features. Note: These features are not yet finalized and future versions may not be backward compatibile.

UBMoD does not provide any method for authenticating users (usernames and passwords are not stored in UBMoD), but can integrate with external authentication systems. Any of the Apache authentication modules should work with UBMoD.

Implementation note: Refer to the Apache authentication and authorization documentation for instructions on setting up authentication.

The first step is to enable authentication system in UBMoD. Once enabled, you will no longer be able to access the UBMoD portal without being authenticated.

Add this section to settings.ini:

[authentication]
enabled = true

After enabling authentication in UBMoD, you must enable an Apache authentication module to provide the authentication mechanism required by UBMoD

For example, to use basic file based authentication (mod_auth_basic and mod_authn_file):

<VirtualHost *>
    ...

    <Directory /usr/share/ubmod/html>
        AuthType basic
        AuthName "UBMoD"
        AuthBasicProvider file
        AuthUserFile /etc/htpasswdfile
        Require valid-user

        ...
    </Directory>
</VirtualHost>

Implementation note: Refer to HTTP authentication with PHP and the $_SERVER superglobal documentation. By default, UBMoD uses REMOTE_USER as defined by the CGI/1.1 specification.

If you use an authentication system that doesn't set REMOTE_USER, but does set another header that is passed to PHP, that can be changed by setting the "key" setting:

[authentication]
enabled = true
key = CUSTOM_HEADER

In addition to authentication, UBMoD has support for limiting access to specific users. This is accomplished by defining multiple roles and assigning a role to specific users. A default role may also be defined for users that haven't been assigned to a specific role.

Before configuring authorization make sure that authentication is working properly. The authorization feature cannot be used without the authentication feature.

[authorization]
enabled = true

Each role provides access to a set of resources and actions that can be performed on those resources. Most of the resources and actions correspond directly to URLs with a few exceptions list in the next section. The complete list of resources are defined in acl-resources.json. All the resources and actions have not been documented outside of the portal code, so it is best to make use of the pre-defined roles that are described later in this documentation.

In addition to the resources and actions that correspond directly to portal URLs, there are also other features that can be controlled with the authorization system. Each page listed in the menu has a "menu" action. Denying access to the "menu" action of the "queue" resource will result in the absence of this menu item, but it won't prevent access to the queue page if accessed directly. The "group" and "user" resources both have an action named "query-all". Denying access to these action will limit the users and groups to those that have the same name as the authenticated user's username and group, respectively.

In addition to the standard dashboard, there are two other dashboards that only display group and user level information. To use the group dashboard for a given role, deny the "dashboard" "utilization" action (See the custom role section below). To use the user dashboard, deny access to the "group" "details" action as well.

There are several roles defined by UBMoD that can be inherited from in custom roles. These roles are defined in a file named acl-roles.json. This file should not be changed. These roles correspond to each section of the UBMoD portal along with a general role that grants access to privileges that are needed by all users. These roles are not meant to be assigned directly to users, but can be combined to create custom roles.

general
dashboard-page
wait-time-page
wall-time-page
user-detail-page
group-detail-page
queue-detail-page
tag-management-page
tag-reports-page
about-page

Custom roles are defined in roles.json. Each role consists of a name with optional sections for parent roles, and resources that each role is allowed or denied access to.

Implementation note: All JSON files must be properly formatted. All strings must be enclosed in double-quotes and no trailing commas are allowed. Refer to Introducing JSON for more details.

Example of roles.json format:

[
    {
        "name": "role-name-1",
        "parents": [
            "parent-role-1",
            "parent-role-2"
        ],
        "allow": {
            "resource-name-1": [
                "action-name-1",
                "action-name-2"
            ],
            "resource-name-2": null
        },
        "deny": {
            "resource-name-2": [
                "action-name-1"
            ]
        }
    }
]

The file consists of an array of role objects. Each role object has a name along with an optional array of parent roles, an optional object defining allowed resources and actions and an optional object defining denied resources and actions.

The parent roles can be any role that is in the default role set listed above or a role that is defined in this file. This list should include the "general" role unless access to those resources is made available by another rule.

The "allow" and "deny" objects can use any of the following three formats where null is used as a wildcard.

Allow everything:

"allow": null

Allow all actions for a resource:

"allow": {
    "resource-name": null
}

Allow specific actions for a resource:

"allow": {
    "resource-name": ["action-name"]
}

If a role exists with the name __default__ it will be used for authenticated users that aren't associated with any other role. If you don't assign every user a role, it is suggested to create a restrictive default role that allow access

Example with restrictive default role that uses the user dashboard, principal investigator role that uses the group dashboard and admin role that allows everything:

[
    {
        "name": "__default__",
        "parents": [
            "general",
            "dashboard-page",
            "wait-time-page",
            "wall-time-page",
            "queue-detail-page",
            "about-page"
        ],
        "allow": {
            "user": null
        },
        "deny": {
            "dashboard": ["utilization"],
            "user": ["menu", "index", "query-all"]
        }
    },
    {
        "name": "principal-investigator",
        "parents": [
            "general",
            "dashboard-page",
            "wait-time-page",
            "wall-time-page",
            "user-detail-page",
            "queue-detail-page",
            "about-page"
        ],
        "allow": {
            "group": ["details"]
        },
        "deny": {
            "dashboard": ["utilization"],
            "user": ["query-all"]
        }
    },
    {
        "name": "admin",
        "allow": null
    }
]

Implementation note: Refer to the Zend Framework Zend_Acl documentation for precedence rules.

Users are assigned to roles in the user-roles.json file. Each user should be assigned only one role. If a user is assigned to more than one role, the behavior is undefined.

{
    "role-name-1": [
        "username-1",
        "username-2",
        "username-3"
    ],
    "role-name-2": [
        "username-4",
        "username-5",
        "username-6"
    ]
}

This example assigns the admin role to three users.

{
    "admin": [
        "admin-username-1",
        "admin-username-2",
        "admin-username-3"
    ]
}