Custom Auth 라이브러리

EIMS에서는 기본적으로 ID/PW 기반 인증을 지원합니다. EIMS 시스템에서 관리하는 사용자 정보를 기반으로 인증을 제공하며, 사용자 커스텀 인증(Custom Auth)을 추가로 지원합니다.

커스텀 인증을 설정하더라도 프론트엔드 변경 없이 기존과 동일한 로그인 UX를 유지할 수 있습니다. 사용자가 입력한 인증 정보는 커스텀 인증 클래스에 전달되며, 해당 클래스에서 사용자 환경에 맞는 인증 로직을 구현할 수 있습니다.

입력 항목의 레이블은 ID/PW로 표시되지만, 실제로는 사용자가 원하는 값을 입력할 수 있습니다.

본 모듈은 커스텀 인증을 구현할 수 있는 SPI(Service Provider Interface)와 내부 호출 서비스를 제공합니다.

패키지 구조

com.tmax.eims.auth
├── spi
│   └── AuthManager.java                    # 커스텀 인증 인터페이스
└── internal
    ├── AuthenticationRequest.java          # 인증 요청 정보
    ├── AuthenticationFailedException.java  # 인증 실패 예외
    ├── User.java                           # 사용자 정보
    └── UserService.java                    # 사용자 조회 서비스

클래스

AuthManager(SPI)

커스텀 인증 로직을 구현할 인터페이스입니다.

public interface AuthManager {
    User authenticate(AuthenticationRequest authenticationRequest, UserService userService) throws Exception;
}

각 파라미터에 대한 설명은 다음과 같습니다.

파라미터 타입 설명

authenticationRequest

AuthenticationRequest

프론트엔드에서 전달된 사용자 인증 정보(ID 및 비밀번호)를 포함하는 요청 파라미터

userService

UserService

사용자 조회를 수행하기 위한 서비스 파라미터(EIMS 백엔드에서 주입)

인증 처리 결과에 따른 반환값 및 예외는 다음과 같습니다.

반환 설명

User

인증 성공 시 인증된 사용자 객체를 반환

null

인증 실패 시 null을 반환

Exception

인증 실패 또는 오류 발생 시 예외를 발생시킴

AuthenticationRequest

프론트엔드에서 사용자가 입력한 인증 요청 정보를 포함하는 클래스입니다.

필드명 타입 설명

username

String

ID 입력 필드 값

password

String

비밀번호 입력 필드 값

UserService

사용자 정보를 조회할 수 있는 서비스 인터페이스입니다.

해당 서비스는 EIMS 백엔드에서 직접 주입되므로 사용자가 직접 구현할 필요가 없습니다.
메서드 반환 타입 설명

getUserById(String id)

User

사용자 ID로 조회

getUserByResourceId(Long resourceId)

User

사용자 PK(resourceId)로 조회

User

인증된 사용자 정보를 포함하는 클래스입니다.

필드명 타입 설명

resourceId

Long

사용자 PK(Primary Key)

id

String

사용자 ID

name

String

사용자 이름

email

String

이메일

role

String

권한

phoneNumber

String

휴대폰 번호

contactNumber

String

연락처

companyName

String

회사명

partName

String

부서명

positionName

String

직책명

inUse

Boolean

사용 여부

isDeleted

Boolean

삭제 여부

AuthenticationFailedException

인증 실패 시 발생시킬 수 있는 예외 클래스입니다.

throw new AuthenticationFailedException("인증 실패 사유");

`message`에 인증 실패 사유를 작성하면 클라이언트에 전달됩니다.

구현 예시

  • ID/PK 기반 인증의 경우

    다음은 ID 필드에 사용자 ID, PW 필드에 사용자 PK(resourceId)를 입력받아 인증하는 커스텀 인증 예시입니다.

    package com.tmax.eims.auth;

