通过Keycloak API理解OAuth2与OpenID Connect

朱雀 2023-01-07 08:48 758阅读 0赞

### 文章目录 ###

*  通过Keycloak API理解OAuth2与OpenID Connect
 *   *  前言
     *  OAuth2 介绍
     *   *  OAuth2核心概念
         *  OAuth2 核心数据
         *  JWT
         *  OAuth2 flow
         *   *  Authorization Code Flow
             *  API Gateway与OIDC
     *  安装和运行Keycloak
     *  配置Keycloak
     *   *  Keycloak主要特性
         *  Keylcoak基本概念
         *  访问Keycloak
         *  新增Realm
         *  新增Client
         *  新增Role
         *  新增User
         *  Keycloak配置列表
     *  测试调用Keycloak的API
     *   *  Keycloak endpoints
         *  用Postman测试访问Keycloak endpoints
         *  用户登录后获取Authorization Code
         *  根据Authroization Code获取Access Token
         *  根据用户名和密码获取AccessToken
         *  验证Access Token和获取Token元信息
         *  获取用户信息
         *  刷新Token
         *  用户注销Logout
     *  参考文档
     *  扩展阅读

# 通过Keycloak API理解OAuth2与OpenID Connect #

## 前言 ##

Keycloak是一个被广泛使用的SSO（单点登录）工具，支持OAuth2和OpenID Connect。

本文通过测试调用Keycloak API来帮助理解OAuth2与OpenID Connect。

## OAuth2 介绍 ##

### OAuth2核心概念 ###

OAuth2核心概念：

*  Resource Owner - 资源所有者，一般指用户。
 *  Resource Server - 资源服务器。
 *  Client - 代表Resource Owner去访问受保护的资源。
 *  Authorization Server - 对Resource Owner进行身份认证，并颁发访问受保护资源的access token。
 *  User Agent - 用户代理，一般指浏览器，负责用户登录和注销后的页面跳转。
 *  Resource - 受保护的资源，比如API，页面。

示例1：

1.  用户William打开浏览器访问业务系统A时，被重定向到Keycloak登录页面。
2.  用户William在Kyecloak登录页面输入用户名和密码，登录成功后，页面跳转到业务系统A的首页。
3.  用户William点击业务系统A的某个菜单查询业务数据，业务系统成功返回数据。

在示例1中：

*  Resource Owner - 用户Willliam
 *  Resource Server - 业务系统A
 *  Client - 业务系统A的Web页面
 *  Authorization Server - Keycloak
 *  User Agent - 浏览器
 *  Resource - 业务数据

### OAuth2 核心数据 ###

OAuth2 核心数据

*  User Credential - 用户登录的凭据，比如用户名和密码。
 *  Client ID - 唯一标识一个Client。
 *  Client Secret - 用于Authroziation Server验证Client身份，不能泄漏。
 *  Authorization Code - 授权码，通过 User Credential + Client ID换取Authorization Code。授权码不能泄漏，且一次性有效。
 *  Access Token - 访问令牌，拥有令牌者可以访问受保护的资源。通过 Authorization Code + Client ID + Client Secret 换取。Access Token在有效期内有效。
 *  Refresh Token - 刷新令牌，用来刷新（重新获取）Access Token和Refresh Token。Refresh Token在有效期内有效。
 *  ID Token - The OpenID Connects ID Token is a signed JSON Web Token (JWT) which contains a set of information about the authentication session, which basically includes identifiers for the end user, identity provider who issued the token, client for which this token was created.

### JWT ###

Access Token为JWT格式。

示例：

eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJqRkdrVnhBbEVXcGN4ekJPZ25RUWxZb2VQYkZfOXM1aG5SeVlRdExHeTNVIn0.eyJleHAiOjE2MTA3MjA5NDAsImlhdCI6MTYxMDcyMDY0MCwianRpIjoiM2Q3M2IyNjItZDU3NC00OWEyLThlMGEtYWQ0ZmM0ZDAxMTA1IiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL2F1dGgvcmVhbG1zL29yZy1kZW1vIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6IjQ4ZGJiMGJkLTBiODYtNDFjNC1hNWUwLTlmNmY2YTAwMGQyMiIsInR5cCI6IkJlYXJlciIsImF6cCI6ImFwcC0xIiwic2Vzc2lvbl9zdGF0ZSI6ImRlNzZmNmYwLTRjMjktNDkwMy04YTQxLTUxYmVlMjllMmNiZiIsImFjciI6IjEiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiVXNlciIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6InByb2ZpbGUgZW1haWwiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsInByZWZlcnJlZF91c2VybmFtZSI6IndpbGxpYW0ifQ.JAZhvi8QHY0MHyiwuhXZ9amxXXvutLhYN3jUclmPUrJizikYNpS61Qub8iVruSGOxI6pfvc5BcwTJUwZ0UsmBl_BalKEox1MkOujHKhtMQ78631H3eZyANCUbbe-u0y4Vp3fmWTk6ErgcIQSY2DkmsE97tzVVCrVC_uGdcpewUpUu1VDzA1TPd5KSvU-2d8T_KOeTUsLoG4964ryheJiYQOkXVxJCe1CN5eQlIIZlSIujq7O71tPDaNif9RunrpU0c2rAtqKoU0bS1iKXIOqRtxfFum7Ju1l7I2Sa4uiZH-T76yLRO5Mxk124FNu49y6H-Zu10u0memWAPvtJSi-ZQ

