swagger: "2.0"
info:
  description: "Enterprise API for managing roles, permissions, and user mappings"
  version: "0.0.1"
  title: "Anchore Enterprise RBAC API"
  contact:
    email: "dev@anchore.com"
tags:
- name: Users
  description: User management
basePath: "/"
schemes:
- "http"
- "https"
consumes:
- application/json
produces:
- application/json

paths:
  /health:
    get:
      x-swagger-router-controller: anchore_engine.apis.common
      operationId: health_check
      x-anchore-authz-action: None
      description: Health check, returns 200 and no body if service is running
      responses:
        200:
          description: Empty body on success
  /version:
    get:
      x-swagger-router-controller: anchore_enterprise.common.apis
      operationId: version_check
      x-anchore-authz-action: None
      description: Returns the version object for the service, including db schema version info
      responses:
        200:
          description: Version object describing version state
          schema:
            $ref: "#/definitions/ServiceVersion"
  /status:
    get:
      x-swagger-router-controller: anchore_enterprise.services.rbac_manager.api.controllers.status
      operationId: get_status
      x-anchore-authz-action: None
      summary: Service status
      description: Get the API service status
      responses:
        200:
          description: Status listing
          schema:
            $ref: "#/definitions/StatusResponse"
        500:
          description: Internal error
          schema:
            $ref: "#/definitions/ApiErrorResponse"
  /roles:
    get:
      x-swagger-router-controller: anchore_enterprise.services.rbac_manager.api.controllers.roles
      x-anchore-authz-action: listRoles
      operationId: list_roles
      summary: List roles available in the system
      responses:
        200:
          description: Role summary listing
          schema:
            $ref: "#/definitions/RoleSummaryList"
        500:
          description: Internal error
          schema:
            $ref: "#/definitions/ApiErrorResponse"
  /roles/{rolename}:
    get:
      x-swagger-router-controller: anchore_enterprise.services.rbac_manager.api.controllers.roles
      operationId: get_role
      x-anchore-authz-action: getRole
      summary: Get detailed information about a specific role
      parameters:
      - name: rolename
        in: path
        required: true
        type: string
      responses:
        200:
          description: Role details
          schema:
            $ref: "#/definitions/Role"
        500:
          description: Internal error
          schema:
            $ref: "#/definitions/ApiErrorResponse"
  /roles/{rolename}/members:
    get:
      x-swagger-router-controller: anchore_enterprise.services.rbac_manager.api.controllers.roles
      operationId: list_role_members
      x-anchore-authz-action: listRoleMembers
      summary: Returns a list of objects that have members in the role. The list is filtered by 'listRoleMembers' access for the 'account' element of each entry.
      parameters:
      - name: rolename
        in: path
        required: true
        type: string
      - name: for_account
        in: query
        required: false
        type: string
        description: Optional filter paramter to limit the set fo returned items to only those with matching account. Will return Access Denied if caller does not have permission to listRoleMembers for that account.
      responses:
        200:
          description: List of users assigned the role
          schema:
            $ref: "#/definitions/RoleMemberList"
        500:
          description: Internal error
          schema:
            $ref: "#/definitions/ApiErrorResponse"
    post:
      x-swagger-router-controller: anchore_enterprise.services.rbac_manager.api.controllers.roles
      operationId: add_role_user
      x-anchore-authz-action: createRoleMember
      summary: Add a user to the role
      parameters:
      - name: rolename
        in: path
        type: string
        required: true
      - name: member
        in: body
        required: true
        schema:
          $ref: "#/definitions/RoleMember"
      responses:
        200:
          description: Added user mapping
          schema:
            $ref: "#/definitions/RoleMember"
        500:
          description: Internal error
          schema:
            $ref: "#/definitions/ApiErrorResponse"
    delete:
      x-swagger-router-controller: anchore_enterprise.services.rbac_manager.api.controllers.roles
      operationId: delete_role_user
      x-anchore-authz-action: deleteRoleMember
      summary: Remove a user from the role
      parameters:
      - name: rolename
        in: path
        type: string
        required: true
      - name: username
        in: query
        required: true
        type: string
        description: The username to remove the role for
      - name: for_account
        in: query
        required: true
        type: string
        description: The account that the user has the role to be removed
      responses:
        204:
          description: Success
        500:
          description: Internal error
          schema:
            $ref: "#/definitions/ApiErrorResponse"
  /my_roles:
    get:
      x-swagger-router-controller: anchore_enterprise.services.rbac_manager.api.controllers.roles
      x-anchore-authz-action: None
      operationId: my_roles
      summary: List the roles for which the authenticated user is a member
      responses:
        200:
          description: Role summary listing
          schema:
            $ref: "#/definitions/UserRoleListing"
        500:
          description: Internal error
          schema:
            $ref: "#/definitions/ApiErrorResponse"
  /users/{username}/roles:
    get:
      x-swagger-router-controller: anchore_enterprise.services.rbac_manager.api.controllers.roles
      x-anchore-authz-action: None
      operationId: list_user_roles
      summary: List the roles for which the requested user is a member
      parameters:
        - name: username
          in: path
          type: string
          required: true
        - name: for_account
          in: query
          type: string
          required: false
        - name: role
          in: query
          type: string
          required: false
      responses:
        200:
          description: Role summary listing
          schema:
            $ref: "#/definitions/UserRoleMembership"
        500:
          description: Internal error
          schema:
            $ref: "#/definitions/ApiErrorResponse"
