88 lines
3 KiB
Text
88 lines
3 KiB
Text
== Admin REST API
|
|
|
|
{project_name} comes with a fully functional Admin REST API with all features provided by the Admin Console.
|
|
|
|
To invoke the API you need to obtain an access token with the appropriate permissions. The required permissions are described in
|
|
{adminguide_link}[{adminguide_name}].
|
|
|
|
A token can be obtained by enabling authenticating to your application with {project_name}; see the
|
|
{adapterguide_link}[{adapterguide_name}]. You can also use direct access grant to obtain an access token.
|
|
|
|
For complete documentation see {apidocs_link}[{apidocs_name}].
|
|
|
|
=== Examples using CURL
|
|
|
|
==== Authenticate with username and password
|
|
|
|
Obtain access token for user in the realm `master` with username `admin` and password `password`:
|
|
[source,bash]
|
|
----
|
|
curl \
|
|
-d "client_id=admin-cli" \
|
|
-d "username=admin" \
|
|
-d "password=password" \
|
|
-d "grant_type=password" \
|
|
"http://localhost:8080/auth/realms/master/protocol/openid-connect/token"
|
|
----
|
|
|
|
NOTE: By default this token expires in 1 minute
|
|
|
|
The result will be a JSON document. To invoke the API you need to extract the value of the `access_token` property. You can then invoke the API by including
|
|
the value in the `Authorization` header of requests to the API.
|
|
|
|
The following example shows how to get the details of the master realm:
|
|
|
|
[source,bash]
|
|
----
|
|
curl \
|
|
-H "Authorization: bearer eyJhbGciOiJSUz..." \
|
|
"http://localhost:8080/auth/admin/realms/master"
|
|
----
|
|
|
|
==== Authenticate with a service account
|
|
|
|
Before being able to authenticate against the Admin REST API using a `client_id` and a `client_secret` you need to make sure the client is configured as it follows:
|
|
|
|
* `client_id` is a **confidential** client that belongs to the realm *master*
|
|
* `client_id` has `Service Accounts Enabled` option enabled
|
|
* `client_id` has a custom "Audience" mapper
|
|
** Included Client Audience: `security-admin-console`
|
|
|
|
Finally, check that `client_id` has the role 'admin' assigned in the "Service Account Roles" tab.
|
|
|
|
After that, you will be able to obtain an access token for the Admin REST API using `client_id` and `client_secret`:
|
|
|
|
[source,bash]
|
|
----
|
|
curl \
|
|
-d "client_id=<YOUR_CLIENT_ID>" \
|
|
-d "client_secret=<YOUR_CLIENT_SECRET>" \
|
|
-d "grant_type=client_credentials" \
|
|
"http://localhost:8080/auth/realms/master/protocol/openid-connect/token"
|
|
----
|
|
|
|
ifeval::[{project_community}==true]
|
|
=== Example using Java
|
|
|
|
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
|
|
`keycloak-admin-client` library.
|
|
|
|
The following example shows how to use the Java client library to get the details of the master realm:
|
|
|
|
[source,java]
|
|
----
|
|
import org.keycloak.admin.client.Keycloak;
|
|
import org.keycloak.representations.idm.RealmRepresentation;
|
|
...
|
|
|
|
Keycloak keycloak = Keycloak.getInstance(
|
|
"http://localhost:8080/auth",
|
|
"master",
|
|
"admin",
|
|
"password",
|
|
"admin-cli");
|
|
RealmRepresentation realm = keycloak.realm("master").toRepresentation();
|
|
----
|
|
|
|
Complete Javadoc for the admin client is available at {apidocs_link}[{apidocs_name}].
|
|
endif::[]
|