1. Application Access Token 인증 활용 범위

프로젝트 사이트에서 AUD플랫폼 보고서 및 i-PORTAL을 임베디드 할 때 사용

외부 사이트에서 AUD플랫폼 에서 제공하는 Rest API를 사용할 때 사용

2. Application Access Token 인증을 위한 준비 사항

1) AUD플랫폼의 Repository DB에 MTX_AUTH_AP_INFO 테이블 추가 필요(이미 있을 경우 필요 없음)


-- [Admin > Repository 테이블 점검]에서 Repository Script 내려받기를 이용하여 사이트에 맞는 Database를 사용 하세요
 CREATE TABLE MTX_AUTH_AP_INFO (
	APP_ID VARCHAR(50) NOT NULL,
	APP_NAME VARCHAR(50) NULL,
	APP_SSH_PUB_KEY VARCHAR(2000) NULL,
	APP_SECRET_KEY VARCHAR(255) NOT NULL,
	CREATE_DATE TIMESTAMP NOT NULL,
	EXPIRE_DATE TIMESTAMP NULL,
	CONSTRAINT MTX_AUTH_AP_INFO_UNIQUE UNIQUE (APP_ID)
);
CREATE INDEX MTX_AUTH_AP_INFO_APP_ID_IDX ON MTX_AUTH_AP_INFO USING BTREE (APP_ID);

2) 프로젝트 사이트와 AUD플랫폼의 Domain name 이 동일 해야 함(Application Access Token은 쿠기에 공유 되기 때문에 발생하는 제약 입니다.)

3. Application Access Token 인증 절차

1) SSH키 발급 방법


1. AUD7 플랫폼 Admin 에서 어플리케이션 정보 등록 후 연동할 어플리케이션에 파일 및 정보 전달.

  • 계정 관리 > 사용자 관리 메뉴에서 사용자 등록 (등록한 비밀번호로 체크 하지는 않지만 사용자 등록 필수 조건이기 때문에 임의의 값을 비밀번호로 등록한다) . 그룹 권한 설정


  • 시스템 운영 관리 > 관리자 메뉴 설정 > '인증 키 관리' 항목 체크 후 저장


Application Access Token 발급용 SSH Key 생성 방식

  • 시스템 운영 관리 > 인증 키 관리 화면에서 'SSH Key 생성' 버튼을 클릭하여 등록
  • 등록 후 'SSH Key 정보' 버튼을 클릭하여 팝업 창 에서 Secret Keyprivate_key.pem 파일 다운로드


애플리케이션 등록이 완료되면 발급되는 Secret Key와 Private.pem 파일을 다운로드 하여 연동할 외부 타 어플리케이션에 제공해야 합니다.


2. AUD 플랫폼 서버에 CORS Allowed origin url 등록

  • AUD플랫폼서버 설치 경로/WEB-INF/classes/framework/service/service_api.properties 확인
    - matrix.prop.location=true 되어 있고 matrix.prop.location.path에 경로가 지정되 있을 경우 해당 경로로 가서 service_api.properties 파일을 수정.

- 인증 할 타 시스템 주소 등록 . 브라우저에서 호출 될 때 Header에 설정된 Origins URL (원격 주소) 을 등록

- matrix.cross.origin.allowed 에 타사 연동 PORTAL URL 추가

# cross origin 허용 url (여러개의 주소를 설정할 경우 구분자는 콤마)
matrix.cross.origin.allowed=http://1.1.1.1,https://2222:8080/XXX,http://a.co.kr
  • service_api.properties 수정 후에 AUD 플랫폼 서버 재기동 하여야 적용이 완료됩니다.

3. 외부 포탈에 적용하는 CORS 연동 소스에서 수정해야될 항목 적용

  • sitePortalXXX.jsp 로 제공하는 샘플 외부 포탈용 JSP를 통해 실제 보고서 연동을 테스트
  • 샘플용 JSP 에서 서버 사이드 영역 소스를 확인하여 실제 AP 토큰 발급 절차에 맞게 정보를 수정한 후에 적용한다. AP 토큰 발급용 Java 샘플 소스는 아래 참고
  • AUD7 플랫폼에서 제공받은 private key 파일로 발급된 Secret Key 서명 한 후에 Header에 암호화한 Key 설정 후 AUD7 토큰 발행 API를 호출한다.
  • AUD 서버의 정보 및 1번 항목에서 등록한 Application User 및 Secret key 정보를 정확히 설정한다.
  • /aud/aud.embedded.setting.jsp 내 정보를 사이트에 맞게 수정
  • AUD_CONFIG_DATA.bimatrix_server_url = {AUD7 플랫폼 도메인 주소 . Protocol + DNSNAME }

  • AUD_CONFIG_DATA.webRoot = {외부 포탈에 소스 webRoot 경로 . 임베디드용 aud 폴더가 위치하는 경로}

  • AUD_CONFIG_DATA.cookie_domain = {Ap 토큰을 공유하기 위한 도메인 이름}

  • AUD_CONFIG_DATA.button_disable_ids = {title 영역 사용 시에 버튼 표시 항목}

