openapi: 3.2.0
info:
  title: NUS Identity Provider API (vafs.nus.edu.sg) Session API
  version: '2026-08-19'
  description: "The National University of Singapore operates its own federated identity service at\n`vafs.nus.edu.sg` (\"NUS VAFS\" — the university's Active Directory Federation Services\ndeployment). It is the one substantial machine-readable, institution-operated API surface\nNUS publishes to the open internet, and it is the front door to essentially every gated\nNUS system.\n\nThe host is unambiguously NUS's own engineering, not a vendor's:\n\n  * `vafs.nus.edu.sg` resolves inside NUS's own address space (137.132.21.18).\n  * Its TLS certificate is an Extended Validation certificate issued to\n    `jurisdictionC=SG, businessCategory=Private Organization, serialNumber=200604346E,\n    O=National University of Singapore, CN=vafs.nus.edu.sg` — NUS is the validated\n    organization, not a hosting provider.\n  * The SAML entityID it asserts is `https://vafs.nus.edu.sg/adfs/services/trust`.\n\nThis document is DERIVED — every path, parameter, scope and response below was read out of\nthe institution's own live OpenID Connect discovery document at\n`https://vafs.nus.edu.sg/adfs/.well-known/openid-configuration` and its JWKS at\n`https://vafs.nus.edu.sg/adfs/discovery/keys`, both fetched 2026-08-19. NUS does not itself\npublish an OpenAPI description; nothing here is invented, but the OpenAPI packaging is\nAPI Evangelist's, not the university's.\n\nThe service speaks OpenID Connect 1.0 / OAuth 2.0, SAML 2.0, WS-Federation and WS-Trust\nfrom the same endpoint family. The SAML half is described in\n`identity-federation/nus-identity-federation.yml`.\n"
  contact:
    name: NUS Information Technology
    url: https://nusit.nus.edu.sg/
  termsOfService: https://nus.edu.sg/ormc/personal-data-protection/nus-privacy-notice
  x-operator: institution
  x-operator-evidence:
  - TLS certificate subject O=National University of Singapore (DigiCert EV RSA CA G2)
  - A record 137.132.21.18 within NUS-assigned address space
  - SAML entityID https://vafs.nus.edu.sg/adfs/services/trust
  x-method: derived
  x-source: https://vafs.nus.edu.sg/adfs/.well-known/openid-configuration
  x-generated: '2026-08-19'
servers:
- url: https://vafs.nus.edu.sg
  description: NUS federated identity service (production)
tags:
- name: Session
  description: End-user claims and session termination.
paths:
  /adfs/userinfo:
    get:
      tags:
      - Session
      operationId: userinfo
      summary: UserInfo endpoint
      description: Returns claims about the authenticated NUS end user. Requires a bearer access token issued with the `openid` scope. Subject identifiers are pairwise.
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Claims for the authenticated subject.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
        '401':
          description: Missing, expired or invalid access token.
  /adfs/oauth2/logout:
    get:
      tags:
      - Session
      operationId: endSession
      summary: End session / front-channel logout endpoint
      description: Terminates the user's session at the provider. The provider advertises front-channel logout with session support.
      security: []
      parameters:
      - name: post_logout_redirect_uri
        in: query
        required: false
        schema:
          type: string
          format: uri
      - name: id_token_hint
        in: query
        required: false
        schema:
          type: string
      responses:
        '302':
          description: Redirect after session termination.
components:
  schemas:
    UserInfo:
      type: object
      description: Claims the provider advertises in `claims_supported`. NUS issues pairwise subject identifiers, so `sub` is per-client and not a stable cross-client campus identifier.
      properties:
        sub:
          type: string
        upn:
          type: string
          description: User principal name, e.g. e0123456@u.nus.edu
        unique_name:
          type: string
        aud:
          type: string
        iss:
          type: string
        iat:
          type: integer
        exp:
          type: integer
        nbf:
          type: integer
        auth_time:
          type: integer
        mfa_auth_time:
          type: integer
        nonce:
          type: string
        at_hash:
          type: string
        c_hash:
          type: string
        sid:
          type: string
        pwd_url:
          type: string
          format: uri
        pwd_exp:
          type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    clientSecretBasic:
      type: http
      scheme: basic
      description: client_secret_basic client authentication.
    clientSecretPost:
      type: apiKey
      in: header
      name: Authorization
      description: Placeholder for client_secret_post; the provider also advertises private_key_jwt and windows_client_authentication.
    oidc:
      type: openIdConnect
      openIdConnectUrl: https://vafs.nus.edu.sg/adfs/.well-known/openid-configuration