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: UserNameString: type: string minLength: 1 maxLength: 60 ResultGlobusAuthUrl: type: object properties: url: type: string sessionId: type: string systemId: 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 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 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 AuthnEnum: type: string enum: - PASSWORD - PKI_KEYS - ACCESS_KEY - TOKEN - TMS_KEYS - CERT 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 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