libre.sh/keycloak-scim
2
0
Fork 0
Code Issues 14 Pull requests Releases Packages Activity Actions 6

KEYCLOAK-401 Service account docs

Browse source
This commit is contained in:
mposolda 2015-07-23 12:17:59 +02:00
parent d4946c1c08
commit b0cb457287
2 changed files with 58 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docbook/reference/en/en-US/master.xml
View file

@ -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;

56
docbook/reference/en/en-US/modules/service-accounts.xml Normal file
View file

@ -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>