Keycloak

1
== Admin REST API
2

3
{project_name} comes with a fully functional Admin REST API with all features provided by the Admin Console.
4

5
To invoke the API you need to obtain an access token with the appropriate permissions. The required permissions are described in the link:{adminguide_link}[{adminguide_name}].
6

7
You can obtain a token by enabling authentication for your application using {project_name}; see the Securing Applications and Services Guide. You can also use direct access grant to obtain an access token.
8

9
=== Examples of using CURL
10

11
==== Authenticating with a username and password
12

13
NOTE: The following example assumes that you created the user `admin` with the password `password` in the `master` realm as shown in the link:{gettingstarted_link}[{gettingstarted_name}] tutorial.
14

15
.Procedure
16

17
. Obtain an access token for the user in the realm `master` with username `admin` and password `password`:
18
+
19
[source,bash,subs=+attributes]
20
----
21
curl \
22
  -d "client_id=admin-cli" \
23
  -d "username=admin" \
24
  -d "password=password" \
25
  -d "grant_type=password" \
26
  "http://localhost:8080{kc_realms_path}/master/protocol/openid-connect/token"
27
----
28
+
29
NOTE: By default this token expires in 1 minute
30
+
31
The result will be a JSON document.
32

33
. Invoke the API you need by extracting the value of the `access_token` property.
34

35
. Invoke the API by including the value in the `Authorization` header of requests to the API.
36
+
37
The following example shows how to get the details of the master realm:
38
+
39
[source,bash,subs="attributes+"]
40
----
41
curl \
42
  -H "Authorization: bearer eyJhbGciOiJSUz..." \
43
  "http://localhost:8080{kc_admins_path}/realms/master"
44
----
45

46
==== Authenticating with a service account
47

48
To authenticate against the Admin REST API using a `client_id` and a `client_secret`, perform this procedure.
49

50
.Procedure
51

52
. Make sure the client is configured as follows:
53

54
* `client_id` is a **confidential** client that belongs to the realm *master*
55
* `client_id` has `Service Accounts Enabled` option enabled
56
* `client_id` has a custom "Audience" mapper
57
  ** Included Client Audience: `security-admin-console`
58

59
. Check that `client_id` has the role 'admin' assigned in the "Service Account Roles" tab.
60

61
[source,bash,subs="attributes+"]
62
----
63
curl \
64
  -d "client_id=<YOUR_CLIENT_ID>" \
65
  -d "client_secret=<YOUR_CLIENT_SECRET>" \
66
  -d "grant_type=client_credentials" \
67
  "http://localhost:8080{kc_realms_path}/master/protocol/openid-connect/token"
68
----
69

70
ifeval::[{project_community}==true]
71
=== Example using Java
72

73
There's a Java client library for the Admin REST API that makes it easy to use from Java. To use it from your application add a dependency on the
74
`keycloak-admin-client` library.
75

76
The following example shows how to use the Java client library to get the details of the master realm:
77

78
[source,java,subs="attributes+"]
79
----
80

81
import org.keycloak.admin.client.Keycloak;
82
import org.keycloak.representations.idm.RealmRepresentation;
83
...
84

85
Keycloak keycloak = Keycloak.getInstance(
86
    "http://localhost:8080{kc_base_path}",
87
    "master",
88
    "admin",
89
    "password",
90
    "admin-cli");
91
RealmRepresentation realm = keycloak.realm("master").toRepresentation();
92
----
93

94
Complete Javadoc for the admin client is available at {apidocs_link}[{apidocs_name}].
95
endif::[]
96

97
=== Additional resources
98
[role="_additional-resources"]
99
* {adminguide_link}[{adminguide_name}]
100
* {adapterguide_link}[{adapterguide_name}]
101
* {apidocs_link}[{apidocs_name}]
102