University of Chicago oauth2 API

openapi: 3.0.0
info:
  title: Fence OpenAPI Specification admin/user oauth2 API
  version: 0.1.0
  description: Access management for Gen3 data commons. Code is available on [GitHub](https://github.com/uc-cdis/fence).
  termsOfService: http://cdis.uchicago.edu/terms/
  contact:
    email: cdis@uchicago.edu
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://example.domain/
tags:
- name: oauth2
  description: Authorization and token management
paths:
  /oauth2/authorize:
    get:
      tags:
      - oauth2
      summary: Perform OAuth2 authorization
      description: '**IMPORTANT NOTE**: These docs are provided as a courtesy but do _NOT_ include the entirety of the OIDC Standard

        simply because of its length and complexity.


        Please [refer to the standard](https://openid.net/specs/openid-connect-core-1_0.html) for complete details.


        Obtain an authorization grant through the OAuth2 protocol. To handle

        this request, render a page for the user to confirm the OAuth2 grant

        (through e.g. Google). Redirect user to `redirect_uri` with an added

        `code` parameter obtained from the authorization provider.

        '
      operationId: authorize
      parameters:
      - name: client_id
        required: true
        in: query
        description: The client's ID, issued by authorization server
        schema:
          type: string
      - name: response_type
        required: true
        in: query
        description: For an authorization request using the access code flow, the response type must be "code". If this is missing from the request then the authorization server must return an error.
        schema:
          type: string
      - name: redirect_uri
        required: true
        in: query
        description: Page to redirect to after access has been granted
        schema:
          type: string
      - name: idp
        required: false
        in: query
        description: Upstream identity provider to use. Specifying `idp=fence` lets us specify a `fence_idp`. Specifying `idp=shibboleth` lets us specify a `shib_idp`. If no `idp` is specified, defaults to the configured default login.
        schema:
          type: string
        example: google
      - name: fence_idp
        required: false
        in: query
        description: Upstream identity provider to use. Specifying `idp=fence` and `fence_idp=shibboleth` lets us specify a `shib_idp`. If no `fence_idp` is specified, defaults to NIH login.
        schema:
          type: string
        example: shibboleth
      - name: shib_idp
        required: false
        in: query
        description: Identifier for the shibboleth IDP. Available identifiers are what is listed by the `login.bionimbus.org/Shibboleth.sso/DiscoFeed` endpoint. If no `shib_idp` is specified, defaults to NIH login.
        schema:
          type: string
        example: urn:mace:incommon:uchicago.edu
      - name: scope
        required: false
        in: query
        description: 'Requested authorization scope. Must include `openid`. `user` allows getting a user''s access information.

          > NOTE: This is required for [OIDC](http://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)

          '
        schema:
          type: string
      - name: upstream_expires_in
        required: false
        in: query
        description: 'the time (in seconds) during which the upstream refresh token (eg. RAS) is valid. Must be less

          than the configured maximum. If it''s greater,

          the configured maximum will be used.

          '
        schema:
          type: string
      responses:
        '200':
          description: successful operation
    post:
      tags:
      - oauth2
      summary: Perform OAuth2 authorization
      description: '**IMPORTANT NOTE**: These docs are provided as a courtesy but do _NOT_ include the entirety of the OIDC Standard

        simply because of its length and complexity.


        Please [refer to the standard](https://openid.net/specs/openid-connect-core-1_0.html) for complete details.


        Obtain an authorization grant through the OAuth2 protocol. To handle

        this request, render a page for the user to confirm the OAuth2 grant

        (through e.g. Google). Redirect user to `redirect_uri` with an added

        `code` parameter obtained from the authorization provider. A POST will

        not render a page for the user; this implementation checks the `confirm`

        value in the request.

        '
      operationId: authorize_post
      responses:
        '200':
          description: successful operation
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                client_id:
                  description: The client's ID, issued by authorization server
                  type: string
                response_type:
                  description: For an authorization request using the access code flow, the response type must be "code". If this is missing from the request then the authorization server must return an error.
                  type: string
                  enum:
                  - code
                  - token
                redirect_uri:
                  description: Page to redirect to after access has been granted
                  type: string
                confirm:
                  description: whether to confirm the OAuth2 grant (should be 'yes')
                  type: string
                scope:
                  description: Requested authorization scope. Must include `openid`. `user` allows getting a user's access information.
                  type: string
                upstream_expires_in:
                  description: the time (in seconds) during which the upstream refresh token (eg. RAS) is valid. Must be less than the configured maximum. If it's greater, the configured maximum will be used.
                  type: string
              required:
              - client_id
              - response_type
              - redirect_uri
  /oauth2/token:
    post:
      tags:
      - oauth2
      summary: Exchange code for or refresh the access token.
      description: '**IMPORTANT NOTE**: These docs are provided as a courtesy but do _NOT_ include the entirety of the OIDC Standard

        simply because of its length and complexity.


        Please [refer to the standard](https://openid.net/specs/openid-connect-core-1_0.html) for complete details.


        Exchange the `code` obtained from OAuth2 for an access token, or refresh

        the access token using a refresh token.

        '
      operationId: token
      responses:
        '200':
          description: successful operation
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  description: 'Value MUST be one of the supported grant types: `"authorization_code"` or `"client_credentials"`'
                  type: string
                code:
                  description: (Required if `grant_type` is `"authorization_code"`; unused otherwise) The authorization code returned from the OAuth2 authorization request
                  type: string
                redirect_uri:
                  description: (Required if `grant_type` is `"authorization_code"`; unused otherwise) Must be identical to the `"redirect_uri"` included in the original authorization request
                  type: string
                scope:
                  description: (Optional if `grant_type` is `"client_credentials"`; unused otherwise) Requested authorization scope. If provided, must include `openid`. `user` allows getting a user's access information.
                  type: string
                client_id:
                  type: string
              required:
              - grant_type
  /oauth2/revoke:
    post:
      tags:
      - oauth2
      summary: Revoke a refresh token per RFC 7009
      description: Revoke a refresh (not access) token granted to a user.
      operationId: revoke
      responses:
        '200':
          description: successful operation, OR invalid token submitted
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                token:
                  description: Refresh token that the user wants to revoke
                  type: string
              required:
              - token
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes:
            user: generic user access