Keycloak各种配置及API的使用说明

2023-03-09 18:03:56 keycloak 配置 使用说明

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值（Oauth2的授权码模式中的授权码）。

从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

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

首先，我们需要通过发送一个POST请求到这个URL来获取Keycloak的access token:

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

这个POST请求的body负载如下，格式是 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应该在每个对keycloak保护的资源的请求中使用，只需将它放在授权头中:

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信息

我们当然可以通过解析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": "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之后，再次发送请求发现，可以拿到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"}

然后调用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中的用户信息进行登录了。

总结

以上为个人经验，希望能给大家一个参考，也希望大家多多支持。

相关文章