SWITCH edu-ID / UZH Identity (SAML & OpenID Connect)

openapi: 3.0.3
info:
  title: SWITCH edu-ID OpenID Connect (UZH Federated Identity)
  description: >-
    OpenID Connect / OAuth 2.0 provider operated by SWITCH edu-ID and used by the
    University of Zurich as its central federated identity. This OpenAPI document
    is derived faithfully from the published OpenID Connect Discovery document at
    https://login.eduid.ch/.well-known/openid-configuration and the matching JWKS
    endpoint. Only endpoints, parameters, scopes, and claims actually advertised by
    the discovery document are represented here. Authorization Code flow with PKCE
    (S256) is the supported interactive flow; refresh_token is supported for
    token renewal.
  version: '2026-06-03'
  contact:
    name: SWITCH edu-ID
    url: https://login.eduid.ch/
  x-uzh-usage: >-
    UZH services rely on SWITCH edu-ID for SAML/Shibboleth and OpenID Connect
    authentication. See https://www.zi.uzh.ch/en/support/identity-access/eduid-faq.html
servers:
  - url: https://login.eduid.ch
    description: SWITCH edu-ID production issuer
tags:
  - name: Discovery
    description: OpenID Provider metadata and key material
  - name: OAuth2
    description: Authorization and token issuance
  - name: OpenID Connect
    description: Identity, userinfo, and session endpoints
