\midcom_services_auth

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.

Summary

Methods
Properties
Constants
__construct()
check_for_login_session()
can_do()
can_user_do()
get_privileges()
request_sudo()
drop_sudo()
is_component_sudo()
is_group_member()
is_valid_user()
require_do()
require_user_do()
require_group_member()
require_admin_user()
require_admin_or_ip()
require_valid_user()
get_assignee()
get_user_by_name()
get_midgard_group_by_name()
get_user()
get_group()
login()
trusted_login()
logout()
show_login_form()
show_login_page()
show_access_denied()
$user
$admin
$acl
No constants found
No protected methods found
No protected properties found
N/A
set_user()
_prepare_authentication_drivers()
is_admin()
access_denied()
_http_basic_auth()
$_group_cache
$_user_cache
$_component_sudo
$backend
$frontend
N/A

Properties

$user

$user : \midcom_core_user

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

It is to be considered read-only.

Type

\midcom_core_user

$admin

$admin : boolean

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.

Type

boolean

$_group_cache

$_group_cache : Array

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

Type

Array

$_user_cache

$_user_cache : Array

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

Type

Array

$_component_sudo

$_component_sudo : integer

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 than 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.

Type

integer

Methods

__construct()

__construct() 

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.

check_for_login_session()

check_for_login_session(\Symfony\Component\HttpFoundation\Request  $request) 

Checks if the current authentication fronted has new credentials ready. If yes, it processes the login accordingly. Otherwise look for existing session

Parameters

\Symfony\Component\HttpFoundation\Request $request

can_do()

can_do(string  $privilege, \MidgardObject  $content_object, \midcom_core_user  $user = null) : boolean

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

string $privilege

The privilege to check for

\MidgardObject $content_object

A Midgard Content Object

\midcom_core_user $user

The 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

boolean —

True if the privilege has been granted, false otherwise.

can_user_do()

can_user_do(string  $privilege, \midcom_core_user  $user = null, string  $class = null) : boolean

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

string $privilege

The privilege to check for

\midcom_core_user $user

The 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.

string $class

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

Returns

boolean —

True if the privilege has been granted, false otherwise.

get_privileges()

get_privileges(\MidgardObject  $content_object, \midcom_core_user  $user = null) : Array

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

\MidgardObject $content_object

A Midgard Content Object

\midcom_core_user $user

The 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

Array —

Associative listing of all privileges and their value.

request_sudo()

request_sudo(string  $domain = null) : boolean

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

string $domain

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

Returns

boolean —

True if admin privileges were granted, false otherwise.

drop_sudo()

drop_sudo() 

Drops previously acquired superuser privileges.

is_component_sudo()

is_component_sudo() 

is_group_member()

is_group_member(mixed  $group,   $user = null) : boolean

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

mixed $group

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

$user

Returns

boolean —

Indicating membership state.

is_valid_user()

is_valid_user() : boolean

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

Returns

boolean —

True if there is a user logged in.

require_do()

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

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

string $privilege

The privilege to check for

\MidgardObject $content_object

A Midgard Content Object

string $message

The message to show if the privilege has been denied.

require_user_do()

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

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

string $privilege

The privilege to check for

string $message

The message to show if the privilege has been denied.

string $class

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

require_group_member()

require_group_member(mixed  $group, string  $message = null) 

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

mixed $group

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

string $message

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

require_admin_user()

require_admin_user(string  $message = null) 

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

string $message

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

require_admin_or_ip()

require_admin_or_ip(string  $domain) : boolean

Require either a configured IP address or admin credentials

Parameters

string $domain

Domain for IP sudo

Throws

\midcom_error

In case request_sudo fails

Returns

boolean —

True if IP sudo is active, false otherwise

require_valid_user()

require_valid_user(string  $method = 'form') 

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

string $method

Preferred authentication method: form or basic

get_assignee()

get_assignee(string  $id) : object|false

Resolve any assignee identifier known by the system into an appropriate user/group object.

Parameters

string $id

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

Returns

object|false —

corresponding object or false on failure.

get_user_by_name()

get_user_by_name(string  $name) : \midcom_core_user|false

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

If the username is unknown, false is returned.

Parameters

string $name

The name of the user to look up.

Returns

\midcom_core_user|false —

The user object matching the username, or false if the username is unknown.

get_midgard_group_by_name()

get_midgard_group_by_name(string  $name) : \midcom_core_group|false

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 than 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

string $name

The name of the group to look up.

Returns

\midcom_core_group|false —

The group object matching the name, or false if the group name is unknown.

get_user()

get_user(mixed  $id) : \midcom_core_user|false

Load a user from the database and returns an object instance.

Parameters

mixed $id

A 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_user|false —

The user object matching the identifier or false on failure.

get_group()

get_group(mixed  $id) : \midcom_core_group|false

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.

Parameters

mixed $id

The identifier of the group as outlined above.

Returns

\midcom_core_group|false —

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

login()

login(  $username,   $password,   $clientip = null) 

This call tells the backend to log in.

Parameters

$username
$password
$clientip

trusted_login()

trusted_login(  $username) 

Parameters

$username

logout()

logout() 

This call clears any authentication state

show_login_form()

show_login_form() 

Render the main login form.

This only includes the form, no heading or whatsoever.

It is recommended to call this function only as long as the headers are not yet sent (which is usually given thanks to MidCOMs output buffering).

What gets rendered depends on the authentication frontend, but will usually be some kind of form.

show_login_page()

show_login_page() 

Show a complete login page unconditionally and exit afterwards.

If the current style has an element called midcom_services_auth_login_page it will be shown instead. The local scope will contain the two variables $title and $login_warning. $title is the localized string 'login' from the main MidCOM L10n DB, login_warning is empty unless there was a failed authentication attempt, in which case it will have a localized warning message enclosed in a paragraph with the ID 'login_warning'.

show_access_denied()

show_access_denied(  $message) 

Parameters

$message

_prepare_authentication_drivers()

_prepare_authentication_drivers() 

Internal startup helper, loads all configured authentication drivers.

is_admin()

is_admin(  $user) 

Parameters

$user

access_denied()

access_denied(  $message,   $fallback,   $data = null) 

Parameters

$message
$fallback
$data

_http_basic_auth()

_http_basic_auth() 

Handles HTTP Basic authentication