#  /oauth/create_client:
#    post:
#      x-swagger-router-controller: anchore_enterprise.services.rbac_manager.api.controllers.auth
#      operationId: create_client
#      x-anchore-authz-action: None
#      description: Create a new client record
#      consumes:
##        - application/x-www-form-urlencoded
#        - application/json
#      parameters:
#        - name: client_definition
#          schema:
#            type: object
#          in: body
#          required: true
#      responses:
#        200:
#          description: Client id
#          schema:
#            type: string
#        500:
#          description: Internal error
#          schema:
#            $ref: "#/definitions/ApiErrorResponse"
#
#  /oauth/token:
#    post:
#      x-swagger-router-controller: anchore_enterprise.services.rbac_manager.api.controllers.auth
#      operationId: get_oauth_token
#      x-anchore-authz-action: None
#      description: Request a jwt token for subsequent operations, this request is authenticated with normal HTTP auth
#      consumes:
#        - application/x-www-form-urlencoded
#      responses:
#        200:
#          description: Resulting JWT token
#          schema:
#            $ref: "#/definitions/TokenResponse"
#        500:
#          description: Internal error
#          schema:
#            $ref: "#/definitions/ApiErrorResponse"

  /saml/login/{idp_name}:
    get:
      x-swagger-router-controller: anchore_enterprise.services.rbac_manager.api.controllers.auth
      operationId: saml_login
      x-anchore-authz-action: None
      description: Initiate an SP-initiated login sequence for the Idp. The SP will respond with the SAML AuthN Request the client must send to the Idp URL
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - name: idp_name
          in: path
          type: string
          required: true
      responses:
        200:
          description: Resulting JWT token
          schema:
            $ref: "#/definitions/TokenResponse"
        500:
          description: Internal error
          schema:
            $ref: "#/definitions/ApiErrorResponse"
  /saml/sso/{idp_name}:
    post:
      x-swagger-router-controller: anchore_enterprise.services.rbac_manager.api.controllers.auth
      operationId: saml_sso
      x-anchore-authz-action: None
      description: Perform a login using a SAML assertion, no HTTP auth is required as the SAML assertion is considered the authenticating token
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - name: idp_name
          in: path
          required: true
          type: string
      responses:
        200:
          description: Resulting JWT token
          schema:
            $ref: "#/definitions/TokenResponse"
        500:
          description: Internal error
          schema:
            $ref: "#/definitions/ApiErrorResponse"
  /saml/idps:
    get:
      x-swagger-router-controller: anchore_enterprise.services.rbac_manager.api.controllers.auth
      operationId: list_idps
      x-anchore-authz-action: None
      description: List the names of configured Identity Providers for this anchore installation
      responses:
        200:
          description: List of idp names
          schema:
            type: array
            items:
              type: string
              description: Name of idp for login or config operations
        500:
          description: Internal error
          schema:
            $ref: "#/definitions/ApiErrorResponse"
    post:
      x-swagger-router-controller: anchore_enterprise.services.rbac_manager.api.controllers.auth
      operationId: add_idp
      x-anchore-authz-action: None
      description: Add a new Identity Provider to the system, with a specific name
      parameters:
        - name: configuration
          in: body
          required: true
          schema:
            $ref: "#/definitions/SamlConfiguration"
      responses:
        200:
          description: Entry created
          schema:
            $ref: "#/definitions/SamlConfiguration"
        409:
          description: Conflict, entry already exists
          schema:
            $ref: "#/definitions/ApiErrorResponse"
        500:
          description: Internal error
          schema:
            $ref: "#/definitions/ApiErrorResponse"
  /saml/idps/{name}:
    get:
      x-swagger-router-controller: anchore_enterprise.services.rbac_manager.api.controllers.auth
      operationId: get_idp
      x-anchore-authz-action: None
      description: Return the configuration for a named Identity Provider
      parameters:
        - name: name
          in: path
          required: true
          type: string
      responses:
        200:
          description: Successfully retrieved configuration
          schema:
            $ref: "#/definitions/SamlConfiguration"
        404:
          description: Not found
          schema:
            $ref: "#/definitions/ApiErrorResponse"
        500:
          description: Internal error
          schema:
            $ref: "#/definitions/ApiErrorResponse"
    put:
      x-swagger-router-controller: anchore_enterprise.services.rbac_manager.api.controllers.auth
      operationId: update_idp
      x-anchore-authz-action: None
      description: Update an existing Identity Provider configuration
      parameters:
        - name: name
          in: path
          required: true
          type: string
        - name: configuration
          in: body
          required: true
          schema:
            $ref: "#/definitions/SamlConfiguration"
      responses:
        200:
          description: Sucessfully updated configuration
          schema:
            $ref: "#/definitions/SamlConfiguration"
        404:
          description: Not found
          schema:
            $ref: "#/definitions/ApiErrorResponse"
        400:
          description: Not found
          schema:
            $ref: "#/definitions/ApiErrorResponse"
        500:
          description: Internal error
          schema:
            $ref: "#/definitions/ApiErrorResponse"
    delete:
      x-swagger-router-controller: anchore_enterprise.services.rbac_manager.api.controllers.auth
      operationId: delete_idp
      x-anchore-authz-action: None
      description: Delete an idp configuration. Users will not longer be able to login from this idp
      parameters:
        - name: name
          in: path
          required: true
          type: string
      responses:
        204:
          description: Successfully deleted
        404:
          description: Not found
        500:
          description: Internal error
          schema:
            $ref: "#/definitions/ApiErrorResponse"
