[17.0.0.3 and later]

MicroProfile JWT(JSON Web Token) 구성

MicroProfile JWT(JSON Web Token)를 인증 토큰으로 승인하도록 Liberty 서버를 구성할 수 있습니다.

시작하기 전에

mpJwt-1.0 기능을 사용하려면 Java™ SE(Java Platform, Standard Edition) 8 이상을 설치하십시오.

이 태스크 정보

MicroProfile 1.2는 다음 세 파트를 포함하는 상호 운용 가능한 MP-JWT(JSON Web Token) 표준을 정의합니다.
  • 토큰 형식 및 청구
  • 가져오기 스타일 액세서를 통해 이 청구 세트를 사용 가능하게 하는 java.security.Principal 인터페이스 확장인 org.eclipse.microprofile.jwt.JsonWebToken 인터페이스
  • JWT(JSON Web Token) 및 청구를 다양한 Java EE 컨테이너 API(Application Programming Interface)에 맵핑

MicroProfile용 JWT RBAC에서 MP-JWT 스펙 및 API를 찾으십시오.

MP-JWT 토큰을 소유하는 신뢰 당사자는 해당 토큰을 사용하여 권한 부여 헤더를 통해 토큰을 보내 Liberty의 연관된 자원에 액세스할 수 있습니다. 토큰 연결 형식은 다음 예제에 표시된 대로 RFC 6750 스펙, OAuth 2.0 권한 부여 프레임워크: 전달자 토큰 사용법을 따라야 합니다.

