一步步学习Keycloak(基础篇)

介绍

最近在研究如何使用KeyCloak来对系统进行认证和授权，相比其他开源的身份认证和授权系统，比如Justauth，我觉得KeyCloak有几个优点。第一是功能十分强大，基本上覆盖了认证和授权的各方面，能够提供SSO,可以支持不同的认证授权方式，OpenID,SAML,也支持不同的服务提供商，比如Google，Facebook，Github等。第二是提供了非常全面的技术文档，包括简单实例，认证，授权，部署以及API文档，而且分类清晰。第三是提供了易用的界面管理，能方便快速的进行用户，组，角色，资源，权限等的配置。唯一的缺点是文档过于偏技术和概念，实例太少，读起来比较晦涩难懂。另外，网上普遍的反应是KeyCloak比较重，可能是大部分应用场景可能只需要其中某一个功能，因此会显得很多功能多余。但作为一个身份认证框架，需要考虑各种认证场景和集成方式。KeyCloak虽然文档很全面，但是要完全理解里面的概念及功能，还是需要花很多的时间去理解和学习，大部分网上的实例都比较简单，基本都是在重复KeyCloak里面的Getting Started Guide里的三个例子。我将通过一个非常通用的实例来介绍如何通过KeyCloak来进行认证和授权，这个实例中会涉及到各种资源的认证授权方式，以及如何在KeyCloak里进行配置。第二，KeyCloak已经提供了各种KeyCloak Adapter，包括SpringBoot，SpringBoot Security，Tomcat，Jetty以及J2EE，但是缺少对Nginx的支持，Nginx作为当前最为流行的反向代理工具，应用十分广泛，而且很多比较流行的API Gateway底层也能见到它的身影，因此对Nginx的支持十分有必要。因此我将介绍如何在Nginx中实现对KeyCloak的集成，作为Nginx KeyCloak Adapter。第三，在介绍这个实例的过程中，我会介绍一些KeyCloak的概念，文档中的概念太难懂，只看文档很难理解它的应用场景及作用，但通过实例就比较容易理解晦涩的概念。
我将要实现的实例比较简单但是很通用，比如在物业管理中，某一个物业管理员只能管理某一个楼或者某一个区域，因此他只能完成对这个楼或者这个区域里的物件进行管理。这个需求非常简单明了，但如何使用KeyCloak来进行权限认证和授权呢？
我将文章分为以下四个部分：

KeyCloak功能及快速入门
KeyCloak的Nginx Adapter实现
KeyCloak如何对资源授权
KeyCloak的Admin Client的使用

KeyCloak的介绍

Keycloak是为现代应用系统和服务提供开源的认证和授权访问控制管理。Keycloak 实现了OpenID、OAuth2.0、SAML单点登录协议，同时提供 LDAP 和 Active Directory 以及 OpenID Connect、SAML2.0 IdPs、Github、Google 等第三方登录适配功能，能够做到非常简单的开箱即用。提供的功能如下：

SSO

通过Keycloak处理用户认证，意味着你的应用不需要处理登录界面，认证用户，存储用户信息。一旦登录Keycloak, 用户不需要再次登录Keycloak管理下的其它应用。实现一次登录，多处登录不同应用，一处登出，所有应用登出。

集成身份认证系统

Keycloak通过配置，可实现对不同身份认证服务的集成，通过这些身份认证服务登录应用。

User Federation

在企业系统中有使用LDAP/AD管理用户，同样，Keycloak 提供了对LDAP/AD的集成方案，可以方便的同步用户。

Client Adapters

Keycloak提供了多种语言和不同平台的支持，支持标准协议，OpenID Connect, OAuth 2.0, and SAML等。下面是从官网上摘取的详细支持列表。

OpenID Connect
Java，JBoss EAP，WildFly，Fuse，Tomcat，Jetty 9，Servlet Filter，Spring Boot，Spring Security，JavaScript，Node.js，C#，Python,Android,iOS,Apache HTTP Server
SAML
Java,JBoss EAP,WildFly,Tomcat,Jetty,Apache HTTP Server

后台管理

Keycloak不仅提供了后台管理界面，同时还有AdminCLI，和RESTFul API方式管理后台。

KeyCloak的安装

Keycloak的安装

本地方式安装

可以从Keycloak的官网 https://www.keycloak.org/docs/latest/server_installation/index.html上下载最新版的Keycloak，有下面三个版本的Keycloak

keycloak-7.0.0.[zip|tar.gz]
keycloak-overlay-7.0.0.[zip|tar.gz]
keycloak-demo-7.0.0.[zip|tar.gz]
keycloak-7.0.0.[zip|tar.gz]是服务发布版，仅包括运行Keycloak server的脚本和二进制文件。keycloak-overlay-7.0.0.[zip|tar.gz]是WildFly插件，可以安装在一个已经存在的WildFly发布版上。keycloak-demo-7.0.0.[zip|tar.gz]包括Keycloak服务的二进制文件，文档以及实例。

Docker方式安装

我推荐使用Keycloak的Docker安装，可以快速的安装和运行Keycloak。Docker Hub地址https://hub.docker.com/r/jboss/keycloak/。默认安装没有设置管理员的账号和密码，因此没法使用Keycloak的控制台，可以通过设置环境变量的方式设置初始的管理员账号和密码。实例如下

docker run -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD='welcome1' -p 8080:8080 jboss/keycloak

对于Keycloak使用的是H2数据库，可以配置成postgre，mysql和mariadb，具体配置方式可以使用环境变量DB_ADDR，DB_PORT，DB_DATABASE，DB_SCHEMA，DB_USER，DB_USER_FILE，DB_PASSWORD，DB_PASSWORD_FILE来配置。
下面使用postgre来配置Keycloak。

第一步，创建Docker用户定义网络

docker network create keycloak-network

第二步，使用Docker创建postgre数据库

docker run -d --name postgres --net keycloak-network -e POSTGRES_DB=keycloak -e POSTGRES_USER=keycloak -e POSTGRES_PASSWORD=password postgres

第三步，启动Keycloak

docker run --name keycloak --net keycloak-network jboss/keycloak

Keycloak的配置

安装完成Keycloak后，访问http://localhost:8080/auth/admin/使用初始的管理员用户名和密码来登陆Keycloak控制台。

创建新的领域(realm)

Realm是一个隔离的概念，Realm A中的用户与Realm B中的用户完全隔离。当然，也可以不创建Realm，直接用 Master 这个Realm，不过一般来说，为了资源的隔离，以及更好的安全性不太建议与管理员共用Realm。从Master的下拉菜单中点击"Add Realm"，如下图所示：

创建新的用户

点击左边导航栏的Users，点击右边的"Add user"来创建新的用户。输入用户名，此参数是必须输入，其他字段可选。点击保存，会出现"Credentials"标签，输入用户名和密码，然后”reset password”,可以关闭临时密码功能。如下图，

接着登出Keycloak，使用上面创建的用户名和密码登陆创建的demo realm，http://localhost:8080/auth/realms/demo/account。

还有创建client，role，group，policy，resource，permission等功能，在以后的文章中使用时将会讲解如何创建。