Realm Configuration HOW-TO

Quick Start

이 문서는 사용자, 비밀번호, 역할을 갖고 있는 기존 "데이터베이스" 에 연결해서 컨테이너가 관리하는 보안 container managed security을 지원하기 위해 톰캣 설정방법을 설명합니다. 하나 이상의 <security-constraint> 엘리먼트와, 사용자가 인증할 때 어떠한 방식으로 할지 정하는 하나의 <login-config> 엘리먼트를 갖고있는 웹 애플리케이션을 사용한다면 이것만 신경쓰면 됩니다. 이러한 기능을 사용하지 않는다면, 이 문서를 읽지 않아도 무방합니다.

컨테이너 관리 보안에 관한 기본적인 배경 지식은 Servlet Specification (Version 2.3), Section 12를 보십시오. 웹 애플리케이션 개발자와 관리자용 초보 수준의 문서는 아직 준비중입니다. (FIXME - link to backgrounder on container managed security to be provided).

Tomcat 4의 단일 인증 Single Sign On 기능 사용에 관한 정보( 가상 호스트와 관계된 전체 웹 애플리케이션을 한번 인증을 통해서 접근하는)는 여기를 보십시오.

개관 Overview

Realm 이란 무엇인가? What is a Realm?

Realm은 하나의 웹 애플리케이션(또는 복수의) 정당한 사용자들을 인증하고, 아울러 각 사용자에 맞는 역할 roles을 지정하는 사용자와 비밀번호의 "database" 입니다. 역할은 Unix 계열의 시스템에서 그룹 groups 과 비슷하다고 생각하면 됩니다. 왜냐하면 특정한 웹 애플리케이션 자원에 접근하는 것은 특정한 역할을 갖고 있는 모든 사용자에게만 주어지기 때문입니다(연관된 사용자 목록 열거가 아닌). 어떤 특정한 사용자는 그 사용자명에 대해서 여러개의 역할을 가질 수 있습니다.

서블릿 사양서가 애플리케이션이 보안 요구사항을 선언 declare하기 위해 이식성있는 메카니즘을 기술합니다만(web.xml 배치 지시자에서), 서블릿 컨테이너와 관련된 사용자와 역할 사이에 인터페이스를 정의하는 이식성있는 API는 없습니다. 그러나, 많은 경우 서블릿 컨테이너를 제품 환경에서 이미 구현된 기존의 인증 데이타베이스나 메카니즘과 "연결"하는 것은 바람직한 일입니다. 그러므로, 톰캣 4 는 이 연결을 설정하는 "plug in" 컴포넌트에 의해 구현될 수 있는 자바 인터페이스 (org.apache.catalina.Realm)를 정의합니다. 세가지 다른 인증 정보 소스에 연결을 지원하는 세가지 표준 plug-in 이 제공됩니다:

JDBCRealm - JDBC 드라이버를 통해서 관계 데이터베이스에 저장된 인증 정보에 접근합니다.

JNDIRealm - JNDI 제공자(provider)를 통해서 LDAP 기반 디렉토리 서버에 저장된 인증 정보에 접근합니다.

MemoryRealm - XML 문서(conf/tomcat-users.xml) 에 있는 정보로부터 초기화되는 내부 메모리 객체 컬렉션에 저장된 인증 정보에 접근합니다.

직접 Realm 구현을 만든 후 Tomcat 에 통합시키는 것도 가능합니다. 그러나, 이것에 관한 것은 이 문서의 범주를 벗어납니다. 더 자세한 정보는 (FIXME - reference to developer stuff)를 보십시오.
Realm 설정하기 Configuring a Realm
표준 Realm 구현의 자세한 내용을 보기 전에, Realm 이 어떻게 설정되는지를 이해해야합니다. 보통 conf/server.xml 환경설정 파일에 XML 엘리먼트를 추가하게 되며, 다음과 같을 것입니다:
<Realm className="... 이 구현에 관한 class 명"
       ... 이 구현을 위한 다른 속성들 .../>
<Realm> 엘리먼트는 해당 Realm 의 "scope" 에 직접적인 영향력을 갖고 있는 세가지 다른 엘리먼트들 중 하나의 내부에 중첩될 수 있습니다. (즉, 어떤 웹 애플리케이션들이 같은 인증 정보를 공유할 것인지 같은...):

<Engine> 엘리먼트 내부 - 이 Realm 은 모든 웹 애플리케이션들과 모든 가상 호스트들이 공유할 수 있습니다. 예외적인 경우는 종속적인 <Host> 또는 <Context> 엘리먼트 내부에 중첩된 Realm 이 있을 때 이것은 제외됩니다.

<Host> 엘리먼트 내부 - 이 Realm 은 한 가상 호스트 내의 모든 웹 애플리케이션들이 공유할 수 있습니다. 예외적인 경우는 종속적인 <Context> 엘리먼트 내부에 중첩된 Realm 이 있을 때 이것은 제외됩니다.

<Context> 엘리먼트 내부 - 이 Realm 은 오로지 이 웹 애플리케이션에서만 사용됩니다.

표준 Realm 구현체 Standard Realm Implementations

JDBCRealm
소개

JDBCRealm 은 JDBC 드라이버를 통해 접근되는 관계형 데이터베이스에 있는 사용자를 찾는 Tomcat 4 Realm 인터페이스의 구현입니다. 데이터베이스 구조가 다음 요건에 부합한다면 기존 테이블과 컬럼에 적용할 수 있는 실질적인 환경설정 유동성을 갖고 있습니다:

