openapi: 3.2.0
info:
  title: HKU Identity Federation Discovery 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. Every path, endpoint URL, scope, grant type, response type and claim in this document is transcribed from HKU''s live OpenID Connect discovery document at https://adfs.hku.hk/adfs/.well-known/openid-configuration (HTTP 200, application/json, 1,874 bytes, fetched 2026-08-19). Nothing here is invented: paths that the discovery document does not advertise are not present, and the observed status code of every endpoint under an unauthenticated probe is recorded in x-probe on the operation.

    HKU does not publish this as a developer-facing API — it is the institution''s federated login infrastructure, used by HKU applications and by service providers HKU trusts. It is catalogued here because it is one of the few genuinely institution-operated, machine-readable contracts the University serves from its own registrable domain.'
  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: Discovery
  description: Metadata documents that describe the identity service.
paths:
  /adfs/.well-known/openid-configuration:
    get:
      tags:
      - Discovery
      operationId: getOpenIdConfiguration
      summary: OpenID Connect discovery document
      description: Returns the OpenID Provider metadata for the HKU AD FS issuer https://adfs.hku.hk/adfs.
      security: []
      x-probe:
        url: https://adfs.hku.hk/adfs/.well-known/openid-configuration
        status: 200
        content_type: application/json
        bytes: 1874
        probed: '2026-08-19'
      responses:
        '200':
          description: OpenID Provider metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenIdConfiguration'
  /adfs/discovery/keys:
    get:
      tags:
      - Discovery
      operationId: getJwks
      summary: JSON Web Key Set
      description: Public signing keys (RS256) used to verify id_tokens and access tokens issued by HKU AD FS.
      security: []
      x-probe:
        url: https://adfs.hku.hk/adfs/discovery/keys
        status: 200
        content_type: application/json
        bytes: 1468
        probed: '2026-08-19'
      responses:
        '200':
          description: JWK Set.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonWebKeySet'
  /FederationMetadata/2007-06/FederationMetadata.xml:
    get:
      tags:
      - Discovery
      operationId: getFederationMetadata
      summary: WS-Federation / SAML 2.0 federation metadata
      description: Signed federation metadata for entityID http://adfs.hku.hk/adfs/services/trust, describing the SAML 2.0 and WS-Federation endpoints and signing certificates of the HKU AD FS deployment.
      security: []
      x-probe:
        url: https://adfs.hku.hk/FederationMetadata/2007-06/FederationMetadata.xml
        status: 200
        content_type: application/samlmetadata+xml
        bytes: 71026
        probed: '2026-08-19'
      responses:
        '200':
          description: SAML 2.0 metadata document.
          content:
            application/samlmetadata+xml:
              schema:
                type: string
components:
  schemas:
    OpenIdConfiguration:
      type: object
      description: OpenID Provider metadata as served by HKU AD FS.
      required:
      - issuer
      - authorization_endpoint
      - token_endpoint
      - jwks_uri
      properties:
        issuer:
          type: string
          format: uri
          examples:
          - https://adfs.hku.hk/adfs
        authorization_endpoint:
          type: string
          format: uri
        token_endpoint:
          type: string
          format: uri
        userinfo_endpoint:
          type: string
          format: uri
        end_session_endpoint:
          type: string
          format: uri
        device_authorization_endpoint:
          type: string
          format: uri
        jwks_uri:
          type: string
          format: uri
        access_token_issuer:
          type: string
        scopes_supported:
          type: array
          items:
            type: string
        response_types_supported:
          type: array
          items:
            type: string
        response_modes_supported:
          type: array
          items:
            type: string
        grant_types_supported:
          type: array
          items:
            type: string
        subject_types_supported:
          type: array
          items:
            type: string
        id_token_signing_alg_values_supported:
          type: array
          items:
            type: string
        token_endpoint_auth_methods_supported:
          type: array
          items:
            type: string
        token_endpoint_auth_signing_alg_values_supported:
          type: array
          items:
            type: string
        claims_supported:
          type: array
          items:
            type: string
        capabilities:
          type: array
          items:
            type: string
        frontchannel_logout_supported:
          type: boolean
        frontchannel_logout_session_supported:
          type: boolean
        microsoft_multi_refresh_token:
          type: boolean
        as_access_token_token_binding_supported:
          type: boolean
        as_refresh_token_token_binding_supported:
          type: boolean
        resource_access_token_token_binding_supported:
          type: boolean
        op_id_token_token_binding_supported:
          type: boolean
        rp_id_token_token_binding_supported:
          type: boolean
    JsonWebKeySet:
      type: object
      required:
      - keys
      properties:
        keys:
          type: array
          items:
            type: object
            properties:
              kty:
                type: string
              use:
                type: string
              alg:
                type: string
              kid:
                type: string
              x5t:
                type: string
              n:
                type: string
              e:
                type: string
              x5c:
                type: array
                items:
                  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.