University of Texas at Austin Credentials API

openapi: 3.2.0
info:
  title: Tapis Systems Credentials API
  description: The Tapis Systems API provides for management of Tapis Systems including permissions, credentials and Scheduler Profiles.
  version: 26Q2.0
  termsOfService: https://tapis-project.org
  contact:
    name: Systems API - CICSupport
    url: https://tapis-project.org
    email: cicsupport@tacc.utexas.edu
  license:
    name: 3-Clause BSD License
    url: https://opensource.org/licenses/BSD-3-Clause
servers:
- url: http://localhost:8080/
  description: Local test environment
  variables: {}
- url: https://dev.develop.tapis.io/
  description: Development environment
  variables: {}
tags:
- name: Credentials
  description: Manage Tapis system user access credentials.
paths:
  /v3/systems/credential/{systemId}/user/{userName}:
    get:
      tags:
      - Credentials
      description: 'Restricted. Only certain Tapis services authorized.


        Retrieve credentials for given system, target *userName* and authentication method.


        If the *effectiveUserId* for the system is dynamic (i.e. equal to *${apiUserId}*) then *{userName}* is

        interpreted as a Tapis user. Note that there may me a mapping of the Tapis user to a host *loginUser* and

        what we call the *Tapis user* comes from the username claim in the Tapis JWT.


        If the *effectiveUserId* for the system is static (i.e. not *${apiUserId}*) then *{userName}* is interpreted

        as the host *loginUser* that is used when accessing the host.


        Desired authentication method may be specified using query parameter *authnMethod*. If desired

        authentication method not specified then credentials for the system''s default authentication method are returned.


        The result includes the attribute *authnMethod* indicating the authentication method associated with

        the returned credentials.'
      operationId: getUserCredential
      security:
      - TapisJWT: []
      parameters:
      - name: systemId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/IdString'
      - name: userName
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UserNameString'
      - name: authnMethod
        in: query
        description: Desired authentication method to use when fetching credentials, default method used if not provided.
        schema:
          type: string
          default: ''
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespCredential'
        '400':
          description: Input error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '403':
          description: Permission denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '404':
          description: System not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
      summary: Get user credential
      x-summary-source: derived
    post:
      tags:
      - Credentials
      description: 'Create or update credentials in the Security Kernel for given system and target *userName* using a request body.

        Credentials for multiple authentication methods may be provided. Note that there is support for only one set of

        credentials per user per system. Updating credentials overwrites previously registered data.


        The Systems service does not store the secrets in its database, they are persisted in the Security Kernel.


        If the *effectiveUserId* for the system is dynamic (i.e. equal to *${apiUserId}*) then *{userName}* is interpreted

        as a Tapis user and the request body may contain the optional attribute *loginUser* which will be used to map the

        Tapis user to a username to be used when accessing the system. If the login user is not provided then there is

        no mapping and the Tapis user is always used when accessing the system. Note that what we call the *Tapis user*

        comes from the username claim in the Tapis JWT.


        If the *effectiveUserId* for the system is static (i.e. not *${apiUserId}*) then *{userName}* is interpreted

        as the login user to be used when accessing the host. Please note that if there is a *loginUser* field in the

        request body, TAPIS will reject the request because the static effective user is always the login user.


        Operation is allowed if requester is the system owner or a tenant administrator.

        If the *effectiveUserId* for the system is dynamic (i.e. equal to *${apiUserId}*) then the operation is allowed

        if *{userName}* is the Tapis user making the request.


        Use query parameter *createTmsKeys=true* to have the service call a Trust Manager System (TMS) server to create and

        store an ssh keypair. Default is *false*.

        Please note that the following restrictions apply:

        - Tapis installation for your site must be configured to support the Trust Manager System (TMS).

        - The host for the system must have the sshd configuration set up to use TMS.

        - The *effectiveUserId* must be dynamic.

        - Mapping of user using *loginUser* is not supported.


        By default credentials for LINUX and S3 type systems are verified. Use query parameter

        *skipCredentialCheck=true* to bypass initial credential validation.'
      operationId: createUserCredential
      security:
      - TapisJWT: []
      parameters:
      - name: systemId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/IdString'
      - name: userName
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UserNameString'
      - name: createTmsKeys
        in: query
        description: Use TMS to generate and store an ssh keypair. Default is false.
        schema:
          type: boolean
          default: false
      - name: skipCredentialCheck
        in: query
        description: Bypass initial credential validation. Default is false.
        schema:
          type: boolean
          default: false
      requestBody:
        required: true
        description: A JSON object specifying credentials.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReqUpdateCredential'
      responses:
        '200':
          description: Credentials updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '400':
          description: Input error. Invalid JSON or credential validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '403':
          description: Permission denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
      summary: Create user credential
      x-summary-source: derived
    delete:
      tags:
      - Credentials
      description: 'Remove credentials from the Security Kernel for given system and *target user*. Requester must be owner of the system.


        Operation is allowed if requester is the system owner or a tenant administrator.

        If the *effectiveUserId* for the system is dynamic (i.e. equal to *${apiUserId}*) then the operation is allowed

        if *{userName}* is the Tapis user making the request.'
      operationId: removeUserCredential
      security:
      - TapisJWT: []
      parameters:
      - name: systemId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/IdString'
      - name: userName
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UserNameString'
      responses:
        '200':
          description: Credentials removed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '400':
          description: Input error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '403':
          description: Permission denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
      summary: Remove user credential
      x-summary-source: derived
  /v3/systems/credential/{systemId}/user/{userName}/check:
    post:
      tags:
      - Credentials
      description: 'Check user credentials by connecting to the system host. Not supported for all system types. Currently supported

        for LINUX and S3 type systems.


        If the *effectiveUserId* for the system is dynamic (i.e. equal to *${apiUserId}*) then *{userName}* is interpreted

        as a Tapis user and a search is made for credentials associated with *{userName}*. Note that the Tapis user

        *{userName}* may have a mapping to a host *loginUser* in which case the *loginUser* will be used when verifying

        the credentials. Note that what we call the *Tapis user* comes from the username claim in the Tapis JWT.


        If the *effectiveUserId* for the system is static (i.e. not *${apiUserId}*) then *{userName}* is interpreted

        as the login user to be used when accessing the host. Note that this would typically be the current

        *effectiveUserId* defined for the system, but that is not a requirement. This allows for registering and

        checking credentials for a login user prior to updating the system definition.


        Operation is allowed if requester is the system owner or a tenant administrator.

        If the *effectiveUserId* for the system is dynamic (i.e. equal to *${apiUserId}*) then the operation is allowed

        if *{userName}* is the Tapis user making the request.


        Desired authentication method may be specified using query parameter *authnMethod*. If not specified,

        then credentials for the system''s default authentication method are verified.'
      operationId: checkUserCredential
      security:
      - TapisJWT: []
      parameters:
      - name: systemId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/IdString'
      - name: userName
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UserNameString'
      - name: authnMethod
        in: query
        description: Desired authentication method to use when verifying, system default method used if not provided.
        schema:
          type: string
          default: ''
      responses:
        '200':
          description: Check successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '400':
          description: Credential validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '403':
          description: Permission denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '404':
          description: System not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
      summary: Check user credential
      x-summary-source: derived
  /v3/systems/credential/{systemId}/globus/authUrl:
    get:
      tags:
      - Credentials
      summary: Retrieve a Globus URL that can be used to generate an authorization code for an…
      description: 'Retrieve a Globus URL + Session Id that can be used to generate an oauth2 authorization code associated with

        the given system. System must be of type GLOBUS.

        In Globus, the code is referred to as a *Native App Authorization Code*.

        The host property of the system is used as the Globus Endpoint Id or Globus Collection Id.

        Once a user has obtained an authorization code, the corresponding Systems endpoint for generating

        Globus tokens should be called to exchange the code + sessionId for a pair of access and refresh tokens.

        The session Id is a Tapis Id that is used to track the oauth2 flow that is started when this call is made.

        The authorization code, as per Globus documentation, is valid for 10 minutes.

        Please note that the Tapis installation for your site must be configured by the site administrator to

        support systems of type GLOBUS.'
      operationId: getGlobusAuthUrl
      security:
      - TapisJWT: []
      parameters:
      - name: systemId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/IdString'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespGlobusAuthUrl'
        '400':
          description: Input error or system not of type GLOBUS.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '401':
          description: Not Authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '404':
          description: System not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
  /v3/systems/credential/{systemId}/user/{userName}/globus/tokens/{authCode}/{sessionId}:
    post:
      tags:
      - Credentials
      summary: Use a Globus authorization code + Tapis session Id to generate tokens
      description: 'Use a Globus *Native App Authorization Code* and a Tapis session Id to generate a pair of access and refresh tokens.

        System must be of type GLOBUS.

        The Systems service will use the Tapis Security Kernel to store the tokens for the given system and user.


        If the *effectiveUserId* for the system is dynamic (i.e. equal to *${apiUserId}*) then *{userName}* must be set

        to the Tapis user. Note that what we call the *Tapis user* comes from the username claim in the Tapis JWT.


        If the *effectiveUserId* for the system is static (i.e. not *${apiUserId}*) then *{userName}* must be set to

        the static *effectiveUserId*.


        The session Id is a Tapis Id that is used to track the oauth2 flow that is started when a call to the

        getGlobusAuthUrl endpoint is made.

        The authorization code, as per Globus documentation, is valid for 10 minutes.

        Please note that the Tapis installation for your site must be configured by the site administrator to

        support systems of type GLOBUS.'
      operationId: generateGlobusTokens
      security:
      - TapisJWT: []
      parameters:
      - name: systemId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/IdString'
      - name: userName
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UserNameString'
      - name: authCode
        in: path
        required: true
        description: Authorization code to be exchanged for tokens.
        schema:
          type: string
      - name: sessionId
        in: path
        required: true
        description: Tapis session Id tracking the OAuth2 flow.
        schema:
          type: string
      responses:
        '200':
          description: Tokens generated and credentials updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '400':
          description: Input error or system not of type GLOBUS.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '401':
          description: Not Authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
