在使用Keycloak的時(shí)候可能有同學(xué)都注意到用戶的管理都是通過Keycloak提供的UI來進(jìn)行的，雖然很方便但是很多時(shí)候并不適合在開發(fā)中使用。比如注冊(cè)總不能讓終端用戶直接去Keycloak的管理控制臺(tái)（Admin Console）操作吧。所以需要將這些功能API化才行，今天來分享一個(gè)通過編程對(duì)Keycloak進(jìn)行操作的方法。

系列博文可通過點(diǎn)擊#keycloak查看。

Keycloak Admin Client簡(jiǎn)介

我們?cè)贙eycloak Admin Console中的所有操作都有特定的Restful API，被統(tǒng)稱為Keycloak Admin REST API。而 Keycloak Admin Client正是對(duì)Keycloak Admin REST API的Java HTTP客戶端封裝。我們只需要引入下面的依賴就可以集成了：

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

這里簡(jiǎn)單提一下，其底層用的是JBoss的Rest Web Service客戶端Resteasy。JBoss RESTEasy 是一個(gè)用來使用Java語言開發(fā) RESTFul Web服務(wù)的框架。它是 JAX-RS（Java API for RESTful Web Services） 的一個(gè)實(shí)現(xiàn)，它的一些亮點(diǎn)：

• 不需要配置文件，基于注解和Java POJO就可以實(shí)現(xiàn)RESTful客戶端。
• 基于JBoss Seam（Java EE的上層強(qiáng)化）編程模型。

這些只作為擴(kuò)展知識(shí)，除非你深入定制，否則不需要學(xué)習(xí)它，因?yàn)?nbsp;Keycloak Admin Client已經(jīng)屏蔽了其陡峭的學(xué)習(xí)成本，接下來讓我們開始使用它。

Keycloak Admin Client的使用

Keycloak Admin REST API都需要在請(qǐng)求中放置一個(gè)Bearer Token的Authorization請(qǐng)求頭。根據(jù)Token中攜帶的權(quán)限信息來獲取對(duì)應(yīng)API的訪問權(quán)限。所以我們?cè)谑褂?code style="font-size: 14px;font-family: "Operator Mono", Consolas, Monaco, Menlo, monospace;padding: 2px 4px;border-radius: 4px;margin-right: 2px;margin-left: 2px;color: rgb(53, 179, 120);background-color: rgba(27, 31, 35, 0.05);word-break: break-all;">Keycloak Admin Client時(shí)要特別注意當(dāng)前你使用的客戶端是否有權(quán)限訪問。接下來的例子就拿注冊(cè)新用戶為例來使用它。

使用Admin賬戶創(chuàng)建新用戶

Master Realm中的Admin管理員擁有管理Keycloak的最高權(quán)限，使用它幾乎可以在Keycloak中“為所欲為”。

根據(jù)我們的配置聲明一個(gè)Keyclock實(shí)例：

Keycloak adminCli = KeycloakBuilder.builder()
                 // 服務(wù)器地址
                .serverUrl("http://localhost:8011/auth/")
                 // master領(lǐng)域
                .realm("master")
                 // 客戶端為 admin-cli  
                .clientId("admin-cli")
                 // 需要我們?cè)谠摽蛻舳讼律擅荑€
                .clientSecret("f7da6497-98ee-455a-87ba-158793134e56")
                 // 管理員賬戶
                .username("admin")
                // 管理員密碼 
                .password("admin")
                // 授權(quán)方式是密碼授權(quán) 
                .grantType(OAuth2Constants.PASSWORD)
                .build();

這里授權(quán)方式為密碼授權(quán)，要求必須在客戶端的Setting選項(xiàng)下打開Direct Access Grants Enabled，這意味著admin-cli客戶端能夠訪問用戶的用戶名和密碼，并以此從Keycloak服務(wù)器獲取訪問令牌，繼而能夠進(jìn)行進(jìn)一步的訪問授權(quán)操作。

?

那么如何注冊(cè)新用戶呢？

我們可以這樣實(shí)現(xiàn)：

 UserRepresentation user = new UserRepresentation();
        user.setUsername("apicreated");
        user.setEnabled(true);

        CredentialRepresentation credentialRepresentation = new CredentialRepresentation();
        credentialRepresentation.setTemporary(false);
        credentialRepresentation.setType(CredentialRepresentation.PASSWORD);
        credentialRepresentation.setValue("123456");

        user.setCredentials(Collections.singletonList(credentialRepresentation));

        RealmResource realm = adminCli.realm("master");

        UsersResource users = realm.users();

        Response response = users.create(user);
        System.out.println("response = " + response.readEntity(String.class));

