api.raml

#%RAML 1.0
title: ID Broker
version: 4
protocols: [ HTTPS ]
mediaType: application/json
securitySchemes:
  AuthzBearerToken:
      type: x-{other}
      describedBy:
        headers:
          Authorization:
            type: string
            example: Bearer abc123
securedBy: [ AuthzBearerToken ]

types:
  Authentication:
    type: object
    properties:
      username?: string
      password?: string
      invite?: string
    examples:
      password: |
        {
          "username": "john_smith",
          "password": "correcthorsebatterystaple"
        }
      invite: |
        {
          "invite": "726fa32e-015d-46fb-ba5c-a579b4a4dcbf"
        }
  Error:
    type: object
    properties:
      name: string
      message: string
      code: integer
      status: integer
    example: |
      {
        "name": "Bad Request",
        "message": "",
        "code": 0,
        "status": 400
      }
  UserResponse:
    description: >
      Information on user record. Password is not included if a password
      has not been assigned to the user. Method options are included only
      if `method.review` is 'yes' and only in response to `POST /authentication`,
      otherwise it will be an empty list.
    type: object
    properties:
      uuid?: string
      employee_id?: string
      first_name?: string
      last_name?: string
      display_name?: string
      username?: string
      email?: string
      active?:
        enum: [ yes, no ]
      locked?:
        enum: [ yes, no ]
      last_login_utc?: string
      created_utc?: string
      deactivated_utc?: string
      manager_email?: string
      personal_email?: string
      hide:
        enum: [ yes, no ]
      member: string[]
      mfa:
        type: object
        properties:
          prompt:
            enum: [ yes, no ]
            description: Flag to indicate that the user must be prompted to provide an mfa before login
          add:
            enum: [ yes, no ]
            description: Flag to indicate whether to remind the user to add an MFA option
          active:
            enum: [ yes, no ]
            description: Flag to indicate whether the user has at least one active MFA option
          options: MfaResponse[]
      method:
        type: object
        properties:
          add:
            enum: [ yes, no ]
            description: Flag to indicate whether to remind the user to add a recovery method
          options: MethodResponse[]
      password?:
        type: object
        properties:
          created_utc: string
          expires_on: string
      profile_review:
        enum: [ yes, no ]
        description: >
          Flag to indicate whether to remind the user to review their mfa options and
          recovery methods.
      require_mfa?:
        enum: [ yes, no ]
    example: |
      {
        "uuid": "11111111-aaaa-1111-aaaa-111111111111",
        "employee_id": "12345",
        "first_name": "John",
        "last_name": "Smith",
        "display_name": "John Smith",
        "username": "john_smith",
        "email": "john_smith@example.com",
        "active": "yes",
        "locked": "no",
        "last_login_utc": "2017-05-24T14:04:51Z",
        "created_utc": "2017-05-24T14:04:51Z",
        "deactivated_utc": null,
        "hide": "no",
        "member": [],
        "mfa": {
          "prompt": "yes",
          "add": "no",
          "active": "yes",
          "options": [
            {
              "id": 123,
              "type": "totp",
              "label": "Google Authenticator",
              "created_utc": "2017-10-24T20:40:47Z",
              "last_used_utc": null,
              "data": {
                "count": 10
              }
            },
            {
              "id": 432,
              "type": "webauthn",
              "label": "Blue YubiKey",
              "created_utc": "2017-10-24T20:40:47Z",
              "last_used_utc": null,
              "data": []
            },
            {
              "id": 345,
              "type": "backupcode",
              "label": "2SV #1",
              "created_utc": "2017-10-24T20:40:47Z",
              "last_used_utc": null,
              "data": []
            }
          ]
        },
        "password": {
          "created_utc":"2017-05-24T14:04:51Z",
          "expires_on":"2018-05-24T23:59:59Z"
        },
        "method": {
          "add": "no",
          "options": [
            {
              "id": "0YrSiNp2P6sfkleepNNvFYMQWuLfssve",
              "value": "email@example.org",
              "verified": true,
              "created": "2017-10-24T20:40:47Z"
            }
          ]
        },
        "profile_review": "yes"
      }
  UserCreation:
    type: object
    properties:
      employee_id: string
      first_name: string
      last_name: string
      display_name?: string
      username: string
      email: string
      active?:
        enum: [ yes, no ]
      locked?:
        enum: [ yes, no ]
      manager_email?: string
      personal_email?: string
      hide:
        enum: [ yes, no ]
      groups?: string
    example: |
      {
        "employee_id": "12345",
        "first_name": "John",
        "last_name": "Smith",
        "username": "john_smith",
        "email": "john_smith@example.com",
        "hide": "no"
      }
  UserUpdate:
    type: object
    properties:
      first_name?: string
      last_name?: string
      display_name?: string
      username?: string
      email?: string
      active?:
        enum: [ yes, no ]
      locked?:
        enum: [ yes, no ]
      manager_email?: string
      personal_email?: string
      hide?:
        enum: [ yes, no ]
      groups?: string
    example: |
      {
        "active": "no"
      }
  MfaCreation:
    type: object
    properties:
      employee_id: string
      type:
        enum: [ backupcode, totp, webauthn, manager ]
      label?: string
    example: |
      {
        "employee_id": "12345",
        "type": "backupcode"
      }
  MfaCreationResponse:
    type: object
    properties:
      id: integer
      data: string[]
    example: |
      {
        "id": 3,
        "data": [
          "51231235",
          "74475261",
          "72412792",
          "23221473",
          "30936163",
          "09641891",
          "99517242",
          "08751652",
          "32842734",
          "25937677"
        ]
      }
  MfaResponse:
    type: object
    properties:
      id: integer
      type:
        enum: [ backupcode, totp, webauthn, manager ]
      label: string
      created_utc: string
      last_used_utc: string?
      data:
        type: object|array
    examples: |
      backupcode: |
        {
            "id": 7,
            "type": "backupcode",
            "label": "2SV #1",
            "created_utc": "2017-10-24T20:40:47Z",
            "last_used_utc": null,
            "data": {
                "count": 10
            }
        }
      webauthn: |
        {
            "id": 8,
            "type": "webauthn",
            "label": "",
            "created_utc": "2017-10-24T20:40:57Z",
            "last_used_utc": null,
            "data": [
                {
                    "id": 88,
                    "label": "My Webauthn Key",
                    "last_used_utc": null,
                    "created_utc": "2022-12-15 19:42:37"
                }
            ]
        }
      totp: |
        {
            "id": 9,
            "type": "totp",
            "label": "2SV #3",
            "created_utc": "2017-10-24T20:41:05Z",
            "last_used_utc": null,
            "data": []
        }
  WebauthnResponse:
    type: object
    properties:
      id: integer
      mfa_id: integer
      key_handle_hash: string
      label: string
      created_utc: string
      last_used_utc: string?
    example: |
      {
        "id": 81,
        "mfa_id": 8,
        "key_handle_hash": "1234567890123456789012345678901234567890ABC",
        "label": "My First Security Key",
        "created_utc": "2017-10-24T20:40:57Z",
        "last_used_utc": null,
      }
  Method:
    type: object
    properties:
      employee_id: string
      value: string
    example: |
      {
        "employee_id": "12345",
        "value": "email@example.org"
      }
  MethodResponse:
    description:
    type: object
    properties:
      id: string
      value: string
      verified: boolean
      created: string
    example: |
      {
          "id": "0YrSiNp2P6sfkleepNNvFYMQWuLfssve",
          "value": "email@example.org",
          "verified": true,
          "created": "2017-10-24T20:41:05Z"
      }