GET /resource/1 HTTP/1.1
Host: example.com
Authorization: Bearer <MP-JWT token>
Liberty 자원 서버는 MP-JWT 토큰을 유효성 검증하고, 인증된 JWT(JSON Web Token)를 작성하며, CDI 인젝션 또는 JAX-RS 보안 컨텍스트를 통해 JWT(JSON Web Token) 및 토큰 청구를 사용 가능하게 합니다. 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. mpJwt-1.0 기능 및 기타 필요한 기능을 server.xml 파일에 추가하십시오. 최소한 mpJwt-1.0 기능에는 AppSecurity-2.0jaxrs-2.0 기능이 필요하며 주로 CDI(Contexts and Dependency Injection) 기능과 함께 사용됩니다.
    <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 속성을 추가하십시오. JWT(Java Web Token)에서 iss 청구와 일치하는 이 속성의 값을 입력하십시오.
    2. JWT에 aud 청구가 포함되어 있는 경우 audiences 속성을 추가하십시오. JWT에서 aud 청구 값 하나가 포함된 이 속성의 값을 입력하십시오.
    3. jwksUri 속성을 추가하십시오. JWK(JSON Web Key)의 URL과 일치하는 이 속성의 값을 입력하십시오. 다음 코드는 JWK가 있는 일반 mpJwt 구성 요소를 보여줍니다.
      <mpJwt 
           id="myMpJwt"
           jwksUri="https://example.com/api/jwk"
           issuer="https://example.com/api/v1"
           audiences="conferenceService">
      </mpJwt>
    4. SSL(Secure Sockets Layer) 구성의 truststore 파일에 JWT 서명 유효성 검증 키를 추가하는 경우 keyName 속성을 추가하십시오. keyName 속성은 truststore 파일에 키 별명을 지정합니다. 다음 코드는 샘플 mpJwt 구성을 보여줍니다.
      <mpJwt 
           keyName="mpJwtValidationKey"
           issuer="https://example.com/api/v1"
           audiences ="conferenceService">
      </mpJwt>
  3. Liberty 서버가 JWK 엔드포인트에 대한 SSL 연결을 작성할 수 있도록 하려면 JWK 엔드포인트 인증서를 포함하도록 truststore 파일을 구성하십시오.
    1. server.xml 파일의 keystore 요소에 truststores를 구성하십시오.
    2. truststore 파일을 참조하도록 SSL을 구성하십시오.
    3. SSL 구성을 서버 기본 SSL 구성으로 설정하거나 mpJwt 요소의 sslRef 속성에 truststore ID를 지정하십시오.
    4. JWT 발급자가 JWK를 지원하지 않고 JWT가 X.509 인증서로 서명된 경우 발급자의 X.509 인증서를 SSL 구성의 truststore 파일로 가져오십시오.
  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 Type, ClaimValue, javax.inject.ProviderJSON-P 유형을 통해 org.eclipse.microprofile.jwt.JsonWebToken API를 삽입하십시오.
    @RequestScopedpublic 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 프린시펄이 포함되어 있습니다. 한 프린시펄은 JWT(JSON Web Token)입니다.
  8. 옵션: [17.0.0.4 and later]어노테이션이 있는 JAX-RS 자원과 JWT의 그룹 청구를 보안하십시오. @RolesAllowed에 사용된 보안 역할 이름을 JWT의 그룹 청구에 있는 그룹 이름으로 맵핑하십시오. 역할 이름과 그룹 이름이 동일하면, application-bnd 요소에서 역할 맵핑을 생략할 수 있습니다. 그러나 JWT가 그룹 정보를 포함하는 MP-JWT이면 역할-그룹 연관을 선언하기 위해 application-bnd 요소에서 맵핑합니다. 자세한 정보는 어노테이션을 사용하여 JAX-RS 자원 보안 설정, ID 액세스 및 인증, 역할 맵핑 바인드를 제공하지 않을 때 애플리케이션을 위한 인증의 내용을 참조하십시오.
  9. 옵션: [17.0.0.4 and later]구성된 Liberty 사용자 레지스트리에 대해 JWT의 사용자 프린시펄 이름을 검사하도록 Liberty를 구성하십시오.

    기본적으로 이 프로그램은 사용자 레지스트리를 요구하지 않고 확인된 JWT에서 직접 보안 주제를 작성합니다. 이 동작을 변경하려면 server.xml 파일에 mapToUserRegistry="true" 구성 속성을 추가할 수 있습니다. 프로그램이 구성된 사용자 레지스트리에 대해 프린시펄 이름을 검색하고 사용자 레지스트리의 사용자 속성을 기반으로 하여 보안 주제를 작성합니다.

  10. 옵션: [17.0.0.4 and later]로그인 메소드 이름이 MP-JWT인 애플리케이션에만 mpJwt-1.0 기능을 적용하도록 Liberty를 구성하십시오.
    기본적으로 mpJwt-1.0 기능이 구성된 경우 권한 부여된 모든 요청은 HTTP 헤더에 올바른 JWT를 포함해야 합니다. 일부 애플리케이션에서만 JWT 인증 토큰이 필요하도록 기본 동작을 수정하려면 server.xml 파일의 <mpJwt> 요소에 ignoreApplicationAuthMethod="false" 구성 속성을 추가하십시오. 그런 다음 두 방법 중 하나로 애플리케이션을 구성하십시오.
    • 애플리케이션에 MP-JWT 로그인 메소드가 인증 메소드로 선언된 @LoginConfig 어노테이션이 있습니다.

      예: @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 and later]Liberty가 다른 JAX-RS 서비스를 호출할 때 자동으로 MP-JWT를 인증 메소드로 전파하도록 Liberty를 구성하십시오.

    Liberty가 JAX-RS 2.0 클라이언트로도 작동하는 경우 <webTarget> 구성 요소에 authnToken="mpjwt" 명령문을 추가합니다. 그러면 Liberty JAX-RS 클라이언트는 자동으로 JWT를 JAX-RS 서비스 호출의 권한 부여 헤더로 추가합니다. 예를 들어 <webTarget uri="http://localhost:56789/protectedResourceWithMPJWT*" authnToken="mpjwt" /> 요소를 server.xml 파일에 추가하는 경우 http://localhost:56789/protectedResourceWithMPJWT/ 서비스가 호출되면 JWT 토큰이 권한 부여 헤더에 추가됩니다.


주제의 유형을 표시하는 아이콘 태스크 주제

파일 이름: twlp_sec_json.html