diff --git a/docbook/reference/en/en-US/master.xml b/docbook/reference/en/en-US/master.xml
index fe6ee0c..29a49a7 100755
--- a/docbook/reference/en/en-US/master.xml
+++ b/docbook/reference/en/en-US/master.xml
@@ -28,6 +28,7 @@
<!ENTITY Email SYSTEM "modules/email.xml">
<!ENTITY Roles SYSTEM "modules/roles.xml">
<!ENTITY DirectAccess SYSTEM "modules/direct-access.xml">
+ <!ENTITY ServiceAccounts SYSTEM "modules/service-accounts.xml">
<!ENTITY CORS SYSTEM "modules/cors.xml">
<!ENTITY Timeouts SYSTEM "modules/timeouts.xml">
<!ENTITY Events SYSTEM "modules/events.xml">
@@ -122,6 +123,7 @@ This one is short
&AccessTypes;
&Roles;
&DirectAccess;
+ &ServiceAccounts;
&CORS;
&Timeouts;
&AdminApi;
diff --git a/docbook/reference/en/en-US/modules/service-accounts.xml b/docbook/reference/en/en-US/modules/service-accounts.xml
new file mode 100644
index 0000000..e641988
--- /dev/null
+++ b/docbook/reference/en/en-US/modules/service-accounts.xml
@@ -0,0 +1,56 @@
+<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 clientId and clientSecret of the client in <literal>Authorization: Basic</literal> header.
+ Later we want to add more mechanisms for authenticating clients. 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>
\ No newline at end of file
