API Access
Manage access to your APIs.
Introduction
API owners need to control access to their APIs, deciding who can use them and how. This is where the APIAccess resource comes in handy. By creating an APIAccess object and linking it to specific user groups and targeted APIs, owners can precisely manage access control to their APIs.
APIAccess behaviour
Basic Usage
Let's start with a basic example. Suppose you want to grant the customer
user group access
to the flight-api
API. Here's how you can achieve that:
- APIAccess
- API
- API Plan
apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
name: flight-customer
namespace: apps
spec:
groups:
- customer
apis:
- name: flight-api
apiPlan:
- name: std-plan
weight: 100
apiVersion: hub.traefik.io/v1alpha1
kind: API
metadata:
name: flight-api
namespace: apps
spec:
openApiSpec:
path: /openapi.yaml
apiVersion: hub.traefik.io/v1alpha1
kind: APIPlan
metadata:
name: std-plan
namespace: default
spec:
title: "Standard"
description: "**Standard Plan**"
rateLimit:
limit: 1
period: 1s
quota:
limit: 10000
period: 750h # 1 month
Configuration options
Field | Description | Required | Default |
---|---|---|---|
groups | List of user groups to grant access | Yes | |
apis | List of APIs to grant access | Yes | |
apiPlan | References the API Plan | No | |
weight | Determines the priority when multiple APIAccess resources overlap. | No | Default value is 0 when not set |
The APIAccess
, APIPlan
and the API
must all exist in the same namespace.
Weight
The weight field in the APIAccess
resource allows you to prioritize access policies when a user belongs to multiple groups that have access to the same API. A higher weight value grants higher priority,
meaning its associated APIPlan
will take precedence over others with lower weights.
Key Points:
- Priority Management: When multiple
APIAccess
resources apply to the same user and API, the one with the highest weight determines the enforced API Plan. - Default Behavior: If weight is not set, it defaults to 0. Resources with higher weights override those with lower or default weights.
- Conflict Resolution: In cases where multiple
APIAccess
resources have the same weight, the system may use alphabetical order of the resource names to determine precedence.
Configuration Example
Consider a scenario where a user belongs to both the standard
and vip
groups, each with different access policies for the same API. By assigning a higher weight to the vip
group's APIAccess
,
you ensure that the vip plan is enforced over the standard one.
- API Plan
- APIAccess
apiVersion: hub.traefik.io/v1alpha1
kind: APIPlan
metadata:
name: standard-plan
namespace: default
spec:
title: "Standard Plan"
description: "Standard API access with basic rate limits."
rateLimit:
limit: 5
period: 1s
quota:
limit: 10000
period: 750h # 1 month
---
apiVersion: hub.traefik.io/v1alpha1
kind: APIPlan
metadata:
name: vip-plan
namespace: default
spec:
title: "VIP Plan"
description: "VIP API access with enhanced rate limits and quotas."
rateLimit:
limit: 20
period: 1s
quota:
limit: 50000
period: 750h # 1 month
---
apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
name: standard-access
namespace: default
spec:
groups:
- standard
apis:
- name: my-api
apiPlan:
name: standard-plan
weight: 0
---
apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
name: vip-access
namespace: default
spec:
groups:
- vip
apis:
- name: my-api
apiPlan:
name: vip-plan
weight: 10
Outcome
A user who belongs to both the standard and vip groups will have the vip-plan
enforced for my-api
due to its higher weight. This allows VIP users to benefit from enhanced rate limits and quotas without being constrained
by the standard plan.
Everyone
To allow every authenticated user to access an API, set the everyone
option to true.
apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
name: flight-everyone
spec:
everyone: true
apis:
- name: flight-api
When Users / Consumers belong to multiple groups, they will inherit access from each group they belong to. Please refer to the documentation about user management for more information.
API Selector
There are 2 ways to select APIs within your APIAccess:
- Reference the targeted API names in the
apis
fields as shown in the example above. - Alternatively, you can select multiple APIs using the advanced
apiSelector
mechanism.
Let's add some labels on your API objects and use standard Kubernetes labels selectors in APIAccesses:
- Flight API
- Ticket API
- Sales APIAccess
- Admin APIAccess
apiVersion: hub.traefik.io/v1alpha1
kind: API
metadata:
name: flight-api
namespace: apps
labels:
area: customers
module: erp
spec:
openApiSpec:
path: /openapi.yaml
apiVersion: hub.traefik.io/v1alpha1
kind: API
metadata:
name: ticket-api
namespace: apps
labels:
area: tickets
module: crm
spec:
openApiSpec:
path: /openapi.yaml
apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
name: sales
namespace: apps
spec:
groups:
- customer
apiSelector:
matchLabels:
module: crm
apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
name: admins
namespace: apps
spec:
groups:
- admin
apiSelector:
matchExpressions:
- key: area
operator: Exists
Multiple APIAccess objects can select the same APIs.
Advanced Selector Examples
- This won't select any APIs
- This will select all APIs
spec:
// no apiSelector
spec:
apiSelector: {}
Please refer to the detailed documentation about Label selectors.
Combining Selectors and API Names
The following example combines API selection by name
, matchLabels
and matchExpressions
.
The selected APIs will include "my-api-1", "my-api-2" and all APIs with the "product" area label set,
along with an audience of either "dev" or "admin".
apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
name: admin-access
namespace: apps
spec:
groups:
- support
apis:
- name: my-api-1
- name: my-api-2
apiSelector:
matchLabels:
area: product
matchExpressions:
- operator: in
key: audience
value: ["dev", "admin"]
OperationFilter
By default, when granting access to an API for a group of users, all of its operations are accessible.
However, you can use the operationFilter
to limit exposure to a subset of operations.
This feature allows you to selectively grant access to a defined set of operations, as specified in the API, using operationSets.
The feature provides fine-grained control over API exposure, enabling precise management of which operations are accessible.
When you add an operationFilter
to an APIAccess, it applies to every API of this APIAccess.
To simultaneously expose all and selected operations of your APIs, you need to use two distinct APIAccess objects: one for exposing all operations; the other for exposing selected operations, that is, to apply operation sets/filters. You can leverage both the UI or the Hub Static Analyzer that explain in details how accesses will propagate.
If an operation-filtering APIAccess and a non-granular APIAccess overlap, the non-granular will take precedence and provide full access to that API.
Example
In the following example, the group intern
has permissions for two operationSets: get-employees
and get-payrolls
, which are defined in the API Object.
- APIAccess
- API
apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
name: intern-api
namespace: apps
spec:
groups:
- intern
apis:
- name: my-api
operationFilter:
include:
- get-employees
- get-payrolls
apiVersion: hub.traefik.io/v1alpha1
kind: API
metadata:
name: my-api
namespace: apps
spec:
openApiSpec:
path: /openapi.yaml
operationSets:
- name: get-employees
matchers:
methods: ["GET"]
path: "/employees"
- name: get-payrolls
matchers:
methods: ["GET"]
path: "/payrolls"
Related Content
- Lean more about authentication & authorization
- Get familiar with users and groups management