概述

所有Keycloak控制台提供的功能，都能通过REST API来实现。要调用API，需要获得具有适当权限的访问令牌。访问令牌可以通过用户名/密码方式授权获取，也可以通过服务账号方式授权获取。

Keycloak提供的REST API列表可以在管网中查看，如下：https://www.keycloak.org/docs-api/16.0/rest-api/index.html#_users_resource

用户名密码授权

获取Token

cURL如下：

curl --location --request POST 'http://localhost:8180/auth/realms/master/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cookie: JSESSIONID=6FCFD67D3063CFE0A443BD7B161601A5.f64bbac2c4cd; JSESSIONID=68D613089536D5B8224A32DA64E0909A' \
--data-urlencode 'client_id=admin-cli' \
--data-urlencode 'username=admin' \
--data-urlencode 'password=admin' \
--data-urlencode 'grant_type=password'

注意：

这里使用的是默认的master realm，admin-cli是master realm中的默认client。默认生成的Token有效期只有60s，可以在client的Settings Tab页的Advanced Settings部分修改，如下：

调用服务

将获取的access_token抠出来，放入请求头中，调用REST API，如下

cURL如下：

curl --location --request GET 'http://localhost:8180/auth/admin/realms/SpringBoot/users' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI4Wm9XTzM0MUdNTXE5WGV2bFhCbTdTLUg4RDViOTQ4ZDA4cWxjdXhKV3k0In0.eyJleHAiOjE2NTExNTA5MzMsImlhdCI6MTY1MTE1MDMzMywianRpIjoiMDIxNTZkYzMtYzBhMi00MTVkLTk5MDMtMWU0NGM5ZDVjODkxIiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MTgwL2F1dGgvcmVhbG1zL21hc3RlciIsInN1YiI6IjA5Y2Q1ZDQ5LTA5MDctNDQ2Zi1hZWYxLWFiNDhiODJiNDYzNyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImFkbWluLWNsaSIsInNlc3Npb25fc3RhdGUiOiIwMjJiZmNkNy0wYWIwLTQwNjQtYTYwNC05OWU5ODNhZjA1ZjMiLCJhY3IiOiIxIiwic2NvcGUiOiJwcm9maWxlIGVtYWlsIiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhZG1pbiJ9.UGM5rtvWZdaSDOXPosYEmJSCtO2D1E_uo8Z6k5-pk57DK7_hgLk_CYzv4kw8gpc-Om8SZPx2f8T9ey9wqZ1fcxe2cilViGMjphuAOySBB8UnXOoeCvSAj9lT8Td2upVL3dolMJ7WmQgmvh1Et_rn0uYUDiuOKUzBYmYwfwFMajWkiHPxtmrXPMfvRom5wpaYzQJGdqBzho9WKmVjQpQ7P62CYnWIk-Vg31CTurPh-wUSb66d4XWvs3cJjpOhPaGox1y5YsJdPSJecK2cji49fhogjK888aXELJnMlJijKoQyi5ZF_L3Q3NIrF_72og8QxOJG1DOaSkSIilBTOWGuFQ' \
--header 'Cookie: JSESSIONID=6FCFD67D3063CFE0A443BD7B161601A5.f64bbac2c4cd; JSESSIONID=68D613089536D5B8224A32DA64E0909A'

服务账号授权

前提条件

在使用client_id和client_secret对Admin REST API进行身份验证之前，需要确保client配置满足如下条件:

• client必须创建在master realm中
• client的Access Type必须是confidential类型
• client必须已启用“Service Account”选项
• client具有一个自定义的“Audience” Mapper

• 包括 Client Audience: security-admin-console

• 确保client的"Service Account Roles" tab页中配置了admin角色

环境准备

我们这里配置一个满足条件的client。直接使用master中为自定义realm创建的client，如下：

这里使用SpringBoot-realm，已经是在master realm中了。查看其Access Type，如下：

