Main Authentication/Authorization service class, it provides means to authenticate users and to check for permissions.

Authentication

Whenever the system successfully creates a new login session (during auth service startup), it checks whether the key midcom_services_auth_login_success_url is present in the HTTP Request data. If this is the case, it relocates to the URL given in it. This member isn't set by default in the MidCOM core, it is intended for custom authentication forms. The MidCOM relocate function is used to for relocation, thus you can take full advantage of the convenience functions in there. See midcom_application::relocate() for details.

Checking Privileges

This class overs various methods to verify the privilege state of a user, all of them prefixed with can_* for privileges and is_* for membership checks.

Each function is available in a simple check version, which returns true or false, and a require_* prefixed variant, which has no return value. The require variants of these calls instead check if the given condition is met, if yes, they return silently, otherwise they throw an access denied error.

todo Fully document authentication.
package midcom.services

 Methods

_http_basic_auth ()

Handles HTTP Basic authentication

_sync_user_with_backend ()

Internal helper, synchronizes the main service class with the authentication state of the authentication backend.

can_do (string $privilege, \MidgardObject $content_object, \midcom_core_user $user)

Checks whether a user has a certain privilege on the given content object.

Works on the currently authenticated user by default, but can take another user as an optional argument.

Parameters

$privilege

stringThe privilege to check for

$content_object

\MidgardObjectA Midgard Content Object

$user

\midcom_core_userThe user against which to check the privilege, defaults to the currently authenticated user. You may specify "EVERYONE" instead of an object to check what an anonymous user can do.

Returns

booleanTrue if the privilege has been granted, false otherwise.

can_user_do (string $privilege, \midcom_core_user $user, string $class, string $component)

Checks, whether the given user have the privilege assigned to him in general.

Be aware, that this does not take any permissions overridden by content objects into account. Whenever possible, you should user the can_do() variant of this call therefore. can_user_do is only of interest in cases where you do not have any content object available, for example when creating root topics.

Parameters

$privilege

stringThe privilege to check for

$user

\midcom_core_userThe user against which to check the privilege, defaults to the currently authenticated user, you may specify 'EVERYONE' here to check what an anonymous user can do.

$class

stringOptional parameter to set if the check should take type specific permissions into account. The class must be default constructible.

$component

stringComponent providing the class

Returns

booleanTrue if the privilege has been granted, false otherwise.

drop_sudo ()

Drops previously acquired superuser privileges.

get_assignee (string $id)

Factory Method: Resolves any assignee identifier known by the system into an appropriate user/group object.

You must adhere the reference that is returned, otherwise the internal caching and runtime state strategy will fail.

Parameters

$id

stringA valid user or group identifier useable as assignee (e.g. the $id member of any midcom_core_user or midcom_core_group object).

Returns

objectA reference to the corresponding object or false on failure.

get_group (mixed $id)

Returns a midcom_core_group instance.

Valid arguments are either a valid group identifier (group:...), any valid identifier for the midcom_core_group constructor or a valid object of that type.

You must adhere the reference that is returned, otherwise the internal caching and runtime state strategy will fail.

Parameters

$id

mixedThe identifier of the group as outlined above.

Returns

\midcom_core_groupA group object instance matching the identifier, or false on failure.

get_midgard_group_by_name (string $name)

This is a wrapper for get_group, which allows Midgard Group retrieval by its name.

If the group name is unknown, false is returned.

In the case that more then one group matches the given name, the first one is returned. Note, that this should not happen as midgard group names should be unique according to the specs.

Parameters

$name

stringThe name of the group to look up.

Returns

\midcom_core_groupA reference to the group object matching the group name, or false if the group name is unknown.

get_privileges (\MidgardObject $content_object, \midcom_core_user $user)

Returns a full listing of all currently known privileges for a certain object/user combination.

The information is cached per object-guid during runtime, so that repeated checks to the same object do not cause repeating checks. Be aware that this means, that new privileges set are not guaranteed to take effect until the next request.

Parameters

$content_object

\MidgardObject&$content_object A Midgard Content Object

$user

\midcom_core_userThe user against which to check the privilege, defaults to the currently authenticated user. You may specify "EVERYONE" instead of an object to check what an anonymous user can do.

Returns

ArrayAssociative listing of all privileges and their value.

get_user (mixed $id)

Factory Method: Loads a user from the database and returns an object instance.

You must adhere the reference that is returned, otherwise the internal caching and runtime state strategy will fail.

Parameters

$id

mixedA valid identifier for a MidgardPerson: An existing midgard_person class or subclass thereof, a Person ID or GUID or a midcom_core_user identifier.

Returns

\midcom_core_userA reference to the user object matching the identifier or false on failure.

get_user_by_name (string $name)

This is a wrapper for get_user, which allows user retrieval by its name.

If the username is unknown, false is returned.

Parameters

$name

stringThe name of the user to look up.

Returns

\midcom_core_userA reference to the user object matching the username, or false if the username is unknown.

initialize ()

Initialize the service:
  • Start up the login session service
  • Load the core privileges.
  • Initialize to the Midgard Authentication, then synchronize with the auth drivers' currently authenticated user overriding the Midgard Auth if necessary.

is_component_sudo ()

