Keycloak各种配置及API的使用

目录

1.创建client

 2.怎样拿到access token信息。

3.拿到用户role信息。

1.将role信息添加到userinfo

2.直接通过API获取role信息

4.Springboot集成Keycloak，SSO多个应用同时登出

5.Keycloak外部User数据源

Keycloak作为单点登录和用户管理的利器，相信很多小伙伴们希望对其功能有更多的了解，本文介绍在使用Keycloak的过程中，可能涉及到的配置以及常用的API。

1.创建client

如果想要在登录时跳转到keycloak的登录页面，那么Access Type 使用confidential方式，这也是实现SSO功能必须的。

怎样设置redirect_url呢？必须与应用程序的地址保持一致，协议，域名(或者IP)与端口都要一致，不然会出现各种各样的错误。

例如下面的错误，应用程序的地址为: http://localhost/，但是未在client中配置正确的redirect_url，会出现下面的错误。只要添加一个新的redirect_url  “http://localhost/*”，就能解决问题。

 2.怎样拿到access token信息。

2.1采用前端登录(例如angular应用)的情况

通过Keycloak登录后（配置了nginx反向代理，实际的keycloak地址是http://127.0.0.1:8082/auth），会重定向到应用程序，并且在cookie中存储一个code值。

从cookie中获取到code值之后，使用API获取access token https://127.0.0.1:8443/auth/realms/master/protocol/openid-connect/token

发送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" }

 在网站JSON Web Tokens – jwt.io中解析access token，发现能获取到realm role信息，以及资源访问权限 resource_access等信息。

2.2 使用keycloak API

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

这个POST请求的body负载如下，格式是 x-www-form-urlencoded: 

client_id:


username:


password:


grant_type:password

在Reponse中，我们能够获得access_token跟refresh_token。

access_token应该在每个对keycloak保护的资源的请求中使用，只需将它放在授权头中:

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

3.拿到用户role信息。

我们当然可以通过解析access token获取到role信息，但如果有的keycloak版本的access token中没有role信息，或者用户role信息在登录后有改变的情况下，我们应该使用其它的方式去重新获取role信息，现在有两种方式获取用户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' }

发送请求后，得到下面的信息，发现没有拿到role信息，只拿到了基本信息，用户名cctf_admin，email信息等等。

{"sub": "1b-2d7c-45ef-bdd5-4b9343b91f9b", "email_verified": false, "name": "bruce wang", "preferred_username": "cctf_admin", "given_name": "bruce", "family_name": "wang", "email": ""}

怎样才能拿到role信息呢？可以通过在client中配置”User Realm Role” Mapper的方式。

添加了Mapper之后，再次发送请求发现，可以拿到role信息，问题解决。

2.直接通过API获取role信息

如果用户没有添加”User Realm Role” Mapper，那么可以直接通过API来获取role信息。

首先也要先获取userinfo， 从中拿到”sub”的值”1b-2d7c-45ef-bdd5-4b9343b91f9b”。

{"sub": "1b-2d7c-45ef-bdd5-4b9343b91f9b", "email_verified": false, "name": "bruce wang", "preferred_username": "cctf_admin", "given_name": "bruce", "family_name": "wang", "email": ""}

然后调用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' }

发送请求之后，得到了403错误，没有权限，这个应该怎样解决？既然没有权限，那就加上权限，用户cctf_admin已经拥有了一个叫做ROLE_VIEWER的Realm Role，需要给这个Realm Role ROLE_VIEWER增加权限，起码要有一个叫做view-users的 Client Roles。

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

[“ROLE_VIEWER”, “offline_access”, “uma_authorization”]

4.Springboot集成Keycloak，SSO多个应用同时登出

使用springboot集成keycloak的时候，按照keycloak官方文档Securing Applications and Services Guide，我们需要在自己的springboot 应用中添加使用Spring Boot Adapter JAR，然后通过springboot的application.properties提供keycloak相关的配置。

如果使用SSO的方式打开了多个springboot应用，当其中一个应用登出后，那么其它应用是否应该同时被登出呢？大部分需求应该是要求同时登出的。

经过Nginx反向代理后，不能同时登出，这个时候怎么办呢？通过设置”Admin URL”，可以解决这个问题，使用其中任何一个springboot应用的地址，后面加上k_logout。

那么这是什么原理呢？

JBoss keycloak在client设置中提供了一个管理url(即上面的Admin URL)，用户可以通过这个属性进行设置，在登出推送事件或其他事件上做出反应，例如发生应用登出事件时，会触发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)结束，那么将会调用方法handleLogout()；如果以其它字段结束，将会进行其它的操作。

 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应用登出。

5.Keycloak外部User数据源

用户可以在keycloak中直接创建新的User，也可以使用外部已有的User数据，例如mysql，LDAP中存储的用户信息，下面给出一个配置LDAP的例子。

配置完成后，就可以使用LDAP中的用户信息进行登录了。