$user
$user : \midcom_core_user
The currently authenticated user or null in case of anonymous access.
It is to be considered read-only.
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.
$user : \midcom_core_user
The currently authenticated user or null in case of anonymous access.
It is to be considered read-only.
$acl : \midcom_services_auth_acl
The ACL management system.
$_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.
$backend : \midcom_services_auth_backend
The authentication backend we should use by default.
$frontend : \midcom_services_auth_frontend
The authentication frontend we should use by default.
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
| \Symfony\Component\HttpFoundation\Request | $request |
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.
| 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. |
True if the privilege has been granted, false otherwise.
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.
| 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. |
True if the privilege has been granted, false otherwise.
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.
| \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. |
Associative listing of all privileges and their value.
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.
| string | $domain | The domain to request sudo for. This is a component name. |
True if admin privileges were granted, false otherwise.
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.
| mixed | $group | Group to check against, this can be either a midcom_core_group object or a group string identifier. |
| $user |
Indicating membership state.
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.
| 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(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.
| 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(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.
| 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(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.
| string | $message | The message to show if the admin level privileges are missing. |
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.
| string | $method | Preferred authentication method: form or basic |
get_assignee(string $id) : object|false
Resolve any assignee identifier known by the system into an appropriate user/group object.
| 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). |
corresponding object or false on failure.
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.
| string | $name | The name of the user to look up. |
The user object matching the username, or false if the username is unknown.
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.
| string | $name | The name of the group to look up. |
The group object matching the name, or false if the group name is unknown.
get_user(mixed $id) : \midcom_core_user|false
Load a user from the database and returns an object instance.
| 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. |
The user object matching the identifier or false on failure.
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.
| mixed | $id | The identifier of the group as outlined above. |
A group object instance matching the identifier, or false on failure.
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 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'.
set_user(\midcom_core_user $user)
| \midcom_core_user | $user |