이 Realm 이 인식할 수 있는 각각의 유효한 사용자마다 한개의 Row 를 갖고 있는 참조할 수 있는 users 테이블이 있어야 합니다.

users 테이블은 적어도 2개 이상의 컬럼이 있어야 합니다. (기존 애플리케이션에서 사용하는 것이 더 있어도 됩니다.):

사용자명은 로그인할 때 Tomcat 에 의해 인식됩니다.

비밀번호는 로그인할 때 Tomcat 에 의해 인식됩니다. 이 값은 일반텍스트나 암호화된 것도 상관없습니다. - 아래 더 자세한 정보를 보십시오.

특정 사용자에 할당되는 유효한 각각의 역할마다 한 Row를 갖고 있는 user roles 테이블이 있어야합니다. 한 사용자에 대해서 역할 정보가 없어도 되고, 하나 이상있어도 됩니다.

user roles 테이블은 적어도 2개 이상의 컬럼이 있어야 합니다. (기존 애플리케이션 에서 사용하는 것이 더 있어도 됩니다.):

사용자명은 Tomcat 에 의해 인식됩니다.( 동일한 값이 users 테이블에 있어야 합니다).

이 사용자와 관계된 유효한 역할 명이 있습니다.

Quick Start

JDBCRealm 을 사용하기 위해 Tocmat 을 설정하려면 다음과 같은 단계를 따라야합니다:

위에 언급한 형태의 Table 이 없다면, 위 요건에 맞는 테이블과 컬럼을 만드십시오.

적어도 읽기 가능한 속성을 가진 위에 기술된 테이블을 사용할 데이터베이스 사용자명과 비밀번호를 설정하십시오. (Tomcat은 이들 테이블에 쓰기 작업을 절대 하지 않습니다.)

사용할 JDBC 드라이버를 $CATALINA_HOME/server/lib 디렉토리(웹 애플리케이션이 접근하지 않아도 된다면)나 또는 $CATALINA_HOME/common/lib 디렉토리(Tomcat 4 와 웹 애플리케이션 모두 사용한다면) 에 복사하십시오. 주의할 점은 오직 JAR 파일만 인식됩니다!

$CATALINA_HOME/conf/server.xml 파일에서 아래처럼 <Realm> 엘리먼트를 설정하십시오.

Tomcat 4 를 재시동하십시오.

Realm 엘리먼트 속성들

JDBCRealm 을 설정하려면, $CATALINA_HOME/conf/server.xml 파일에서 <Realm> 엘리먼트를 추가하고 위에서 설명한 대로 내재시켜야 합니다. 다음의 속성들은 이 구현에서 지원되는 것들입니다:

Attribute Description
className
이 Realm 구현의 전체 Java 클래스 명. 반드시 이곳에 "org.apache.catalina.realm.JDBCRealm" 을 사용해야 합니다.

connectionName
JDBC 연결에 사용되는 데이터베이스 사용자명.

connectionPassword
JDBC 연결에 사용되는 데이터베이스 비밀번호.

connectionURL
JDBC 연결에 사용되는 데이터베이스 URL

debug
관련된 Logger 에 남겨지는 이 Realm 정보의 디버깅 정보 수준. 높은 숫자는 더 자세한 정보를 남깁니다. 기본값으로 디버깅 정보 수준은 0 입니다.

digest
일반적인 텍스트가 아닌 형태로 비밀번호를 저장하는데 사용하는 다이제스트 알고리즘. 유효한 밸브는 java.security.MessageDigest 클래스에 의해 받아들여지는 알고리즘명입니다. 자세한 정보는 Digested Passwords 를 보십시오. 만일 지정되지 않았다면, 비밀번호는 일반 텍스트로 저장됩니다.

driverName
사용하는 JDBC 드라이버의 전체 경로명. 적절한 밸브를 위해서 JDBC 드라이버의 문서를 참조하십시오.

roleNameCol
현 사용자에 할당된 역할 명을 갖고 있는 user roles 테이블의 컬럼 이름

userCredCol
현 사용자의 비밀번호(일반텍스트 또는 digest 속성이 설정되어서 다이제스트 되어 있는)를 갖고 있는 users 테이블에서 컬럼 이름.

userNameCol
users 와 user roles 테이블에서 현사용자의 사용자명을 갖고 있는, 컬럼 이름.

userRoleTable
특정한 username에 할당된 각각의 role 마다 하나씩의 row를 갖고 있는 테이블의 이름. 이 테이블은 최소한 userNameCol 과 roleNameCol 속성에 의해 명명된 컬럼들을 갖고 있어야 합니다.

userTable
Tomcat 에서 인식되는 각가의 username 마다 하나의 row를 갖고 있는 테이블 이름. 이 테이블은 최소한 userNameCol 과 userCredCol 속성에 의해 명명된 컬럼들을 갖고 있어야 합니다.

예제

필요한 테이블을 생성하는 예제 SQL 스크립트는 이것과 같을 것입니다 (각자의 데이터베이스에 맞게 수정하십시오):
create table users (
  user_name         varchar(15) not null primary key,
  user_pass         varchar(15) not null
);