Access Type必须选择confidential，并且打开Service Accounts Enabled选项。进入Mappers tab页，确保配置了“Audience” Mapper，如下：

如果没有，点右上角创建一个，如下：

进入"Service Account Roles" tab页，添加admin角色，如下：

获取Token

cURL如下：

curl --location --request POST 'http://localhost:8180/auth/realms/master/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cookie: JSESSIONID=6FCFD67D3063CFE0A443BD7B161601A5.f64bbac2c4cd; JSESSIONID=68D613089536D5B8224A32DA64E0909A' \
--data-urlencode 'client_id=SpringBoot-realm' \
--data-urlencode 'client_secret=bc22a5c9-5f7a-44f2-abb5-cff0deab037e' \
--data-urlencode 'grant_type=client_credentials'

此时grant_type是client_credentials，而不是password，这样就不会泄漏管理员的账号密码了

调用服务

同上

Java API

KeyCloak提供了Java SDK，方便调用REST API

依赖

<dependency>
  <groupId>org.keycloak</groupId>
  <artifactId>keycloak-admin-client</artifactId>
  <version>${keycloak.version}</version>
</dependency>

<dependency>
  <groupId>commons-logging</groupId>
  <artifactId>commons-logging</artifactId>
  <version>1.2</version>
</dependency>

主要是keycloak-admin-client这个依赖

单元测试

• 通过管理员账号密码调用

@Test
public void listUsers1() {
    Keycloak keycloak = Keycloak.getInstance(
            "http://localhost:8180/auth",
            "master",
            "admin",
            "admin",
            "admin-cli",
            "13777dab-59da-4781-bd6e-bad4813459b9"
    );

    List<UserRepresentation> users = keycloak.realm("SpringBoot")
            .users()
            .list();

    System.out.println(users);
    for (UserRepresentation user : users) {
        System.out.println(user.getUsername());
    }
}

注意，这里Keycloak.getInstance()方法中传入的realm参数是master realm，而不是我们创建的自定义realm；下面通过Keycloak实例访问资源时方法realm()中传入的才是创建的自定义realm

• 省略clientSecret参数

@Test
public void listUsers2() {
    Keycloak keycloak = Keycloak.getInstance(
            "http://localhost:8180/auth",
            "master",
            "admin",
            "admin",
            "admin-cli"
    );

    List<UserRepresentation> users = keycloak.realm("SpringBoot")
            .users()
            .list();

    System.out.println(users);
    for (UserRepresentation user : users) {
        System.out.println(user.getUsername());
    }
}

通过admin-cli也能省略clientSecret参数

• 通过token访问

也可以先过去到token，然后使用token访问rest api，如下：