import com.tmax.eims.auth.internal.AuthenticationFailedException;
import com.tmax.eims.auth.internal.AuthenticationRequest;
import com.tmax.eims.auth.internal.User;
import com.tmax.eims.auth.internal.UserService;
import com.tmax.eims.auth.spi.AuthManager;

public class CustomAuthManagerSampleImpl implements AuthManager {

    @Override
    public User authenticate(AuthenticationRequest authenticationRequest, UserService userService) throws Exception {
        // 1. 요청 유효성 검증
        if (authenticationRequest == null) {
            throw new AuthenticationFailedException("Request must not be null");
        }

        // 2. ID 필드에서 사용자 ID 추출
        String id = authenticationRequest.getUsername();

        // 3. PW 필드에서 PK 추출 (Long 타입으로 파싱)
        long pk;
        try {
            pk = Long.parseLong(authenticationRequest.getPassword());
        } catch (Exception e) {
            throw new AuthenticationFailedException("PK 값이 올바르지 않습니다.");
        }

        // 4. UserService를 통해 사용자 조회
        User user = userService.getUserById(id);
        if (user == null) {
            throw new AuthenticationFailedException("사용자를 찾을 수 없습니다.");
        }

        // 5. PK 일치 여부 검증
        if (user.getResourceId() == null || !user.getResourceId().equals(pk)) {
            throw new AuthenticationFailedException("인증에 실패했습니다.");
        }

        // 6. 인증 성공 - 사용자 객체 반환
        return user;
    }
}

    위 구현 예시는 다음과 같이 동작합니다.

    단계 동작

    1

    인증 요청 객체가 null인지 검증

    2

    username 필드에서 사용자 ID 추출

    3

    password 필드에서 PK 값 추출 (Long으로 파싱)

    4

    UserService.getUserById()로 사용자 정보 조회

    5

    조회된 사용자의 resourceId와 입력된 PK 비교

    6

    인증 성공 시 User 객체 반환

    각 인증 결과에 따른 처리 방법은 다음과 같습니다.

    결과 처리 방법

    인증 성공

    UserService에서 조회한 User 객체 반환

    인증 실패

    null을 반환하거나 AuthenticationFailedException 발생시킴

배포 및 설정

JAR 파일 배포

AuthManager를 구현한 Java 프로젝트를 JAR로 빌드한 후, EIMS 설치 디렉토리 내 lib 디렉토리에 위치시킵니다.

EIMS_HOME/
└── lib/                          # EIMS 백엔드 JAR 의존성 디렉토리
    └── my-custom-auth.jar        # 커스텀 인증 JAR 파일

설정 파일 등록

application-extensions.yml 파일에 커스텀 인증 클래스와 인증 이름을 매핑합니다.

eims:
  custom-auth:
    activate: true
    auths:
      - class-name: com.tmax.eims.auth.CustomAuthManagerSampleImpl
        auth-name: id-pk
설정 항목 설명

activate

커스텀 인증 기능 활성화 여부

auths[].class-name

커스텀 인증 구현 클래스의 전체 경로(FQCN)

auths[].auth-name

인증 방식 식별자

커스텀 인증 클래스는 하나만 등록 가능합니다. 두 개 이상의 커스텀 인증 클래스를 등록할 경우, EIMS가 정상 동작하지 않으며 기동이 중단됩니다.

의존성 추가

커스텀 인증 프로젝트에서 이 라이브러리를 사용하려면 JAR 파일을 직접 프로젝트에 추가합니다.

필요 JAR 파일

JAR 파일 설명

eims-custom-auth-{version}.jar

EIMS Custom Auth 라이브러리

Maven(로컬 JAR 참조)

<dependency>
    <groupId>com.tmax.anyeims</groupId>
    <artifactId>eims-custom-auth</artifactId>
    <version>{version}</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/libs/eims-custom-auth-{version}.jar</systemPath>
</dependency>

Gradle(로컬 JAR 참조)

dependencies {
    implementation files('libs/eims-custom-auth-{version}.jar')
}