[NEW] API Keys, Roles and Policies

Introducing API Keys and the difference between Access Keys

API Keys are a new resource type for Identity and Access Management, replacing Access Keys. They provide finer grained restrictions and a more expressive API.

Through Access Keys, a user can manage keys which embed their own policy, and can specify which operations or set of operations are allowed.

API Keys introduce the concept of a Role, and decouple the key itself (used for authentication) from the policy (used for authorization). A role is attached to a policy, and can be referenced by multiple keys. Furthermore, API Key policies offer more powerful authorization mechanisms and a wider spectrum of parameters.

Currently, both /api-key and /access-key endpoints are available as each implementation is separate from the other. Eventually, Access Keys will be migrated to an equivalent API key, at which point the old endpoints will be deprecated.

IAM Authorization flow

The introduction of API keys decouples the authorization and authentication mechanisms. Therefore, we can split authorization through several levels or “gateways” for a single request.

• The Org policy applies to any user under an organization.
• The Role policy is created and managed by individual users within an organization.

A request has to be authorized at both levels to be processed by the platform.

IAM Roles

A Role is a way to store a user’s (potentially) mutable policy, which can be re-used across several API keys.

{
  "name": "my-new-role",
  "policy": {
    "default-service-strategy": "deny",
    "services": {
      "iam": {
        "type": "allow"
      }
    }
  }
}

In the example above, the role called "my-new-role" states that all operations are denied except for iam services, which are explicitly allowed.

After a role is created, an api-key can reference that role’s ID. Then, that api-key will have the permissions stated in that policy.

A role can be created with the create-iam-role operation (POST /iam-role) endpoint. We can modify the role’s policy by calling update-iam-role-policy (PUT /iam-role/<id>:policy). Finally, to assume the role in a request, we can distribute one or more API keys by calling create-api-key (POST /api-key).

API Key Policies

Incoming requests to the Exoscale API go through several layers of authorization. The last of which is defined by a policy attached to the user role. Given the right permissions, a user can create their own policies to enforce fine-grained authorization parameters. The rest of this document describes what possibilities are available when creating policies, as well as some best practices and examples.

A policy is composed of

• The Services map - a separation of the authorization logic according to which platform service the request belongs to.
• The Default Service Strategy - a default top-level allow or deny decision that applies when there is no entry in the services map for the service of the incoming API operation. For example: list-zones is an operation that belongs to the compute service - if compute is not present in the services map, the default service strategy will be applied.

{"defaul-service-strategy": "allow",
 "services": {"compute": {...},
              "dbaas":   {...}}}

Requests are evaluated in the context of the platform service they belong to - Compute, SOS, DBaaS, etc - a user can define one of the following authorization bodies for each service.

• Nothing - in the abscence of a specification, use the default service strategy
• Allow overrides the default service strategy - allow all requests.
• Deny overrides the default service strategy - deny all requests.
• Rule-based a more fine-grained approach to authorization

Rule based authorization 101

{"default-service-strategy": "deny",
 "services":
 {"compute": {"type":  "allow"},
  "sks":     {"type":  "rules",
              "rules": [{"action":     "deny",
                         "expression": "resource.sks_nodepool.name in ['important-nodepool', 'foobar']"}
                         {"action":     "allow"
                          "expression": "true"}]}}}

A rule-based service policy consists of a list of one or more rules:

• Rules are composed of an Expression - against which the request is evaluated, and an Action - the resulting decision should the evaluated expression returns TRUE.
• Expressions are written in the Common Expression Language CEL
• Rules are evaluated in order
• If the expression of a rule is valid, its action becomes the authorization output - allow or deny.
• If the expression of a rule is invalid, nothing is concluded and we evaluate the next rule
• If no rule is valid, the request is not authorized to proceed regardless of the default service strategy.

The authorization flow will process each rule in order. The first valid rule will short-circuit the authorization process, resulting in its action (either allow or deny) - equivalent to an OR condition between rules. If all rules are exhausted the request is rejected, regardless of the default service strategy.

CEL bindings

A binding refers to the coupling of a variable in a CEL expression and its corresponding value at the time the expression is evaluated.

The top-level bindings are:

• service - the service class in scope (ex: “sos”, “instance-pool”, etc)
• zone - the zone where the call is attempted (ex: “ch-gva-2”)
• now - a CEL timestamp (string, can be coerced to CEL timestamp in expressions via timestamp(now))
• source_ip - the ip of the caller
• api_key - the exoscale api key of the caller
• operation - the operation performed (ex: “scale-instance-pool”)
• parameters - parameters passed to the command (ex: parameters.size -> 3)
• resources - a map of resource type -> resource (varies depending on the call, see IAM Reference: Operations and Resources)

The resources and parameters bindings are special, as they don’t resolve to mere literals, they can contain nested bindings. The key difference between parameters and resources is the later might contain metadata that is not in the request payload.

For example:

• parameters.foo == 'bar' restrict the call if the input foo is equal to bar.
• parameters.foo.bar == 'baz' or parameters.foo == {'bar':'baz'} - restrict the call if the input object foo has a key bar equal to baz
• parameters.foo.exists(k, k.bar == 'baz') - restrict the call if the input collection foo has and object with a key bar equals to baz
• resources.elastic_ip.ip == 10.10.10.10 - restrict the call on an elastic_ip resource that has the specified IP address.
• resources.instance_pool.id == "d4c1673a-a342-4a0f-b8e7-b2da4091ddfd" - restrict the call on an instance_pool that has the specified ID.