is_group_member (mixed $group, \midcom_core_user $user)

Check, whether a user is member of a given group.

By default, the query is run against the currently authenticated user.

It always returns true for administrative users.

Parameters

$group

mixedGroup to check against, this can be either a midcom_core_group object or a group string identifier.

$user

\midcom_core_userThe user which should be checked, defaults to the current user.

Returns

booleanIndicating membership state.

is_valid_user ()

Returns true if there is an authenticated user, false otherwise.

Returns

booleanTrue if there is a user logged in.

logout ()

This call clears any authentication state

request_sudo (string $domain)

Request superuser privileges for the domain passed.

STUB IMPLEMENTATION ONLY, WILL ALWAYS GRANT SUDO.

You have to call midcom_services_auth::drop_sudo() as soon as you no longer need the elevated privileges, which will reset the authentication data to the initial credentials.

Parameters

$domain

stringThe domain to request sudo for. This is a component name.

Returns

booleanTrue if admin privileges were granted, false otherwise.

require_admin_user (string $message)

Validates that we currently have admin level privileges, which can either come from the current user, or from the sudo service.

If the check is successful, the function returns silently.

Parameters

$message

stringThe message to show if the admin level privileges are missing..

require_do (string $privilege, \MidgardObject $content_object, string $message)

Validates that the current user has the given privilege granted on the content object passed to the function.

If this is not the case, an Access Denied error is generated, the message defaulting to the string 'access denied: privilege %s not granted' of the MidCOM main L10n table.

The check is always done against the currently authenticated user. If the check is successful, the function returns silently.

Parameters

$privilege

stringThe privilege to check for

$content_object

\MidgardObjectA Midgard Content Object

$message

stringThe message to show if the privilege has been denied.

require_group_member (mixed $group, string $message)

Validates that the current user is a member of the given group.

If this is not the case, an Access Denied error is generated, the message defaulting to the string 'access denied: user is not member of the group %s' of the MidCOM main L10n table.

The check is always done against the currently authenticated user. If the check is successful, the function returns silently.

Parameters

$group

mixedGroup to check against, this can be either a midcom_core_group object or a group string identifier.

$message

stringThe message to show if the user is not member of the given group.

require_user_do (string $privilege, string $message, string $class)

Validates, whether the given user have the privilege assigned to him in general.

Be aware, that this does not take any permissions overridden by content objects into account. Whenever possible, you should user the require_do() variant of this call therefore. require_user_do is only of interest in cases where you do not have any content object available, for example when creating root topics.

If this is not the case, an Access Denied error is generated, the message defaulting to the string 'access denied: privilege %s not granted' of the MidCOM main L10n table.

The check is always done against the currently authenticated user. If the check is successful, the function returns silently.

Parameters

$privilege

stringThe privilege to check for

$message

stringThe message to show if the privilege has been denied.

$class

stringOptional parameter to set if the check should take type specific permissions into account. The class must be default constructible.

require_valid_user (string $method)

Validates that there is an authenticated user.

If this is not the case, the regular login page is shown automatically, see show_login_page() for details..

If the check is successful, the function returns silently.

Parameters

$method

stringPreferred authentication method: form or basic

_generate_http_response ()

_initialize_user_from_midgard ()

Internal startup helper, synchronizes the authenticated user with the Midgard Authentication for startup.

This will be overridden by MidCOM Auth, but is there for compatibility reasons.

_prepare_authentication_drivers ()

Internal startup helper, loads all configured authentication drivers.

 Properties

 

\midcom_services_auth_acl $acl

This is a reference to the ACL management system.
 

boolean $admin

Admin user level state.

This is true if the currently authenticated user is an Midgard Administrator, false otherwise.

This effectively maps to midcom_connection::is_admin(); but it is suggested to use the auth class for consistency reasons nevertheless.

 

boolean $auth_credentials_found

Flag, which is set to true if the system encountered any new login credentials during startup.

If this is true, but no user is authenticated, login did fail.

The variable is to be considered read-only.

 

\midcom_services_auth_sessionmgr $sessionmgr

This is a reference to the login session management system.
 

\midcom_core_user $user

The currently authenticated user or null in case of anonymous access.

It is to be considered read-only.

 

\midcom_services_auth_backend $_auth_backend

A reference to the authentication backend we should use by default.
 

\midcom_services_auth_frontend $_auth_frontend

A reference to the authentication frontend we should use by default.
 

int $_component_sudo

This flag indicates if sudo mode is active during execution.

This will only be the case if the sudo system actually grants this privileges, and only until components release the rights again. This does override the full access control system at this time and essentially give you full admin privileges (though this might change in the future).

Note, that this is no boolean but an int, otherwise it would be impossible to trace nested sudo invocations, which are quite possible with multiple components calling each others callback. A value of 0 indicates that sudo is inactive. A value greater then zero indicates sudo mode is active, with the count being equal to the depth of the sudo callers.

It is thus still safely possible to evaluate this member in a boolean context to check for an enabled sudo mode.

see \request_sudo()
see \drop_sudo()
 

Array $_group_cache

Internal cache of all loaded groups, indexed by their identifiers.
 

Array $_user_cache

Internal cache of all loaded users, indexed by their identifiers.