Keycloak各種配置及API的使用說(shuō)明

更新時(shí)間：2023年03月09日 10:21:12 作者：困知勉行1985

這篇文章主要介紹了Keycloak各種配置及API的使用說(shuō)明，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方，望不吝賜教

1.創(chuàng)建client

如果想要在登錄時(shí)跳轉(zhuǎn)到keycloak的登錄頁(yè)面，那么Access Type 使用confidential方式，這也是實(shí)現(xiàn)SSO功能必須的。

怎樣設(shè)置redirect_url呢？

必須與應(yīng)用程序的地址保持一致，協(xié)議，域名(或者IP)與端口都要一致，不然會(huì)出現(xiàn)各種各樣的錯(cuò)誤。

例如下面的錯(cuò)誤，應(yīng)用程序的地址為: http://localhost/，但是未在client中配置正確的redirect_url，會(huì)出現(xiàn)下面的錯(cuò)誤。

只要添加一個(gè)新的redirect_url "http://localhost/*"，就能解決問(wèn)題。

2.怎樣拿到access token信息

2.1采用前端登錄(例如angular應(yīng)用)的情況

通過(guò)Keycloak登錄后（配置了nginx反向代理，實(shí)際的keycloak地址是http://127.0.0.1:8082/auth），會(huì)重定向到應(yīng)用程序，并且在cookie中存儲(chǔ)一個(gè)code值（Oauth2的授權(quán)碼模式中的授權(quán)碼）。

從cookie中獲取到code值（授權(quán)碼）之后，使用API獲取access token https://127.0.0.1:8443/auth/realms/master/protocol/openid-connect/token

發(fā)送Post請(qǐng)求，其payload是：

得到的response：