첨부된 파일을 참고하여 외부 포탈 사이트에서 적용 테스트 진행

  • 기본적으로 AP 토큰이 쿠키에 공유되어 사용되기 때문에 외부 PORTAL (타 사이트 포탈) 과 AUD7 플랫폼 PORTAL의 Domain name이 동일해야 된다.
  • 외부 POTAL에서는 발급된 AP 인증 토큰이 정상적으로 브라우저 Cookiebimatrix_ap_accessToken으로 설정되어 있는지 확인이 필요하다.
  • 최초 AP 토큰 발행은 SSH key 인증 기반으로 서명 확인 후 발급되기 때문에 AUD7 플랫폼 보고서 및 Rest API 연동을 하기 위한 타 어플리케이션에서는 발급받은 Private.pem 파일을 이용하여 Secret Key 서명 기능 적용 (샘플 소스 참고)

등록된 Application 정보로 AP 인증 토큰(bimatrix_ap_accessToken)을 발급 한 후 AUD 플랫폼에서 제공하는 Rest API 호출 및  보고서 연동 기능.

    타 시스템에서 AUD 플랫폼에서 제공하는 보고서 및 PORTAL을 임베디드 형식으로 구성이 가능합니다.


1. AUD 플랫폼에 등록한 Application용 클라이언트 아이디와 클라이언트 시크릿를 인증 정보로 설정하여 Application 인증 JWT 토큰 발급

  • 클라이언트에서 해당 인증 토큰 발급은 제한됩니다. 보안상 클라이언트 인증 정보가 확인될 소지 방지.
  • 타 시스템 포탈에서 최초 1회 인증 토큰 발급 후 만료되었거나 유효하지 않은 토큰일 경우 클라이언트 아이디와 클라이언트 시크릿 정보를 이용하여 인증 토큰을 재발급 합니다.
  • 발급한 토큰은 타 시스템 쿠키에 등록하여 사용합니다 . (쿠키 key = bimatrix_ap_accessToken)
요청 URL메서드Header 설정응답 형식설명

{AUD서버 주소}/api/auth/sign/ap/token

POST

서버 영역에서 API 호출 시에 Request Header로 설정하여 전달

Key설명
X-AUD-AP-Id애플리케이션 클라이언트 아이디값
X-AUD-AP-Secret-SSH

애플리케이션 클라이언트 시크릿값

  • AUD7 플랫폼 발급한 ssh private pem 파일을 이용하여 전달받은 시크릿 Key에 서명을 한 후에 전달하여 토큰 발급 요청
X-AUD-USER
  • Application용 아이디가 아닌 타 시스템에서 로그인 한 사용자로 인증 토큰 발급받아 사용 시에 세션 사용자 아이디 설정
  • 해당 사용자도 AUD 플랫폼 사용자에 등록된 id만 가능
X-AP-UPDATE-ADDR
  • 설정 도메인 (쿠키에 토큰 공유를 위한 도메인 정보)
  • 서브 도메인 , 포트는 달라도 무방함


String

AUD 플랫폼에서 발급된 SSH Private.pem 인증서를 이용하여 Secret Key를 서명한 후에 Header에 Secret Key를 설정하여 전달하여 인증 후 전달된 사용자 또는 클라이언트 아이디로 AUD 플랫폼에서 사용 가능한 인증 토큰 발급.

해당 JWT 인증 토큰을 통해 AUD 플랫폼의 기능 연동을 지원


Application 인증 토큰 발급을 위한 API 호출 자바 샘플 코드입니다.

> 예시로 작성한 sitePortalAUD7Em_iAudSample.jsp 은 서버사이드 영역에 자바 샘플 코드 작성

/**
 * AUD 플랫폼의 AP Token 발급 호출용 샘플 JAVA
 */
public class AudGetApToken {
    private static final String AUD_AP_TOKEN_URL = "aud7 플랫폼주소/matrix/api/auth/sign/ap/token";

