13.1.1. Authorization

Send the following POST request to get authorization cookie.

POST /api/component/auth/login

Authorization request to NextGIS Web

Request Headers
Request JSON Object
  • login (string) – login

  • password (string) – password

Response JSON Object
  • id (int) – user identifier

  • keyname (string) – user login

  • display_name (string) – user full name

Status Codes

Example request:

POST /api/component/auth/login
Host: ngw_url
Accept: */*

{
   "login": "test_user",
   "password":"secret"
}

Example response:

{
  "id": 10,
  "keyname": "test_user",
  "display_name": "Test user"
}

If authorization succeeds, NextGIS Web will return HTTP code 200 and Set-Cookie. Requests with this cookie into the header will be considered authorized.

Authorized data (HTTP AUTH) can be sent with each request.

Note

When the user agent wants to send the server authentication credentials it may use the Authorization header.

The Authorization header is constructed as follows:

  1. Username and password are combined into a string “username:password”

  2. The resulting string is then encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line

  3. The authorization method and a space i.e. “Basic ” is then put before the encoded string.

For example, if the user agent uses ‘Aladdin’ as the username and ‘open sesame’ as the password then the header is formed as follows:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

If you have configured an OAuth server, you can use OAuth user credentials in the same way as the local user or send Bearer token.

13.1.2. Managing users

To create new user execute following request:

POST /api/component/auth/user/

Request to create new user.

Request Headers
Request JSON Object
  • display_name (string) – user full name

  • keyname (string) – user login

  • description (string) – user description

  • password (string) – user password

Response JSON Object
  • id (int) – new user identifier

Status Codes

Example request:

POST /api/component/auth/user/ HTTP/1.1
Host: ngw_url
Accept: */*

{
   "display_name": "Test user",
   "keyname": "test_user",
   "password":"secret",
   "disabled": false,
   "member_of": [ 5 ]
}

Example response:

{
  "id": 10
}

Get information about existing user with id returned in previous request:

GET /api/component/auth/user/(int: id)

Example request:

GET /api/component/auth/user/10 HTTP/1.1
Host: ngw_url
Accept: */*

Example response:

{
  "id": 10,
  "system": false,
  "display_name": "Test user",
  "description": null,
  "keyname": "test_usera",
  "superuser": false,
  "disabled": false,
  "last_activity": null,
  "oauth_subject": null,
  "oauth_tstamp": null,
  "member_of": [ 5 ]
}

Update user details:

PUT /api/component/auth/user/10

{
  "display_name": "Dear test user",
  "disabled": true
}

Get information about all local users in WebGIS (some output was clipped):

GET /api/component/auth/user/

[
  // ...
  {
    "id": 4,
    "system": false,
    "display_name": "Administrator",
    "description": null,
    "keyname": "administrator",
    "superuser": false,
    "disabled": false,
    "last_activity": "2020-08-07T01:27:52.870601",
    "oauth_subject": null,
    "oauth_tstamp": null,
    "member_of": [ 5 ]
  },
  {
    "id": 6,
    "system": true,
    "display_name": "Owner",
    "description": null,
    "keyname": "owner",
    "superuser": false,
    "disabled": false,
    "last_activity": null,
    "oauth_subject": null,
    "oauth_tstamp": null,
    "member_of": []
  },
  // ...
  {
    "id": 10,
    "system": false,
    "display_name": "Dear test user",
    "description": null,
    "keyname": "test_usera",
    "superuser": false,
    "disabled": true,
    "last_activity": null,
    "oauth_subject": null,
    "oauth_tstamp": null,
    "member_of": [ 5 ]
  }
]

Delete previously created user:

DELETE /api/component/auth/user/10

To get current user details execute following request:

POST /api/component/auth/current_user

Request to get current user details

Request Headers
Response JSON Object
  • keyname (string) – user login

  • display_name (string) – user name

  • id (int) – user identifier

Status Codes

Example response:

{
    "keyname": "administrator",
    "display_name": "Admin",
    "id": 4
}

13.1.3. Managing groups

To create new group execute following request:

POST /api/component/auth/group

Request to create new group

POST /api/component/auth/group/

{
  "display_name": "Test group",
  "keyname": "test_group",
  "members": [ 10 ]
}

Get information about existing group:

GET /api/component/auth/group/20

{
  "id": 20,
  "system": false,
  "display_name": "Test group",
  "description": null,
  "keyname": "test_group",
  "register": false,
  "members": [ 10 ]
}

Update group details and remove all members from it:

PUT /api/component/auth/group/20

{
  "display_name": "Empty group",
  "members": []
}

Delete group:

DELETE /api/component/auth/group/20

13.1.4. Automatically creating users

To self creating user (anonymous user) execute following request:

POST /api/component/auth/register

Request to create new user

Request Headers
Request JSON Object
  • display_name (string) – user full name

  • keyname (string) – user login

  • description (string) – user description

  • password (string) – user password

Status Codes

Administrator can configure anonymous user registration to the specific group (via setting checkbox on group in administrative user interface).

This feature requires the special section in NGW config file:

[auth]
register = true

13.1.5. Get resource permissions

13.1.5.1. Simple output

To get resource permissions execute following request. Returned json may vary depends on resource type.

The following request returns resource permissions:

GET /api/resource/(int: id)/permission

Permissions request

Request Headers
Parameters
  • id – resource identifier

Status Codes

Example request:

GET /api/resource/56/permission HTTP/1.1
Host: ngw_url
Accept: */*