{
"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJNS1FBX0VtX3JVNGhLOVhqMG9qU0pMckRDZ25RRjdRam9MZ2JMOXRjQTQ4In0.eyJqdGkiOiIwZmNlNzgwMC1iZjM3LTRiN2EtOTY3OC00ZWNjOTBmMWE1MjIiLCJleHAiOjE2MTAzNTMwOTYsIm5iZiI6MCwiaWF0IjoxNjEwMzQ5NDk2LCJpc3MiOiJodHRwczovLzEyNy4wLjAuMTo4NDQzL2F1dGgvcmVhbG1zL21hc3RlciIsImF1ZCI6ImFjY291bnQiLCJzdWIiOiIyY2ZhZjlhOS0yYzA5LTQ3MjktODdjMC00MGM4YmZjM2M0NWEiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJjY3RmLWZyb250ZW5kLWNsaWVudCIsIm5vbmNlIjoiN2ZkNmFjZjQtMDZjNC00MTcyLThlNWEtMDg4YTdmZjIwYzFjIiwiYXV0aF90aW1lIjoxNjEwMzQ5NDk2LCJzZXNzaW9uX3N0YXRlIjoiZDU5NDY5YWQtZWFhOC00NjA0LWE3NGYtYWZmN2UxMTE2MGQ1IiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6WyIqIl0sInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJvZmZsaW5lX2FjY2VzcyIsIlJPTEVfVklFV0VSIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6Im9wZW5pZCBwcm9maWxlIGVtYWlsIiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJjY3RmX2FkbWluIn0.RK7HGRFtUUEOQ23I0E3GXN06R1NsRMOg3gO7IDz-rijBnDfpdfYbf53lsxRpwEsvbhF4gWKWfeeD4gEQA8u_IirHR48ZaKzvmQHRZSMSb8NA4eeDZ9HM5Olwk5DL9SW0BLK9_XGeyYRrJdjlvNNLWYOKLZEs2hiyNYODo0mPIR4j6vZixc011PGxMN4M7xe2JFbSru0F64oN1wuburbSXj_Sn7v7Amv93jq6uzKNTidEb8AlPQIjBnYGoPZydWrVX-UEjMpvD5b64PBtbomOIlgTBTVCruE0LHbk_PDUpZsinhNdqMnB0TFxg-h1vREcZ-4ReVRoyFKAVtY__FPPGw",
"expires_in":3600,
"refresh_expires_in":1800,
"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI0MGUyNDRmMS05YzkxLTQyMjctOWJhNy1iOTY5ZDYxZWIyYWMifQ.eyJqdGkiOiIyODQzZjA5MS0zMmQ2LTRlMTItODQxNy1lN2NiNjY4NGYyNGEiLCJleHAiOjE2MTAzNTEyOTYsIm5iZiI6MCwiaWF0IjoxNjEwMzQ5NDk2LCJpc3MiOiJodHRwczovLzEyNy4wLjAuMTo4NDQzL2F1dGgvcmVhbG1zL21hc3RlciIsImF1ZCI6Imh0dHBzOi8vMTI3LjAuMC4xOjg0NDMvYXV0aC9yZWFsbXMvbWFzdGVyIiwic3ViIjoiMmNmYWY5YTktMmMwOS00NzI5LTg3YzAtNDBjOGJmYzNjNDVhIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImNjdGYtZnJvbnRlbmQtY2xpZW50Iiwibm9uY2UiOiI3ZmQ2YWNmNC0wNmM0LTQxNzItOGU1YS0wODhhN2ZmMjBjMWMiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJkNTk0NjlhZC1lYWE4LTQ2MDQtYTc0Zi1hZmY3ZTExMTYwZDUiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsib2ZmbGluZV9hY2Nlc3MiLCJST0xFX1ZJRVdFUiIsInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwic2NvcGUiOiJvcGVuaWQgcHJvZmlsZSBlbWFpbCJ9.qpoZB8OH-BFYBLhLZVde-NEYiOwUmHAT0d4xvBvYbWQ",
"token_type":"bearer",
"id_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJNS1FBX0VtX3JVNGhLOVhqMG9qU0pMckRDZ25RRjdRam9MZ2JMOXRjQTQ4In0.eyJqdGkiOiJhOWU3NTc5NS04NDQ4LTQ2OGYtYTA1Mi0xMmRiYTFkZTcyODIiLCJleHAiOjE2MTAzNTMwOTYsIm5iZiI6MCwiaWF0IjoxNjEwMzQ5NDk2LCJpc3MiOiJodHRwczovLzEyNy4wLjAuMTo4NDQzL2F1dGgvcmVhbG1zL21hc3RlciIsImF1ZCI6ImNjdGYtZnJvbnRlbmQtY2xpZW50Iiwic3ViIjoiMmNmYWY5YTktMmMwOS00NzI5LTg3YzAtNDBjOGJmYzNjNDVhIiwidHlwIjoiSUQiLCJhenAiOiJjY3RmLWZyb250ZW5kLWNsaWVudCIsIm5vbmNlIjoiN2ZkNmFjZjQtMDZjNC00MTcyLThlNWEtMDg4YTdmZjIwYzFjIiwiYXV0aF90aW1lIjoxNjEwMzQ5NDk2LCJzZXNzaW9uX3N0YXRlIjoiZDU5NDY5YWQtZWFhOC00NjA0LWE3NGYtYWZmN2UxMTE2MGQ1IiwiYWNyIjoiMSIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwicHJlZmVycmVkX3VzZXJuYW1lIjoiY2N0Zl9hZG1pbiJ9.hShn2KIz2zaFkyCnmAbxy7Y1pbVXYMENM1ly8v6WmGMXjoL7G5jBDbmaY060Rlv2RMPu5WHAIuDYyCZGJzLAKPAOKd8ChwaFtMnmPjpRYw987zi3g7NiOWqJOlcZjEoMxODqfS0WwfNG8p4TgX9ILgjvfJpD5Mce_psX_44gULqX5DXUeijjredNyOrFRZp_2MFE7LYtuarJKeyKa8dQ1MUFAqUpZXFKMBvI09wsSIbB0w9ANxDB6pxunOLzijTlexsTJoF_Js5oOBilGSCnbG3s_QfLcfCw01GRo093OnaATpUq08lmlZ-zj3V_3DpVRaGmBLxhZUlv0dYHzlmzMQ",
"not-before-policy":0,
"session_state":"d59469ad-eaa8-4604-a74f-aff7e11160d5",
"scope":"openid profile email"
}

