[17.0.0.3 以及更新版本]

配置 MicroProfile JSON Web 記號

您可以配置 Liberty 伺服器,以接受 MicroProfile JSON Web 記號作為鑑別記號。

開始之前

安裝 Java™ Platform, Standard Edition (Java SE) 8 或更新版本,以使用 mpJwt-1.0 特性。

關於這項作業

MicroProfile 1.2 定義了可交互作業的 JSON Web 記號 (MP-JWT) 標準,其中包含三部分:
  • 記號格式和聲明
  • org.eclipse.microprofile.jwt.JsonWebToken 介面,這是 java.security.Principal 介面的延伸,會透過 get style 存取元來提供這組聲明
  • 將 JSON Web 記號和聲明對映至各種不同的 Java EE 儲存器應用程式設計介面 (API)

JWT RBAC for MicroProfile 尋找 MP-JWT 規格和 API。

任何授信方只要獲得 MP-JWT 記號,即可經由授權標頭傳送該記號,以利用該記號來存取 Liberty 中的相關聯資源。記號的發訊格式必須遵循 RFC 6750 規格 The OAuth 2.0 Authorization Framework: Bearer Token Usage,如下列範例所示:

GET /resource/1 HTTP/1.1
Host: example.com
Authorization: Bearer <MP-JWT token>
Liberty 資源伺服器會驗證 MP-JWT 記號,建立已鑑別的 JSON Web 記號,並透過 CDI 注入或 JAX-RS 安全環境定義,來提供 JSON Web 記號和記號聲明。如果要接受作為 MP-JWT 記號,JWT 記號必須包含聲明清單。下列範例顯示 MP-JWT 記號:
{
    "typ": "JWT",
    "alg": "RS256",
    "kid": "abc-1234567890"
}
{
       "iss": "https://server.example.com",
       "aud": "s6BhdRkqt3",
       "jti": "a-123",
       "exp": 1311281970,
       "iat": 1311280970,
       "sub": "24400320",
       "upn": "jdoe@server.example.com",
       "groups": ["red-group", "green-group", "admin-group", "admin"],
}