The IAM Reference: Operations and Resources contains the necessary information to map any API endpoint to its corresponding operation, parameters, and resources bindings.

CEL Best Practices

Split expressions into rules

When writing a rule with more than one condition, it becomes more manageable to write several smaller rules.

This can be achieved as long as the conditions are separated by OR operands.

[{"action":    "allow",
 "expression": "operation == 'list-sos-buckets' || resource.bucket.name.startsWith('public-')"}]

is equivalent to

[{"action":    "allow",
 "expression": "operation == 'list-sos-buckets'"},
 {"action":    "allow",
  "expression": "resource.bucket.name.startsWith('public-')"}]

Write a catch-all rule

Sometimes, we want our service to have a different default behavior than the rest, while still abiding to some rules.

Because rules are evaluated in order, we can achieve this by writing a catch-all rule at the end of the list.

This is also useful to prevent unexpected authorization failures due to no rule matching the request.

{"default-service-strategy": "allow",
 "services": {"sks": {"type": "rules",
                      "rules": [{"action":     "allow",
                                 "expression": "'foo' in resource.cluster.addons"},
                                {"action":     "deny",
                                 "expression": "true"}]}}}

Don’t mix resources in one rule

Every request may load a specific number of resources in order to have enough information to evaluate the rule properly. This means that not every rule will be able to evaluate every request.

For example: the expression "resource.security-group.name == 'dev-sg'" assumes the presence of a security group resource has been loaded into the context.

Consider the incoming request is GET /instance-pool/<id> (listing instance pools). Both instance pools and security groups belong to the compute service, thus the aforementioned CEL expression will be evaluated. However, only the instance pool resource is loaded for get-instance-pool so a CEL expression that refers to resources.instance_pool.id and resources.security_group.id cannot result in a match for the get-instance-pool endpoint.

Even if the expression includes an instance pool parameter "resource.security-group.name == 'dev-sg' && size(resource.instancepool.instances) > 2", it will be invalid too.

Therefore we strongly recommended to write separate rules based on the resource types.

CEL examples

Allow everything, deny everything

{"default-service-strategy": "allow"}

{"default-service-strategy": "deny"}

Deny IAM requests

Deny requests to the IAM service. Allow all requests to other services.

{"default-service-strategy": "allow",
 "services": {"iam": {"type": "deny"}}}

Deny IAM requests for a specific API key

Deny requests to the IAM service for a specific key. Allow all requests to other services regardless of which key is used.

{"default-service-strategy": "allow",
 "services": 
 {"iam": {"type": "rules",
          "rules": [{"action": "allow",
                     "expression": "api_key != 'EXO123456789'"}]}}}

Alternatively

{"default-service-strategy": "allow",
 "services": 
 {"iam": {"type": "rules",
          "rules": [{"action": "deny",
                     "expression": "api_key == 'EXO123456789'"},
                    {"action": "allow",
                     "expression": "true"}]}}}

Restrict requests to instances labeled dev

Allow only requests that load an instance resource - eg. the resize-instance-disk operation - whose labels include "dev".

{"default-service-strategy": "allow",
 "services": 
 {"compute": {"type": "rules",
              "rules": [{"action": "allow",
                         "expression": "!has(resources.instance)"},
                         {"action": "allow",
                         "expression": "'dev' in resources.instance.labels"}]}}}

The second rule !has(resources.instance) is needed because the first rule will fail for any request that doesn’t involve an instance, thus denying authorization.

Only allow specific request endpoints

Restrict requests to a service down to two endpoints. Endpoints in a policy are represented by their operation name.

• create-api-key - POST /api-key
• list-api-keys - GET /api-key
• get-api-key - GET /api-key/<id>

{"default-service-strategy": "allow",
 "services": 
 {"iam": {"type": "rules",
              "rules": [{"action": "allow",
                         "expression": "operation in ['create-api-key', 'list-api-keys', 'get-api-key']"}]}}}

Make an SOS bucket read-only

When my-bucket is the object of the request, allow only head-sos-bucket and get-sos-bucket operations.

{"default-service-strategy": "allow",
 "services": 
 {"sos": {"type": "rules",
          "rules": [{"action": "deny",
                     "expression": "!operation in ['head-sos-bucket', get-sos-bucket'] && resources.bucket in ['my-bucket']"},
                    {"action": "allow",
                     "expression": "true"}]}}}

Ensure one can only create keys with the same role

{"default-service-strategy": "allow",
 "services": 
 {"iam": {"type": "rules",
          "rules": [{"action": "deny",
                     "expression": "operation == 'create-api-key' && parameters.role_id != '<my-role-id uuid>'"}]}}}

Understanding a forbidden API call

Here are possible scenarios when the API returns a 403 Forbidden response.

• forbidden by [role|org] policy, [compute|sos|dns|iam]: Unable to find an operation in the list defined by the policy. The message indicates that on the specific policy (at role or organization level), the performed operation is not specified with either deny or allow action. As the parser is not able to find a single match - the call is denied. The message also shows a service-class the restriction belongs to.

• forbidden by [role|org] policy, [compute|sos|dns|iam] - A deny rule matched. Rule index: *INDEX_NUMBER* This extended version of the previous message, will appear when a policy has rules whose action is deny and matches the performed call. The index indicates the sequence number of the rule in the rules set starting at 0 for the first rule.