API Access
Manage access to your APIs.
Introduction
The API Access object defines which groups can access which APIs or Collections.
Gateways will embed the API Accesses they can expose. API accesses that don't belong to any gateway will be of no effect.
Users and Groups
When Users / Consumers belongs to multiple groups, they will inherit access from each group they belong to.
Please refer to the documentation about user management for more information.
Managing API Access Using CRDs
The API Access object has several properties.
Field | Description | Required |
---|---|---|
groups | Name of the user group(s) with permissions for the API(s). Requires apiSelector.matchLabels , apiSelector.matchExpressions or a combination of both to select APIs. | Yes |
apis.name | Select APIs based on names You can combine it with apiSelector.matchLabels and apiSelector.matchExpressions . See Labels and Selectors. | No |
apis.namespace | Name of the Kubernetes Namespace used by the API(s) defined in apis.name . This is required for apis.name . | No |
operationFilter.include | Allow API operations which are configured via an operationSet for one or multiple group(s). | No |
apiSelector.matchLabels | Select APIs based on label matching: Equality-Based Requirements. | No |
apiSelector.matchExpressions | Select APIs based on advanced label expressions: Set-Based Requirements. | No |
apiCollections | Select API Collections based on names. | No |
apiCollectionSelector.matchLabels | Select API Collections based on label matching: Equality-Based Requirements | No |
apiCollectionSelector.matchExpressions | Select API Collections based on advanced label expressions: Set-Based Requirements. | No |
OperationFilter
By default, when an API is granted to a group of users, all of its operations become accessible.
If you only want to expose a specific subset of operations, you can utilize the operationFilter
.
This feature enables you to selectively grant access to a defined set of operations, as specified in the API, through the use of operationSets definitions.
This provides fine-grained control over API exposure, allowing you to precisely manage which operations are accessible.
When you configure an operationFilter
on an APIAccess, it is effective for all the APIs selected by this APIAccess.
To expose APIs in their entirety and APIs with selected operations, you must use two APIAccess objects.
One is for publishing the whole API, and one is for the operation sets/filters.
This way, both the whole APIs and the selected operations will be available to the user as intended.
In case of an overlap between an operation filtering APIAccess and a non-granular APIAccess, the non-granular will be the stronger, providing all access to that API.
Examples
All examples below show how to give users from group support
credentials to APIs.
- Using Labels
- Using API Name
- API Collections
- Combining Selectors and API Names
- Operation Filter
apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
name: customer-support
spec:
groups:
- support
apiSelector:
matchLabels:
area: customers
apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
name: customer-support
spec:
groups:
- support
apis:
- name: my-api-1
namespace: my-ns
- name: my-api-2
namespace: my-ns
apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
name: customer-support
spec:
groups:
- support
apiCollections:
- name: crm-all
# Example of combing selecting APIs by `name`, `matchLabels` and `matchExpressions`.
# The selected APIs will be "my-api-1", "my-api-2" and all APIs with the area Label sets to "product" and audience either "dev" or "admin".
apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
name: admin-access
spec:
groups:
- support
apis:
- name: my-api-1
namespace: my-ns
- name: my-api-2
namespace: my-ns
apiSelector:
matchLabels:
area: product
matchExpressions:
- operator: in
key: audience
value: ["dev", "admin"]
apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
name: intern-api
spec:
groups:
- intern
apis:
- name: my-api
namespace: my-ns
# Using operationFilters to allow access only for two specific operationSets, operationSets are configured as part of the API or API versioning configuration
operationFilter:
include:
- getEmployees
- getPayrolls
Selector Examples
- This won't select any APIs
- This will select all APIs
- Select all APIs where the label key equals the value
spec:
// no apiSelector
spec:
apiSelector: {}
spec:
apiSelector:
key: value
For more information, please refer to detailed documentation about Label selectors.
Related Content
- Lean more about authentication & authorization
- Get familiar with users and groups management