University of Hong Kong O Auth API

openapi: 3.2.0
info:
  title: HKU Identity Federation OAuth API
  version: '2026-08-19'
  summary: OAuth 2.0 / OpenID Connect endpoints published by the University of Hong Kong's own AD FS identity provider.
  description: Machine-readable description of the OAuth 2.0 / OpenID Connect surface that the University of Hong Kong operates on its own host, adfs.hku.hk.
  contact:
    name: The University of Hong Kong — Information Technology Services
    url: https://its.hku.hk/
  license:
    name: Not stated
servers:
- url: https://adfs.hku.hk
  description: HKU AD FS — institution-operated identity provider (Shibboleth IdP is separate, see conformance/).
security:
- bearerAuth: []
tags:
- name: OAuth
  description: OAuth 2.0 / OpenID Connect protocol endpoints.
paths:
  /adfs/oauth2/authorize/:
    get:
      tags:
      - OAuth
      operationId: authorize
      summary: Authorization endpoint
      description: OAuth 2.0 authorization endpoint. Advertised by the discovery document. An unauthenticated probe with no query parameters returned HTTP 503 from the AD FS edge, so the request parameters below are the RFC 6749 / OpenID Connect Core parameters the advertised response_types and response_modes imply, not parameters observed in a successful call.
      security: []
      x-probe:
        url: https://adfs.hku.hk/adfs/oauth2/authorize/
        status: 503
        note: Service Unavailable to an unauthenticated probe with no parameters; endpoint is advertised in discovery.
        probed: '2026-08-19'
      parameters:
      - name: client_id
        in: query
        required: true
        schema:
          type: string
      - name: response_type
        in: query
        required: true
        schema:
          type: string
          enum:
          - code
          - id_token
          - code id_token
          - id_token token
          - code token
          - code id_token token
      - name: redirect_uri
        in: query
        required: true
        schema:
          type: string
          format: uri
      - name: scope
        in: query
        schema:
          type: string
        description: Space-delimited subset of the scopes in scopes_supported.
      - name: response_mode
        in: query
        schema:
          type: string
          enum:
          - query
          - fragment
          - form_post
      - name: state
        in: query
        schema:
          type: string
      - name: nonce
        in: query
        schema:
          type: string
      responses:
        '302':
          description: Redirect back to redirect_uri carrying the authorization response.
        '503':
          description: Returned to unparameterised public probes.
  /adfs/oauth2/token/:
    post:
      tags:
      - OAuth
      operationId: token
      summary: Token endpoint
      description: OAuth 2.0 token endpoint. Supported grant types and client authentication methods are transcribed from the discovery document.
      security: []
      x-probe:
        url: https://adfs.hku.hk/adfs/oauth2/token/
        status: 411
        note: POST with no body returned 411 Length Required; GET returned 503. Endpoint is live and advertised.
        probed: '2026-08-19'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum:
                  - authorization_code
                  - refresh_token
                  - client_credentials
                  - urn:ietf:params:oauth:grant-type:jwt-bearer
                  - implicit
                  - password
                  - srv_challenge
                  - urn:ietf:params:oauth:grant-type:device_code
                  - device_code
                client_id:
                  type: string
                client_secret:
                  type: string
                code:
                  type: string
                redirect_uri:
                  type: string
                  format: uri
                refresh_token:
                  type: string
              required:
              - grant_type
      responses:
        '200':
          description: Token response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: OAuth 2.0 error response (RFC 6749 section 5.2).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
        '411':
          description: Length Required — returned to a POST with no body.
  /adfs/oauth2/devicecode:
    post:
      tags:
      - OAuth
      operationId: deviceAuthorization
      summary: Device authorization endpoint
      description: RFC 8628 device authorization endpoint, advertised as device_authorization_endpoint.
      security: []
      x-probe:
        url: https://adfs.hku.hk/adfs/oauth2/devicecode
        status: 405
        note: GET returns 405 Method Not Allowed — the endpoint exists and accepts POST only.
        probed: '2026-08-19'
      responses:
        '200':
          description: Device authorization response.
        '405':
          description: Method Not Allowed — returned to GET.
  /adfs/userinfo:
    get:
      tags:
      - OAuth
      operationId: userinfo
      summary: UserInfo endpoint
      description: OpenID Connect UserInfo endpoint. Requires a bearer access token.
      x-probe:
        url: https://adfs.hku.hk/adfs/userinfo
        status: 401
        note: 401 with no body to an unauthenticated request and to an invalid bearer token.
        probed: '2026-08-19'
      responses:
        '200':
          description: Claims about the authenticated subject.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          description: Unauthorized — missing or invalid access token.
  /adfs/oauth2/logout:
    get:
      tags:
      - OAuth
      operationId: endSession
      summary: End-session endpoint
      description: OpenID Connect RP-initiated logout endpoint; front-channel logout is advertised as supported.
      security: []
      x-probe:
        url: https://adfs.hku.hk/adfs/oauth2/logout
        status: 503
        note: Service Unavailable to an unparameterised public probe; endpoint is advertised in discovery.
        probed: '2026-08-19'
      responses:
        '302':
          description: Redirect after sign-out.
        '503':
          description: Returned to unparameterised public probes.
components:
  schemas:
    OAuthError:
      type: object
      description: RFC 6749 section 5.2 error response.
      properties:
        error:
          type: string
        error_description:
          type: string
        error_uri:
          type: string
          format: uri
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
        token_type:
          type: string
          examples:
          - bearer
        expires_in:
          type: integer
        refresh_token:
          type: string
        id_token:
          type: string
        scope:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Access token issued by https://adfs.hku.hk/adfs, signed RS256.
    oauth2:
      type: oauth2
      description: Flows transcribed from the HKU AD FS discovery document.
      flows:
        authorizationCode:
          authorizationUrl: https://adfs.hku.hk/adfs/oauth2/authorize/
          tokenUrl: https://adfs.hku.hk/adfs/oauth2/token/
          scopes:
            openid: Request an ID token for the signed-in HKU account.
            profile: Release profile claims.
            email: Release the account's email claim.
            allatclaims: Include all claims from the underlying token in the issued token.
            aza: Microsoft primary-refresh-token / broker scope.
            user_impersonation: Act on behalf of the signed-in user against a relying party.
            logon_cert: Request a logon certificate.
            winhello_cert: Request a Windows Hello for Business certificate.
            vpn_cert: Request a VPN client certificate.
        clientCredentials:
          tokenUrl: https://adfs.hku.hk/adfs/oauth2/token/
          scopes:
            openid: Request an ID token.
        deviceCode:
          tokenUrl: https://adfs.hku.hk/adfs/oauth2/token/
          scopes:
            openid: Request an ID token.
x-operator: institution
x-operator-rationale: adfs.hku.hk is under hku.hk, the University's own registrable domain, and the AD FS deployment, its signing keys and its trust relationships are operated by HKU ITS. Microsoft supplies the software; HKU runs the service and issues the tokens.
x-provenance:
  generated: '2026-08-19'
  method: derived
  source: https://adfs.hku.hk/adfs/.well-known/openid-configuration
  source_saved: well-known/hku-adfs-openid-configuration.json
  note: Derived, not published by HKU. HKU publishes the discovery document; API Evangelist derived this OpenAPI from it. Do not credit HKU with an OpenAPI they did not write.