在網(wǎng)站JSON Web Tokens - jwt.io中解析access token，發(fā)現(xiàn)能獲取到realm role信息，以及資源訪問(wèn)權(quán)限 resource_access等信息。

2.2 使用keycloak API

Keycloak提供了一個(gè)用于生成和刷新access token的REST API。

首先，我們需要通過(guò)發(fā)送一個(gè)POST請(qǐng)求到這個(gè)URL來(lái)獲取Keycloak的access token:

http://localhost:8082/auth/realms/SpringBootKeycloak/protocol/openid-connect/token

這個(gè)POST請(qǐng)求的body負(fù)載如下，格式是 x-www-form-urlencoded:

client_id:<your_client_id>
username:<your_username>
password:<your_password>
grant_type:password

在Reponse中，我們能夠獲得access_token跟refresh_token。

access_token應(yīng)該在每個(gè)對(duì)keycloak保護(hù)的資源的請(qǐng)求中使用，只需將它放在授權(quán)頭中:

headers: {
??? 'Authorization': 'Bearer' + access_token
}

一旦access_token過(guò)期，那么我們可以使用refresh_token去刷新它，得到一個(gè)新的有效的access_token，也是使用上面的API，不過(guò)body信息要使用refresh_token.

{
??? 'client_id': 'your_client_id',
??? 'refresh_token': refresh_token_from_previous_request,
??? 'grant_type': 'refresh_token'
}

3.拿到用戶(hù)role信息

我們當(dāng)然可以通過(guò)解析access token獲取到role信息，但如果有的keycloak版本的access token中沒(méi)有role信息，或者用戶(hù)role信息在登錄后有改變的情況下，我們應(yīng)該使用其它的方式去重新獲取role信息，現(xiàn)在有兩種方式獲取用戶(hù)role信息。

1.將role信息添加到userinfo

給用戶(hù)添加role信息，下圖中給用戶(hù)cctf_admin添加了 ROLE_VIEWER 這個(gè)Realm Role。

請(qǐng)求用戶(hù)信息userinfo的API(GET請(qǐng)求)：http://{server}/auth/realms/{realm}/protocol/openid-connect/userinfo (例如 http://localhost:8082/auth/realms/master/protocol/openid-connect/userinfo)

將access token添加到header中。

headers={
    'Authorization': 'Bearer ' + accessToken,
    'Content-Type': 'application/json'
}

發(fā)送請(qǐng)求后，得到下面的信息，發(fā)現(xiàn)沒(méi)有拿到role信息，只拿到了基本信息，用戶(hù)名cctf_admin，email信息等等。

{"sub": "1b535469-2d7c-45ef-bdd5-4b9343b91f9b", "email_verified": false, "name": "bruce wang", "preferred_username": "cctf_admin", "given_name": "bruce", "family_name": "wang", "email": "4xxxxxxxx@qq.com"}

怎樣才能拿到role信息呢？可以通過(guò)在client中配置"User Realm Role" Mapper的方式。

添加了Mapper之后，再次發(fā)送請(qǐng)求發(fā)現(xiàn)，可以拿到role信息，問(wèn)題解決。

2.直接通過(guò)API獲取role信息

如果用戶(hù)沒(méi)有添加"User Realm Role" Mapper，那么可以直接通過(guò)API來(lái)獲取role信息。

首先也要先獲取userinfo，從中拿到"sub"的值"1b535469-2d7c-45ef-bdd5-4b9343b91f9b"。

{"sub": "1b535469-2d7c-45ef-bdd5-4b9343b91f9b", "email_verified": false, "name": "bruce wang", "preferred_username": "cctf_admin", "given_name": "bruce", "family_name": "wang", "email": "4xxxxxxxx@qq.com"}

然后調(diào)用role API http://{server}/auth/admin/realms/{realm}/users/{user-uuid}/role-mappings/realm，其中的{user-uuid}是上面拿到的"sub"值。

同樣需要在header中加入access token。

headers={
	'Authorization': 'Bearer ' + accessToken,
	'Content-Type': 'application/json'
}

發(fā)送請(qǐng)求之后，得到了403錯(cuò)誤，沒(méi)有權(quán)限，這個(gè)應(yīng)該怎樣解決？