create table user_roles (
  user_name         varchar(15) not null,
  role_name         varchar(15) not null,
  primary key (user_name, role_name)
);
예제의 Realm 엘리먼트는 기본 $CATALINA_HOME/conf/server.xml 파일에 (주석을 제거하고) 포함되어 있습니다. 다음은 위에 있는 테이블들로 설정되고, 사용자명 "dbuser" 와 비밀번호 "dbpass"로 접근할 수 있는 "authority" 라는 MySQL 데이터베이스를 사용한 예제입니다:
<Realm className="org.apache.catalina.realm.JDBCRealm" debug="99"
      driverName="org.gjt.mm.mysql.Driver"
   connectionURL="jdbc:mysql://localhost/authority?user=dbuser&password=dbpass"
       userTable="users" userNameCol="user_name" userCredCol="user_pass"
   userRoleTable="user_roles" roleNameCol="role_name"/>
추가 주의사항 Additional Notes

JDBCRealm 은 다음 규칙에 따라 동작합니다:

맨처음 보호된 자원에 접근하려고 시도할 때에 Tomcat 4 는 현재 Realm 의 authenticate() 메소드를 호출합니다. 그러므로, 데이터베이스에 변경된 사항(새로운 사용자, 비밀번호, 역할의 변경, 등)은 바로 반영됩니다.

일단 인증을 통과한 사용자(그 사용자의 역할도 함께)는 로그인해 있는 동안 Tomcat에 캐쉬됩니다. (FORM기반 인증은 session 시간이 종료되거나 무효화될 때까지이고; BASIC 인증은 사용자가 브라우저를 닫을 때 까지입니다.) 이미 인증된 사용자는 데이터베이스가 변경되어도 다음 로그인할 때까지 반영되지 않습니다.

users 와 user roles 테이블에 있는 정보를 관리하는 것은 애플리케이션이 담당할 부분입니다. Tomcat 내부적으로 사용자와 역할을 관리하는 기능은 제공되지 않습니다.

Realm 에서 로그로 남겨지는 디버깅과 예외메시지는, 사용되고 있는 환경의 Context, Host, Engine 에 있는 Logger 에 의해 기록됩니다. 기본적으로, 해당 Logger 는 $CATALINA_HOME/logs 디렉토리에 log 파일을 생성합니다.
JNDIRealm
소개

JNDIRealm 은 JNDI 제공자(전형적으로, JNDI API 클래스를 사용하는 표준 LDAP 제공자)에 의해 접근되는 디렉토리 서버에 있는 사용자를 찾는 Tomcat 4 의 Realm 인터페이스 구현입니다. realm 은 디렉토리 별 인증에 따라 다양한 접근을 지원합니다.

디렉토리에 연결하기 Connecting to the directory

realm 의 디렉토리 연결은 connectionURL 설정 속성에 따라 정해집니다. JNDI 제공자가 지정하는 형태의 URL 입니다. 보통 LDAP URL 이며, 이것은 연결할 디렉토리 서버의 도메인 이름이나 선택적으로 필요한 루트 네이밍 컨텍스트의 포트 번호와 구분명 distinguished name (DN)을 지정합니다.

디렉토리 검색과 사용자와 역할 정보를 가져오기 위해 연결할때, realm 은 connectionName 와 connectionPassword 속성에 지정된 사용자 명과 비밀번호로 직접 디렉토리에 인증을 시도합니다. 이 속성값이 지정되지 않았다면 익명 연결이 됩니다. 대부분의 경우 충분합니다.

사용자 디렉토리 엔트리 선택하기 Selecting the user's directory entry

인증된 각각의 사용자는 디렉토리에서 connectionURL 속성에 정의된 초기 DirContext 에 있는 엘리면트에 해당되는 개별 엔트리에 의해 대표되어야 합니다. 이 사용자 엔트리는 인증에 사용된 사용자 명을 속성으로 갖고 있어야 합니다.

종종 사용자 엔트리의 구분명은 인증을 나타내는 사용자명을 포함하지만 그 외의 경우 모든 사용자가 동인합니다. 이런 경우 userPattern 속성이 DN을 지정하기 위해서 사용되며, 사용자명으로 대체될 "{0}" 표시가 사용됩니다.

그 외의 경우 realm 은 사용자명을 포함하는 유일한 엔트리를 찾기위해 디렉토리를 검색해야됩니다. 다음 속성들은 이 검색에 사용됩니다:

userBase - 사용자들을 포함하는 서브트리의 베이스가 되는 엔트리. 지정되지 않으면, 최상위수준의 컨텍스트가 검색 베이스로 됩니다.

userSubtree - 검색 스코프. true 로 정할 경우 userBase 엔트리로부터 전체의 서브트리를 검색하게 됩니다. 기본 값은 false 이며 최상위 수준을 포함하는 하나의 수준만 검색하게됩니다.

userSearch - 사용자명을 대체한 후 LDAP 검색필터를 지정하는 패턴.

사용자 인증하기 Authenticating the user

바인드 모드 Bind mode

기본적으로 realm은 사용자와 제시한 패스워드에 대한 엔트리의 구분명DN으로 디렉토리에 바인딩함으로 사용자인증을 합니다. 이런 간단한 바인드가 성공하면 사용자는 인증된 것으로 간주됩니다.

보안 이유로 디렉토리는 사용자의 패스워드를 일반텍스트 형태가 아닌 다이제스트된 형태로 저장합니다(더 자세한 정보는 Digested Passwords). 그런 경우, 단순 바인드 작업의 일부분으로 디렉토리는 자동으로 저장된 값에 비교하기 전에 사용자의 일반텍스트 패스워드의 올바른 다이제스트를 계산합니다. 그러므로, 바인드 모드에서 realm 은 다이제스트 처리에 연관되지 않습니다. digest 속성은 사용되지 않으며, 설정되어도 무시됩니다.

