////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////

= Impersonation
== What is Impersonation in Apache OFBiz
The Apache OFBiz Project
Release trunk

:imagesdir: ./images/security

=== Introduction to User impersonation

User Impersonation is a feature that offer a way to select a user login and impersonate it, i.e. see what the user could
see navigating through the application in his name.

=== How do this work ?

An authorized user _(see <<impersonation_security,security>> and <<Controls,controls>> section for configuration)_, can select a user
that will be impersonated.

The impersonation start, if everything is well configured, in current application (partymgr for the demo).
Everything appears like if we were logged in with the userLoginId and the valid password (though we know nothing about it)

The only thing showing that we currently are impersonating a user is the little bottom-right image :

image::impersonate-ico.png[Impersonate icon, pdfwidth=0.5in, align=left]

This icon indicates, when clicking on it, the user impersonated, and offer a way to depersonate.

The impersonate period is stored for audit purpose, and if the impersonator forgot to depersonate, the period
is terminated _one hour_ after impersonation start.

[[impersonation_security]]
=== Security

This feature can draw some concerns about security aspect. This paragraph will introduce every controls and properties
that have been implemented around the impersonation feature.

[CAUTION]
These configuration steps are not to be neglected for a *production environment* since this feature offer a way to act
 in place of another user.

==== Properties

The _security.properties_ file introduce two properties that control impersonation feature :


[source]
security.disable.impersonation = true

This property, set by default to *true*, controls the activation of impersonation feature. If no configuration is done
any user trying to use impersonation will face an error message, indicating that the feature is disabled.

To enable impersonation this property need to be set to *false*


[source]
security.login.authorised.during.impersonate = false

This property controls the way impersonation occurred to the impersonated user :

In default configuration, the impersonated user see nothing and can use the application without knowing that he is
currently impersonated. Several authorized user can impersonate a same login without any issue.

[NOTE]
This configuration is intended for testing/QA environment allowing any authorized user to impersonate a login
to validate its configuration, test the application etc.

Set to *true*, this configuration improve the control of the data generated by the impersonated user. Indeed, Only one
authorized user can impersonate a login at the same time, and during the impersonation process, the impersonated user
is unable to act within the application.

Since the impersonation period is stored in database, the actions done by the
authorized user can be identified if there is the need to do so.
[NOTE]
This configuration is intended for production environment


==== Controls

The permission::

First, to be able to use impersonation, a user need to possess _IMPERSONATE_ADMIN_ permissions. Demo data offer
_IMPERSONATION_ security group for this purpose. +
In demo data, _FULLADMIN_ security group also possess the permission.


Permission based user restriction::

An authorized user cannot impersonate any user. There are two main controls that will restrict the impersonation feature.

Cannot impersonate Admin user:::

It is impossible to impersonate a user that is granted any of the admin permission :

            "IMPERSONATE_ADMIN"
            "ARTIFACT_INFO_VIEW"
            "SERVICE_MAINT"
            "ENTITY_MAINT"
            "UTIL_CACHE_VIEW"
            "UTIL_DEBUG_VIEW"

Cannot impersonate more privileged user:::

It is impossible to impersonate a user that has more permission than your user. Even if the missing persmission is
a minor one.


