This REST API allows to manage users allowed to use Mission Portal as also Role Based Access Control settings.

List users

URI: https://hub.cfengine.com/api/user

Method: GET

List all users. API call allowed only for administrator.

Parameters:

  • id (regex string) Regular expression for filtering usernames.
  • external ('true', 'false') Returns only internal users (false) or only external (true), or all if not specified.

Example response:

code
{
  "meta": {
    "page": 1,
    "count": 3,
    "total": 3,
    "timestamp": 1437383957
  },
  "data": [
    {
      "id": "CFE_ROBOT",
      "email": "admin@organisation.com",
      "roles": [
        "admin",
        "cf_remoteagent"
      ],
      "external": false,
      "two_factor_enabled": true
    },
    {
      "id": "admin",
      "name": "admin",
      "email": "admin@organisation.com",
      "roles": [
        "admin",
        "cf_remoteagent"
      ],
      "external": false,
      "two_factor_enabled": false
    },
    {
      "id": "user_1",
      "email": "user_1@example.com",
      "roles": [
        "linux_team"
      ],
      "external": false
    }
  ]
}

Output:

  • id User name.
  • email Email address.
  • roles List of assigned RBAC roles.
  • external Is user from external source (LDAP/AD).
  • two_factor_enabled If a user has enabled two-factor authentication

Example usage: Example: Listing users

Get user data

URI: https://hub.cfengine.com/api/user/:username

Method: GET

Get info for a specified user. API call allowed only for administrator.

Example response:

code
{
  "meta": {
    "page": 1,
    "count": 1,
    "total": 1,
    "timestamp": 1437385581
  },
  "data": [
    {
      "id": "user_1",
      "name": "",
      "email": "user_1@example.com",
      "roles": [
        "linux_team"
      ],
      "external": false,
      "time_zone": "Europe/Oslo",
      "two_factor_enabled": false
    }
  ]
}

Output:

  • id User name.
  • email Email address.
  • roles List of assigned RBAC roles.
  • external Is user from external source (LDAP/AD).
  • time_zone Time zone
  • two_factor_enabled If a user has enabled two-factor authentication

Example usage: Example: Retrieving a user

Create new user

URI: https://hub.cfengine.com/api/user/:username

Method: PUT

Parameters:

  • username (string) User name
  • password (string) User password
  • email (string) User email
  • roles (array) User roles, emp: ["admin", "test"]
  • time_zone (string) Time zone

Create a new user. API call allowed only for administrator.

Example Request Body:

code
{
  "email": "user_1@example.com",
  "roles": [
    "linux_team"
  ]
}

Example usage: Example: Creating a new user

Update user

URI: https://hub.cfengine.com/api/user/:username

Method: POST

Update user information. API call allowed only for administrator.

Parameters:

  • username (string) User name
  • password (string) User password
  • email (string) User email
  • roles (array) User roles, emp: ["admin", "test"]
  • time_zone (string) Time zone

Example Request Body:

code
{
  "email": "user_1@example.com",
  "roles": [
    "linux_team"
  ]
}

Example usage: Example: Updating an existing user, Example: Adding a user to a role

Delete user

URI: https://hub.cfengine.com/api/user/:username

Method: DELETE

Remove internal user. API call allowed only for administrator.

Example usage: Example: Deleting a user

List RBAC roles

URI: https://hub.cfengine.com/api/role

Method: GET

List defined roles for Role Based Access Control. API call allowed only for administrator.

Example response:

code
{
  "meta": {
    "page": 1,
    "count": 3,
    "total": 3,
    "timestamp": 1437391879
  },
  "data": [
    {
      "id": "admin",
      "description": "Admin role"
    },
    {
      "id": "cf_remoteagent",
      "description": "Allow execution of cf-runagent"
    },
    {
      "id": "linux_team",
      "description": "Linux team is responsible for all linux test servers.",
      "includeContext": "linux,test_env",
      "excludeContext": "dev_env|production_env"
    }
  ]
}

Output:

  • id Unique role name.
  • description Role description.
  • includeContext Permit access to hosts that have class set.
  • excludeContext Permit access to hosts that have class not set.

Get RBAC role

URI: https://hub.cfengine.com/api/role/:role_id

Method: GET

Get role definition. API call allowed only for administrator.

Example response:

code
{
  "meta": {
    "page": 1,
    "count": 1,
    "total": 1,
    "timestamp": 1437392992
  },
  "data": [
    {
      "id": "linux_team",
      "description": "Linux team is responsible for all linux servers.",
      "includeContext": "linux"
    }
  ]
}

Output:

  • id Unique role name.
  • description Role description.
  • includeContext Permit access to hosts that have class set.
  • excludeContext Permit access to hosts that have class not set.

Create RBAC role

URI: https://hub.cfengine.com/api/role/:role_id

Method: PUT

Create a new role definition. API call allowed only for administrator.

Fields:

  • description Role description.
  • includeContext Permit access to hosts that have class set.
  • excludeContext Permit access to hosts that have class not set.

Example Request Body:

code
{
  "description": "Linux team is responsible for all linux servers.",
  "includeContext": "linux",
  "excludeContext": "product_a"
}

Update RBAC role

URI: https://hub.cfengine.com/api/role/:role_id

Method: POST

Update role definition. API call allowed only for administrator.

Fields:

  • description Role description.
  • includeContext Permit access to hosts that have class set.
  • excludeContext Permit access to hosts that have class not set

Example Request Body:

code
{
  "description": "Linux team is responsible for all linux servers.",
  "includeContext": "linux",
  "excludeContext": "product_a"
}

Delete RBAC role

URI: https://hub.cfengine.com/api/role/:role_id

Method: DELETE

Remove role definition. API call allowed only for administrator.

Unlock user

If a system enforces using two-factor authentication (2FA), users must configure it after their first login within 48 hours. This endpoint unlocks users who have been locked out due to this reason and grants an additional 48 hours to complete the 2FA setup.

Note: to be able to perform this action related RBAC rule (alias user.unlock) should be enabled.

URI: https://hub.cfengine.com/api/user/:username/unlock

Method: POST

Example request (curl):

code
curl --user <username>:<password> \
  -X POST \
  https://hub.cfengine.com/api/user/tom/unlock

Example response:

code
HTTP 202 ACCEPTED