这是一串Base64URL的编码。

对其解码后，内容包括header, payload 和 signature：

*  Header:

{ 
     "typ": "JWT",
     "alg": "RS256",
     "kid": "jFGkVxAlEWpcxzBOgnQQlYoePbF_9s5hnRyYQtLGy3U"
    }

*  Payload:

{ 
     "exp": 1610720940, # 令牌过期时间戳
     "iat": 1610720640, # 令牌颁发时间戳
     "jti": "3d73b262-d574-49a2-8e0a-ad4fc4d01105", # 令牌唯一标识符
     "iss": "http://localhost:8080/auth/realms/org-demo", # 令牌颁发者
     "aud": "account", # 令牌的受众，接收者
     "sub": "48dbb0bd-0b86-41c4-a5e0-9f6f6a000d22", # 令牌的主体
     "typ": "Bearer", # 令牌的类型
     "azp": "app-1",
     "session_state": "de76f6f0-4c29-4903-8a41-51bee29e2cbf",
     "acr": "1",
     "realm_access": { 
      "roles": [
       "User",
       "offline_access",
       "uma_authorization"
      ]
     },
     "resource_access": { 
      "account": { 
       "roles": [
        "manage-account",
        "manage-account-links",
        "view-profile"
       ]
      }
     },
     "scope": "profile email",
     "email_verified": false,
     "preferred_username": "william"
    }

*  Signture

secret

JWT 解码网站（只做debug用，不要泄漏token！）：

