페이지 이력

Page No.

Showpageid

작성자 : / 검수자 :

Launch Release No. 7 7.30.500.20250722 20250918-11 / Latest Release No.

※ 주의 : SAML인증과 OAUTH2인증 기타 외부 시스템 인증 방식의 SSO연동을 적용하기 위해 '32-0.공통 설정' 과정을 선행으로 설정해야 함

maxLevel	5
indent	목차
style	square
separator	pipe

1. 사전 확인 작업

AUD플랫폼 Repository DB에 'MTX_PORTAL_SSO_OPTION'테이블 존재 여부 확인(없다면 아래 DDL로 테이블 생성)

코드 블럭

language	sql
title	(!) MTX_PORTAL_SSO_OPTION 테이블 확인 및 Create DDL
collapse	true

-- 테이블 조회 SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_NAME ~* 'MTX_PORTAL_SSO_OPTION'; -- 'MTX_PORTAL_SSO_OPTION' 테이블 생성 CREATE TABLE MTX_PORTAL_SSO_OPTION ( OP_CODE VARCHAR(50), OP_VALUE VARCHAR(5000), OP_TYPE VARCHAR(100), OP_GROUP_CODE VARCHAR(100), OP_ATTR01 VARCHAR(100), OP_ATTR02 VARCHAR(100), OP_ATTR03 VARCHAR(100), OP_DESC

Easy Heading Macro

navigationExpandOption	expand-all-by-default

기타 외부 시스템 인증

− 개요

> 이 가이드를 통해 자체 인증 방식에 대한 로직을 SpCustomEndPoint.java에 자유롭게 구현하고, 그 성공 또는 실패 결과 만을 AUD플랫폼 시스템에 전달하여 후속 처리를 위임할 수 있습니다.

− API 명세

> Endpoint URL: [AUD플랫폼 서비스 도메인]/api/auth/ap/sso/endpoint
> HTTP Method: GET, POST (둘 다 지원)
> Content-Type: application/x-www-form-urlencoded

− 처리 흐름

> /api/auth/ap/sso/endpoint 호출 -> SpCustomEndPoint.java의 responseParsing에서 httpServletRequest로 받아서 처리

− 적용 방법

1) 파일 준비 및 사전 작업

1-1) sso_error.jsp 추가

> 경로 : [Context Root]/extention/sso/sso_error.jsp 혹은 [자동 설치 본 설치 위치]/matrix/extention/sso/sso_error.jsp
> 작업 내용 : 위 경로에 아래 첨부한 zip파일 내 /extention/sso/sso_error.jsp 파일 위치
Image Added
< 그림 2-1. sso_error.jsp 파일 위치 캡처 >

1-2) SpCustomEndPoint.java 추가

> 경로 : [Context Root]/WEB-INF/classes/com/matrix/outer/sso/SpCustomEndPoint.java 혹은 [자동 설치 본 설치 위치]/matrix/WEB-INF/classes/com/matrix/outer/sso/SpCustomEndPoint.java
> 작업 내용: 위 경로에 아래 첨부한 zip파일 내 /WEB-INF/classes/com/matrix/outer/sso경로의 파일을 이동 및 로직 작성
Image Added
< 그림 2-2. SpCustomEndPoint.java 파일 위치 캡처 >

1-3) Compile.sh or Compile.bat 컴파일 스크립트 수정 및 실행

> 경로 : [Context Root]/WEB-INF/classes/com/matrix/outer/sso/Compile.* 혹은 [자동 설치 본 설치 위치]/matrix/WEB-INF/classes/com/matrix/outer/sso/Compile.*
> 작업 내용 : 스크립트의 내용을 사이트의 환경에 맞도록 설정 후 해당 스크립트를 사용하여 SpCustomEndPoint.java를 컴파일
(※ 주의 : 컴파일 후 변경사항 적용 시 WAS 재기동)
Image Added
< 그림 2-3. Compile.* 파일 위치 캡처 >
> Compile.bat 수정 (예시 - 자동 설치 본을 기준으로 하여 작성)
Image Added
< 그림 2-4. Compile.bat파일 수정 캡처 >
> Compile.sh 수정 (예시 - 자동 설치 본을 기준으로 하여 작성)
Image Added
< 그림 2-5. Compile.sh파일 수정 캡처 >

