Keycloak各種配置及API的使用說明

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

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

1.創(chuàng)建client

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

怎樣設(shè)置redirect_url呢？

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

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

只要添加一個新的redirect_url "http://localhost/*"，就能解決問題。

2.怎樣拿到access token信息

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

通過Keycloak登錄后（配置了nginx反向代理，實際的keycloak地址是http://127.0.0.1:8082/auth），會重定向到應(yīng)用程序，并且在cookie中存儲一個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請求，其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信息，以及資源訪問權(quán)限 resource_access等信息。

2.2 使用keycloak API

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

首先，我們需要通過發(fā)送一個POST請求到這個URL來獲取Keycloak的access token:

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

這個POST請求的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)該在每個對keycloak保護的資源的請求中使用，只需將它放在授權(quán)頭中:

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

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

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

3.拿到用戶role信息

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

1.將role信息添加到userinfo

給用戶添加role信息，下圖中給用戶cctf_admin添加了 ROLE_VIEWER 這個Realm Role。

請求用戶信息userinfo的API(GET請求)：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ā)送請求后，得到下面的信息，發(fā)現(xiàn)沒有拿到role信息，只拿到了基本信息，用戶名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信息呢？可以通過在client中配置"User Realm Role" Mapper的方式。

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

2.直接通過API獲取role信息

如果用戶沒有添加"User Realm Role" Mapper，那么可以直接通過API來獲取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ā)送請求之后，得到了403錯誤，沒有權(quán)限，這個應(yīng)該怎樣解決？

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

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

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

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

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

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

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

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

那么這是什么原理呢？

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

參看代碼：

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;
    }

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

    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() 會將所有springboot應(yīng)用登出。