通過管理API管理OAuth2 認(rèn)證授權(quán)服務(wù)器Keycloak
在使用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語(yǔ)言開發(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è)新用戶為例來使用它。
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必須看的文檔。
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)注。
往期推薦