Chula SSO Authentication API

openapi: 3.0.3
info:
  title: Chula SSO Authentication API
  version: '2017.01'
  description: >-
    Single sign-on authentication service operated by Chulalongkorn University at
    account.it.chula.ac.th, in production since January 2017. The protocol is a modified
    CAS 1.0 flow with an added application-authentication step: a relying application
    presents an appid/appsecret pair alongside the user's ticket, so the SSO can control
    which applications are permitted to authenticate Chula IDs. Users never pass
    credentials to the relying application.

    THIS DOCUMENT WAS NOT PUBLISHED BY CHULALONGKORN UNIVERSITY. It is an API Evangelist
    transcription of the university's own public servlet reference at
    https://account.it.chula.ac.th/wiki/doku.php?id=how_does_it_work (HTTP 200), which
    documents the endpoints, parameters, headers and response bodies in prose. Nothing here
    was invented: every path, parameter, header and schema below appears on that page.
    Endpoints named on the page but not documented there (activation, forget) are omitted
    rather than guessed.
  contact:
    name: Office of Information Technology, Chulalongkorn University
    url: https://www.it.chula.ac.th/
  termsOfService: https://account.it.chula.ac.th/wiki/doku.php
  x-provenance:
    generated: '2026-09-01'
    method: derived
    source: https://account.it.chula.ac.th/wiki/doku.php?id=how_does_it_work
    source_status: 200
    authored_by: API Evangelist
    note: >-
      Derived from the institution's published prose documentation. The institution does
      not publish a machine-readable contract for this service.
servers:
  - url: https://account.it.chula.ac.th
    description: Production Chula SSO
tags:
  - name: Authentication
    description: Session establishment and teardown
  - name: Validation
    description: Ticket validation for relying applications
paths:
  /login:
    get:
      tags: [ Authentication ]
      operationId: login
      summary: Establish an SSO session and issue a service ticket
      description: >-
        Validates credentials and generates a ticket-granting session. Without a valid
        session the service issues a 302 to /html/login.html carrying the service
        parameter; with a valid session it issues a 302 back to the service URL carrying a
        ticket parameter.
      parameters:
        - name: service
          in: query
          required: true
          schema: { type: string, format: uri }
          description: URL to redirect to after successful authentication.
        - name: username
          in: query
          required: false
          schema: { type: string }
          description: Username, in email form.
        - name: password
          in: query
          required: false
          schema: { type: string, format: password }
        - name: remember
          in: query
          required: false
          schema: { type: integer, enum: [ 0, 1 ] }
          description: Any non-zero value makes the session non-expiring.
      responses:
        '302':
          description: >-
            Redirect. To /html/login.html with the service parameter when there is no valid
            session; to the service URL with a ticket parameter when there is.
          headers:
            Location:
              schema: { type: string, format: uri }
    post:
      tags: [ Authentication ]
      operationId: loginPost
      summary: Establish an SSO session (form POST)
      description: Same contract as GET /login; the documentation states GET/POST.
      responses:
        '302':
          description: Redirect, as for GET /login.
  /logout:
    get:
      tags: [ Authentication ]
      operationId: logout
      summary: Terminate the SSO session
      parameters:
        - name: service
          in: query
          required: false
          schema: { type: string, format: uri }
          description: URL to redirect to after logout. Defaults to /html/logout.html.
      responses:
        '302':
          description: Redirect to the service URL.
  /serviceValidation:
    get:
      tags: [ Validation ]
      operationId: serviceValidation
      summary: Validate a service ticket and retrieve the authenticated user
      description: >-
        Relying applications exchange a ticket for the authenticated user's identity. The
        application authenticates itself with the DeeAppId and DeeAppSecret headers, which
        are issued on request by the university and are not self-service.
      parameters:
        - name: DeeAppId
          in: header
          required: true
          schema: { type: string }
          description: Application identifier issued by the university.
        - name: DeeAppSecret
          in: header
          required: true
          schema: { type: string, format: password }
          description: Application secret issued by the university.
        - name: DeeTicket
          in: header
          required: true
          schema: { type: string }
          description: Ticket to validate.
      responses:
        '200':
          description: Ticket valid. Body is the authenticated user object.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SSOUser' }
              example:
                uid: '0001'
                username: demo
                gecos: Demo Account
                email: demo@example.com
                roles: [ faculty, student ]
                ouid: '6031234521'
        '401':
          description: Invalid ticket or the application is not permitted.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SSOError' }
              example:
                type: error
                content: invalid ticket/permission
components:
  securitySchemes:
    DeeAppId:
      type: apiKey
      in: header
      name: DeeAppId
    DeeAppSecret:
      type: apiKey
      in: header
      name: DeeAppSecret
  schemas:
    SSOUser:
      type: object
      description: Authenticated Chula ID, as returned by /serviceValidation on success.
      properties:
        uid:
          type: string
          description: Internal SSO user identifier.
        username:
          type: string
          description: Chula ID username.
        gecos:
          type: string
          description: Display name, carried through from the university LDAP directory.
        email:
          type: string
          format: email
        roles:
          type: array
          description: Directory roles, e.g. faculty, student.
          items: { type: string }
        ouid:
          type: string
          description: Employee ID or student ID.
    SSOError:
      type: object
      properties:
        type:
          type: string
          example: error
        content:
          type: string
          example: invalid ticket/permission