@Test
    public void listUsers3() {
        Keycloak keycloak = Keycloak.getInstance(
                "http://localhost:8180/auth",
                "master",
                "SpringBoot-realm",
                "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI4Wm9XTzM0MUdNTXE5WGV2bFhCbTdTLUg4RDViOTQ4ZDA4cWxjdXhKV3k0In0.eyJleHAiOjE2NTExNTMwMzgsImlhdCI6MTY1MTE1MjQzOCwianRpIjoiZTE1YzM0OWItZDkwMS00YTNmLWIxMmItOGFhNjIzOTk3YTBkIiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MTgwL2F1dGgvcmVhbG1zL21hc3RlciIsImF1ZCI6WyJzZWN1cml0eS1hZG1pbi1jb25zb2xlIiwibWFzdGVyLXJlYWxtIiwiYWNjb3VudCJdLCJzdWIiOiI2MmU2YTBlNy1mMzI3LTRmMjktODMzYi1iMjM3MWYxYjhmMDgiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJTcHJpbmdCb290LXJlYWxtIiwic2Vzc2lvbl9zdGF0ZSI6IjY4MDgzOWZlLWNhNzYtNGMxNS05NGNiLTJhZDYxMmMwYTcxMyIsImFjciI6IjEiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiY3JlYXRlLXJlYWxtIiwib2ZmbGluZV9hY2Nlc3MiLCJhZG1pbiIsInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiU3ByaW5nQm9vdC1yZWFsbSI6eyJyb2xlcyI6WyJ2aWV3LXJlYWxtIiwidmlldy1pZGVudGl0eS1wcm92aWRlcnMiLCJtYW5hZ2UtaWRlbnRpdHktcHJvdmlkZXJzIiwiaW1wZXJzb25hdGlvbiIsImNyZWF0ZS1jbGllbnQiLCJtYW5hZ2UtdXNlcnMiLCJxdWVyeS1yZWFsbXMiLCJ2aWV3LWF1dGhvcml6YXRpb24iLCJxdWVyeS1jbGllbnRzIiwicXVlcnktdXNlcnMiLCJtYW5hZ2UtZXZlbnRzIiwibWFuYWdlLXJlYWxtIiwidmlldy1ldmVudHMiLCJ2aWV3LXVzZXJzIiwidmlldy1jbGllbnRzIiwibWFuYWdlLWF1dGhvcml6YXRpb24iLCJtYW5hZ2UtY2xpZW50cyIsInF1ZXJ5LWdyb3VwcyJdfSwibWFzdGVyLXJlYWxtIjp7InJvbGVzIjpbInZpZXctcmVhbG0iLCJ2aWV3LWlkZW50aXR5LXByb3ZpZGVycyIsIm1hbmFnZS1pZGVudGl0eS1wcm92aWRlcnMiLCJpbXBlcnNvbmF0aW9uIiwiY3JlYXRlLWNsaWVudCIsIm1hbmFnZS11c2VycyIsInF1ZXJ5LXJlYWxtcyIsInZpZXctYXV0aG9yaXphdGlvbiIsInF1ZXJ5LWNsaWVudHMiLCJxdWVyeS11c2VycyIsIm1hbmFnZS1ldmVudHMiLCJtYW5hZ2UtcmVhbG0iLCJ2aWV3LWV2ZW50cyIsInZpZXctdXNlcnMiLCJ2aWV3LWNsaWVudHMiLCJtYW5hZ2UtYXV0aG9yaXphdGlvbiIsIm1hbmFnZS1jbGllbnRzIiwicXVlcnktZ3JvdXBzIl19LCJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6InByb2ZpbGUgZW1haWwiLCJjbGllbnRJZCI6IlNwcmluZ0Jvb3QtcmVhbG0iLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsImNsaWVudEhvc3QiOiIxNzIuMjEuMC4xIiwicHJlZmVycmVkX3VzZXJuYW1lIjoic2VydmljZS1hY2NvdW50LXNwcmluZ2Jvb3QtcmVhbG0iLCJjbGllbnRBZGRyZXNzIjoiMTcyLjIxLjAuMSJ9.rrS3b6K0W6kvIc-MrIMd-Y3H7PWr732BTDIavLx0gqAfjZ_pr46o_IAuPbDzN8lwWEjiWXeWlAE6YvTiEve_X0o7ByrqhzcU1CSEsHbk_yOqNsJ58cSaEQ8yLoPvr4ME4bwYXGjUQfn4CjgwvKMlWZKbfTa4LUCIsZmW6_azxgx1t7-48w0_I0n_3JLbyQQKN-Ji0WzEpgJt5fK89zgU4uZGOLHOIRjAxBaG8DxiDlkramN94scZ9GYTh636mepFNc56BIG1xsWOUsaU_slexx7Wd6jUsr2T_jTsRjp5bRErLhHIw2cXZkb-RXMjTbhaQbIaQMiJkU-RZjRWEjgpNQ"
        );

        List<UserRepresentation> users = keycloak.realm("SpringBoot")
                .users()
                .list();

        System.out.println(users);
        for (UserRepresentation user : users) {
            System.out.println(user.getUsername());
        }
    }

源码

https://github.com/ywu2014/keycloak-demo/tree/master/keycloak-rest-api