From 568f4b142d63fa5fdc374ef6ef8f810447c8af94 Mon Sep 17 00:00:00 2001 From: Nick Muerdter Date: Tue, 15 Nov 2016 22:29:27 -0700 Subject: [PATCH] Add initial documentation on roles system. --- docs/admin/api-backends/index.rst | 1 + docs/admin/api-backends/role-restrictions.md | 35 ++++++++++++++++++++ docs/admin/api-users/index.rst | 2 ++ docs/admin/api-users/roles.md | 5 +++ 4 files changed, 43 insertions(+) create mode 100644 docs/admin/api-backends/role-restrictions.md create mode 100644 docs/admin/api-users/roles.md diff --git a/docs/admin/api-backends/index.rst b/docs/admin/api-backends/index.rst index 7f57f0cc8..d0a85f81b 100644 --- a/docs/admin/api-backends/index.rst +++ b/docs/admin/api-backends/index.rst @@ -6,3 +6,4 @@ API Backends caching http-headers + role-restrictions diff --git a/docs/admin/api-backends/role-restrictions.md b/docs/admin/api-backends/role-restrictions.md new file mode 100644 index 000000000..dfb258169 --- /dev/null +++ b/docs/admin/api-backends/role-restrictions.md @@ -0,0 +1,35 @@ +# Role Restrictions + +API Umbrella's "roles" feature can be used to restrict access to APIs so that only certain API keys may access certain APIs. + +## Adding Roles to API Keys + +To grant specific API keys a role: + +1. In the Admin, under Users > API Users, find the API key you want to add roles to. +2. Under Permissions > Roles, enter roles to assign to this API key. + - You can name roles however you'd like. + - Existing roles will auto-complete, but new roles can be created by entering a new name. + +## Enforcing Role Requirements With API Umbrella + +If you'd like for API Umbrella to enforce role restrictions, then role requirements can be defined within the API Backend configuration: + +1. In the Admin, under Configuration > API Backends, choose your API Backend to edit. +2. Under Global Request Settings > Required Roles, enter roles to require. + - You can name roles however you'd like. + - Existing roles will auto-complete, but new roles can be created by entering a new name. + - If multiple roles are set, then the API key must have all of the roles. +3. Save changes to the API Backend and publish the configuration changes. + +Once configured, then only API keys with the required roles will be able to access your API backend. If an API key lacks all of the required roles then API Umbrella will reject the request with a 403 Forbidden error and your API will never receive the request. + +### Sub-URL Role Requirements + +The API Backend's "Sub-URL Request Settings" can be used to define more granular role requirements. For example, this could be used to require roles on just a single API URL path, or to only require roles for POST/PUT write access. + +## Enforcing Role Requirements Inside Your API + +Instead of enforcing role requirements at the API Umbrella proxy layer, you can also utilize the role information in other ways within your API backend. If you have more complex authorization logic, then this may be easier to implement within your API's code. + +On each request with a valid API key that's passed to your API backend, there's an `X-Api-Roles` HTTP header. This contains a comma-delimited list of all the roles assigned to the API key that's making the request. Your APIs can parse this HTTP header and use it to decide whether access should be permitted or denied. diff --git a/docs/admin/api-users/index.rst b/docs/admin/api-users/index.rst index e162cd581..5a8d62219 100644 --- a/docs/admin/api-users/index.rst +++ b/docs/admin/api-users/index.rst @@ -3,3 +3,5 @@ API Users .. toctree:: :maxdepth: 1 + + roles diff --git a/docs/admin/api-users/roles.md b/docs/admin/api-users/roles.md new file mode 100644 index 000000000..185ef820b --- /dev/null +++ b/docs/admin/api-users/roles.md @@ -0,0 +1,5 @@ +# Roles + +API Umbrella's "roles" feature can be used to restrict access to APIs so that only certain API keys may access the API. + +See the [API Backends' Role Restrictions](../api-backends/role-restrictions.html) documentation for more detail.