keycloak-scim/docbook/auth-server-docs/reference/en/en-US/modules/admin-permissions.xml

<!--
  ~ Copyright 2016 Red Hat, Inc. and/or its affiliates
  ~ and other contributors as indicated by the @author tags.
  ~
  ~ Licensed 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.
  -->

<chapter id="admin-permissions">
    <title>Master Admin Access Control</title>
    <para>
        You can create and manage multiple realms by logging into the <literal>master</literal> Keycloak admin console
        at <literal>/{keycloak-root}/admin/index.html</literal>
    </para>
    <para>
        Users in the Keycloak <literal>master</literal> realm can be granted permission to manage zero or more realms that are
        deployed on the Keycloak server.  When a realm is created, Keycloak automatically creates various roles that grant fine-grain
        permissions to access that new realm.
        Access to The Admin Console and REST endpoints can be controlled by mapping these roles to users in the <literal>master</literal> realm.
        It's possible to create multiple super users as well as users that have only access to certain operations in specific realms.
    </para>
    <section>
        <title>Global Roles</title>
        <para>
            There are two realm roles in the <literal>master</literal> realm. These are:
            <itemizedlist>
                <listitem>
                    <literal>admin</literal> - This is the super-user role and grants permissions to all operations on all realms
                </listitem>
                <listitem>
                    <literal>create-realm</literal> - This grants the user permission to create new realms. A user that creates a realm is granted all permissions to the newly created realm.
                </listitem>
            </itemizedlist>
        </para>
        <para>
            To add these roles to a user select the <literal>master</literal> realm, then click on <literal>Users</literal>.
            Find the user you want to grant permissions to, open the user and click on <literal>Role Mappings</literal>. Under
            <literal>Realm Roles</literal> assign any of the above roles to the user by selecting it and clicking on the right-arrow.
        </para>
    </section>

    <section>
        <title>Realm Specific Roles</title>
        <para>
            Each realm in Keycloak is represented by an application in the <literal>master</literal> realm. The name of the application
            is <literal>&lt;realm name&gt;-realm</literal>. This allows assigning access to users for individual realms. The
            roles available are:
            <itemizedlist>
                <listitem>
                    <literal>view-realm</literal> - View the realm configuration
                </listitem>
                <listitem>
                    <literal>view-users</literal> - View users (including details for specific user) in the realm
                </listitem>
                <listitem>
                    <literal>view-applications</literal> - View applications in the realm
                </listitem>
                <listitem>
                    <literal>view-clients</literal> - View clients in the realm
                </listitem>
                <listitem>
                    <literal>view-events</literal> - View events in the realm
                </listitem>

                <listitem>
                    <literal>manage-realm</literal> - Modify the realm configuration (and delete the realm)
                </listitem>
                <listitem>
                    <literal>manage-users</literal> - Create, modify and delete users in the realm
                </listitem>
                <listitem>
                    <literal>manage-applications</literal> - Create, modify and delete applications in the realm
                </listitem>
                <listitem>
                    <literal>create-clients</literal> - Create clients in the realm
                </listitem>
                <listitem>
                    <literal>manage-clients</literal> - Create, modify and delete clients in the realm
                </listitem>
                <listitem>
                    <literal>manage-events</literal> - Enable/disable events, clear logged events and manage event listeners
                </listitem>
            </itemizedlist>
            Manage roles includes permissions to view (for example a user with manage-realm role can also view the realm configuration).
        </para>
        <para>
            To add these roles to a user select the <literal>master</literal> realm, then click on <literal>Users</literal>.
            Find the user you want to grant permissions to, open the user and click on <literal>Role Mappings</literal>. Under
            <literal>Application Roles</literal> select the application that represents the realm you're adding permissions to
            (<literal>&lt;realm name&gt;-realm</literal>), then assign any of the above roles to the user by selecting it and clicking on the right-arrow.
        </para>
    </section>
</chapter>