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

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

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

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

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 영역 사용 시에 버튼 표시 항목}


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 플랫폼의 기능 연동을 지원

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('데이터를 가져오는데 실패했습니다.');
                }); 





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;

        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\\aud_id_rsa");
			// 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", 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 {
   		// 개인 키 로딩 로직을 구현 (파일 파싱 또는 다른 방법으로)
   		KeyFactory keyFactory = KeyFactory.getInstance("RSA");
   		PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(Files.readAllBytes(Paths.get(path)));
   		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);
	}


}
















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


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