Skip to content
Snippets Groups Projects

Add documentation on enabling admin mode

Merged Jon Glassman requested to merge enable-admin-mode into master
All threads resolved!
@@ -28,47 +28,79 @@ You can restrict the password authentication for web interface and Git over HTTP
In the event of an external authentication provider outage, use the [GitLab Rails console](../../../administration/operations/rails_console.md) to [re-enable the standard web sign-in form](#re-enable-standard-web-sign-in-form-in-rails-console). This configuration can also be changed over the [Application settings REST API](../../../api/settings.md#change-application-settings) while authenticating with an administrator account's personal access token.
## Admin Mode
## Admin mode
> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2158) in GitLab 13.10.
When this feature is enabled, instance administrators are limited as regular users. During that period,
they do not have access to all projects, groups, or the **Admin Area** menu.
In admin mode, instance administrators are limited as regular users,
and do not have access to all projects, groups, or the **Admin Area** menu.
To access potentially dangerous resources, an administrator can activate Admin Mode by:
- Selecting the *Enable Admin Mode* button
- Trying to access any part of the UI that requires administrator access, specifically those which call `/admin` endpoints.
The main use case allows administrators to perform their regular tasks as a regular
In this mode, administrators can perform regular tasks as a regular
user, based on their memberships, without having to set up a second account for
security reasons.
When Admin Mode status is disabled, administrative users cannot access resources unless
they've been explicitly granted access. For example, when Admin Mode is disabled, they
get a `404` error if they try to open a private group or project, unless
they are members of that group or project.
### Enable admin mode
Administrators can enable admin mode though the API, the Rails console, or the UI.
#### Use the API to enable admin mode
Make the following request to your instance endpoint:
```shell
curl --request PUT --header "PRIVATE-TOKEN:$ADMIN_TOKEN" "<gitlab-url>/api/v4/application/settings?admin_mode=true"
```
Replace the `<gitlab-url>` with your instance URL.
#### Use the Rails console to enable admin mode
Open the [Rails console](../../../administration/operations/rails_console.md) and run the following:
```ruby
::Gitlab::CurrentSettings.update_attributes!(admin_mode: true)
```
#### Use the UI to enable admin mode
To enable admin mode through the UI:
1. On the top bar, select **Main menu > Admin**.
1. On the left sidebar, select **Settings > General**.
1. Expand **Sign-in restrictions**.
1. In the **Admin Mode** section, select the **Require additional authentication for administrative tasks** checkbox.
### Activate admin mode
To activate admin mode and access potentially dangerous resources, an administrator:
1. On the top bar, selects **Enable Admin Mode**.
1. Tries to access any part of the UI that calls `/admin` endpoints, and so requires administrator access.
When admin mode status is disabled or deactivated, administrators cannot access resources unless
they've been explicitly granted access. For example, administrators get a `404` error
if they try to open a private group or project, unless they are members of that group or project.
2FA should be enabled for administrators and is supported for the Admin Mode flow, as are
OmniAuth providers and LDAP auth. The Admin Mode status is stored in the active user
session and remains active until it is explicitly disabled (it will be disabled
automatically after a timeout otherwise).
2FA should be enabled for administrators. 2FA, OmniAuth providers, and LDAP
authentication are supported for the admin mode flow. Admin mode status is
stored in the active user session and remains active until it is explicitly disabled,
or is disabled automatically after a timeout.
### Limitations of Admin Mode
### Limitations of admin mode
The following access methods are **not** protected by Admin Mode:
The following access methods are **not** protected by admin mode:
- Git client access (SSH using public keys or HTTPS using Personal Access Tokens).
- API access using a Personal Access Token.
In other words, administrators who are otherwise limited by Admin Mode can still use
In other words, administrators who are otherwise limited by admin mode can still use
Git clients, and access RESTful API endpoints as administrators, without additional
authentication steps.
We may address these limitations in the future. For more information see the following epic:
[Admin Mode for GitLab Administrators](https://gitlab.com/groups/gitlab-org/-/epics/2158).
### Troubleshooting Admin Mode
### Troubleshooting admin mode
If necessary, you can disable **Admin Mode** as an administrator by using one of these two methods:
Loading