Chapter 3. Auth Policies API

Auth polices allow you to define different methods for authenticating and authorizing your application users. Different Auth Policies require different authentication configuration options to be defined. The structure of the various authentication configuration options are defined in the Authentication Configuration Options.

3.1. Create Auth Policy

3.1.1. Description

Create a new Auth policy.

3.1.2. Endpoint

  • uri - /box/srv/1.1/admin/authpolicy/create
  • method - POST

3.1.3. Request Body

{
  // required - a unique id for the policy. Used by $fh.auth() to
  // specify which Auth policy to use for authenticating/authorizing users
  "policyId": "<for example, oauth-google>",
  // required - the type of Autheitcation policy
  "policyType": "<oauth1 | oauth2 | ldap | openid>",
  // required, the configuration parameters for the policy
  // See Configuration Options section for full details
  "configurations": {<Config JSON Object>},
  // optional, default false
  // Flag to indicate if a check should be performed to
  // validate that the user id of the user being autheticated exists
  // in the platform. This should be set to
  // true for private apps & false for public apps.
  "checkUserExists": true | false,
  // Flag to indicate if our User needs to be approved for Auth
  "checkUserApproved": true | false
}

3.1.4. Response Body

3.1.4.1. Success

{
  "status": "ok",
  "guid": "<new_auth_policy_global_unique_id>"
}

3.1.4.2. Error

{
  "status": "error",
  "message": "<error_message>"
}

3.2. Read Auth Policy

3.2.1. Description

Read details of an existing Auth policy.

3.2.2. Endpoint

  • uri - /box/srv/1.1/admin/authpolicy/read
  • method - POST

3.2.3. Request Body

{
  // required - the unique id the policy to read
  "policyId": "<for example, oauth-google>"
}

3.2.4. Response Body

3.2.4.1. Success

{
  "status": "ok",
  "guid": "<auth_policy_global_unique_id>",
  "policyId" : "<user_defined_policy_identifier>"
  "policyType": "<oauth1 | oauth2 | ldap | openid>",
  "configurations": {<Config JSON Object>},
  "checkUserExists": true | false,
  "checkUserApproved": true | false,
  "users" : [<user-id>]
}

3.2.4.2. Error

{
  "status": "error",
  "message": "<error_message>"
}

3.3. Update Auth Policy

3.3.1. Description

Update an existing Auth policy.

3.3.2. Endpoint

  • uri - /box/srv/1.1/admin/authpolicy/update
  • method - POST

3.3.3. Request Body

{
  // required - the global unique identifier for the policy to update
  "guid" : "<global_unique_identifier>",
  // required - a unique id for the policy. Used by $fh.auth() to
  // specify which authentication policy to use for authenticating/authorizing users
  "policyId": "<for example, oauth-google>",
  // required - the type of Auth policy
  "policyType": "<oauth1 | oauth2 | ldap | openid>",
  // required, the configuration parameters for the policy
  // See See Configuration Options section for full details
  "configurations": {<Config JSON Object>},
  // optional, default false
  // Flag to indicate if a check should be performed to
  // validate that the user id of the user being authenticated exists
  // in the platform. This should be set to
  // true for private apps & false for public apps.
  "checkUserExists": true | false,
  // Flag to indicate if our User needs to be approved for Auth
  "checkUserApproved": true | false
}

3.3.4. Response Body

3.3.4.1. Success

{
  "status": "ok",
  "guid": "<auth_policy_global_unique_id>"
}

3.3.4.2. Error

{
  "status": "error",
  "message": "<error_message>"
}

3.4. Delete Auth Policy

3.4.1. Description

Delete an existing Auth policy.

3.4.2. Endpoint

  • uri - /box/srv/1.1/admin/authpolicy/delete
  • method - POST

3.4.3. Request Body

{
  // required - the global unique identifier for the policy to delete
  "guid" : "<global_unique_identifier>"
}

3.4.4. Response Body

3.4.4.1. Success

{
  "status": "ok"
}

3.4.4.2. Error

{
  "status": "error",
  "message": "<error_message>"
}

3.5. List Auth Policies

3.5.1. Description

List all existing Auth policies.

3.5.2. Endpoint

  • uri - /box/srv/1.1/admin/authpolicy/list
  • method - POST | GET