程序

  1. server.xml 檔中新增 mpJwt-1.0 特性和其他任何必要的特性。 mpJwt-1.0 特性至少需要 AppSecurity-2.0jaxrs-2.0 特性,且常與「環境定義和相依關係注入 (CDI)」特性搭配使用。
    <featureManager>
        <feature>mpJwt-1.0</feature>
        <feature>appSecurity-2.0</feature>
        <feature>jaxrs-2.0</feature>
        <feature>cdi-1.2</feature>
        ...
    </featureManager>
  2. 配置 mpJwt 元素。
    1. 新增 issuer 屬性。輸入這個屬性的值,且該值符合 Java Web 記號 (JWT) 中的 iss 聲明。
    2. 如果 JWT 包含 aud 聲明,請新增 audiences 屬性。輸入這個屬性的值,且該值含有 JWT 中的一個 aud 聲明值。
    3. 新增 jwksUri 屬性。輸入這個屬性的值,且該值符合 JSON Web 金鑰 (JWK) 的 URL。 下列程式碼顯示具有 JWK 的 mpJwt 配置元素:
      <mpJwt 
           id="myMpJwt"
           jwksUri="https://example.com/api/jwk"
           issuer="https://example.com/api/v1"
           audiences="conferenceService">
      </mpJwt>
    4. 如果您在 Secure Sockets Layer (SSL) 配置的 truststore 檔中,新增了 JWT 簽章驗證金鑰,請新增 keyName 屬性。 keyName 屬性用來指定 truststore 檔中的金鑰別名。 下列程式碼顯示範例 mpJwt 配置:
      <mpJwt 
           keyName="mpJwtValidationKey"
           issuer="https://example.com/api/v1"
           audiences ="conferenceService">
      </mpJwt>
  3. 配置 truststore 檔以包含 JWK 端點憑證,使 Liberty 伺服器可以與該 JWK 端點建立 SSL 連線。
    1. server.xml 檔的 keystore 元素上,配置 truststores
    2. 配置 SSL,以參照這個 truststore 檔。
    3. 將 SSL 配置設定成伺服器的預設 SSL 配置,或是在 mpJwt 元素的 sslRef 屬性上,指定 truststore ID。
    4. 如果 JWT 發證者不支援 JWK,並且是以 X.509 憑證來簽署 JWT,請將 X.509 憑證從發證者匯入至 SSL 配置中的 truststore 檔。 如需相關資訊,請參閱在 Liberty 中啟用 SSL 通訊
  4. 選擇性的: 針對不是採用 MP-JWT 格式的 JWT,定義「JWT 聲明至鑑別主體」對映規則。 依預設,程式會使用 upn 聲明,作為使用者的主體身分名稱及唯一安全名稱,且程式會使用群組聲明,作為安全角色對映的群組名稱。如果要變更預設對映,請使用 userNameAttribute 屬性,針對使用者主體身分選擇一項聲明,並使用 groupAttribute 屬性,針對群組名稱選擇一項聲明。
  5. 選擇性的: 使用 JAX-RS 應用程式來呼叫 javax.ws.rs.core.SecurityContext.getUserPrincipal() API,以存取 JsonWebToken getter。 在下列範例中,會將使用者主體身分強制轉型為 org.eclipse.microprofile.jwt.JsonWebToken API 實例,且應用程式可以透過 JsonWebToken getter 存取所有的聲明:
    @GET
    @Path("/getGroups")
    public Set<String> getGroups(@Context SecurityContext sec) {
           Set<String> groups = null;
           Principal user = sec.getUserPrincipal();
           if (user instanceof JsonWebToken) {
                    JsonWebToken jwt = (JsonWebToken) user;
                    groups= = jwt.getGroups();
           }
           return groups;
    }
  6. 選擇性的: 使用 JAX-RS 應用程式,透過 Raw TypeClaimValuejavax.inject.ProviderJSON-P 類型,來注入 org.eclipse.microprofile.jwt.JsonWebToken API,如下列範例所示:
    @RequestScoped
    public class JwtEndpoint {
           @Inject
           private JsonWebToken jwtPrincipal;
           @GET
           @Path("/getInjectedPrincipal")
           public String getInjectedJWT() {
              return  this.jwtPrincipal.getName();
           }
    }
  7. 選擇性的: 如果您的程式會執行程式化安全,且您可以從主體取得 org.eclipse.microprofile.jwt.JsonWebToken API,請使用 com.ibm.websphere.security.auth.WSSubject.getCallerPrincipal() API。 在現行安全環境定義中,主體含有兩項 java.security.Principal 主體身分。其中一個主體身分是 JSON Web 記號。
  8. 選擇性的: [17.0.0.4 以及更新版本]使用註釋和 JWT 群組聲明,來維護 JAX-RS 資源的安全。將 @RolesAllowed 註釋中使用的安全角色名稱,對映至 JWT 之群組聲明中的群組名稱。 如果角色名稱和群組名稱相同,您可以在 application-bnd 元素中省略角色對映。不過,如果 JWT 是一個含有群組資訊的 MP-JWT, 請在 application-bnd 元素中對映,以宣告「角色至群組」關聯。如需相關資訊,請參閱使用註釋來維護 JAX-RS 資源的安全存取 ID 和授權,以及未提供角色對映連結時的應用程式授權
  9. 選擇性的: [17.0.0.4 以及更新版本]將 Liberty 配置成檢查 JWT 中的使用者主體身分名稱,是否符合所配置的 Liberty 使用者登錄。

    依預設,程式會直接從已驗證的 JWT 建立一個安全主體,而不需要使用者登錄。如果要變更此行為,可在 server.xml 檔中,新增 mapToUserRegistry="true" 配置屬性。程式會根據所配置的使用者登錄,搜尋主體名稱,並根據使用者登錄中的使用者屬性,建立一個安全主體。

  10. 選擇性的: [17.0.0.4 以及更新版本]配置 Liberty,以便只將 mpJwt-1.0 特性套用至其登入方法名稱為 MP-JWT 的應用程式。
    依預設,如果配置了 mpJwt-1.0 特性,則所有授權要求都需要在 HTTP 標頭中包含有效的 JWT。如果要修改預設行為,以便只有某些應用程式中才需要 JWT 鑑別記號,請在 server.xml 檔中,新增 ignoreApplicationAuthMethod="false" 配置屬性至 <mpJwt> 元素。然後以下列兩種方式之一,來配置應用程式:
    • 應用程式具有 @LoginConfig 註釋,並宣告以 MP-JWT 登入方法作為鑑別方法。

      例如 @LoginConfig(authMethod = "MP-JWT", realmName = "MP-JWT")

    • 應用程式的 web.xml 檔在 login-config 元素中已宣告 MP-JWT 鑑別方法。

      例如 <login-config> <auth-method>MP-JWT</auth-method> <realm-name>MP-JWT</realm-name></login-config>

  11. 選擇性的: [17.0.0.4 以及更新版本]配置 Liberty,以便在 Liberty 呼叫其他 JAX-RS 服務時,會自動將 MP-JWT 當成鑑別記號來傳播。

    如果 Liberty 還擔任 JAX-RS 2.0 用戶端,請新增 authnToken="mpjwt" 陳述式至 <webTarget> 配置元素。之後,Liberty JAX-RS 用戶端會在呼叫 JAX-RS 服務時,自動新增 JWT 作為授權標頭。例如,如果您新增 <webTarget uri="http://localhost:56789/protectedResourceWithMPJWT*" authnToken="mpjwt" /> 元素至 server.xml 檔,則當呼叫 http://localhost:56789/protectedResourceWithMPJWT/ 服務時,會新增 JWT 記號至授權標頭。


指示主題類型的圖示 作業主題

檔名:twlp_sec_json.html