75 lines
No EOL
3.6 KiB
XML
75 lines
No EOL
3.6 KiB
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> |