2) SpCustomEndPoint.java 사용가이드

> 인증 결과(성공 또는 실패)에 따라 HttpServletRequest 객체에 속성(Attribute)을 설정하여 반환합니다.
> Attribute 중 'targetUrl'은 고객사에 맞춰 수정합니다.
> Attribute 중 login_flag의 속성 값에 따라 로그인 후 동작과 세션 처리 방식이 달라집니다.
'sso' - 세션이 유지되어 일반적인 로그아웃이 동작하지 않습니다. 완전한 SSO 환경에 사용합니다.
'main' - 일반적인 로그인과 동일하게 세션을 처리하여 로그아웃이 가능합니다.
'adm' - 관리자 페이지로 진입할 때 사용하며, targetUrl을 /iMgt/main.jsp로 설정해야 합니다.

Image Added

< 그림 2-6. SpCustomEndPoint.java파일 수정 캡처 >

3) 디버깅 방법

> cLoger클래스의 info 메서드 사용하여 로그 기록 시 해당 내용을 matrix.properties의 matrix.logerpath에서 지정한 로그 경로의 Matrix.log에서 확인 할 수 있습니다.
> 경로 : [Context Root]/WEB-INF/classes/matrix/logs/logs/Matrix.log 혹은 [자동 설치 본 설치 위치]/logs/matrix/logs/Matrix.log
> 사용 방법
Image Added
< 그림 2-7. SpCustomEndPoint.java파일 디버깅 방법 캡처 >

− 요청 파라미터 목록 확인 방법

1) 파일 준비 및 사전 작업

1-1) sso_dev.jsp 추가

> 경로 : [Context Root]/extention/sso/sso_dev.jsp 혹은 [자동 설치 본 설치 위치]/matrix/extention/sso/sso_dev.jsp
> 작업 내용 : 위 경로에 아래 첨부한 zip파일 내 /extention/sso/sso_dev.jsp 파일 위치

2) 사용법

2-1) CORS와 SSO_AUTH_IP가 정상적으로 설정된 이후 [/api/auth/ap/sso/endpoint]가 호출 시 request에 'ssotest' 파라미터를 포함해서 넘기는 경우 httpServletRequest 목록을 조회 하는 화면 제공
ex) api 호출 시 request param으로 [ssotest=true] 라는 값을 포함해서 넘기는 경우 parameter 정보를 출력하는 화면과 Matrix.log에 로그 정보를 제공

> parameter 출력 정보 화면
Image Added
< 그림 2-8. SSO 전달 파라메터 캡처 >

> Matrix.log 정보
Image Added
< 그림 2-9. SSO 전달 파라메터 수신시 로그 캡처 >
※ CORS와 SSO_AUTH_IP 설정이 반드시 선행되어야 합니다.

코드 블럭

theme	Midnight
title	SpCustomEndPoint.java 샘플 소스
linenumbers	true
collapse	true

package com.matrix.outer.sso;

import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import com.matrix.common.CLoger;
import com.matrix.common.XMatrix;
import com.matrix.framework.common.util.MatrixUtil;

import javax.net.ssl.HttpsURLConnection;
import javax.net.ssl.SSLContext;
import javax.net.ssl.TrustManager;
import javax.net.ssl.X509TrustManager;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.BufferedReader;
import java.io.File;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.security.cert.CertificateException;
import java.security.cert.X509Certificate;

public class SpCustomEndPoint {