components:
  schemas:
    RespGlobusAuthUrl:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
        version:
          type: string
        commit:
          type: string
        build:
          type: string
        result:
          $ref: '#/components/schemas/ResultGlobusAuthUrl'
        metadata:
          type: object
    IdString:
      type: string
      minLength: 1
      maxLength: 80
    ReqUpdateCredential:
      type: object
      properties:
        loginUser:
          $ref: '#/components/schemas/UserNameString'
        password:
          type: string
        privateKey:
          type: string
        publicKey:
          type: string
        accessKey:
          type: string
        accessSecret:
          type: string
        accessToken:
          type: string
        refreshToken:
          type: string
        certificate:
          type: string
    ResultGlobusAuthUrl:
      type: object
      properties:
        url:
          type: string
        sessionId:
          type: string
        systemId:
          type: string
    AuthnEnum:
      type: string
      enum:
      - PASSWORD
      - PKI_KEYS
      - ACCESS_KEY
      - TOKEN
      - TMS_KEYS
      - CERT
    UserNameString:
      type: string
      minLength: 1
      maxLength: 60
    Credential:
      type: object
      properties:
        authnMethod:
          $ref: '#/components/schemas/AuthnEnum'
        loginUser:
          $ref: '#/components/schemas/UserNameString'
        password:
          type: string
        privateKey:
          type: string
        publicKey:
          type: string
        accessKey:
          type: string
        accessSecret:
          type: string
        accessToken:
          type: string
        refreshToken:
          type: string
        tmsPrivateKey:
          type: string
        tmsPublicKey:
          type: string
        tmsFingerprint:
          type: string
        certificate:
          type: string
    RespBasic:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
        version:
          type: string
        commit:
          type: string
        build:
          type: string
        result:
          type: object
        metadata:
          type: object
    RespCredential:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
        version:
          type: string
        commit:
          type: string
        build:
          type: string
        result:
          $ref: '#/components/schemas/Credential'
        metadata:
          type: object
  securitySchemes:
    TapisJWT:
      type: apiKey
      description: Tapis signed JWT token authentication
      name: X-Tapis-Token
      in: header
externalDocs:
  description: Tapis Project
  url: https://tapis-project.org