/authentication:
  post:
    queryParameters:
      rpOrigin:
        description: relying party origin
        type: string
        example: "https://sub.domain.com"
    body:
      type: Authentication
    responses:
      200:
        description: >
          The given credentials were acceptable/valid (i.e. - the
          authentication succeeded). The body of the response will have the
          attributes of the authenticated User.
        body:
          type: UserResponse
      400:
        description: >
          The given credentials were NOT acceptable/valid (i.e. - the
          authentication failed).
        body:
          type: Error
      403:
        description: The rpOrigin does not match any of the configured values.
        body:
          type: Error
      410:
        description: >
          The invite has expired. A new code has been generated and emailed
          to the user.
        body:
          type: Error
      500:
        description: A server-side error occurred.
        body:
          type: Error
/user:
  get:
    description: Get a list of the existing users.
    queryParameters:
      fields?:
        type: string
        description: A comma-delimited list of fields to include for each user.
        default: "uuid,employee_id,first_name,last_name,display_name,username,email,active,locked,password"
        example: "employee_id,active"
      username?:
        type: string
        description: Search user by username.
        example: "john_smith"
      email?:
        description: Search user by email.
        type: string
        example: "john_smith@example.com"
      search?:
        description: |
          Partial text search across multiple fields: 'employee_id', 'first_name',
          'last_name', 'display_name', 'username', 'email', and 'personal_email'
        type: string
        example: "@example.com"
      mask?:
        description: |
          Mask personal information (method options, personal_email) for privacy.
          Default is 'yes'.
        enum: [ yes, no ]
    responses:
      200:
        body:
          type: UserResponse[]
  post:
    description: Create a new user record.
    body:
      type: UserCreation
    responses:
      200:
        description: The new user record was created.
        body:
          type: UserResponse
      422:
        description: The given user data does not satisfy some validation rule.
        body:
          type: Error
      500:
        description: A server-side error occurred.
        body:
          type: Error
  /{employee_id}:
    get:
      description: Get information about a specific user.
      responses:
        200:
          description: >
            The corresponding user record (matching on the `employee_id` URL
            parameter).
          body:
            type: UserResponse
        204:
          description: No user record was found with that `employee_id`.
    put:
      description: Update a user record.
      body:
        type: UserUpdate
      responses:
        200:
          description: >
            The corresponding user record (matching on the `employee_id` URL
            parameter) was updated to match the given data.
          body:
            type: UserResponse
        204:
          description: No user record was found with that `employee_id`.
        422:
          description: The given user data does not satisfy some validation rule.
          body:
            type: Error
        500:
          description: A server-side error occurred.
          body:
            type: Error
    /update-last-login:
      put:
        description: Update the last login timestamp of a user based on their employee ID.
        responses:
          200:
            description: Successfully updated the last login time.
            body:
              properties:
                employee_id: string
                last_login_utc: string
              example: |
                {
                  "employee_id": "12345",
                  "last_login_utc": "2024-09-18T12:34:56Z"
                }
          404:
            description: Not found. The user with the specified `employeeId` was not found.
          500:
            description: Server error. Failed to update the last login time.
    /mfa:
      get:
        description: Get a list of configured MFA devices for user
        queryParameters:
          rpOrigin?:
            type: string
            description: The Relying Party origin url (only needed for WebAuthn)
            default: ""
            example: "https://sub.domain.com"
        responses:
          200:
            body:
              type: MfaResponse[]
          400:
            description: User not found for given `employee_id`
            body:
              type: Error
    /method:
      get:
        description: Get a list of verified and unverified recovery methods for user
        responses:
          400:
            description: User not found for given `employee_id`
            body:
              type: Error
          200:
            body:
              type: MethodResponse[]
    /password:
      put:
        description: Set the password for a User.
        body:
          properties:
            password: string
          example: |
            {
              "password": "correcthorsebatterystaple"
            }
        responses:
          200:
            description: >
              The password for the user with that `employee_id` was successfully updated.
            body:
              type: UserResponse
          204:
            description: No user record was found with that `employee_id`.
          409:
            description: A recently-used password was given.
            body:
              type: Error
              example: |
                {
                  "name": "Conflict",
                  "message": "May not be reused yet.",
                  "code": 1542395933,
                  "status": 409
                }
          422:
            description: >
              The given password does not meet some requirement (such as if an
              empty string was given).
            body:
              type: Error
          500:
            description: A server-side error occurred.
            body:
              type: Error
      /assess:
        put:
          description: Validate a potential new password. Does not save the password.
          body:
            properties:
              password: string
            example: |
              {
                "password": "correcthorsebatterystaple"
              }
          responses:
            204:
              description: >
                The `password` is valid for the user with the given `employee_id`.
            404:
              description: No user found with given `employee_id`.
              body:
                type: Error
            409:
              description: A recently-used password was given.
              body:
                type: Error
                example: |
                  {
                    "name": "Conflict",
                    "message": "May not be reused yet.",
                    "code": 1542395933,
                    "status": 409
                  }
            422:
              description: >
                The given password does not meet some requirement (such as if an
                empty string was given).
              body:
                type: Error
            500:
              description: A server-side error occurred.
              body:
                type: Error