    /**
     * audApId , audApPw 는 AUD 플랫폼에 등록한 Application 공통 계정을 사용
     * 파라메터로 전달 시에 암호화에 대한 처리하여 Application용 id / pw가 유출되지 않도록 구성
     */
    public static String getAPToken(String audApId , String audApSecretKey , String userCode) {
        HttpURLConnection connection = null;
		// 쿠키에 발급한 aud 인증 jwt 토큰을 공유하기 위한 도메인 설정.
		String AUD_AP_TOKEN_UPDATE_URL = "bimatrix.co.kr";
        try{
            if ((audApId == null || audApId.isEmpty()) || (audSecretKey == null || audSecretKey.isEmpty())){
                System.out.println("AUD 플랫폼에서 application 인증을 위한 id,pw에 대한 정보가 없습니다.");
                return null ;
            }


			// aud7 플랫폼에서 발급받은 secret key를 ssh의 private key로 서명하여 전달한다.
			PrivateKey privateKey = loadPrivateKey("D:\\tomcat\\apache-tomcat-7.0.107-windows-x64\\apache-tomcat-7.0.107\\webapps\\examples\\aud\\apSSH\\private_key.pem");
			// aud7 secret key 서명 생성
			String signedMessage = signMessage(audSecretKey, privateKey);

            // header 설정은 아래처럼 해주세요.
            Map<String, String> requestHeaders = new HashMap();
			requestHeaders.put("X-AUD-AP-Id", audApId);
			requestHeaders.put("X-AUD-AP-Secret-SSH", signedMessage);
			requestHeaders.put("X-AP-UPDATE-ADDR" , AUD_AP_TOKEN_UPDATE_URL);
			if (userCode != null || !userCode.isEmpty())
   				requestHeaders.put("X-AUD-USER" , userCode);

            try{
                // URL 객체 생성
                URL url = new URL(AUD_AP_TOKEN_URL);
                connection = (HttpURLConnection) url.openConnection();
            }catch(MalformedURLException e){
                System.out.println("AUD 플랫폼 주소가 잘못되었습니다.");
                return null;
            }catch(IOException e){
                System.out.println("연결이 실패했습니다 [api url:"+ AUD_AP_TOKEN_URL +"]");
                return null ;
            }

            // HTTP 메서드 설정
            connection.setRequestMethod("POST");
            for(Map.Entry<String, String> header :requestHeaders.entrySet()) {
                connection.setRequestProperty(header.getKey(), header.getValue());
            }
            // 응답 코드 확인
            int responseCode = connection.getResponseCode();

            System.out.println("Response Code: " + responseCode);
            if (responseCode == HttpURLConnection.HTTP_OK){
                String apAccessToken = connection.getHeaderField("bimatrix_ap_accessToken");
                if (apAccessToken == null){
                    System.out.println("ap token이 정상적으로 발급되지 않았습니다");
                    return null;
                }
                else{
                    return apAccessToken;
                }
            }else if (responseCode == HttpURLConnection.HTTP_UNAUTHORIZED){
                System.out.println("만료된 ap token 입니다.");
                return null;
            }

        }catch(Exception e){
            e.printStackTrace();
        }finally {
            if (connection != null) {
                connection.disconnect();
            }
        }

        return null;
    }


	// 개인 키 로딩
	private static PrivateKey loadPrivateKey(String path) throws Exception {
   		// 개인 키 로딩 로직을 구현 (파일 파싱 또는 다른 방법으로)
   		System.out.println("Private Key path: " + path);
   		String keyPEM = new String(Files.readAllBytes(Paths.get(path)))
         .replaceAll("-----BEGIN PRIVATE KEY-----", "")
         .replaceAll("-----END PRIVATE KEY-----", "")
         .replaceAll("\\s", "");  // 모든 공백 제거

   		byte[] keyBytes = Base64.getDecoder().decode(keyPEM);
   		PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(keyBytes);
   		KeyFactory keyFactory = KeyFactory.getInstance("RSA");
   		return keyFactory.generatePrivate(keySpec);
	}

	// 메시지 서명
	private static String signMessage(String message, PrivateKey privateKey) throws Exception {
   		Signature signature = Signature.getInstance("SHA256withRSA");
   		signature.initSign(privateKey);
   		signature.update(message.getBytes());

   		byte[] signedBytes = signature.sign();
   		return Base64.getEncoder().encodeToString(signedBytes);
	}
}


2. 발급받은 AUD플랫폼 JWT 토큰을 타 시스템 내 쿠키에 설정하여 자동으로 토큰이 정상 토큰이면 갱신 가능.

  • Rest API 호출만으로 사용할 경우에는 호출시마다 Header에 설정하여 api 조회도 가능

    클라이언트에서 API 호출 시에 CORS 옵션 추가하여 API 호출
    ex) fetch를 통한 호출 시

    fetch(biServerUrl + apiUrl, {
                method: 'POST', // 또는 'POST', 'GET' 
                headers: {
                    'Content-Type': 'application/json',
                    'bimatrix_ap_accessToken':'발급받은 AUD플랫폼 인증 JWT 토큰값'
                },
                credentials: 'include', // 쿠키를 포함하여 요청하려면 사용
                body: JSON.stringify(params)
            })
                .then(response => {
                    if (!response.ok) {
                        throw new Error('Network response was not ok');
                    }
                    return response.json(); // 응답을 JSON으로 변환
                })
                .then(data => {
                    alert(JSON.stringify(data));
                })
                .catch(error => {
                    console.error('There has been a problem with your fetch operation:', error);
                    alert('데이터를 가져오는데 실패했습니다.');
                }); 




















                                    AUD7 플랫폼 패키지 500 버전의 2025년 3월 이후부터 기본 기능으로 적용되어 배포됩니다.


                                      • VS_ , VN_ 전역 파라메터를 AUD 보고서 영역으로 넘기려면 샘플 jsp 호출 시에 request parameter로 VS_ , VN_ 로 시작하는 형식으로 전달하면 보고서 영역까지 전달