definitions:
  Role:
    type: object
    description: Role definition
    required:
    - name
    properties:
      name:
        type: string
        description: The name of the role
      description:
        type: string
        description: A role description for humans
      permissions:
        $ref: "#/definitions/PermissionList"
      immutable:
        type: boolean
        description: Are the permissions of this role modifiable by users (including admin users)
      created_at:
        type: string
        format: date-time
        description: The timestamp when the role was created
      last_updated:
        type: string
        format: date-time
        description: The timestamp of the last update to the role metadata itself
  Permission:
    type: object
    description: A grant of specific action against a specific scope and target
    properties:
      action:
        type: string
        description: The allowed action. e.g. getImage
      target:
        type: string
        description: The target to which the action may be applied. Either a '*' for all or a specific target id
  PermissionList:
    type: array
    items:
      $ref: "#/definitions/Permission"
  RoleMember:
    type: object
    description: A mapping between a username and a role with an account context
    required:
      - username
      - for_account
    properties:
      username:
        type: string
      for_account:
        type: string
      created_at:
        type: string
        format: date-time
  RoleMemberList:
    type: array
    description: List of members of the role, may be filtered by the calling user's access level (e.g. will not display members for which the caller doesn't have listRoleMembers acocunt access)
    items:
      $ref: "#/definitions/RoleMember"
  RoleSummaryList:
    type: array
    items:
      $ref: "#/definitions/RoleSummary"
  RoleSummary:
    type: object
    properties:
      name:
        type: string
      description:
        type: string
      created_at:
        type: string
        format: date-time