비교 모드 Comparison mode

다른 한 편, realm 은 디렉토리에서 저장된 패스워드를 불러와서 명시적으로 사용자가 입력한 값과 비교할 수 있습니다. 패스워드를 가진 사용자 엔트리의 디렉토리 속성명에 대해서 userPassword속성을 설정할 경우 이 모드가 됩니다.

비교모드는 몇가지 단점이 있습니다. 우선, connectionName 과 connectionPassword 속성을, 디렉토리에 있는 사용자의 패스워드들을 realm 이 읽도록 설정해야됩니다. 보안의 관점에서 이는 바람직하지 않습니다; 실제로 대다수의 디렉토리 구현체는 디렉토리 관리자 조차 이들 패스워드를 보는 것을 허용하지 않습니다. 추가적으로, realm 은 직접 패스워드 다이제스트도 처리해야되며, 여기에는 디렉토리에 있는 패스워드 해쉬를 구현하는데 사용된 알고리즘의 변형도 포함됩니다. 그러나 HTTP 다이제스트 접근 인증(RFC 2069)을 지원하는 것처럼, 때로는 저장된 패스워드에 접근할 필요가 있습니다. (주지할 것은 위에서 논의한 사용자 정보에 대한 저장소의 패스워드 창고와 HTTP 다이제스트 인증은 다르다는 것입니다.)

사용자의 역할 부여 Assigning roles to the user

디렉토리 realm 은 디렉토리의 역할 표시에 접근하는 방법으로 두가지를 지원합니다:

명시적인 디렉토리 엔트리로서의 역할 Roles as explicit directory entries

역할은 명시적인 디렉토리 엔트리에 의해 나타내어질 수 있습니다. 역할 엔트리는 보통 하나의 LDAP 그룹 엔트리입니다. 역할명을 포함하는 하나의 속성과 , 다른 하나의 속성은 구분명들이나 그 역할에 해당하는 사용자들의 사용자명을 값으로 가지고 있습니다. 다음 속성들은 인증된 사용자와 연관된 역할들의 이름을 찾기 위한 디렉토리 검색을 설정합니다:

roleBase - 역할 검색을 위한 기반 엔트리. 지정되지 않으면, 검색 기반은 최상위레벨 디렉토리 컨텍스트가 됩니다.

roleSubtree - 검색 범위. roleBase 엔트리를 기준으로 전체 하위 디렉토리를 검색하려면 true 로 설정합니다. 기본 값은 false이고 탑 레벨만 포함하는 싱글레벨 검색만 하게 됩니다.

roleSearch - 역할 엔트리를 선택하는 LDAP 검색 필터. 선택적으로 패턴을 포함합니다. "{0}" 은 구분명에 대해서 "{1}" 은 인증된 사용자의 사용자명에 대치됩니다.

roleName - 해당 역할 이름을 포함하는 역할 엔트리에 있는 속성

사용자 엔트리의 속성으로서의 역할 Roles as an attribute of the user entry

역할 이름은 사용자 디렉토리 엔트리의 속성에 있는 값에서 가져올 수도 있습니다. 이 속성의 이름을 지정하기 위해서 userRoleName를 사용합니다.

역할 표시에 두 가지 접근방식의 조합이 사용될 수도 있습니다.

Quick Start

JNDIRealm 을 사용하기 위해 Tomcat 을 설정하려면 다음과 같은 단계가 필요합니다:

디렉토리 서버의 구성된 스키마가 위에 나열된 요구사항들에 부합되는지 먼저 확인합니다.

필요하다면, Tomcat 에서 사용할 사용자명과 비밀번호를 설정합니다. 위에 기술된 정보에 적어도 읽기전용 접속권한을 갖고 있어야 합니다. (Tomcat 은 이 정보를 절대 수정하려고 하지 않습니다.)

사용할 JNDI 드라이버(전형적으로 JNDI가 가능한 ldap.jar)를 $CATALINA_HOME/server/lib 디렉토리 내에 복사해 놓거나(웹 애플리케이션에서 사용하지 않는 경우라면) , 또는 $CATALINA_HOME/common/lib 디렉토리에 복사해 놓습니다(Tomcat 4 와 웹 애플리케이션 모두 사용하는 드라이버라면).

$CATALINA_HOME/conf/server.xml 파일에 아래와 같이 <Realm> 엘리먼트를 설정합니다.

구동중이라면 Tomcat 4를 재시동합니다.

Realm 엘리먼트 속성들 Realm Element Attributes

JNDIRealm 설정하려면, 위에서 설명한 대로 $CATALINA_HOME/conf/server.xml 파일에 <Realm> 요소를 만들어야 합니다. 이 구현에 지원되는 속성들은 다음과 같습니다:

Attribute Description
className
이 Realm 구현의 전체 Java 클래스 명. 여기에 반드시 "org.apache.catalina.realm.JDBCRealm" 를 써줘야 합니다.

connectionName
LDAP 검색 작업용 디렉토리에 연결설정시 사용할 디렉토리 사용자명. 지정되지 않았다면 익명(anonymous) 연결이 만들어지고, 보통은 userPassword 프로퍼티를 지정하지 않아도 됩니다.

