Administrator

The administrator API provides knowledge factor authentication to identify admin request by access token (aka API token in other literatures) associated with a registered administrator maintained in NotifyBC database. Because knowledge factor authentication is vulnerable to brute-force attack, administrator API based access token authentication is less favorable than admin ip list, client certificate, or OIDC authentication.

Avoid Administrator API

Administrator API was created to circumvent an OpenShift limitation - the source ip of a request initiated from an OpenShift pod cannot be exclusively allocated to the pod's project, rather it has to be shared by all OpenShift projects. Therefore it's difficult to impose granular access control based on source ip.

With the introduction client certificate in v2.4.0, most use cases, if not all, that need Administrator API including the OpenShift use case mentioned above can be addressed by client certificate. Therefore only use Administrator API sparingly as last resort.

To enable access token authentication,

  1. a super-admin signs up an administrator

    For example,

    curl -X POST "http://localhost:3000/api/administrators" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{\"username\":\"Foo\",\"email\":\"user@example.com\",\"password\":\"secret\"}"

    The step can also be completed in web console using add button in Administrators panel.

  2. Either super-admin or the user login to generate an access token

    For example,

    curl -X POST "http://localhost:3000/api/administrators/login" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{\"email\":\"user@example.com\",\"password\":\"secret\",\"tokenName\":\"myApp\"}"

    The step can also be completed in web console GUI by an anonymous user using login button at top right corner. Access token generated by GUI is valid for 12hrs.

  3. Apply access token to either Authorization header or access_token query parameter to make authenticated requests. For example, to get a list of notifications

    ACCESS_TOKEN=6Nb2ti5QEXIoDBS5FQGWIz4poRFiBCMMYJbYXSGHWuulOuy0GTEuGx2VCEVvbpBK

# Authorization Header
curl -X GET -H "Authorization: $ACCESS_TOKEN" \
http://localhost:3000/api/notifications

# Query Parameter
curl -X GET http://localhost:3000/api/notifications?access_token=$ACCESS_TOKEN

    In web console, once login as administrator, the access token is automatically applied.

Model Schemas

The Administrator API operates on three related sub-models - Administrator, UserCredential and AccessToken. An administrator has one and only one user credential and zero or more access tokens. Their relationship is diagramed as

administrator model diagram

Administrator

NameAttributes

id

typestring, format depends on db
auto-generatedtrue

email

typestring
requiredtrue
uniquetrue

username

user name

typestring
requiredfalse

UserCredential

NameAttributes

id

typestring, format depends on db
auto-generatedtrue

password

hashed password

typestring
requiredtrue

userId

foreign key to Administrator model

typestring
requiredtrue

AccessToken

NameAttributes

id

64-byte random alphanumeric characters

typestring
auto-generatedtrue

userId

foreign key to Administrator model

typestring
requiredtrue

ttl

Time-to-live in seconds. If absent, access token never expires.

typenumber
requiredfalse

name

Name of the access token. Can be used to identify applications that use the token.

typestring
requiredfalse

Sign Up

POST /administrators

This API allows a super-admin to create an admin.

  • permissions required, one of

    • super admin

  • inputs

    • user information

      {
  "email": "string",
  "password": "string",
  "username": "string"
}

      Password must meet following complexity rules:

      • contains at least 10 characters
      • contains at least one lower case character a-z
      • contains at least one upper case character A-Z
      • contains at least one numeric character 0-9
      • contains at lease one special character in !_@#$&*

      email must be unique. username is optional.

      • required: true
      • parameter type: request body
      • data type: object

  • outcome

    • for super-admin requests,
      • an Administrator is generated, populated with email and username
      • a UserCredential is generated, populated with hashed password
      • Administrator is returned
    • forbidden otherwise

Login

POST /administrators/login

This API allows an admin to login and create an access token

  • inputs

    • user information

      {
  "email": "user@example.com",
  "password": "string",
  "tokenName": "string",
  "ttl": 0
}

      tokenName and ttl are optional. If ttl is absent, access token never expires.

      • required: true
      • parameter type: request body
      • data type: object

  • outcome

    • if login is successful
      • a new AccessToken is generated with tokenName is saved to AccessToken.name and ttl is saved to AccessToken.ttl.
      • the new access token is returned
        {
  "token": "string"
}
    • forbidden otherwise

Set Password

POST /administrators/{id}/user-credential

This API allows a super-admin or admin to create or update password by id. An admin can only create/update own record.

  • permissions required, one of

    • super admin
    • admin

  • inputs

    • Administrator id

      • required: true
      • parameter type: path
      • data type: string

    • password

      {
  "password": "string"
}

      The password must meet complexity rules specified in Sign Up.

      • required: true
      • parameter type: request body
      • data type: object
  • outcome
    • for super-admins or admin,
      1. hash the input password
      2. remove any existing UserCredential.password for the Administrator
      3. create a new UserCredential.password
    • forbidden otherwise

Get Administrators

GET /administrators

This API allows a super-admin or admin to search for administrators. An admin can only search for own record

  • permissions required, one of

    • super admin
    • admin

  • inputs

    • a filter containing properties where, fields, order, skip, and limit

      • parameter name: filter
      • required: false
      • parameter type: query
      • data type: object

      The filter can be expressed as either

      1. URL-encoded stringified JSON object (see example below); or
      2. in the format supported by qs, for example ?filter[where][created][$gte]="2023-01-01"&filter[where][created][$lt]="2024-01-01"

      Regardless, the filter will have to be parsed into a JSON object conforming to

      {
    "where": {...},
    "fields": ...,
    "order": ...,
    "skip": ...,
    "limit": ...,
}

      All properties are optional. The syntax for each property is documented, respectively

  • outcome

    • for super-admins, returns an array of Administrators matching the filter
    • for admins, returns an array of one element - own record if the record matches the filter; empty array otherwise
    • forbidden otherwise

  • example

    to retrieve administrators created in year 2023, run

    curl -X GET --header 'Accept: application/json' 'http://localhost:3000/api/administrators?filter=%7B%22where%22%3A%7B%22created%22%3A%7B%22%24gte%22%3A%222023-01-01%22%2C%22%24lt%22%3A%222024-01-01%22%7D%7D%7D'

    the value of the filter query parameter is URL-encoded stringified JSON object

    {
  "where": {
    "created": {
      "$gte": "2023-01-01",
      "$lt": "2024-01-01"
    }
  }
}

Get Administrator Count

GET /administrators/count

This API allows a super-admin or admin to count administrators by filter. An admin can only count own record therefore the number is at most 1.

  • permissions required, one of

    • super admin
    • admin

  • inputs

    • a where query parameter with value conforming to MongoDB Query Documents

      • parameter name: where
      • required: false
      • parameter type: query
      • data type: object

      The value can be expressed as either

      1. URL-encoded stringified JSON object (see example below); or
      2. in the format supported by qs, for example ?where[created][$gte]="2023-01-01"&where[created][$lt]="2024-01-01"

  • outcome

    • for super-admins or admin, a count matching the filter
    • forbidden otherwise

  • example

    to retrieve the count of administrators created in year 2023 , run

    curl -X GET --header 'Accept: application/json' 'http://localhost:3000/api/administrators/count?where=%7B%22created%22%3A%7B%22%24gte%22%3A%222023-01-01%22%2C%22%24lt%22%3A%222024-01-01%22%7D%7D'

    the value of the where query parameter is URL-encoded stringified JSON object

    {
  "created": {
    "$gte": "2023-01-01",
    "$lt": "2024-01-01"
  }
}

Delete an Administrator

DELETE /administrators/{id}

This API allows a super-admin or admin to delete administrator by id. An admin can only delete own record.

  • permissions required, one of

    • super admin
    • admin

  • inputs

    • Administrator id
      • required: true
      • parameter type: path
      • data type: string

  • outcome

    • for super-admins or admin
      • all AccessToken of the Administrator are deleted
      • the corresponding UserCredential is deleted
      • the Administrator is deleted
    • forbidden otherwise

Get an Administrator

GET /administrators/{id}

This API allows a super-admin or admin to get administrator by id. An admin can only get own record.

  • permissions required, one of

    • super admin
    • admin

  • inputs

    • Administrator id
      • required: true
      • parameter type: path
      • data type: string

  • outcome

    • for super-admins or admin, returns the Administrator
    • forbidden otherwise

Update an Administrator

PATCH /administrators/{id}

This API allows a super-admin or admin to update administrator fields by id. An admin can only update own record.

  • permissions required, one of

    • super admin
    • admin

  • inputs

    • Administrator id

      • required: true
      • parameter type: path
      • data type: string

    • user information

      {
  "username": "string",
  "email": "string"
}
      • required: true
      • parameter type: request body
      • data type: object
  • outcome
    • for super-admins or admin, updates the Administrator
    • forbidden otherwise

Replace an Administrator

PUT /administrators/{id}

This API allows a super-admin or admin to replace administrator records by id. An admin can only replace own record. This API is different from Update an Administrator in that update/patch needs only to contain fields that are changed, ie the delta, whereas replace/put needs to contain all fields to be saved.

  • permissions required, one of

    • super admin
    • admin

  • inputs

    • Administrator id

      • required: true
      • parameter type: path
      • data type: string

    • user information

      {
  "username": "string",
  "email": "string"
}
      • required: true
      • parameter type: request body
      • data type: object
  • outcome
    • for super-admins or admin, updates the Administrator. If password is also supplied, the password is handled same way as Set Password API
    • forbidden otherwise

Get an Administrator's AccessTokens

GET /administrators/{id}/access-tokens

This API allows a super-admin or admin to get access tokens by Administrator id. An admin can only get own records.

  • permissions required, one of

    • super admin
    • admin

  • inputs

    • Administrator id

      • required: true
      • parameter type: path
      • data type: string

    • a filter containing properties where, fields, order, skip, and limit

      • parameter name: filter
      • required: false
      • parameter type: query
      • data type: object

      The filter can be expressed as either

      1. URL-encoded stringified JSON object (see example below); or
      2. in the format supported by qs, for example ?filter[where][created][$gte]="2023-01-01"&filter[where][created][$lt]="2024-01-01"

      Regardless, the filter will have to be parsed into a JSON object conforming to

      {
    "where": {...},
    "fields": ...,
    "order": ...,
    "skip": ...,
    "limit": ...,
}

      All properties are optional. The syntax for each property is documented, respectively

  • outcome

    • for super-admins or admin, a list of AccessTokens matching the filter
    • forbidden otherwise

  • example

    to retrieve access tokens created in year 2023 for administrator with id of 1, run

    curl -X GET --header 'Accept: application/json' 'http://localhost:3000/api/administrators/1/access-tokens?filter=%7B%22where%22%3A%7B%22created%22%3A%7B%22%24gte%22%3A%222023-01-01%22%2C%22%24lt%22%3A%222024-01-01%22%7D%7D%7D'

    the value of the filter query parameter is URL-encoded stringified JSON object

    {
  "where": {
    "created": {
      "$gte": "2023-01-01",
      "$lt": "2024-01-01"
    }
  }
}

Update an Administrator's AccessTokens

PATCH /administrators/{id}/access-tokens

This API allows a super-admin or admin to update access tokens by Administrator id. An admin can only update own records.

  • permissions required, one of

    • super admin
    • admin

  • inputs

    • Administrator id

      • required: true
      • parameter type: path
      • data type: string

    • a where query parameter with value conforming to MongoDB Query Documents

      • parameter name: where
      • required: false
      • parameter type: query
      • data type: object

      The value can be expressed as either

      1. URL-encoded stringified JSON object (see example below); or
      2. in the format supported by qs, for example ?where[created][$gte]="2023-01-01"&where[created][$lt]="2024-01-01"

    • AccessToken information

      {
  "ttl": 0,
  "name": "string"
}
      • required: true
      • parameter type: request body
      • data type: object

  • outcome

    • for super-admins or admin, success count
    • forbidden otherwise

  • example

    to set ttl token to 0 for all access tokens created in year 2023 for administrator with id 1, run

    curl -X PATCH --header 'Content-Type: application/json' 'http://localhost:3000/api/administrators/1/access-tokens?where=%7B%22created%22%3A%7B%22%24gte%22%3A%222023-01-01%22%2C%22%24lt%22%3A%222024-01-01%22%7D%7D' -d '{"ttl":0}'

    the value of the where query parameter is URL-encoded stringified JSON object

    {
  "created": {
    "$gte": "2023-01-01",
    "$lt": "2024-01-01"
  }
}

Create an Administrator's AccessToken

POST /administrators/{id}/access-tokens

This API allows a super-admin or admin to create an access token by Administrator id. An admin can only create own records.

  • permissions required, one of

    • super admin
    • admin

  • inputs

    • Administrator id

      • required: true
      • parameter type: path
      • data type: string

    • AccessToken information

      {
  "ttl": 0,
  "name": "string"
}
      • required: true
      • parameter type: request body
      • data type: object
  • outcome
    • for super-admins or admin
      • Create and save AccessToken
      • return AccessToken created
    • forbidden otherwise

Delete an Administrator's AccessTokens

DELETE /administrators/{id}/access-tokens

This API allows a super-admin or admin to delete access tokens by Administrator id. An admin can only delete own records.

  • permissions required, one of

    • super admin
    • admin

  • inputs

    • Administrator id

      • required: true
      • parameter type: path
      • data type: string

    • a where query parameter with value conforming to MongoDB Query Documents

      • parameter name: where
      • required: false
      • parameter type: query
      • data type: object

      The value can be expressed as either

      1. URL-encoded stringified JSON object (see example below); or
      2. in the format supported by qs, for example ?where[created][$gte]="2023-01-01"&where[created][$lt]="2024-01-01"

  • outcome

    • for super-admins or admin
      • delete all AccessToken under the Administrator matching the filter
      • return success count
    • forbidden otherwise

  • example

    to delete all access tokens created in year 2023 for administrator with id 1, run

    curl -X DELETE --header 'Accept: application/json' 'http://localhost:3000/api/administrators/1/access-tokens?where=%7B%22created%22%3A%7B%22%24gte%22%3A%222023-01-01%22%2C%22%24lt%22%3A%222024-01-01%22%7D%7D'

    the value of the where query parameter is URL-encoded stringified JSON object

    {
  "created": {
    "$gte": "2023-01-01",
    "$lt": "2024-01-01"
  }
}