3.5.3. Request Body

N/A

3.5.4. Response Body

3.5.4.1. Success

{
  "status": "ok",
  "list" : [
    {
      "guid": "<auth_policy_global_unique_id#1>",
      "policyId" : "<user_defined_policy_identifier#1>"
      "policyType": "<oauth1 | oauth2 | ldap | openid>",
      "configurations": {<Config JSON Object>},
      "checkUserExists": true | false,
      "checkUserApproved": true | false
    },
    {
      "guid": "<auth_policy_global_unique_id#2>",
      "policyId" : "<user_defined_policy_identifier#2>"
      "policyType": "<oauth1 | oauth2 | ldap | openid>",
      "configurations": {<Config JSON Object>},
      "checkUserExists": true | false,
      "checkUserApproved": true | false
    },
    ...
    {
      "guid": "<auth_policy_global_unique_id#N>",
      "policyId" : "<user_defined_policy_identifier#N>"
      "policyType": "<oauth1 | oauth2 | ldap | openid>",
      "configurations": {<Config JSON Object>},
      "checkUserExists": true | false,
      "checkUserApproved": true | false
    }
  ],
  "count" : "<number_of_policies>"
}

3.5.4.2. Error

{
  "status": "error",
  "message": "<error_message>"
}

3.6. List Policy Users

3.6.1. Description

List all Users associated with an Auth Policy.

3.6.2. Endpoint

  • uri - /box/srv/1.1/admin/authpolicy/users
  • method - POST

3.6.3. Request Body

{
  "guid": "<policy_guid>",
}

3.6.4. Response Body

3.6.4.1. Success

{
  "status": "ok",
  "list" : [
    {
      "userid": "<user_id>",
      "name" : "<user_name>"
      "email": "<user_email>",
    }
  ],
  "count" : "<number_of_users_for_this_policy>"
}

3.6.4.2. Error

{
  "status": "error",
  "message": "<error_message>"
}

3.7. Add Users to a Policy

3.7.1. Description

Associate Users with an Auth Policy.

3.7.2. Endpoint

  • uri - /box/srv/1.1/admin/authpolicy/addusers
  • method - POST

3.7.3. Request Body

{
  "guid": "<policy_guid>",
  "users": ["<user_id>"]
}

3.7.4. Response Body

3.7.4.1. Success

{
  "status": "ok"
}

3.7.4.2. Error

{
  "status": "error",
  "message": "<error_message>"
}

3.8. Remove Users from a Policy

3.8.1. Description

Remove Users association with an Auth Policy.

3.8.2. Endpoint

  • uri - /box/srv/1.1/admin/authpolicy/removeusers
  • method - POST

3.8.3. Request Body

{
  "guid": "<policy_guid>",
  "users": ["<user_id>"]
}

3.8.4. Response Body

3.8.4.1. Success

{
  "status": "ok"
}

3.8.4.2. Error

{
  "status": "error",
  "message": "<error_message>"
}

3.9. Authentication Configuration Options

3.9.1. OAuth 2.0

  • clientId - The public key used to identify the client which is requesting the authentication. This key will be passed to, and used by, the client.
  • clientSecret - The secret key assigned by your OAuth provider. This key should never be set to, or stored on the client. It is used for server-to-server communication between the platform and the OAuth Provider.

3.9.1.1. Example:

{
  "clientId": "1234567890.apps.example.com",
  "clientSecret": "Wfv8DQw80hhyaBqnW37x5R23"
}

3.9.2. LDAP

  • authmethod - The authentication method to uses when authenticating against the LDAP server. This can be one of: 'simple', 'DIGEST-MD5', 'CRAM-MD5', or 'GSSAPI'.
  • url - The LDAP Server url for example, "ldap://foo.example.com:389/".
  • dn - The "Distinguished Name" to use. A DN is a sequence of relative distinguished names (RDN) connected by commas - for example, "ou=people,dc=example,dc=com".
  • dn_prefix - The prefix to use for authentication for example, "uid" or "cn".

3.9.2.1. Example:

{
  "authmethod" : "simple",
  "url" : "ldap://foo.example.com:389/",
  "dn": "ou=people,dc=example,dc=com",
  "dn_prefix": "cn",
}