openapi: 3.0.0
info:
  title: Fence OpenAPI Specification admin/user link 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: link
  description: Link access identities
paths:
  /link/google:
    get:
      tags:
      - link
      summary: Link Google identity to user
      parameters:
      - name: redirect
        required: true
        in: query
        description: Page to redirect to after account linking
        schema:
          type: string
      - name: expires_in
        required: false
        in: query
        description: the time (in seconds) during which the Google account has bucket access. Must be less than the configured maximum (default is 24 hours). If it's greater, the configured maximum will be used.
        schema:
          type: integer
      description: "Link a Google identity to a User (AuthN using Google Oauth2 flow). Google identity will be associated with a user and added to a proxy group for that user. The user's proxy group will be given access to data via Google's IAM. `redirect` will be stored in the session to follow after linking.\n---\nIf AuthN is successful with Google, eventually will redirect to `/link/google/callback`, where the actual account linkage occur.\n> *See `/link/google/callback` endpoint for details about eventual\n   redirect with descriptive query params about success/failure.*\n"
      operationId: linkCloudIdentityStart2
      responses:
        '302':
          description: redirect to Oauth2 flow with Google to AuthN user
    patch:
      tags:
      - link
      summary: Extend Google identity's access expiration
      parameters:
      - name: expires_in
        required: false
        in: query
        description: the time (in seconds) during which the Google account has bucket access. Must be less than the configured maximum (default is 24 hours). If it's greater, the configured maximum will be used.
        schema:
          type: integer
      description: Extend previously linked Google identity's access expiration from the user's proxy group (thus extending its access to data). This can only be done if the user has ALREADY linked their Google account before.
      operationId: extendCloudIdentityExpiration
      responses:
        '200':
          description: successfully extended access
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/LinkedGoogleEmailExpiration'
        '404':
          description: No linked Google account found for user
    delete:
      tags:
      - link
      summary: Unlink a Google identity from a user
      description: Remove link between a user and a Google identity.
      operationId: unlinkCloudIdentity
      responses:
        '200':
          description: Google identity unlinked from user
        '400':
          description: Failure with Google's API to remove account from proxy group. See response for details
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/GoogleLinkingError'
        '404':
          description: No linked Google account found for user
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/GoogleLinkingError'
  /link/google/callback:
    get:
      tags:
      - link
      summary: Google's callback for linking Google identity
      description: "Linking of Google identity to user after successful Oauth2 flow with Google. Use code to retrieve user info from Google.\nWill return to session stored redirect.\nResponse will contain query params about the new linkage (`exp` or `linked_email`) or error params (`error` and `error_description`) detailing what went wrong.\n--- ---\nQuery Params on Successful Linking\n\n  * `exp`\n    * Expiration time in unix time (seconds since last epoch).\n      This represents when the newly linked account's temporary access\n      rights will be removed\n  * `linked_email`\n    * Google account email that was linked to the user and provided\n      temporary access\n\n---\nPossible Error Types (for `error` param)\n\n  * `g_acnt_link_error`\n    * Issue with the linkage between User and their Google account\n  * `g_acnt_auth_failure`\n    * Issue with Oauth2 flow to AuthN user's Google account\n  * `g_acnt_access_error`\n    * Issue with providing access to Google account by putting in\n      user's proxy group\n\nFor details about the error, check the `error_description` param.\n"
      parameters:
      - name: code
        required: true
        in: query
        description: The authorization code returned from the OAuth2 authorization request
        schema:
          type: string
      operationId: linkCloudIdentity
      responses:
        '302':
          description: redirect to session-stored redirect value
components:
  schemas:
    GoogleLinkingError:
      type: object
      properties:
        error:
          type: string
          description: Error name/class
        error_description:
          type: string
          description: Description of what caused the error
      example:
        error: error_name
        error_description: A description of what caused the error
    LinkedGoogleEmailExpiration:
      type: object
      properties:
        exp:
          type: integer
          description: expiration of linked email's access (e.g. expiration until it is removed from the user's Google Proxy Group)
      example:
        exp: 1526653869
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes:
            user: generic user access