    CLoger cLoger = new CLoger();
    /*
     * 외부 통합 인증 서비스에서 전달해준 request의 파라메터 데이터를 파싱하여 로그인할 유저 아이디를 추출한다.
     * [setAttribute 설정 항목]
     * httpServletRequest.setAttribute("userCode", "userId"); // 추출한 유저코드
     * httpServletRequest.setAttribute("logWrite", "false"); // MTX_LOGIN_LOG 적재 여부
     * httpServletRequest.setAttribute("login_flag", "sso"); // 고정
     * httpServletRequest.setAttribute("langCode", "de"); // 로그인 시 적용할 언어 코드 (de ,en
     * , ko , jp)
     * httpServletRequest.setAttribute("targetUrl", "/portal/Content.jsp"); // sso를
     * 통한 인증 생성 완료 후에 호출할 페이지 주소
     */
    public void responseParsing(HttpServletRequest httpServletRequest, HttpServletResponse httpServletResponse)
           VARCHAR(200),
  CREATE_CODE throws Exception {
        /**
         * 외부 통합 인증 연동을 통해 필요한 사용자 코드를 추출하여 AUD SSO 인증 처리 시 필요한 request attribute 설정
         **/
        String userCode = httpServletRequest.getParameter("userCode");
         VARCHAR(50),String userPwd = httpServletRequest.getParameter("userpassword");

 CREATE_DATE       TIMESTAMP,
  MODIFY_CODEcLoger.info("==== Success [userCode:"+userCode+"]");

      VARCHAR(50),
  MODIFY_DATE  if (userCode == null || userCode.isEmpty() || "null".equals(userCode)){
       TIMESTAMP,  constraint PK_MTX_PORTAL_SSO_OPTION PRIMARY KEY (OP_CODE)
);
COMMENT ON TABLE MTX_PORTAL_SSO_OPTION IS 'Portal SSO Option Management';

2. SAML인증

− 처리 흐름

> 사용자 로그인 → IdP(인증 정보 제공자)에서 인증 → SAML Assertion 생성 → SP(서비스 제공자)로 전달 → SP(서비스 제공자)에서 인증 완료

> 이때, SAML Assertion 안에 AttributeStatement가 포함되어 사용자의 역할, 부서, 이메일 등 속성 정보가 전달

(※ 주의: 고객사 측 인증 시스템에 등록된 사용자가 AUD플랫폼에 사용자로 등록되어 있어야 함)

− 적용 방법

1) PORTAL 설정

1-1) Admin 시스템 운영관리 > PORTAL 설정 > sso 설정 사용 체크 후 옵션 버튼 클릭

1-2) SSO Type = SAML

1-3) NAME ID 설정 = (SAML 응답에서 사용자의 주요 식별자(ID)를 어떤 방식으로 받을지 결정하는 설정)

true : SAML 표준 필드인 <NameID> 태그의 값을 사용자 ID로 사용하겠다는 의미

false : <NameID> 필드를 사용하지 않고, 별도의 <AttributeStatement> 안에 포함된 커스텀 속성(Attribute) 값을 사용자 ID로 사용하겠다는 의미

1-4) AttributeStatement Claims (?) = (NAME ID 설정이 false일 때 사용, SAML 응답의 <AttributeStatement> 안에 여러 속성들이 있을 때, 그중 어떤 속성이 실제 사용자 ID인지 알려주는 속성 )

1-5) SSO 서비스 URL = (사용자가 로그인을 해야 할 때, SP가 사용자를 보내야 하는 IdP의 로그인 페이지 URL)

1-6) SSO ENTITY ID = (IdP를 유일하게 식별하는 고유한 이름(주소))

1-7) SSO 로그아웃 URL = (SP에서 시작된 로그아웃 요청을 처리하기 위해 IdP가 제공하는 로그아웃 URL)

1-8) 인증서 알고리즘 = (인증서를 검증하는 또 다른 방법인 지문(Fingerprint)을 생성할 때 사용할 해시 알고리즘을 지정)

1-9) Public 인증서 정보 = (IdP가 보낸 SAML 응답이 위조되지 않았음을 검증하기 위한 IdP의 공개 인증서)

(※ 해당 값들은 사이트에서 별도로 전달하므로 전달 받은 속성 값을 그대로 설정)

Image Removed

(?)

2) PORTAL 더보기 설정

> Admin -> Portal 설정 -> 더보기

> OP06_PATH_LOGIN_CONTENT = /extention/portal/samlLogin.jsp 로 변경

Image Removed

3) IdP(고객사 측 인증 시스템)에 Service URL, Endpoint URL 등록 요청

> Service URL : https://[AUD플랫폼 서비스 도메인]/api/auth/saml/sp/entity

> Endpoint Url : https://[AUD플랫폼 서비스 도메인]/extention/sso/acs.jsp

3. OAUTH2인증

− 처리 흐름

> 사용자 로그인 → SP(서비스 제공자)가 사용자를 IdP(인증 정보 제공자)의 로그인 페이지로 리다이렉트 → IdP(인증 정보 제공자)에서 SP(서비스 제공자)이 정보를 사용하는 것을 허용 동의

