keycloak-scim/docbook/auth-server-docs/reference/en/en-US/modules/service-accounts.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="service-accounts">
    <title>Service Accounts</title>
    <para>
        Keycloak allows you to obtain an access token dedicated to some Client Application (not to any user).
        See <ulink url="http://tools.ietf.org/html/rfc6749#section-4.4">Client Credentials Grant</ulink>
        from OAuth 2.0 spec.
    </para>
    <para>
        To use it you must have
        registered a valid confidential Client and you need to check the switch <literal>Service Accounts Enabled</literal> in Keycloak
        admin console for this client. In tab <literal>Service Account Roles</literal> you can configure the roles available to the service account retrieved on behalf of this client.
        Don't forget that you need those roles to be available in Scopes of this client as well (unless you have <literal>Full Scope Allowed</literal> on).
        As in normal login, roles from access token are intersection of scopes and the service account roles.
    </para>

    <para>
        The REST URL to invoke on is <literal>/{keycloak-root}/realms/{realm-name}/protocol/openid-connect/token</literal>.
        Invoking on this URL is a POST request and requires you to post the client credentials. By default, client credentials are
        represented by clientId and clientSecret of the client in <literal>Authorization: Basic</literal> header, but you can also
        authenticate client with signed JWT assertion or any other custom mechanism for client authentication. See
        <link linkend="client_authentication">Client Authentication</link> section for more details. You also need to use parameter <literal>grant_type=client_credentials</literal> as per OAuth2 specification.
    </para>
    <para>
        For example the POST invocation to retrieve service account can look like this:
        <programlisting><![CDATA[
    POST /auth/realms/demo/protocol/openid-connect/token
    Authorization: Basic cHJvZHVjdC1zYS1jbGllbnQ6cGFzc3dvcmQ=
    Content-Type: application/x-www-form-urlencoded

    grant_type=client_credentials]]>
        </programlisting>
        The response would be this <ulink url="http://tools.ietf.org/html/rfc6749#section-4.4.3">standard JSON document</ulink> from the OAuth 2.0 specification.
        <programlisting><![CDATA[
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"bearer",
    "expires_in":60,
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
    "refresh_expires_in":600,
    "id_token":"tGzv3JOkF0XG5Qx2TlKWIA",
    "not-before-policy":0,
    "session_state":"234234-234234-234234"
}]]>
        </programlisting>
    </para>
    <para>
        The retrieved access token can be refreshed or logged out by out-of-bound request.
    </para>
    <para>
        See the example application <literal>service-account</literal>
        from the main Keycloak <literal>demo</literal> example.
    </para>
</chapter>