這里的UserRepresentation就是用戶對(duì)象，我們定義了一個(gè)用戶名為apicreated、非臨時(shí)密碼為123456的用戶并注冊(cè)到Master Realm中。

?

我是怎么知道這些API的呢？

官方給了一個(gè)Admin API的說明文檔，地址為：

https://www.keycloak.org/docs-api/15.0/rest-api/index.html

這是使用Keycloak Admin REST API必須看的文檔。

使用Realm管理用戶創(chuàng)建新用戶

Master Realm的管理員賬戶不屑于干這些“低級(jí)”的操作，這種事一般會(huì)交給“小弟”去做。為了在felord.cn這個(gè)Realm創(chuàng)建用戶，你可以給一個(gè)Master Realm的用戶賦予一個(gè)創(chuàng)建felord.cn用戶的角色manager-users:

創(chuàng)建一個(gè)管理給特定的Realm用戶

?

紅框中還有很多角色需要你去了解。

利用Master賬戶給felord.cn創(chuàng)建用戶應(yīng)該這么寫：

        Keycloak adminCli = KeycloakBuilder.builder()
                .serverUrl("http://localhost:8011/auth/")
                .realm("master")
                .clientId("admin-cli")
                .clientSecret("86ef2225-14d4-49b1-908e-2b5e058030cc")
                .username("felordadmin")
                .password("123456")
                .grantType(OAuth2Constants.PASSWORD)
                .build();
        // 創(chuàng)建用戶        
        UserRepresentation user = new UserRepresentation();
        user.setUsername("apicreated2");
        user.setEnabled(true);

        CredentialRepresentation credentialRepresentation = new CredentialRepresentation();
        credentialRepresentation.setTemporary(false);
        credentialRepresentation.setType(CredentialRepresentation.PASSWORD);
        credentialRepresentation.setValue("123456");

        user.setCredentials(Collections.singletonList(credentialRepresentation));

        RealmResource realm = adminCli.realm("felord.cn");

        UsersResource users = realm.users();
 
        Response response = users.create(user);

利用服務(wù)賬戶創(chuàng)建用戶

每個(gè)Realm都有一個(gè)叫realm-management的管理客戶端，這個(gè)客戶端的作用就是用來管理當(dāng)前的Realm。按照下面的配置你可以開啟realm-management的服務(wù)賬戶功能。

開啟服務(wù)賬戶功能

這樣我們可以直接向Keycloak服務(wù)器獲取realm-management的訪問憑據(jù)，因?yàn)?code style="font-size: 14px;font-family: "Operator Mono", Consolas, Monaco, Menlo, monospace;padding: 2px 4px;border-radius: 4px;margin-right: 2px;margin-left: 2px;color: rgb(53, 179, 120);background-color: rgba(27, 31, 35, 0.05);word-break: break-all;">realm-management有全部的管理功能，所以我們可以以客戶端的名義而非管理用戶的名義創(chuàng)建新用戶了，而且不局限于創(chuàng)建用戶。

Keycloak的實(shí)例化代碼就跟之前不大一樣了：

Keycloak adminCli = KeycloakBuilder.builder()
        .serverUrl("http://localhost:8011/auth/")
        .realm("felord.cn")
        .clientId("realm-management")
        .clientSecret("38836e47-2c82-4412-a858-9be2a35aa366")
        .grantType(OAuth2Constants.CLIENT_CREDENTIALS)
        .build();

?

這里的授權(quán)模式區(qū)別于用戶行為，它屬于客戶端行為，因此grant_type改成了客戶端模式。

總結(jié)

創(chuàng)建用戶和前面兩種方法相同，你可以創(chuàng)建一個(gè)用戶試試，還有其它的API都可以用這種方式實(shí)現(xiàn)。今天介紹了如何調(diào)用Keycloak Admin REST API，它可以實(shí)現(xiàn)在代碼中對(duì)Keycloak進(jìn)行一些管理操作。需要注意的是，這些操作和當(dāng)前操作主體的角色息息相關(guān)。后面會(huì)有篇幅來對(duì)Keycloak中的管理角色進(jìn)行一個(gè)簡(jiǎn)單的介紹，希望對(duì)Keycloak有興趣的同學(xué)多多關(guān)注。