connectionPassword
LDAP 검색 작업용 디렉토리에 연결설정시 사용할 디렉토리 비밀번호. 지정되지 않았다면 익명(anonymous) 연결이 만들어지고, 보통은 userPassword 프로퍼티를 지정하지 않아도 됩니다.

connectionURL
LDAP 검색 작업용 디렉토리에 연결설정시 JNDI 드라이버에 건네줄 연결 URL.

contextFactory
이 연결에 사용될 JNDI 컨텍스트 팩토리의 전체 Java 클래스명. 기본적으로, 표준 JNDI LDAP 프로바이더가 사용됩니다. (com.sun.jndi.ldap.LdapCtxFactory).

debug
관련된 Logger 에 남겨지는 이 Realm 정보의 디버깅 정보 수준. 높은 숫자는 더 자세한 정보를 남깁니다. 기본값으로 디버깅 정보 수준은 0 입니다.

digest
일반적인 텍스트가 아닌 형태로 비밀번호를 저장하는데 사용하는 다이제스트 알고리즘. 유효한 밸브는 java.security.MessageDigest 클래스에 의해 받아들여지는 알고리즘명입니다. 자세한 정보는 Digested Passwords 를 보십시오. 만일 지정되지 않았다면, 비밀번호는 일반 텍스트로 저장됩니다. userPassword 가 지정되지 않았다면 필요없습니다.

roleBase
역할 검색을 위한 베이스 디렉토리 엔트리. 지정되지 않으면, 디렉토리 컨텍스트에 있는 최상위 엘리먼트가 사용됩니다.

roleName
역할 검색이 찾는 디렉토리 엔트리의 역할명을 갖고 있는 속성의 이름. 추가로 속성 이름을 지정하기 위해 사용자 엔트리에 있고 추가 역할 이름을 포함하는 userRoleName 프로퍼티를 사용할 수 있다. 만일 roleName 이 지정되지 않으면 역할 검색을 하지 않고, 역할은 사용자 엔트리에서만 가져온다.

roleSearch
java.text.MessageFormat 의 문법을 따르는, 역할 검색에 사용되는 LDAP 필터 표현식. 사용자 구분명(DN) 자리는 {0} 를 사용하고, 사용자명 자리에는 {1} 을 사용합니다. 지정되지 않으면 역할 검색은 하지 않고 userRoleName 속성에 지정된 사용자 엔트리에 있는 속성에서만 가져옵니다.

roleSubtree
사용자에 관계된 역할 엔트리에 대한 roleBase 로 지정된 엘리먼트의 하위트리를 검색하려면 true 로 설정한다. false 가 기본값이며 상위레벨만 찾게된다.

userBase
userSearch 표현식을 사용해서 사용자 검색을 수행하는 것에 대한 기반 엘리먼트. 지정되지 않았다면, 디렉토리 컨텍스트에 있는 상위 레벨 엘리먼트가 사용된다. userPattern 표현식을 사용한다면 사용하지 않음.

userPassword
사용자의 비밀번호를 포함하는 사용자 엔트리에 있는 속성의 이름. 이 값을 지정하면, JNDIRealm 은 connectionName 과 connectionPassword 속성에 지정된 값을 사용해서 디렉토리에 바인드할 것이고, 인증된 사용자가 지정한 값과 비교해서 해당 속성을 불러올 것이다. digest 속성이 설치된 경우, 지정된 다이제스트 알고리즘은 디렉토리에서 불러온 값과 비교하기 전에 사용자가 제시한 비밀번호에 적용된다. 이 값을 지정하지 않으면, JNDIRealm 은 사용자의 지정한 엔트리와 패스워드의 구분명 DN을 사용하는 디렉토리에 대해 단순한 바인드를 시도할 것이다.

userPattern
사용자 디렉토리 엔트리의 구분명에 대한 패턴이고, java.text.MessageFormat 의 문법을 따른다. 실제 사용자명의 자리는 {0} 로 표시된다. 구분명이 사용자 이름을 포함하며 다른 모든 사용자들에 대해서도 동일할 경우에 userSearch, userSubtree, userBase 대신 이 속성을 사용할 수 있다.

userRoleName
이 사용자에 정해진 역할의 이름들에 대한 0 개 이상의 값을 갖고 있는 사용자 디렉토리 엔트리에 있는 속성의 이름. 추가로 디렉토리 검색에서 발견된 개별적인 역할 엔트리들로부터 불러온 속성의 이름을 지정하기 위해 roleName 프로퍼티를 사용할 수 있다. 만일 userRoleName 이 지정되지 않았다면 사용자에 대한 모든 역할들은 역할 검색으로부터 끌어온다.

userSearch
사용자 디렉토리 엔트리 검색에 사용되는 LDAP 필터 표현식. 실제 사용자명의 자리는 {0} 로 표시된다. 사용자 엔트리에 대해 디렉토리 검색을 하려면 userPattern 대신에 이 프로퍼티를 사용한다(userBase 과 userSubtree 프로퍼티와 함께).

userSubtree
사용자 엔트리에 대해 userBase 프로퍼티에서 지정된 엘리먼트의 전체 하위 디렉토리를 검색하려면 true 로 설정합니다. 기본 값은 false이고 탑 레벨만 검색하게 됩니다. userPattern 표현식을 사용한다면 사용되지 않습니다.

예제