/mfa:
  post:
    description: Create a new mfa record.
    queryParameters:
      rpOrigin?:
        type: string
        description: The Relying Party origin url (only needed for WebAuthn)
        default: ""
        example: "https://sub.domain.com"
    body:
      type: MfaCreation
    responses:
      200:
        description: The new mfa record was created.
        body:
          type: MfaCreationResponse
      400:
        description: The given mfa data does not satisfy some validation rule.
        body:
          type: Error
      409:
        description: >
          An MFA of the requested type already exists. Note that this would only
          be returned for 'totp' or 'webauthn'. The code types ('backupcode' and
          'manager') reuse the existing MFA and create new codes.
        body:
          type: Error
      500:
        description: The server encountered an error
        body:
          type: Error
  /{id}:
    put:
      description: Update an MFA label
      body:
        properties:
          employee_id: string
          label: string
        example: |
          {
            "employee_id": "12345",
            "label": "My blue USB key"
          }
      responses:
        200:
          body:
            type: MfaResponse
        400:
          description: Missing or invalid employee_id
          body:
            type: Error
        404:
          description: MFA record not found or mismatched employee_id
          body:
            type: Error
        500:
          description: The server encountered an error
          body:
            type: Error
    delete:
      description: Delete an MFA configuration
      body:
        properties:
          employee_id: string
        example: |
          {
            "employee_id": "12345"
          }
      responses:
        204:
          description: Successful deletion of record
        400:
          description: >
            `employee_id` was not provided or it did not match an employee record
          body:
            type: Error
        404:
          description: The MFA record was not found
          body:
            type: Error
        500:
          description: Unable to delete the MFA record
          body:
            type: Error
    /verify:
      post:
        description: Verify the value provided for this MFA device.
        queryParameters:
          rpOrigin?:
            type: string
            description: The Relying Party origin url (only needed for WebAuthn)
            default: ""
            example: "https://sub.domain.com"
        body:
          properties:
            employee_id: string
            value: string
          example: |
            {
              "employee_id": "12345",
              "value": "01234987"
            }
        responses:
          200:
            description: Value provided passed verification
            body:
              type: MfaResponse
          400:
            description: >
              Value provided failed verification or was unacceptable for some
              other reason (such as an invalid `employee_id`).
            body:
              type: Error
          404:
            description: No MFA record found with that `id` and `employee_id`.
            body:
              type: Error
          429:
            description: >
              Too many failed attempts for this MFA record recently.
            body:
              type: Error
      /registration:
        post:
          description: Verify the registration of a new mfa webauthn credential.
          queryParameters:
            rpOrigin:
              type: string
              description: The Relying Party origin url (only needed for WebAuthn)
              default: ""
              example: "https://sub.domain.com"
          body:
            properties:
              employee_id: string
              value: string
              label: string
            example: |
              {
                "employee_id": "12345",
                "value": "01234987",
                "label": "Yubikey"
              }
          responses:
            200:
              description: Value provided passed verification
              body:
                type: MfaResponse
            400:
              description: >
                Value provided failed verification or was unacceptable for some
                other reason (such as an invalid `employee_id`).
              body:
                type: Error
            404:
              description: No MFA record found with that `id` and `employee_id`.
              body:
                type: Error
            429:
              description: >
                Too many failed attempts for this MFA record recently.
              body:
                type: Error
  /{mfaId}:
    /webauthn:
      /{webauthnId}:
        put:
          description: Update the label of a MFA webauthn credential.
          body:
            properties:
              employee_id: string
              label: string
            example: |
              {
                "employee_id": "12345",
                "label": "My First Security Key"
              }
          responses:
            200:
              description: Webauthn label successfully updated
              body:
                type: WebauthnResponse
            400:
              description: Missing or blank label value or invalid employee_id
              body:
                type: Error
            404:
              description: >
                No MFA record found with that `mfa_id` or no webauthn
                record found with that `id` and that `mfa_id`.
              body:
                type: Error
            500:
              description: Internal server error
              body:
                type: Error
        delete:
          description: >
            Delete a webauthn credential from an MFA. If it is the last credential,
            the whole MFA will be deleted.
          body:
            properties:
              employee_id: string
            example: |
              {
                "employee_id": "abc123"
              }
          responses:
            204:
              description: Successful deletion of record
            400:
              description: invalid employee_id
              body:
                type: Error
            403:
              description: The MFA record was not of type webauthn
              body:
                type: Error
            404:
              description: >
                No MFA record found with that `mfa_id` or no webauthn
                record found with that `id` and that `mfa_id`.
              body:
                type: Error
            500:
              description: Unable to delete the webauthn credential or the MFA record
              body:
                type: Error