paths:
  /.well-known/openid-configuration:
    get:
      tags: [Discovery]
      operationId: getOpenIdConfiguration
      summary: OpenID Provider configuration (discovery document)
      description: >-
        Returns the OpenID Provider metadata document describing supported
        endpoints, scopes, claims, response types, and signing/encryption
        algorithms.
      responses:
        '200':
          description: Provider metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenIdConfiguration'
  /idp/profile/oidc/keyset:
    get:
      tags: [Discovery]
      operationId: getJwks
      summary: JSON Web Key Set (JWKS)
      description: Returns the provider's public keys used for signing and encryption.
      responses:
        '200':
          description: A JWK Set
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JwkSet'
  /idp/profile/oidc/authorize:
    get:
      tags: [OAuth2]
      operationId: authorize
      summary: Authorization endpoint
      description: >-
        Initiates the OAuth 2.0 Authorization Code flow. PKCE (code_challenge with
        method S256) is supported. The only advertised response_type is "code"
        and response_mode may be query, fragment, or form_post.
      parameters:
        - name: response_type
          in: query
          required: true
          schema:
            type: string
            enum: [code]
        - name: client_id
          in: query
          required: true
          schema:
            type: string
        - name: redirect_uri
          in: query
          required: true
          schema:
            type: string
            format: uri
        - name: scope
          in: query
          required: true
          description: Space-delimited scopes; must include "openid".
          schema:
            type: string
            example: openid profile email
        - name: state
          in: query
          required: false
          schema:
            type: string
        - name: nonce
          in: query
          required: false
          schema:
            type: string
        - name: code_challenge
          in: query
          required: false
          schema:
            type: string
        - name: code_challenge_method
          in: query
          required: false
          schema:
            type: string
            enum: [S256]
        - name: response_mode
          in: query
          required: false
          schema:
            type: string
            enum: [query, fragment, form_post]
      responses:
        '302':
          description: >-
            Redirect back to redirect_uri with an authorization code (or an error).
          headers:
            Location:
              schema:
                type: string
                format: uri
  /idp/profile/oidc/token:
    post:
      tags: [OAuth2]
      operationId: token
      summary: Token endpoint
      description: >-
        Exchanges an authorization code for tokens or refreshes an access token.
        Supported grant types are authorization_code and refresh_token.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          description: Token response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: OAuth 2.0 error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
  /idp/profile/oidc/userinfo:
    get:
      tags: [OpenID Connect]
      operationId: userinfo
      summary: UserInfo endpoint
      description: Returns claims about the authenticated end-user.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: UserInfo claims
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
        '401':
          description: Invalid or missing access token
  /idp/profile/oauth2/introspection:
    post:
      tags: [OAuth2]
      operationId: introspect
      summary: Token introspection endpoint (RFC 7662)
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [token]
              properties:
                token:
                  type: string
                token_type_hint:
                  type: string
                  enum: [access_token, refresh_token]
      responses:
        '200':
          description: Introspection result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntrospectionResponse'
  /idp/profile/oauth2/revocation:
    post:
      tags: [OAuth2]
      operationId: revoke
      summary: Token revocation endpoint (RFC 7009)
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [token]
              properties:
                token:
                  type: string
                token_type_hint:
                  type: string
                  enum: [access_token, refresh_token]
      responses:
        '200':
          description: Token revoked (or already invalid)
  /idp/profile/oidc/end-session:
    get:
      tags: [OpenID Connect]
      operationId: endSession
      summary: End-session (RP-initiated logout) endpoint
      parameters:
        - name: id_token_hint
          in: query
          required: false
          schema:
            type: string
        - name: post_logout_redirect_uri
          in: query
          required: false
          schema:
            type: string
            format: uri
        - name: state
          in: query
          required: false
          schema:
            type: string
      responses:
        '302':
          description: Redirect after session termination
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    oidc:
      type: openIdConnect
      openIdConnectUrl: https://login.eduid.ch/.well-known/openid-configuration
  schemas:
    OpenIdConfiguration:
      type: object
      description: OpenID Provider metadata as advertised by the discovery endpoint.
      properties:
        issuer:
          type: string
          format: uri
          example: https://login.eduid.ch/
        authorization_endpoint:
          type: string
          format: uri
        token_endpoint:
          type: string
          format: uri
        userinfo_endpoint:
          type: string
          format: uri
        introspection_endpoint:
          type: string
          format: uri
        revocation_endpoint:
          type: string
          format: uri
        end_session_endpoint:
          type: string
          format: uri
        jwks_uri:
          type: string
          format: uri
        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
        code_challenge_methods_supported:
          type: array
          items:
            type: string
        token_endpoint_auth_methods_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
        claims_supported:
          type: array
          items:
            type: string
    JwkSet:
      type: object
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/Jwk'
    Jwk:
      type: object
      properties:
        kty:
          type: string
          example: RSA
        use:
          type: string
          enum: [sig, enc]
        kid:
          type: string
        alg:
          type: string
          nullable: true
        n:
          type: string
        e:
          type: string
        crv:
          type: string
        x:
          type: string
        y:
          type: string
    TokenRequest:
      type: object
      required: [grant_type]
      properties:
        grant_type:
          type: string
          enum: [authorization_code, refresh_token]
        code:
          type: string
        redirect_uri:
          type: string
          format: uri
        code_verifier:
          type: string
        refresh_token:
          type: string
        client_id:
          type: string
        client_secret:
          type: string
    TokenResponse:
      type: object
      required: [access_token, token_type]
      properties:
        access_token:
          type: string
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
        scope:
          type: string
        id_token:
          type: string
          description: Signed JWT ID token (present when openid scope requested).
        refresh_token:
          type: string
    OAuthError:
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
    IntrospectionResponse:
      type: object
      properties:
        active:
          type: boolean
        scope:
          type: string
        client_id:
          type: string
        token_type:
          type: string
        exp:
          type: integer
        iat:
          type: integer
        sub:
          type: string
        aud:
          type: string
        iss:
          type: string
    UserInfo:
      type: object
      description: >-
        Claims about the end-user. Only claims advertised in claims_supported by
        the discovery document are listed; many are SWITCH edu-ID specific
        (swissEduPerson*, swissEduID*) or eduPerson schema attributes.
      properties:
        sub:
          type: string
        name:
          type: string
        given_name:
          type: string
        family_name:
          type: string
        gender:
          type: string
        birthdate:
          type: string
        locale:
          type: string
        email:
          type: string
          format: email
        email_verified:
          type: boolean
        swissEduID:
          type: string
        swissEduIDUniqueID:
          type: string
        swissEduIDAssuranceLevel:
          type: string
        swissEduPersonUniqueID:
          type: string
        swissEduPersonMatriculationNumber:
          type: string
        swissEduPersonHomeOrganization:
          type: string
        swissEduPersonHomeOrganizationType:
          type: string
        eduPersonAffiliation:
          type: array
          items:
            type: string
        eduPersonScopedAffiliation:
          type: array
          items:
            type: string
        eduPersonPrincipalName:
          type: string
        eduPersonOrcid:
          type: string
        schacHomeOrganization:
          type: string
        schacHomeOrganizationType:
          type: string