디렉토리 서버에서 적절한 스키마를 만드는 법은 이 문서의 범위를 벗어납니다. 왜냐하면 각각의 디렉토리 서버 구현마다 다르기 때문입니다. 아래 예제에서 OpenLDAP 디렉토리 서버 (2.0.11 이상 버전)를 사용한다고 가정합니다. 이것은 http://www.openldap.org 에서 다운로드 받을 수 있습니다. slapd.conf 파일에는 다음 세팅을 포함한다고 가정합니다:
database ldbm
suffix dc="mycompany",dc="com"
rootdn "cn=Manager,dc=mycompany,dc=com"
rootpw secret
connectionURL 에 대해 가정하는 것은 디렉토리 서버가 운용되는 동일한 컴퓨터에서 톰캣이 운용된다는 것입니다. JNDI LDAP 제공자(provider) 설정과 사용법에 관한 자세한 정보는 http://java.sun.com/products/jndi/docs.html 를 보세요.

다음으로, 이 디렉토리 서버는 아래 보이는 엘리먼트로 활성화 되었다고 가정합니다.(LDIF 형식으로):
# Define top-level entry
dn: dc=mycompany,dc=com
objectClass: dcObject
dc:mycompany

# Define an entry to contain people
# searches for users are based on this entry
dn: ou=people,dc=mycompany,dc=com
objectClass: organizationalUnit
ou: people

# Define a user entry for Janet Jones
dn: uid=jjones,ou=people,dc=mycompany,dc=com
objectClass: inetOrgPerson
uid: jjones
sn: jones
cn: janet jones
mail: j.jones@mycompany.com
userPassword: janet

# Define a user entry for Fred Bloggs
dn: uid=fbloggs,ou=people,dc=mycompany,dc=com
objectClass: inetOrgPerson
uid: fbloggs
sn: bloggs
cn: fred bloggs
mail: f.bloggs@mycompany.com
userPassword: fred

# Define an entry to contain LDAP groups
# searches for roles are based on this entry
dn: ou=groups,dc=mycompany,dc=com
objectClass: organizationalUnit
ou: groups

# Define an entry for the "tomcat" role
dn: cn=tomcat,ou=groups,dc=mycompany,dc=com
objectClass: groupOfUniqueNames
cn: tomcat
uniqueMember: uid=jjones,ou=people,dc=mycompany,dc=com
uniqueMember: uid=fbloggs,ou=people,dc=mycompany,dc=com

# Define an entry for the "role1" role
dn: cn=role1,ou=groups,dc=mycompany,dc=com
objectClass: groupOfUniqueNames
cn: role1
uniqueMember: uid=fbloggs,ou=people,dc=mycompany,dc=com
사용자가 uid(예 jjones) 로 어플리케이션에 로그인 한다는 것과 디렉토리 검색해서 역할 정보를 가져오는데 익명 연결이면 충분하다는 것을 가정한다면 위에 설명한 대로 설정된 OpenLDAP 디렉토리 서버에 대한 Realm 엘리먼트 예제는 다음과 같을 것입니다:
<Realm   className="org.apache.catalina.realm.JNDIRealm" debug="99"
     connectionURL="ldap://localhost:389"
       userPattern="uid={0},ou=people,dc=mycompany,dc=com"
          roleBase="ou=groups,dc=mycompany,dc=com"
          roleName="cn"
        roleSearch="(uniqueMember={0})"
/>
이런 설정에서, realm 은 사용자의 구분명을 userPattern 에 사용자명으로 대치해서 결정한다. 이 DN 과 사용자가 입력한 비밀번호로 디렉토리에 바인딩해서 인증한 후에 사용자의 역할을 찾기 위해 디렉토리를 검색한다.

만일 로그인 할 때 사용자 아이디가 아닌 이메일 주소를 사용하려고 한다면 어떻게 될까요. 이런 경우 realm 은 사용자 엔트리의 디렉토리를 검색해야만 됩니다. (사용자 엔트리가 아마도 다른 조직 부서나 회사 위치같은 다중의 하위트리에 담겨있을 때 역시 검색은 필요합니다).

더 나아가, 만일 그룹 엔트리에 추가로 역할을 갖고 있는 사용자 엔트리의 속성을 사용하고 싶을 경우는 어떻게 될까요? Janet Jones 에 대한 엔트리를 찾는다면 다음과 같을 것이다:
dn: uid=jjones,ou=people,dc=mycompany,dc=com
objectClass: inetOrgPerson
uid: jjones
sn: jones
cn: janet jones
mail: j.jones@mycompany.com
memberOf: role2
memberOf: role3
userPassword: janet
이 realm 설정법은 새로운 요구를 만족시킨다:
<Realm   className="org.apache.catalina.realm.JNDIRealm" debug="99"
     connectionURL="ldap://localhost:389"
          userBase="ou=people,dc=mycompany,dc=com"
        userSearch="(mail={0})"
      userRoleName="memberOf"
          roleBase="ou=groups,dc=mycompany,dc=com"
          roleName="cn"
        roleSearch="(uniqueMember={0})"
/>
Janet Jones 이 "j.jones@mycompany.com" 로 로그인 한다면, realm 은 메일 속성처럼 유일한 엔트리에 대한 디렉토리를 검색하고, 주어진 비밀번호를 갖고 uid=jjones,ou=people,dc=mycompany,dc=com 처럼 디렉토리에 바인드하려고 시도할 것이다. 인증이 성공하면, 세개의 역할이 할당된다: "role2" 과 "role3" 과 디렉토리 엔트리에 있는 "memberOf" 속성의 값들, "톰캣", 사용자가 소속된 유일한 그룹엔트리 "cn" 속성의 값.