/method:
  post:
    description: >
      Create a new recovery method and send verification email. At this point,
      all methods are email, so 'value' is always an email address.
    body:
      type: Method
    responses:
      200:
        description: Recovery method created and email sent.
        body:
          type: MethodResponse
      400:
        description: Missing parameter
        body:
          type: Error
      409:
        description: New method matches an already existing verified method
        body:
          type: Error
      422:
        description: A model validation error occurred.
        body:
          type: Error
      500:
        description: Database or other system error
        body:
          type: Error
  /{uid}:
    get:
      description: Retrieve a specific, verified recovery method.
      body:
        properties:
          employee_id: string
        example: |
          {
            "employee_id": "12345"
          }
      responses:
        200:
          description: Recovery method found
          body:
            type: MethodResponse
        404:
          description: User not found or method not found
          body:
            type: Error
    delete:
      description: Delete a specific recovery method.
      body:
        properties:
          employee_id: string
        example: |
          {
            "employee_id": "12345"
          }
      responses:
        204:
          description: Recovery method found and deleted
        404:
          description: User not found or method not found
          body:
            type: Error
        500:
          description: Delete failed
          body:
            type: Error
    /verify:
      put:
        description: Verify the recovery method by a matching code.
        body:
          properties:
            code: string
          example: |
            {
              "code": "987654"
            }
        responses:
          200:
            description: Provided code matches original code
            body:
              type: MethodResponse
          400:
            description: Missing or invalid code
          404:
            description: User not found or method not found
            body:
              type: Error
          410:
            description: Expired verification code
            body:
              type: Error
          429:
            description: Too many verification attempts
            body:
              type: Error
          500:
            description: Database or other system error
            body:
              type: Error
    /resend:
      put:
        description: Resend the method verification email
        body:
          properties:
            employee_id: string
          example: |
            {
              "employee_id": "12345"
            }
        responses:
          204:
            description: Method found and email sent
          400:
            description: Method already verified
            body:
              type: Error
          404:
            description: User not found or method not found
            body:
              type: Error