keycloak-scim/docbook/auth-server-docs/reference/en/en-US/modules/per-realm-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="per-realm-admin-permissions">
    <title>Per Realm Admin Access Control</title>
    <para>
        Administering your realm through the <literal>master</literal> realm as discussed in <xref linkend="admin-permissions" /> may not always be
        ideal or feasible.  For example, maybe you have more than one admin application that manages various admin aspects of your organization
        and you want to unify all these different "admin consoles" under one realm so you can do SSO between them.  Keycloak allows you to
        grant realm admin privileges to users within that realm.  These realm admins can participate in SSO for that realm and
        visit a keycloak admin console instance that is dedicated solely for that realm by going to the url:
        <literal>/{keycloak-root}/admin/{realm}/console</literal>
    </para>
    <section>
        <title>Realm Roles</title>
        <para>
            Each realm has a built-in application called <literal>realm-management</literal>.  This application defines
            roles that define permissions that can be granted to manage the realm.
            <itemizedlist>
                <listitem>
                    <literal>realm-admin</literal> - This is a composite role that grants all admin privileges for managing
                    security for that realm.
                </listitem>
            </itemizedlist>
            These are more fine-grain roles you can assign to the user.

            <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>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 realm you want. 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 <literal>realm-management</literal>, then assign any of the above roles to the user by selecting it and clicking on the right-arrow.
        </para>
    </section>
</chapter>