> IdP(인증 정보 제공자)는 사용자를 redirect_uri(api/auth/oauth2/callback)로 인증 코드와 함께 다시 돌려보냄

> SP(서비스 제공자)에서 인증코드와 함께 CLIENT_ID, CLIENT_SECRET을 IdP의 토큰 엔드포인트로 보냄

> IdP(인증 정보 제공자)는 모든 정보가 일치 시 액세스 토큰 발급 → SP(서비스 제공자)은 발급받은 Access Token을 사용자 정보 엔드포인트로 보냄

> IdP(인증 정보 제공자)는 토큰을 검증하고 해당 사용자의 정보(JSON)를 응답 → SP(서비스 제공자)은 외부 IdP(인증 정보 제공자)를 통해 검증된 사용자의 ID를 확보하여 로그인 처리

(※ 주의: 고객사 측 인증 시스템에 등록된 사용자가 AUD플랫폼에 사용자로 등록되어 있어야 함)

− 적용 방법

1) PORTAL 설정

1-1) Admin 시스템 운영관리 > PORTAL 설정 > sso 설정 사용 체크 후 옵션 버튼 클릭

1-2) SSO Type = OAUTH2

1-3) OAUTH2 서버 Base URL = (IdP 서버의 기본 주소)

1-4) Client ID = (IdP가 AUD 시스템을 식별하기 위해 발급해주는 공개된 ID)

1-5) Client Secrets = (CLIENT_ID와 함께 사용되는 비밀 키로, AUD 시스템이 정당한 클라이언트임을 증명할 때 사용)

1-6) Scope = (어떤 권한들을 요청하는지를 명시하는 목록) ex) openid profile email

1-7) 인가 코드 엔드포인트 = (ID 공급자(IdP)의 로그인 및 권한 동의 페이지 URL) ex) /v1/authorize

1-8) 토큰 엔드포인트 = (인증 코드를 액세스 토큰으로 교환해주는 API의 경로)

1-9) 유저 정보 조회 엔드포인트 = (액세스 토큰을 사용하여 사용자 정보(ID, 이메일 등)를 조회할 수 있는 API의 경로)

1-10) User ID Key = (사용자 정보 API 응답(JSON)에서 **사용자 ID가 담긴 필드의 이름)

1-11) AUD Target URL = (모든 인증 과정이 성공적으로 끝난 후, 사용자를 최종적으로 이동시킬 페이지 주소) ex) /portal/Content.jsp

(※ 해당 값들은 사이트에서 별도로 전달하므로 전달 받은 속성 값을 그대로 설정)

Image Removed

(?)

2) PORTAL 더보기 설정

> Admin -> Portal 설정 -> 더보기

> OP06_PATH_LOGIN_CONTENT = /extention/portal/oauth2Login.jsp 로 변경

Image Removed

3) IdP(고객사 측 인증 시스템)에 Redirection URL 등록 요청

> Redirection URL : https://[AUD플랫폼 서비스 도메인]/api/auth/oauth2/callback

 cLoger.info("==== fail ====");
            httpServletRequest.setAttribute("failRedirect", "/portal/loginContent.jsp?errorCode=E");
        }else {
            cLoger.info("==== Success [userCode:"+userCode+"]");
            httpServletRequest.setAttribute("userCode", userCode);
            httpServletRequest.setAttribute("targetUrl", "/portal/Content.jsp");
            httpServletRequest.setAttribute("login_flag", "sso");
        }
    }
}

코드 블럭

theme	Midnight
title	compile.bat 샘플 소스
linenumbers	true
collapse	true

@echo off
set "JAVA_HOME=C:\AUDPlatform_7\apps\openjdk"
set "PATH=%JAVA_HOME%\bin;%PATH%"

REM === 여러 JAR 파일 설정  구분자 ;(세미콜론)===
set SERVLET_JAR=C:\AUDPlatform_7\apps\tomcat\lib\servlet-api.jar
set UTILS_JAR=C:\AUDPlatform_7\matrix\WEB-INF\lib\maf-4.0.jar;C:\AUDPlatform_7\matrix\WEB-INF\lib\matrix-service.jar;C:\AUDPlatform_7\matrix\WEB-INF\lib\gson-2.10.1.jar