既然沒(méi)有權(quán)限，那就加上權(quán)限，用戶(hù)cctf_admin已經(jīng)擁有了一個(gè)叫做ROLE_VIEWER的Realm Role，需要給這個(gè)Realm Role ROLE_VIEWER增加權(quán)限，起碼要有一個(gè)叫做view-users的 Client Roles。

加入client role之后，可以得到role信息。

["ROLE_VIEWER", "offline_access", "uma_authorization"]

4.Springboot集成Keycloak，SSO多個(gè)應(yīng)用同時(shí)登出

使用springboot集成keycloak的時(shí)候，按照keycloak官方文檔Securing Applications and Services Guide，我們需要在自己的springboot 應(yīng)用中添加使用Spring Boot Adapter JAR，然后通過(guò)springboot的application.properties提供keycloak相關(guān)的配置。

如果使用SSO的方式打開(kāi)了多個(gè)springboot應(yīng)用，當(dāng)其中一個(gè)應(yīng)用登出后，那么其它應(yīng)用是否應(yīng)該同時(shí)被登出呢？大部分需求應(yīng)該是要求同時(shí)登出的。

經(jīng)過(guò)Nginx反向代理后，不能同時(shí)登出，這個(gè)時(shí)候怎么辦呢？

通過(guò)設(shè)置"Admin URL"，可以解決這個(gè)問(wèn)題，使用其中任何一個(gè)springboot應(yīng)用的地址，后面加上k_logout。

那么這是什么原理呢？

JBoss keycloak在client設(shè)置中提供了一個(gè)管理url(即上面的Admin URL)，用戶(hù)可以通過(guò)這個(gè)屬性進(jìn)行設(shè)置，在登出推送事件或其他事件上做出反應(yīng)，例如發(fā)生應(yīng)用登出事件時(shí)，會(huì)觸發(fā)Admin URL中配置的請(qǐng)求，Keycloak會(huì)對(duì)這個(gè)請(qǐng)求進(jìn)行處理

參看代碼：

https://github.com/keycloak/keycloak/blob/master/adapters/oidc/adapter-core/src/main/java/org/keycloak/adapters/PreAuthActionsHandler.java

    public boolean handleRequest() {
        String requestUri = facade.getRequest().getURI();
        log.debugv("adminRequest {0}", requestUri);
        if (preflightCors()) {
            return true;
        }
        if (requestUri.endsWith(AdapterConstants.K_LOGOUT)) {
            if (!resolveDeployment()) return true;
            handleLogout();
            return true;
        } else if (requestUri.endsWith(AdapterConstants.K_PUSH_NOT_BEFORE)) {
            if (!resolveDeployment()) return true;
            handlePushNotBefore();
            return true;
        } else if (requestUri.endsWith(AdapterConstants.K_TEST_AVAILABLE)) {
            if (!resolveDeployment()) return true;
            handleTestAvailable();
            return true;
        } else if (requestUri.endsWith(AdapterConstants.K_JWKS)) {
            if (!resolveDeployment()) return true;
            handleJwksRequest();
            return true;
        }
        return false;
    }

可以看到如果請(qǐng)求的URI 如果以AdapterConstants.K_LOGOUT(即k_logout)結(jié)束，那么將會(huì)調(diào)用方法handleLogout()；如果以其它字段結(jié)束，將會(huì)進(jìn)行其它的操作。

    protected void handleLogout()  {
        if (log.isTraceEnabled()) {
            log.trace("K_LOGOUT sent");
        }
        try {
            JWSInput token = verifyAdminRequest();
            if (token == null) {
                return;
            }
            LogoutAction action = JsonSerialization.readValue(token.getContent(), LogoutAction.class);
            if (!validateAction(action)) return;
            if (action.getAdapterSessionIds() != null) {
                userSessionManagement.logoutHttpSessions(action.getAdapterSessionIds());
            } else {
                log.debugf("logout of all sessions for application '%s'", action.getResource());
                if (action.getNotBefore() > deployment.getNotBefore()) {
                    deployment.updateNotBefore(action.getNotBefore());
                }
                userSessionManagement.logoutAll();
            }
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

其中的userSessionManagement.logoutAll() 會(huì)將所有springboot應(yīng)用登出。