#      permissions:
#        $ref: "#/definitions/PermissionList"
  UserRoleListing:
    type: array
    description: List of role mappings for a user
    items:
      $ref: "#/definitions/AccountRole"
  AccountRole:
    type: object
    description: An account identifier and roles a user has within that account
    properties:
      for_account:
        type: string
        description: The account scope that applies to the set of roles
      roles:
        $ref: "#/definitions/Role"
  UserRoleMembership:
    type: array
    description: List of role mappings for a user
    items:
      $ref: "#/definitions/RoleMembership"
  RoleMembership:
    type: object
    description: Membership for a role in an account
    properties:
      role:
        type: string
        description: The name of the role the user has permissions for
      for_account:
        type: array
        items:
          type: string
          description: The accounts for which the user has the role permission
      created_at:
        type: string
        format: date-time
  ApiErrorResponse:
    description: "Generic HTTP API error response"
    type: object
    properties:
      code:
        type: integer
        format: int32
      error_type:
        type: "string"
      message:
        type: "string"
      detail:
        type: object
        description: Details structure for additional information about the error if available. Content and structure will be error specific.
  StatusResponse:
    type: object
    description: System status response
    properties:
      busy:
        type: boolean
      up:
        type: boolean
      message:
        type: string
  ServiceVersion:
    type: object
    description: Version information for a service
    properties:
      service:
        type: object
        properties:
          version:
            type: string
            description: Semantic Version string of the service implementation
      api:
        type: object
        description: Api Version string
        properties:
          version:
            type: string
            description: Semantic version of the api
      db:
        type: object
        properties:
          schema_version:
            type: string
            description: Semantic version of the db schema
      engine:
        type: object
        properties:
          version:
            type: string
            description: Version of the installed engine library
          db:
            type: string
            description: Version of the installed engine db schema

  TokenResponse:
    type: object
    description: An auth token for use in future requests as an Authorization header value of type 'bearer'
    required:
      - token
    properties:
      token:
        type: string
        description: The token content
  SamlConfiguration:
    type: object
    description: A named configuration for interaction with an Identity Provider that supports SAML 2.0
    required:
      - name
      - sp_entity_id
      - acs_url
      - enabled
    properties:
      name:
        type: string
        description: The name to use for referencing this IDP configuration. This will configured as part of the url string the Idp must have the client POST the saml assertion to.
        pattern: '^[a-zA-Z0-9_-]+$'
      enabled:
        type: boolean
        description: If this IDP configuration should be enabled for user logins
      sp_entity_id:
        type: string
        description: The entity ID for this SP. Can be the same for all IDP configurations in this installation or unique to each. This is typically a URL, but you can use any value as long as you also configure the IDP to expect this value.
      acs_url:
        type: string
        description: The URL the IDP can use to access the Assertion Consumer Service to provide the token for sso. This is the way to reach the rbac manager services /v1/saml/sso/{IDP_name} route externally
      acs_https_port:
        type: integer
        description: The port number to use for https if not 443. If omitted or -1, 443 is assumed and used as a default
      idp_metadata_url:
        type: string
        description: The url where the SP (anchore) can retrieve the metadata about the Identity Provider. Only one of this or metadata_xml should be set. This is typically provided by the IDP.
      idp_metadata_xml:
        type: string
        description: The direct metadata xml payload, if a url is not available. Only one of this or metadata_url should be set.
      idp_username_attribute:
        type: string
        description: The SAML attribute to use from the response assertions to determine the anchore username. If unset, the subject is used.
      idp_account_attribute:
        type: string
        description: The SAML attribute to use from the response assertions to determine the anchore account to use. If unset, the default is used.
      idp_role_attribute:
        type: string
        description: The SAML attribute to use from the response assertions to determine the anchore role(s) to assign a new user in the specified account. If unset, the default is used.
      default_account:
        type: string
        description: The existing anchore account to assign all users to from this IDP if no account attribute is mapped or present.
      default_role:
        type: string
        description: The default role to apply to new users from this IDP if no attribute is mapped or found in the SAML assertions.
      require_signed_assertions:
        type: boolean
        description: Require assertions in to be signed from the IDP
        default: true
      require_signed_response:
        type: boolean
        description: Require the authn response to be signed by the IDP
        default: true
      created_at:
        type: string
        format: date-time
      last_updated:
        type: string
        format: date-time