마지막으로, 디렉토리에서 비밀번호를 가져옴으로 사용자 인증을 처리하고 realm 에 있는 로컬 비교를 한다면, realm 설정은 다음과 같을 것입니다:
<Realm   className="org.apache.catalina.realm.JNDIRealm" debug="99"
    connectionName="cn=Manager,dc=mycompany,dc=com"
connectionPassword="secret"
     connectionURL="ldap://localhost:389"
      userPassword="userPassword"
       userPattern="uid={0},ou=people,dc=mycompany,dc=com"
          roleBase="ou=groups,dc=mycompany,dc=com"
          roleName="cn"
        roleSearch="(uniqueMember={0})"
/>
그러나, 위에서 논의된 것처럼, 인증을 위한 기본 바인드 모드가 보통 잘 쓰입니다.

추가 주의사항 Additional Notes

JNDIRealm 는 다음 규칙에 따라서 동작합니다:

사용자가 보호된 자원에 처음으로 접근을 시도하면 Tomcat 4는 해당 Realm 의 authenticate() 메소드를 호출하게 됩니다. 그러므로, 직접 데이터베이스에 변경한 것(새 사용자, 비밀번호나 역할 변경, 등)은 즉시 반영됩니다.

일단 사용자가 인증을 통과하면, 사용자(이에 관계된 역할) 는 사용자 로그인 세션 동안 Tomcat 내에 캐시됩니다. (FORM기반 인증에서는, 세션이 시간 종료되거나 무효화 될때까지를 뜻하고; BASIC 인증에서는, 사용자가 브라우저를 닫을 때까지를 뜻합니다). 이미 인증된 사용자의 데이터베이스 정보에 변화가 생기면 바로 반영되지 않고 다시 사용자가 로그인 하는 시점에 반영됩니다.

디렉토리 서버에 있는 정보의 관리는 해당 애플리케이션의 책임입니다. Tocmat 은 사용자와 역할을 유지하기 위해서 어떠한 내장된 기능도 제공하지 않습니다.

Realm 에서 로그로 남겨지는 디버깅과 예외메시지는, 사용되고 있는 환경의 Context, Host, Engine 에 있는 Logger 에 의해 기록됩니다. 기본적으로, 해당 Logger 는 $CATALINA_HOME/logs 디렉토리에 log 파일을 생성합니다.
MemoryRealm
소개

MemoryRealm은 Tomcat 4 Realm 인터페이스의 단순한 시범 구현체입니다. 실제 서비스하는데 사용하도록 설계된 것이 아닙니다. 시동할 때, MemoryRealm 은 모든 사용자와 해당되는 역할을 XML 문서(기본적으로, 이 문서는 $CATALINA_HOME/conf/tomcat-users.xml 에서 불려집니다 )로부터 불러들입니다. 이 파일의 데이터가 변경될 경우 Tomcat 을 재시작해야 인식됩니다.

Realm 엘리먼트의 속성

MemoryRealm 설정하려면, $CATALINA_HOME/conf/server.xml 파일에서 <Realm> 요소를 추가하고 위에서 설명한 대로 내재시켜야 합니다. 다음의 속성들은 이 구현에서 지원되는 것들입니다:

Attribute Description
className
이 Realm 구현체의 전체 Java 클래스 명. 여기에는 반드시 "org.apache.catalina.realm.MemoryRealm" 값을 넣어줘야 합니다.

debug
관련된 Logger 에 남겨지는 이 Realm 정보의 디버깅 정보 수준. 높은 숫자는 더 자세한 정보를 남깁니다. 기본값으로 디버깅 정보 수준은 0 입니다.

digest
일반적인 텍스트가 아닌 형태로 비밀번호를 저장하는데 사용하는 다이제스트 알고리즘. 유효한 밸브는 java.security.MessageDigest 클래스에 의해 받아들여지는 알고리즘명입니다. 자세한 정보는 Digested Passwords 를 보십시오. 만일 지정되지 않았다면, 비밀번호는 일반 텍스트로 저장됩니다.

pathname
유효한 사용자명, 비밀번호, 역할을 갖고 있는 XML 문서의 절대 또는 상대적 ($CATALINA_HOME에 대해) 경로. 이 파일의 형식에 관한 자세한 정보는 아래에 나와있습니다. 기본 값은 conf/tomcat-users.xml 입니다.

사용자 파일 형식

사용자 파일(기본적으로, conf/tomcat-users.xml)은 root 요소가 <tomcat-users>인 XML 문서이어야 합니다. root 요소 내부에 유효한 사용자마다 <user> 요소가 다음 속성을 갖고 있어야 됩니다:

name - 로그온 할 사용자명.

password - 로그온할 때 필요한 비밀번호( <Realm> 요소에 digest 속성이 지정되어 있지 않다면 일반 텍스트 형태이고, 아니면 여기에서 설명한 양식에 따라서 적절하게 다이제스트된 형태).

roles - 이 사용자에 연관된 쉼표로 구분된 역할명 목록.

예제

Tomcat 4 의 기본 설치에는 MemoryRealm 이 <Engine> 요소에 내재되어 있고, 모든 가상 호스트들과 웹 애플리케이션에 적용될 수 있습니다. conf/tomcat-users.xml 파일의 기본 내용은 다음과 같습니다:
<tomcat-users>
  <user name="tomcat" password="tomcat" roles="tomcat" />
  <user name="role1"  password="tomcat" roles="role1"  />
  <user name="both"   password="tomcat" roles="tomcat,role1" />