[https://www.jsonwebtoken.io/][https_www.jsonwebtoken.io]

可以看到JWT本身已经包含验证Token所需的全部元数据，因此Resource Server无需调用Authorization Server的接口就可以验证Access Token的有效性。

当然，Resource Server也可以再调用Authorization Server的Introspect Token (令牌内省)接口来验证Access Token的有效性，作为防止令牌被伪造的增强性安全措施。

### OAuth2 flow ###

OAuth2 框架定义以下几种flow (授权流程）：

*  Authorization Code Flow - 授权码授权流程；最常见的授权流程。
 *  Implicit Flow - 隐式授权流程
 *  Resource Owner Credential Flow - 资源所有者凭据授权流程；不安全，强烈不建议使用。
 *  Client Credential Flow - 客户端凭据授权流程

#### Authorization Code Flow ####

Authorization Code Flow （授权码授权流程）如下图所示：

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25rbGluc2lydWk_size_16_color_FFFFFF_t_70]

说明：

*  因为Access Token采用JWT格式，已经包含了验证Access Token的元数据，因此Resource Server无需调用Authorization Server的接口就可以验证Access Token的有效性。
 *  当然，Resource Server也可以再调用Authorization Server的Token Introspection (令牌内省)接口来验证Access Token的有效性，作为防止令牌被伪造的增强性安全措施。

安全性要求：

*  保证数据链路安全：Client - Authorizaiton Server 、Client - Resource Server 和 Authorization Server - Resource Server 之间强烈建议为HTTPS协议，防止数据被窃听后泄密。
 *  加密数据：对敏感数据进行加密，万一泄漏，也无法被解密。
 *  防止重放攻击：对Authorization Server和Resource Server提供的API需要通过nonce的方法防止重放攻击（replay attack）。
 *  防止数据被篡改：对对Authorization Server和Resource Server提供的API需要通过签名和验签的方法防止数据被篡改。
 *  双向验证：服务端要验证客户端的合法性，客户端也要验证服务端的合法性。
 *  代码安全：不能将Client Secret存储在前端代码中，防止Client Secret泄漏。

参见：

*  [https://auth0.com/docs/flows/authorization-code-flow][https_auth0.com_docs_flows_authorization-code-flow]
 *  [https://auth0.com/docs/flows/authorization-code-flow-with-proof-key-for-code-exchange-pkce][https_auth0.com_docs_flows_authorization-code-flow-with-proof-key-for-code-exchange-pkce]
 *  [API安全风险与防范][API]

下图从系统关系角度来描述了OAuth 2 authorization code flow:

![Oauth2 authorization code flow][]

说明：

*  其中front channel一般在互联网上传输数据，被认为是在不安全的网络中，而back channel一般在内网中传输数据，被认为是相对安全的网络。
 *  当然如果是由第三方平台扮演Authorization Server时，back channel一般也在互联网上传输数据。

参见：

*  [OpenID connect Authentication with OAuth2.0 Authorizatio][]

#### API Gateway与OIDC ####

![Authorization Code Flow with API Gateway][]

说明：

*  API Gateway - 以Kong为例
 *  IDP - 比如Keycloak

另外一个图：

![Kong-Keycloak-authorizaiton-flow][]

参见：

*  [https://github.com/d4rkstar/kong-konga-keycloak][https_github.com_d4rkstar_kong-konga-keycloak]

另外一个图：  
![kong-oidc-auth-flow][]

参见：

*  [https://github.com/nokia/kong-oidc][https_github.com_nokia_kong-oidc]

## 安装和运行Keycloak ##

Keycloak 支持多种部署方式：

*  VM
 *  Docker
 *  Kubernetes
 *  OpenShift

测试原因，在本地以Docker容器方式安装和运行Keycloak。

参见：

*  [https://www.keycloak.org/getting-started/getting-started-docker][https_www.keycloak.org_getting-started_getting-started-docker]

docker run --name keycloak \
      -d \
      -p 8080:8080 \
      -p 8443:8443 \
      -e KEYCLOAK_USER=admin \
      -e KEYCLOAK_PASSWORD=admin \
      quay.io/keycloak/keycloak:12.0.1

如果无法从quay.io 下载镜像，可以先为Docker添加阿里云Docker registry mirror。

## 配置Keycloak ##

### Keycloak主要特性 ###

*  单点登录（Sign-Sign-On)：允许用户通过Keycloak进行身份认证，而不是没个单独的应用或服务。用户登录Keycloak后，他们可以访问任何通过Keycloak进行身份认证的应用或服务。
 *  社交媒体登录（Social Login）：使用Keyclaok启用社交媒体登录非常简单，在管理控制台中配置需要授权的社交媒体登录方式（比如Google，Facebook等）即可，不需要修改代码或应用。
 *  用户联邦（User Federation): 如果用户通过LDAP或Active Directory注册，那么可以轻易地将他们于Keycloak联合。如果用户在不同类型的数据库中，也可以开发自己的Provider来访问用户。
 *  标准协议：Keycloak对OpenID Connect, OAuth2 和SAML提供了开箱即用的支持。

### Keylcoak基本概念 ###

![Keycloak基本概念][Keycloak]

### 访问Keycloak ###

访问Keycloak web console：

*  [http://localhost:8080][http_localhost_8080] （测试用）
 *  [https://localhost:8443][https_localhost_8443] (CA证书不被浏览器认可)

输入Keycloak管理员账号密码登录。

### 新增Realm ###

新增Realm：

*  Name - `org-demo`
 *  Display Name - `Demo Organization`

### 新增Client ###

在新建的Realm下，新增Client：

*  Client-ID - `app-1`
 *  Client Protocol - `openid-connect`
 *  Access Type - `confidential`
 *  Valid Redirect URIs
    
     *  `http://localhost:8082/*`

保存。

### 新增Role ###

在新增的Realm下，新增Role：

*  普通用户
    
     *  Name - `User`
     *  Description - `普通用户`
 *  管理员
    
     *  Name - `Admin`
     *  Description - `管理员`

### 新增User ###

在新增的Realm下，新增User:

*  普通用户
    
     *  Username - `william`
     *  在Credentials菜单中设置初始密码。
     *  Role Mappings / Assigned Roles: `User`
 *  普通用户
    
     *  Username - `admin` (注意，这个`admin` 和`master` realm 下的Keycloak管理员`admin` 没有关系，不冲突。)
     *  在Credentials菜单中设置初始密码。
     *  Role Mappings / Assigned Roles: `Admin`

### Keycloak配置列表 ###

下表列出了上面的Keycloak配置：

<table> 
 <thead> 
  <tr> 
   <th>Realm</th> 
   <th>Client</th> 
   <th>Role</th> 
   <th>User</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><code>org-demo</code></td> 
   <td><code>app-1</code></td> 
   <td><code>User</code></td> 
   <td><code>william</code></td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>…</td> 
   <td><code>Admin</code></td> 
   <td><code>admin</code></td> 
  </tr> 
 </tbody> 
</table>

## 测试调用Keycloak的API ##

### Keycloak endpoints ###

在新建的Realm上，点击Endpoints / OpenID Endpoint Configuration，查看Keycloak endpoints。

*  [http://localhost:8080/auth/realms/org-demo/.well-known/openid-configuration][http_localhost_8080_auth_realms_org-demo_.well-known_openid-configuration]

常用的Keycloak endpoints包括：

*  `authorization_endpoint` \- 获取Authorization code
 *  `token_endpoint` \- 获取Access Token
 *  `introspection_endpointt` \- Token内省，可验证Token和获取Token的元信息。
 *  `userinfo_endpoint` \- 获取用户信息
 *  `end_session_endpoint` \- 用户注销

另外`xxx_supported` 列出了支持的grant\_type，response\_type和scope等。

### 用Postman测试访问Keycloak endpoints ###

参见：

*  [Accessing Keycloak Endpoints Using Postman][]

为方便测试，在Postman上创建名为`keycloak`的Collection。

在Collection上，右键选择Edit，打开Variable。

在该Collection上定义Collection variables:

*  `client_id`
 *  `client_secret`

### 用户登录后获取Authorization Code ###

在浏览器上打开Keycloak authorization endpoint:

复制到浏览器中执行：

http://localhost:8080/auth/realms/org-demo/protocol/openid-connect/auth?client_id=app-1&redirect_uri=http://localhost:8082/&response_type=code&scope=openid
    
    # html encoded redirect_uri
    http://localhost:8080/auth/realms/org-demo/protocol/openid-connect/auth?client_id=app-1&redirect_uri=http%3A%2F%2Flocalhost%3A8082%2F&response_type=code&scope=openid

或直接点击执行：

[http://localhost:8080/auth/realms/org-demo/protocol/openid-connect/auth?client\_id=app-1&redirect\_uri=http://localhost:8082/&response\_type=code&scope=openid][http_localhost_8080_auth_realms_org-demo_protocol_openid-connect_auth_client_id_app-1_redirect_uri_http_localhost_8082_response_type_code_scope_openid]

说明：

*  `response_type=code` \- 表示返回Authorization Code
 *  `redirect_uri` \- 用户在Keycloak登录界面登录成功跳转回来的页面URL; 可以为[html encode][]后的URL
 *  `scope` \- 值为`openid`。 The permissions represented by the access token, in OAuth terms, are known as [scopes][].

可选参数还包括：

*  `state` \- An opaque value, used for security purposes. If this request parameter is set in the request, then it is returned to the application as part of the `redirect_uri`. 用来验证发起重定向Identifier Provider的合法性，一般为随机生成的Hash字符串。

在Keycloak登录页面，输入用户名密码登录成功后，跳转到类似URL：

http://localhost:8082/?session_state=4b5a4f74-4113-4907-b031-49a3988cbc46&code=fffa871a-587c-48bb-b0c1-508207e4c136.4b5a4f74-4113-4907-b031-49a3988cbc46.5f704b1c-09c2-440f-9c6b-8f697be4e88a

其中code的值就是Authorization Code。

### 根据Authroization Code获取Access Token ###

Request:

# url
    # Keycloak token endpoint
    http://localhost:8080/auth/realms/org-demo/protocol/openid-connect/token
    
    # http verb
    POST
    
    # request body
    x-www-form-urlencoded
    
    # parameters
    code: 
    client_id: { { client_id}}
    client_secret: { { client_secret}}
    redirect_url
    grant_type: authorization_code

{ 
        "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJqRkdrVnhBbEVXcGN4ekJPZ25RUWxZb2VQYkZfOXM1aG5SeVlRdExHeTNVIn0.eyJleHAiOjE2MTA3Mjg4MjAsImlhdCI6MTYxMDcyODUyMCwiYXV0aF90aW1lIjoxNjEwNzI4NTA0LCJqdGkiOiJjYzY0MjA5MS03ZWNjLTQ5YTEtODRiYS1jZjhlYWIxZTVkMmUiLCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvb3JnLWRlbW8iLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiNDhkYmIwYmQtMGI4Ni00MWM0LWE1ZTAtOWY2ZjZhMDAwZDIyIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiYXBwLTEiLCJzZXNzaW9uX3N0YXRlIjoiNjYyN2QyMGUtYTRmNC00YWNhLWE3YWYtMTVmNjkzY2ZjY2FiIiwiYWNyIjoiMSIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJVc2VyIiwib2ZmbGluZV9hY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoib3BlbmlkIHByb2ZpbGUgZW1haWwiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsInByZWZlcnJlZF91c2VybmFtZSI6IndpbGxpYW0ifQ.UZDOfafRY8TPSqsIGzfPKtpo530X2gLHeS79Kwz1fFnNTgvYzvF1WRqAmSRDnl6gIfXwqqnert6hoizm_Rq3-zVbPTT1aKaoVGqPgf_NbFpYIRkPAce0utsafbWbc6c2vPY60uMXvTdr7MeHOAwQT8zrO3Qpc5ubvZJrE16dlYEb8dzSW-mAE-vFvesC5YnfTrTEkLnV-FTjfReP-yuJ_6aZjIdt8CdNCXp7stz-_xutlCa-2PnNh_GNG8WLXP5nQfCFBq-GhvSxotdWfNWjPHYwJuXPgQkNIWNacIzxHY4O5wUqsI6SpsGGSqALqn4PqsgD-6-R_eiaaFnOINDG6w",
        "expires_in": 300,
        "refresh_expires_in": 1800,
        "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI3MTk1YjM5ZC03MzQwLTQ4ZGQtOGVmMi0zMDY4Y2M4MWFhYzAifQ.eyJleHAiOjE2MTA3MzAzMjAsImlhdCI6MTYxMDcyODUyMCwianRpIjoiYWQyNmMyYmQtOWM1OS00MzIxLTk4Y2ItYzdmYjBiZjA1YWQ2IiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL2F1dGgvcmVhbG1zL29yZy1kZW1vIiwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL2F1dGgvcmVhbG1zL29yZy1kZW1vIiwic3ViIjoiNDhkYmIwYmQtMGI4Ni00MWM0LWE1ZTAtOWY2ZjZhMDAwZDIyIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImFwcC0xIiwic2Vzc2lvbl9zdGF0ZSI6IjY2MjdkMjBlLWE0ZjQtNGFjYS1hN2FmLTE1ZjY5M2NmY2NhYiIsInNjb3BlIjoib3BlbmlkIHByb2ZpbGUgZW1haWwifQ.mXIV3aY08CH-VFvfS2jTfCuQOA3ZRSQA-GfaN4IlHDI",
        "token_type": "Bearer",
        "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJqRkdrVnhBbEVXcGN4ekJPZ25RUWxZb2VQYkZfOXM1aG5SeVlRdExHeTNVIn0.eyJleHAiOjE2MTA3Mjg4MjAsImlhdCI6MTYxMDcyODUyMCwiYXV0aF90aW1lIjoxNjEwNzI4NTA0LCJqdGkiOiJmMjRhNGNiMC04YTY0LTQ2OTgtOGYxMS0wOTVlYzhjNDRhMTciLCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvb3JnLWRlbW8iLCJhdWQiOiJhcHAtMSIsInN1YiI6IjQ4ZGJiMGJkLTBiODYtNDFjNC1hNWUwLTlmNmY2YTAwMGQyMiIsInR5cCI6IklEIiwiYXpwIjoiYXBwLTEiLCJzZXNzaW9uX3N0YXRlIjoiNjYyN2QyMGUtYTRmNC00YWNhLWE3YWYtMTVmNjkzY2ZjY2FiIiwiYXRfaGFzaCI6Ik1KVVlMdkgxcEFPMDMxdTdaMV84TGciLCJhY3IiOiIxIiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ3aWxsaWFtIn0.cSrvhsolxLCjb3UHPsZ-3DrSyB0CsCxD8XFkNAbI60ugiJOZdZwemRrzVA6JxAgYizQzq3jaYhYt6OOLpScumDOgK9Wkn-4dAFIRRggfrJ4lp8BcxOmZnuAN6_yyXHOu3sJ9h3axE3pNhQJo_GQdiTX7F8hjKywLo4jpcJv_vhsWyd3rTJDnNKx-NxZRTNa72TJeBfdSyrG1UdbN4dC1tQQ3zi4jbNztOFMhW_GV2GiL03bxiBChIF-pe0wAHnOfFRWJVYQMdBIczQeDO1lRrKyCCuFQb0CIX1UPxH1r9aZKuYKSl-MatZxqufbKLTUVDtrPm_kpilnbavNJBfZXWg",
        "not-before-policy": 1610728470,
        "session_state": "6627d20e-a4f4-4aca-a7af-15f693cfccab",
        "scope": "openid profile email"
    }

注意Authorization Code只能调用一次(即一次性有效），第二次调用时会报错：

{ 
        "error": "invalid_grant",
        "error_description": "Code not valid"
    }

### 根据用户名和密码获取AccessToken ###

Request：

# url
    # Keycloak token endpoint
    http://localhost:8080/auth/realms/org-demo/protocol/openid-connect/token
    
    # http verb
    POST
    
    # request body
    x-www-form-urlencoded
    
    # parameters
    username
    password
    client_id: { { client_id}}
    client_secret: { { client_secret}}
    grant_type: password

{ 
        "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJqRkdrVnhBbEVXcGN4ekJPZ25RUWxZb2VQYkZfOXM1aG5SeVlRdExHeTNVIn0.eyJleHAiOjE2MTA3MjA5NDAsImlhdCI6MTYxMDcyMDY0MCwianRpIjoiM2Q3M2IyNjItZDU3NC00OWEyLThlMGEtYWQ0ZmM0ZDAxMTA1IiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL2F1dGgvcmVhbG1zL29yZy1kZW1vIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6IjQ4ZGJiMGJkLTBiODYtNDFjNC1hNWUwLTlmNmY2YTAwMGQyMiIsInR5cCI6IkJlYXJlciIsImF6cCI6ImFwcC0xIiwic2Vzc2lvbl9zdGF0ZSI6ImRlNzZmNmYwLTRjMjktNDkwMy04YTQxLTUxYmVlMjllMmNiZiIsImFjciI6IjEiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiVXNlciIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6InByb2ZpbGUgZW1haWwiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsInByZWZlcnJlZF91c2VybmFtZSI6IndpbGxpYW0ifQ.JAZhvi8QHY0MHyiwuhXZ9amxXXvutLhYN3jUclmPUrJizikYNpS61Qub8iVruSGOxI6pfvc5BcwTJUwZ0UsmBl_BalKEox1MkOujHKhtMQ78631H3eZyANCUbbe-u0y4Vp3fmWTk6ErgcIQSY2DkmsE97tzVVCrVC_uGdcpewUpUu1VDzA1TPd5KSvU-2d8T_KOeTUsLoG4964ryheJiYQOkXVxJCe1CN5eQlIIZlSIujq7O71tPDaNif9RunrpU0c2rAtqKoU0bS1iKXIOqRtxfFum7Ju1l7I2Sa4uiZH-T76yLRO5Mxk124FNu49y6H-Zu10u0memWAPvtJSi-ZQ",
        "expires_in": 300,
        "refresh_expires_in": 1800,
        "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI3MTk1YjM5ZC03MzQwLTQ4ZGQtOGVmMi0zMDY4Y2M4MWFhYzAifQ.eyJleHAiOjE2MTA3MjI0NDAsImlhdCI6MTYxMDcyMDY0MCwianRpIjoiMzkxMTg2YTktZWEyNS00MGNhLTkwNjEtOWRmODc3MDBjOGUxIiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL2F1dGgvcmVhbG1zL29yZy1kZW1vIiwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL2F1dGgvcmVhbG1zL29yZy1kZW1vIiwic3ViIjoiNDhkYmIwYmQtMGI4Ni00MWM0LWE1ZTAtOWY2ZjZhMDAwZDIyIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImFwcC0xIiwic2Vzc2lvbl9zdGF0ZSI6ImRlNzZmNmYwLTRjMjktNDkwMy04YTQxLTUxYmVlMjllMmNiZiIsInNjb3BlIjoicHJvZmlsZSBlbWFpbCJ9.TXJH0MuqirDUwr3vd_mPxZkbeiZAtL90CkHsPZZnSXY",
        "token_type": "Bearer",
        "not-before-policy": 0,
        "session_state": "de76f6f0-4c29-4903-8a41-51bee29e2cbf",
        "scope": "profile email"
    }

可以在Postman的Tests中定义JavaScript来将将返回的`access_token`和`refresh_token` 保存到Postman Collection Variables中。

var jsonData = JSON.parse(responseBody);
    pm.collectionVariables.set("access_token", jsonData.access_token);
    pm.collectionVariables.set("refresh_token", jsonData.refresh_token);
    
    // View / Show Postman Console
    // console.log(pm.variables.get("access_token"));
    // console.log(pm.variables.get("refresh_token"));

关于Postman variable的用法参见：

*  [https://learning.postman.com/docs/sending-requests/variables/][https_learning.postman.com_docs_sending-requests_variables]

### 验证Access Token和获取Token元信息 ###

Request：

# url
    # Keycloak introspect endpoint
    http://localhost:8080/auth/realms/org-demo/protocol/openid-connect/token/introspect
    
    # http verb
    POST
    
    # request body
    x-www-form-urlencoded
    
    # parameters
    token: { { access_token}}
    client_id: { { client_id}}
    client_secret: { { client_secret}}

Access Token有效时，返回：

{ 
        "exp": 1610721664,
        "iat": 1610721364,
        "jti": "c6d5e8b2-1b3e-4ceb-a6ef-367d29b62f02",
        "iss": "http://localhost:8080/auth/realms/org-demo",
        "aud": "account",
        "sub": "48dbb0bd-0b86-41c4-a5e0-9f6f6a000d22",
        "typ": "Bearer",
        "azp": "app-1",
        "session_state": "ea06aa4b-20f0-46b4-b83a-44c349fc00f5",
        "preferred_username": "william",
        "email_verified": false,
        "acr": "1",
        "realm_access": { 
            "roles": [
                "User",
                "offline_access",
                "uma_authorization"
            ]
        },
        "resource_access": { 
            "account": { 
                "roles": [
                    "manage-account",
                    "manage-account-links",
                    "view-profile"
                ]
            }
        },
        "scope": "profile email",
        "client_id": "app-1",
        "username": "william",
        "active": true
    }

Access Token无效时返回：

{ 
        "active": false
    }

所以根据返回结果的`active`是否为true，就可以判断Access Token是否有效。

### 获取用户信息 ###

Request：

# url
    # Keycloak userinfo endpoint
    http://localhost:8080/auth/realms/org-demo/protocol/openid-connect/userinfo
    
    # http verb
    GET
    
    # request headers
    Content-Type: application/x-www-form-urlencoded
    
    # Authorization
    Type: Bearer Token
    Token: { { access_token}}

{ 
        "sub": "48dbb0bd-0b86-41c4-a5e0-9f6f6a000d22",
        "email_verified": false,
        "preferred_username": "william"
    }

### 刷新Token ###

Request:

# url
    # Keycloak token endpoint
    http://localhost:8080/auth/realms/org-demo/protocol/openid-connect/token
    
    # http verb
    POST
    
    # request body
    x-www-form-urlencoded
    
    # parameters
    client_id: { { client_id}}
    client_secret: { { client_secret}}
    grant_type: refresh_token
    refresh_token: { { refresh_token}}

{ 
        "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJqRkdrVnhBbEVXcGN4ekJPZ25RUWxZb2VQYkZfOXM1aG5SeVlRdExHeTNVIn0.eyJleHAiOjE2MTA3Nzk5OTQsImlhdCI6MTYxMDc3OTY5NCwianRpIjoiMzc0YTY1MDctMTkwMS00OTM1LTllMjMtYTgwNTJmZmM1NWUwIiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL2F1dGgvcmVhbG1zL29yZy1kZW1vIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6IjQ4ZGJiMGJkLTBiODYtNDFjNC1hNWUwLTlmNmY2YTAwMGQyMiIsInR5cCI6IkJlYXJlciIsImF6cCI6ImFwcC0xIiwic2Vzc2lvbl9zdGF0ZSI6ImMxMjczZWI1LWY5MjItNDIwYy1iMjNhLTg1NGJlOTczNWMxZCIsImFjciI6IjEiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiVXNlciIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6InByb2ZpbGUgZW1haWwiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsInByZWZlcnJlZF91c2VybmFtZSI6IndpbGxpYW0ifQ.HcWS26-VgqEIGEtb6QzTNKHPFnSrDh1bOkSi2X3leyFBoxavtwnHXCoVANKeQ_CONqyXXLxseTE5zxfhm_knOd4dtJyqaYzC30n7Hvp8PJR51P0GxM7Kq3eDAVNmfNwSmfxv_Y9MDyY8c4AFLU9CZY_GKPA_QCNAVA5wPcg0PvwHx1VHga2N8GGEv3AcVWeL3RegF4HrnWX287jAXeuPXVnIejCZxnSHbu0o24ahLI9AyMRnHWaDsb_uiazere3nWTmC1bdkyiY724c7W8vpBhsL0kNN_FX7AYcqCZKJdXH8p4vy23LLhacjE_daGq-w5Lll7PVCcQyKKS6DkY84Ng",
        "expires_in": 300,
        "refresh_expires_in": 1800,
        "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI3MTk1YjM5ZC03MzQwLTQ4ZGQtOGVmMi0zMDY4Y2M4MWFhYzAifQ.eyJleHAiOjE2MTA3ODE0OTQsImlhdCI6MTYxMDc3OTY5NCwianRpIjoiMjRiNTc3ZTgtNTIyNy00NWZjLWFmNTctYmM3ZDA2ZmUzY2U2IiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL2F1dGgvcmVhbG1zL29yZy1kZW1vIiwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL2F1dGgvcmVhbG1zL29yZy1kZW1vIiwic3ViIjoiNDhkYmIwYmQtMGI4Ni00MWM0LWE1ZTAtOWY2ZjZhMDAwZDIyIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImFwcC0xIiwic2Vzc2lvbl9zdGF0ZSI6ImMxMjczZWI1LWY5MjItNDIwYy1iMjNhLTg1NGJlOTczNWMxZCIsInNjb3BlIjoicHJvZmlsZSBlbWFpbCJ9.1YfhB1RcDb4tkYfp6EIoUUFbvMaah_nktq-XkhfMqqo",
        "token_type": "Bearer",
        "not-before-policy": 1610728470,
        "session_state": "c1273eb5-f922-420c-b23a-854be9735c1d",
        "scope": "profile email"
    }

### 用户注销Logout ###

Request:

# url
    # Keycloak token endpoint
    http://localhost:8080/auth/realms/org-demo/protocol/openid-connect/logout
    
    # http verb
    POST
    
    # request body
    x-www-form-urlencoded
    
    # parameters
    client_id: { { client_id}}
    client_secret: { { client_secret}}
    refresh_token: { { refresh_token}}

## 参考文档 ##

参考文档

*  [Accessing Keycloak Endpoints Using Postman][]
 *  [Keycloak REST API End-Point URLs for OAuth/OIDC Authentication][Keycloak REST API End-Point URLs for OAuth_OIDC Authentication]

Keycloak:

*  [Keycloak - Server Installation and Configuration Guide][]
 *  [Keycloak - Authorization Services Guide][]
 *  [Keycloak - Server Administration Guide][]

OAuth2:

*  [Auth0 - OAuth 2.0 Authorization Framework][]
 *  [RFC - OAuth 2.0][]
 *  [OAuth 2 Simplified][]
 *  [OAuth 2.0 and OpenID Connect (in plain English)][OAuth 2.0 and OpenID Connect _in plain English]
 *  [Securing APIs with OpenID Connect][]

JWT

*  [https://jwt.io/][https_jwt.io]

## 扩展阅读 ##

*  [微信登录开发指南][Link 1]
 *  [https://learning.postman.com/docs/sending-requests/authorization/][https_learning.postman.com_docs_sending-requests_authorization]
 *  [OAuth 2.0 Client Authentication][] 描述了详细的OAuth2 flow
 *  [Authorization Server Implementation in Java][]
 *  [Authentication as a Microservice][] 描述了认证方式的演变，以及如何在微服务中作认证
 *  [How HTTPS works][] 以卡通形式说明了HTTPS的3个重要方面：privacy （隐私性）, integrity（完整性）, identification （身份认证）。privacy （隐私性），数据包被劫持后，无法被解密。integrity（完整性），数据包被劫持后，无法被篡改。identification （身份认证），确保访问可信任站点。
 *  [An Illustrated Guide to OAuth and OpenID Connect][]

[https_www.jsonwebtoken.io]: https://www.jsonwebtoken.io/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25rbGluc2lydWk_size_16_color_FFFFFF_t_70]: /images/20221119/06aa5dae8c324b919286da41118fde95.png
[https_auth0.com_docs_flows_authorization-code-flow]: https://auth0.com/docs/flows/authorization-code-flow
[https_auth0.com_docs_flows_authorization-code-flow-with-proof-key-for-code-exchange-pkce]: https://auth0.com/docs/flows/authorization-code-flow-with-proof-key-for-code-exchange-pkce
[API]: https://blog.csdn.net/nklinsirui/article/details/107818341
[Oauth2 authorization code flow]: /images/20221119/2c3eea9b48dd447b93e78c3e32fadc63.png
[OpenID connect Authentication with OAuth2.0 Authorizatio]: http://innovationm.co/openid-connect-authentication-with-oauth2-0-authorization/
[Authorization Code Flow with API Gateway]: /images/20221119/d976b76ed84f4b4ea75a3b48faa28d26.png
[Kong-Keycloak-authorizaiton-flow]: /images/20221119/7c47e8ceb1ff48829896b7763e1859a6.png
[https_github.com_d4rkstar_kong-konga-keycloak]: https://github.com/d4rkstar/kong-konga-keycloak
[kong-oidc-auth-flow]: /images/20221119/19d75b4c08f64fe9a212d584715700c8.png
[https_github.com_nokia_kong-oidc]: https://github.com/nokia/kong-oidc
[https_www.keycloak.org_getting-started_getting-started-docker]: https://www.keycloak.org/getting-started/getting-started-docker
[Keycloak]: https://img-blog.csdnimg.cn/img_convert/cf78952c485585d17a5c92c0a311d8e7.png
[http_localhost_8080]: http://localhost:8080
[https_localhost_8443]: https://localhost:8443
[http_localhost_8080_auth_realms_org-demo_.well-known_openid-configuration]: http://localhost:8080/auth/realms/org-demo/.well-known/openid-configuration
[Accessing Keycloak Endpoints Using Postman]: https://www.baeldung.com/postman-keycloak-endpoints
[http_localhost_8080_auth_realms_org-demo_protocol_openid-connect_auth_client_id_app-1_redirect_uri_http_localhost_8082_response_type_code_scope_openid]: http://localhost:8080/auth/realms/org-demo/protocol/openid-connect/auth?client_id=app-1&redirect_uri=http://localhost:8082/&response_type=code&scope=openid
[html encode]: https://www.w3schools.com/tags/ref_urlencode.ASP
[scopes]: https://auth0.com/docs/scopes
[https_learning.postman.com_docs_sending-requests_variables]: https://learning.postman.com/docs/sending-requests/variables/
[Keycloak REST API End-Point URLs for OAuth_OIDC Authentication]: https://medium.com/@maxlam79/keycloak-rest-api-end-point-urls-for-oauth-oidc-authentication-26c3cb05086e
[Keycloak - Server Installation and Configuration Guide]: https://www.keycloak.org/docs/latest/server_installation/
[Keycloak - Authorization Services Guide]: https://www.keycloak.org/docs/latest/authorization_services/
[Keycloak - Server Administration Guide]: https://www.keycloak.org/docs/latest/server_admin/
[Auth0 - OAuth 2.0 Authorization Framework]: https://auth0.com/docs/protocols/protocol-oauth2
[RFC - OAuth 2.0]: https://tools.ietf.org/html/rfc6749
[OAuth 2 Simplified]: https://aaronparecki.com/oauth-2-simplified/#web-server-apps
[OAuth 2.0 and OpenID Connect _in plain English]: https://www.youtube.com/watch?v=996OiexHze0
[Securing APIs with OpenID Connect]: https://www.youtube.com/watch?v=fGlay8Ri5zo
[https_jwt.io]: https://jwt.io/
[Link 1]: https://developers.weixin.qq.com/doc/oplatform/Mobile_App/WeChat_Login/Development_Guide.html
[https_learning.postman.com_docs_sending-requests_authorization]: https://learning.postman.com/docs/sending-requests/authorization/
[OAuth 2.0 Client Authentication]: https://darutk.medium.com/oauth-2-0-client-authentication-4b5f929305d4
[Authorization Server Implementation in Java]: https://github.com/authlete/java-oauth-server
[Authentication as a Microservice]: https://www.youtube.com/watch?v=SLc3cTlypwM
[How HTTPS works]: https://howhttps.works/why-do-we-need-https/
[An Illustrated Guide to OAuth and OpenID Connect]: https://developer.okta.com/blog/2019/10/21/illustrated-guide-to-oauth-and-oidc