Example response:

{
    "resource": {
        "read": true,
        "create": true,
        "update": true,
        "delete": true,
        "manage_children": true,
        "change_permissions": true
    },
    "datastruct": {
        "read": true,
        "write": true
    },
    "data": {
        "read": true,
        "write": true
    },
    "metadata": {
        "read": true,
        "write": true
    }
}

13.1.5.2. Detailed output

To get explain how permissions were set execute following request. Returned json may vary depends on resource type.

The following request returns resource permissions explain:

GET /api/resource/(int: id)/permission/explain

Permissions explain request

Request Headers
Parameters
  • id – resource identifier

Status Codes

Example request:

GET /api/resource/56/permission/explain HTTP/1.1
Host: ngw_url
Accept: */*

Example response:

{
    "resource": {
        "read": {
            "result": true,
            "explain": [
                {
                    "result": true,
                    "resource": {
                        "id": 0
                    },
                    "type": "acl_rule",
                    "acl_rule": {
                        "action": "allow",
                        "principal": {
                            "id": 2,
                            "cls": "user",
                            "keyname": "everyone"
                        },
                        "scope": "resource",
                        "permission": "read",
                        "identity": "",
                        "propagate": true
                    }
                },
                {
                    "result": true,
                    "resource": {
                        "id": 3880
                    },
                    "type": "acl_rule",
                    "acl_rule": {
                        "action": "allow",
                        "principal": {
                            "id": 2,
                            "cls": "user",
                            "keyname": "everyone"
                        },
                        "scope": "resource",
                        "permission": "read",
                        "identity": "",
                        "propagate": true
                    }
                },
                {
                    "result": true,
                    "resource": {
                        "id": 4232
                    },
                    "type": "requirement",
                    "requirement": {
                        "scope": "resource",
                        "permission": "read",
                        "attr": "parent",
                        "attr_empty": true
                    },
                    "satisfied": true,
                    "explain": {
                        "resource": {
                            "read": {
                                "result": true,
                                "explain": [
                                    {
                                        "result": true,
                                        "resource": {
                                            "id": 0
                                        },
                                        "type": "acl_rule",
                                        "acl_rule": {
                                            "action": "allow",
                                            "principal": {
                                                "id": 2,
                                                "cls": "user",
                                                "keyname": "everyone"
                                            },
                                            "scope": "resource",
                                            "permission": "read",
                                            "identity": "",
                                            "propagate": true
                                        }
                                    },
                                    {
                                        "result": true,
                                        "resource": {
                                            "id": 3880
                                        },
                                        "type": "acl_rule",
                                        "acl_rule": {
                                            "action": "allow",
                                            "principal": {
                                                "id": 2,
                                                "cls": "user",
                                                "keyname": "everyone"
                                            },
                                            "scope": "resource",
                                            "permission": "read",
                                            "identity": "",
                                            "propagate": true
                                        }
                                    },
                                    {
                                        "result": true,
                                        "resource": {
                                            "id": 3880
                                        },
                                        "type": "requirement",
                                        "requirement": {
                                            "scope": "resource",
                                            "permission": "read",
                                            "attr": "parent",
                                            "attr_empty": true
                                        },
                                        "satisfied": true,
                                        "explain": {
                                            "resource": {
                                                "read": {
                                                    "result": true,
                                                    "explain": [
                                                        {
                                                            "result": true,
                                                            "resource": {
                                                                "id": 0
                                                            },
                                                            "type": "acl_rule",
                                                            "acl_rule": {
                                                                "action": "allow",
                                                                "principal": {
                                                                    "id": 2,
                                                                    "cls": "user",
                                                                    "keyname": "everyone"
                                                                },
                                                                "scope": "resource",
                                                                "permission": "read",
                                                                "identity": "",
                                                                "propagate": true
                                                            }
                                                        },
                                                        {
                                                            "result": true,
                                                            "resource": {
                                                                "id": 3880
                                                            },
                                                            "type": "acl_rule",
                                                            "acl_rule": {
                                                                "action": "allow",
                                                                "principal": {
                                                                    "id": 2,
                                                                    "cls": "user",
                                                                    "keyname": "everyone"
                                                                },
                                                                "scope": "resource",
                                                                "permission": "read",
                                                                "identity": "",
                                                                "propagate": true
                                                            }
                                                        },
                                                        {
                                                            "result": true,
                                                            "resource": {
                                                                "id": 0
                                                            },
                                                            "type": "requirement",
                                                            "requirement": {
                                                                "scope": "resource",
                                                                "permission": "read",
                                                                "attr": "parent",
                                                                "attr_empty": true
                                                            },
                                                            "satisfied": true,
                                                            "explain": {
                                                                "resource": {
                                                                    "read": {
                                                                        "result": true,
                                                                        "explain": [
                                                                            {
                                                                                "result": true,
                                                                                "resource": {
                                                                                    "id": 0
                                                                                },
                                                                                "type": "acl_rule",
                                                                                "acl_rule": {
                                                                                    "action": "allow",
                                                                                    "principal": {
                                                                                        "id": 2,
                                                                                        "cls": "user",
                                                                                        "keyname": "everyone"
                                                                                    },
                                                                                    "scope": "resource",
                                                                                    "permission": "read",
                                                                                    "identity": "",
                                                                                    "propagate": true
                                                                                }
                                                                            },
                                                                            {
                                                                                "result": true,
                                                                                "resource": null,
                                                                                "type": "requirement",
                                                                                "requirement": {
                                                                                    "scope": "resource",
                                                                                    "permission": "read",
                                                                                    "attr": "parent",
                                                                                    "attr_empty": true
                                                                                },
                                                                                "satisfied": false,
                                                                                "explain": null
                                                                            }
                                                                        ]
                                                                    }
                                                                }
                                                            }
                                                        }
                                                    ]
                                                }
                                            }
                                        }
                                    }
                                ]
                            }
                        }
                    }
                }
            ]
        },
        "create": {
            "result": false,
            "explain": [
                {
                    "result": false,
                    "resource": {
                        "id": 4234
                    },
                    "type": "default"
                }
            ]
        },
        "update": {
            "result": false,
            "explain": [
                {
                    "result": false,
                    "resource": {
                        "id": 4234
                    },
                    "type": "default"
                }
            ]
        },
        "delete": {
            "result": false,
            "explain": [
                {
                    "result": false,
                    "resource": {
                        "id": 4234
                    },
                    "type": "default"
                }
            ]
        },
        "manage_children": {
            "result": false,
            "explain": [
                {
                    "result": false,
                    "resource": {
                        "id": 4234
                    },
                    "type": "default"
                }
            ]
        },
        "change_permissions": {
            "result": false,
            "explain": [
                {
                    "result": false,
                    "resource": {
                        "id": 4234
                    },
                    "type": "default"
                }
            ]
        }
    },
    "datastruct": {
        "read": {
            "result": true,
            "explain": [
                {
                    "result": true,
                    "resource": {
                        "id": 0
                    },
                    "type": "acl_rule",
                    "acl_rule": {
                        "action": "allow",
                        "principal": {
                            "id": 2,
                            "cls": "user",
                            "keyname": "everyone"
                        },
                        "scope": "datastruct",
                        "permission": "read",
                        "identity": "",
                        "propagate": true
                    }
                }
            ]
        },
        "write": {
            "result": false,
            "explain": [
                {
                    "result": false,
                    "resource": {
                        "id": 4234
                    },
                    "type": "default"
                }
            ]
        }
    },
    "data": {
        "read": {
            "result": true,
            "explain": [
                {
                    "result": true,
                    "resource": {
                        "id": 0
                    },
                    "type": "acl_rule",
                    "acl_rule": {
                        "action": "allow",
                        "principal": {
                            "id": 2,
                            "cls": "user",
                            "keyname": "everyone"
                        },
                        "scope": "data",
                        "permission": "read",
                        "identity": "",
                        "propagate": true
                    }
                },
                {
                    "result": true,
                    "resource": {
                        "id": 4233
                    },
                    "type": "requirement",
                    "requirement": {
                        "scope": "connection",
                        "permission": "connect",
                        "attr": "connection",
                        "attr_empty": false
                    },
                    "satisfied": true,
                    "explain": {
                        "connection": {
                            "connect": {
                                "result": true,
                                "explain": [
                                    {
                                        "result": true,
                                        "resource": {
                                            "id": 0
                                        },
                                        "type": "acl_rule",
                                        "acl_rule": {
                                            "action": "allow",
                                            "principal": {
                                                "id": 2,
                                                "cls": "user",
                                                "keyname": "everyone"
                                            },
                                            "scope": "connection",
                                            "permission": "connect",
                                            "identity": "",
                                            "propagate": true
                                        }
                                    }
                                ]
                            }
                        }
                    }
                }
            ]
        },
        "write": {
            "result": false,
            "explain": [
                {
                    "result": false,
                    "resource": {
                        "id": 4234
                    },
                    "type": "default"
                }
            ]
        }
    },
    "metadata": {
        "read": {
            "result": true,
            "explain": [
                {
                    "result": true,
                    "resource": {
                        "id": 0
                    },
                    "type": "acl_rule",
                    "acl_rule": {
                        "action": "allow",
                        "principal": {
                            "id": 2,
                            "cls": "user",
                            "keyname": "everyone"
                        },
                        "scope": "metadata",
                        "permission": "read",
                        "identity": "",
                        "propagate": true
                    }
                }
            ]
        },
        "write": {
            "result": false,
            "explain": [
                {
                    "result": false,
                    "resource": {
                        "id": 4234
                    },
                    "type": "default"
                }
            ]
        }
    }
}