</tomcat-users>
추가 주의사항 Additional Notes

MemoryRealm 은 다음 규칙에 따라 동작합니다:

Tomcat 이 시작할 때, 모든 정의된 사용자와 관계된 정보들을 사용자 파일에서 불러들입니다. 이 파일의 데이터를 변경하면 톰캣을 재시동할 때까지 적용되지 않습니다.

사용자가 보호된 자원에 처음으로 접근을 시도하면 Tomcat 4는 이 Realm 의 authenticate() 메소드를 호출하게 됩니다.

일단 사용자가 인증을 통과하면, 사용자(이에 관계된 역할) 는 사용자 로그인 기간동안 Tomcat 내에 캐시됩니다. (FORM기반 인증에서는, 세션이 시간 종료되거나 무효화 될때까지를 뜻하고; BASIC 인증에서는, 사용자가 브라우저를 닫을 때까지를 뜻합니다).

사용자 파일에 있는 정보의 관리는 해당 애플리케이션의 책임입니다. Tocmat 은 사용자와 역할을 유지하기 위해서 어떠한 내장된 기능도 제공하지 않습니다.

Realm 에서 로그로 남겨지는 디버깅과 예외메시지는, 사용되고 있는 환경의 Context, Host, Engine 에 있는 Logger 에 의해 기록됩니다. 기본적으로, 해당 Logger 는 $CATALINA_HOME/logs 디렉토리에 log 파일을 생성합니다.

공통 특성 Common Features

Digested Passwords
표준 Realm 구현체에서 사용자 비밀번호는 (기본적으로) 일반 텍스트로 저장됩니다. 많은 환경에서, 이것은 바람직하지 않습니다. 왜냐하면 우연히 로그온 할 수 있는 인증데이터를 본 사람이 있다면 그 데이터로 접속한 뒤에 다른 사람인척 할 수 있기 때문입니다. 이런 문제를 피하기 위해서, 표준 구현에서 사용자 비밀번호의 다이제스팅 digesting 개념을 지원합니다. 이것은 저장된 비밀번호들이 (쉽게 해독할 수 없는 형태로) 암호화시켜주고, Realm 구현에서는 여전히 인증에 사용할 수 있게됩니다.

<Realm> 요소에 digest 속성을 지정하면 다이제스트된 비밀번호를 사용하게 됩니다. 이 속성을 위한 값은 java.security.MessageDigest 클래스가 지원하는 다이제스트 알고리즘(SHA, MD2, or MD5) 중에 하나입니다. 이 옵션을 선택할 때, Realm에 저장된 비밀번호의 내용은 선택된 알고리즘으로 다이제스트된 일반텍스트형태이어야 됩니다.

Realm의 authenticate() 메소드가 호출될 때, 사용자의 (일반텍스트) 비밀번호는 같은 알고리즘으로 다이제스트되어야 되고, 결과는 Realm에서 반환되는 값과 비교됩니다. 원래 비밀번호의 일반텍스트 형태가 사용자가 입력한 것과 같다는 등식이 성립되면, 이 사용자는 인증을 통과합니다.

일반텍스트 비밀번호의 다이제스트되어진 값을 계산하기 위해, 두 가지 편리한 기술이 지원됩니다:
동적으로 다이제스트된 암호를 계산할 필요가 있는 애플리케이션을 만든다면, 매개변수로 일반텍스트 비밀번호와 알고리즘 이름을 받는 org.apache.catalina.realm.RealmBase 클래스의 정적 Digest() 메소드를 호출합니다. 이 메소드는 다이제스트된 패스워드를 반환합니다.
다이제스트된 비밀번호를 계산하기 위해서 콘솔상에서 실행하기 원한다면, 단순히 다음처럼 실행하면 됩니다.
java org.apache.catalina.realm.RealmBase \
    -a {algorithm} {cleartext-password}
그렇게 되면 표준 출력으로 일반텍스트 패스워드의 다이제스트된 값이 나옵니다.
위의 두가지 방법을 사용하려면, RealmBase 클래스를 사용하기 위해 $CATALINA_HOME/server/lib/catalina.jar 파일이 글래스패스에 잡혀있어야 됩니다.
예제 애플리케이션 Example Application

Tomcat 4 에 있는 예제 애플리케이션은 form 기반 로그인의 사용해서 보안 제한으로 보호되는 지역을 포함하고 있습니다. 접근 주소는 http://localhost:8080/examples/jsp/security/protected/ 이고 MemoryRealm 에 설명한 사용자명과 비밀번호 중의 하나로 로그 온 할 수 있습니다.

관리 애플리케이션 Manager Application

만일 운영중인 Tomcat 4 에서 애플리케이션을 설치와 제거하기 위해서 관리 애플리케이션 Manager Application을 사용하려면, 선택된 Realm 구현에서 적어도 하나 이상의 사용자명에 "manager" 역할을 추가해주어야 합니다. 이렇게 하는 이유는 관리 웹 애플리케이션 내의 모든 요청 주소에 접근하기 위해서는 "manager" 보안 제한을 사용하기 때문입니다.

보안때문에 기본 Realm (즉, conf/tomcat-users.xml 을 사용하는 ) 에는 "manager" 역할로 설정된 사용자명이 없습니다. 그러므로, Tomcat 관리자가 특별히 이 역할을 한사람 이상 지정해주기 전에는 이 애플리케이션을 사용할 수 있는 사용자는 없습니다.