Add student verification

Take the student ID and password from a sign-up form, check enrollment, and fetch only student ID, name and major. The password is neither stored nor logged.

The example code is for reference

Method names, arguments, result fields and error codes follow RESULT_SCHEMA. With a real portal account, scripts/verify-live.sh in the repository compares the three languages (Issues and pull requests).

Verification flow

A wrong password stops at the first failure. There is no retry, so the library never locks the account.

Request parameters

Names follow Python snake_case; Node.js and Java use camelCase. A portal login is required.

Method	Parameter	Type	Required	Default	Meaning
authenticate	student_id	string	Yes		Student ID
	password	string	Yes		Portal password. Never stored or logged
	include_raw	boolean	No	false	Also return the portal’s raw text (rawHtml, rawJson)
	include_extra	boolean	No	false	Return the school’s remaining SIS fields as extra
authenticate_dhc	student_id, password, include_raw				When only student ID, name, major, year and status are needed (lighter, no contact lookup)

Response data structure

The result authenticate returns (top) and the value the example function hands back to the sign-up form (bottom). Field names are Python snake_case (student_id); Node.js and Java use camelCase (studentId, getStudentId()). Values are made-up and only show the shape.

{
  "success": true,
  "student_id": "20000000",
  "name": "홍길동",
  "major": "컴퓨터공학과",
  "grade": "3",
  "status": "재학",
  "email": "user@example.com",
  "phone_number": "010-0000-0000",
  "english_name": "Gildong Hong",
  "user_category": "학부생"
}

{ "verified": true, "student_id": "20000000", "name": "홍길동", "major": "컴퓨터공학과" }

Field	Meaning
student_id / name / major	Student ID / name / major. What the example function returns
status	Enrollment status (enrolled, on leave, graduated, …). The portal’s own text, so the wording can change
grade	Year of study (string)
email / phone_number / english_name / user_category	Contact (SIS) lookup. null when the SIS lookup fails. The other SIS school-code fields are omitted here
verified	Built by the example function by comparing status with the enrolled value. Not a library field

All fields: Result fields.

On failure: a wrong password, a locked account and so on are thrown as SejongAuthError (with an error code). Error codes

Good to know

• Never resend a wrong password repeatedly. The portal locks the account. The library stops at the first failure, but if anyone can type a student ID into your form, limit failures per student ID. Login verdict and account lock protection
• status and major are the portal’s own strings. The 재학 comparison above is an example; keep it as a constant in one place since the wording can change.
• One authenticate call includes the contact (SIS) lookup. If you only need student ID, name and major, the DHC-only call authenticate_dhc / authenticateDhc / authenticateWithDHC is lighter. See Authentication methods and Result fields.
• Call it from a server only. Calling from a browser or app exposes the password to third-party code.
• Branch on the error code, never on the message. Error codes

Example code

The user-facing messages are in Korean in the original examples; replace them with your own. ACTIVE_STATUS = "재학" is the portal’s own string for “enrolled” and must stay as the school sends it.

Java

import kr.suhsaechan.sejongpeia.auth.model.SejongAuthResult;
import kr.suhsaechan.sejongpeia.auth.service.SuhSejongAuthEngine;
import kr.suhsaechan.sejongpeia.common.exception.SejongAuthErrorCode;
import kr.suhsaechan.sejongpeia.common.exception.SejongAuthException;
import org.springframework.stereotype.Service;

@Service
class StudentVerificationService {

  private static final String ACTIVE_STATUS = "재학"; // compare with the school's own string

  private final SuhSejongAuthEngine sejongAuthEngine;

  StudentVerificationService(SuhSejongAuthEngine sejongAuthEngine) {
    this.sejongAuthEngine = sejongAuthEngine;
  }

  /** Return only name and major; the password is not kept */
  String verifySejongStudent(String studentId, String password) {
    try {
      SejongAuthResult result = sejongAuthEngine.authenticate(studentId, password);
      boolean isActiveStudent = ACTIVE_STATUS.equals(result.getStatus());
      return isActiveStudent ? result.getName() + " (" + result.getMajor() + ")" : "Not an enrolled student";
    } catch (SejongAuthException exception) {
      SejongAuthErrorCode errorCode = exception.getErrorCode();
      if (errorCode == SejongAuthErrorCode.AUTHENTICATION_FAILED) {
        return "Wrong student ID or password";
      }
      if (errorCode == SejongAuthErrorCode.ACCOUNT_LOCKED) {
        return "The portal account is locked. Reset the password on the portal";
      }
      return "Cannot verify right now. Try again later";
    }
  }
}

Python

from sejongpeia import authenticate, SejongAuthError, ErrorCode

ACTIVE_STATUS = "재학"  # compare with the school's own string (change only here if the portal wording changes)


def verify_sejong_student(student_id: str, password: str) -> dict:
    """Student verification for club sign-up: return only ID, name and major; the password is not kept"""
    try:
        result = authenticate(student_id, password)
    except SejongAuthError as error:
        if error.code == ErrorCode.AUTHENTICATION_FAILED:
            return {"verified": False, "reason": "Wrong student ID or password"}
        if error.code == ErrorCode.ACCOUNT_LOCKED:
            return {"verified": False, "reason": "The portal account is locked. Reset the password on the portal"}
        if error.code == ErrorCode.INVALID_INPUT:
            return {"verified": False, "reason": "Enter your student ID and password"}
        return {"verified": False, "reason": "Cannot verify right now. Try again later"}  # connection, parsing, etc.

    return {
        "verified": result.status == ACTIVE_STATUS,
        "student_id": result.student_id,
        "name": result.name,
        "major": result.major,
    }

Node.js

import { authenticate, SejongAuthError, ErrorCode } from 'pro-sejongpeia';

const ACTIVE_STATUS = '재학'; // compare with the school's own string (change only here if the portal wording changes)

/** Student verification for club sign-up: return only ID, name and major; the password is not kept */
export async function verifySejongStudent(studentId, password) {
  try {
    const result = await authenticate(studentId, password);
    return { verified: result.status === ACTIVE_STATUS, studentId: result.studentId, name: result.name, major: result.major };
  } catch (error) {
    if (!(error instanceof SejongAuthError)) throw error;
    if (error.code === ErrorCode.AUTHENTICATION_FAILED) return { verified: false, reason: 'Wrong student ID or password' };
    if (error.code === ErrorCode.ACCOUNT_LOCKED) return { verified: false, reason: 'The portal account is locked. Reset the password on the portal' };
    if (error.code === ErrorCode.INVALID_INPUT) return { verified: false, reason: 'Enter your student ID and password' };
    return { verified: false, reason: 'Cannot verify right now. Try again later' }; // connection, parsing, etc.
  }
}