REM === 클래스패스 구성 ===
set CP=%SERVLET_JAR%;%UTILS_JAR%

REM === 컴파일 ===
javac -encoding UTF-8 -classpath "%CP%" .\SpCustomEndPoint.java

코드 블럭

theme	Midnight
title	compile.sh 샘플 소스
linenumbers	true
collapse	true

#!/bin/bash

# === JAVA_HOME 설정 ===
export JAVA_HOME="/AUDPlatform_7/apps/openjdk"
export PATH="$JAVA_HOME/bin:$PATH"

# === SERVLET_JAR 경로 (해당 WAS의 Servlet library 경로 지정) 구분자  :(콜론) ===
SERVLET_JAR="/AUDPlatform_7/apps/tomcat/lib/servlet-api.jar"
UTILS_JAR="/AUDPlatform_7/matrix/WEB-INF/lib/maf-4.0.jar:/AUDPlatform_7/matrix/WEB-INF/lib/matrix-service.jar:/AUDPlatform_7/matrix/WEB-INF/lib/gson-2.10.1.jar"

# === 클래스패스 구성 ===
CP="$SERVLET_JAR:$UTILS_JAR"

# === 컴파일 ===
javac -encoding UTF-8 -classpath "$CP" ./SpCustomEndPoint.java

코드 블럭

theme	Midnight
title	sso_dev.jsp
linenumbers	true
collapse	true

<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<%@ page import="java.util.Map" %>
<%@ page import="java.util.List" %>
<%@ page import="java.util.ArrayList" %>
<%@ page import="com.matrix.common.CLoger" %>


<%!
    // Utility method to prevent XSS attacks by escaping HTML special characters.
    public String escapeHtml(String text) {
        if (text == null) {
            return "";
        }
        return text.replace("&", "&amp;")
                   .replace("<", "&lt;")
                   .replace(">", "&gt;")
                   .replace("\"", "&quot;")
                   .replace("'", "&#039;");
    }
%>

<!DOCTYPE html>
<html>
<head>
    <title>AUD Platform SSO Parameter List</title>
    <style>
        body { font-family: sans-serif; }
        code { background-color: #f4f4f4; padding: 2px 5px; border-radius: 4px; }
    </style>
</head>
<body>

    <h1>AUD Platform SSO Request Parameter List</h1>

    <%
        CLoger cloger = new CLoger();
        // 1. Set character encoding to UTF-8 to prevent garbled text (IMPORTANT)
        request.setCharacterEncoding("UTF-8");

        Map<String, String[]> paramMap = request.getParameterMap();
        List<String> paramList = new ArrayList<>();
        
        cloger.info("=== [sso_dev.jsp] Start: SSO HttpServletRequest Parameters ===");    
        for (Map.Entry<String, String[]> entry : paramMap.entrySet()) {
            String paramName = entry.getKey();
            String[] paramValues = entry.getValue();
            String valueStr = String.join(", ", paramValues);

            // 2. Escape both name and value for security before adding to the list (CRITICAL)
            String safeOutput = escapeHtml(paramName) + " = " + escapeHtml(valueStr);
            paramList.add(safeOutput);
            cloger.info("Parameter Key: " + paramName + ", Values: " + valueStr);
        }
        cloger.info("=== [sso_dev.jsp] End: SSO HttpServletRequest Parameters ===");
    %>

    <%-- Display Results --%>
    <%
        if (paramList.isEmpty()) {
    %>
        <p>No parameters were received.</p>
    <%
        } else {
    %>
        <p>Total parameters: <strong><%= paramList.size() %></strong></p>
        <ul>
    <%
            for (String param : paramList) {
    %>
            <%-- The 'param' variable is now a safe, escaped string --%>
            <li><code><%= param %></code></li>
    <%
            }
    %>
        </ul>
    <%
        }
    %>

    <hr>

</body>
</html>

정보

title	기타 외부 시스템 SSO연동 소스

View file

name	기타 외부 시스템 SSO 연동 소스.zip
height	250

페이지 트리

버전 비교

이전 버전 5

새 버전 현재

키

1. 사전 확인 작업

기타 외부 시스템 인증

− 개요

− API 명세

− 처리 흐름

− 적용 방법

− 요청 파라미터 목록 확인 방법

2. SAML인증

3. OAUTH2인증