Vocabulary ========== .. include:: _warning.rst .. include:: _links.rst IAM Floyd provides a fluid interface and enables you to define policy statements in a human readable and easy to understand phrase. **allow** | **deny** (Effect) ----------------------------- The methods ``allow()`` and ``deny()`` control the `Effect `_ of the statement. The default effect of any statement is ``Allow``, so it's not mandatory to add either of these methods to the method chain. Though it is recommended to improve readability: .. example:: allow-and-deny **to** (Action) --------------- Every available IAM `action`_ is represented by a distinct method. These methods start with ``to``. You allow/deny **to** *do something* .. example:: allow In case of `missing actions `__, you can just add any action key yourself via ``to()``: .. example:: actions-raw **all** (Action) ---------------- While methods starting with ``to`` add a single action to a statement, methods starting with ``all`` add multiple `actions `_. allActions ^^^^^^^^^^ This method adds all actions of the related service to the statement, e.g. `ec2:*` .. example:: actions-all allMatchingActions ^^^^^^^^^^^^^^^^^^ Adds all actions matching regular expressions to the statement. .. ATTENTION:: The list of actions is compiled at run time. The generated statement object contains an exact list of actions that matched when you build it. If AWS later adds/removes actions that would match the regular expression, you need to re-generate the statements. The regular expressions need to be in `Perl/JavaScript literal style `_ and need to be passed as strings: .. example:: actions-matching Access levels ^^^^^^^^^^^^^ To add all actions of a certain `access level `_ to the statement use the below methods. .. ATTENTION:: The list of actions is compiled at run time. The generated statement object contains an exact list of actions that matched when you build it. If AWS later adds/removes actions or changes the level, you need to re-generate the statements. .. NOTE:: When working with access levels the policy size limits may be exceeded quickly, just because there are so many actions available for some services like EC2. In these cases you should use the `compact`_ method, to compile the action list to a list of wildcard patterns. allListActions """""""""""""" Adds all actions with `access level `_ **list** to the statement. .. example:: access-levels-list allReadActions """""""""""""" Adds all actions with `access level `_ **read** to the statement. .. example:: access-levels-read allWriteActions """"""""""""""" Adds all actions with `access level `_ **write** to the statement. .. example:: access-levels-write allPermissionManagementActions """""""""""""""""""""""""""""" Adds all actions with `access level `_ **permission management** to the statement. .. example:: access-levels-permission-management allTaggingActions """"""""""""""""" Adds all actions with `access level `_ **tagging** to the statement. .. example:: access-levels-tagging **if** (Condition) ------------------ Every available IAM `condition`_ key is represented by a distinct method. These methods start with ``if``. You allow/deny something **if** a condition is met. Every statement provider (e.g. ``Ec2``) brings its unique conditions. `Global condition context keys `_ start with ``ifAws``. .. NOTE:: Multiple conditions on a statement all have to be true. When you have multiple values on a single condition, one of them has to be true. Other than that, IAM has no concept of ``OR``. You need to define multiple statements for each ``OR`` branch. .. example:: conditions Every ``if`` method has a default operator. For instance, conditions which operate on strings usually have ``StringLike`` as default. Most methods allow you to pass an operator as last argument. .. NOTE:: Operators can be passed as string, though it is recommended to use the `Operators `__ provided by the package. .. example:: conditions-operator-string In case of `missing conditions `__, you can define just any condition yourself via ``if()``: .. example:: conditions-raw **on** (Resource) ----------------- Every available IAM `resources `_ key is represented by a distinct method. These methods start with ``on``. You allow/deny something **on** a specific resource (or pattern). .. example:: resource In case of `missing resources `__ or if you already have an ARN ready, use the ``on()`` method: .. example:: resource-raw Non-global resource ARNs contain the region and/or account. Generally all ARNs contain the partition. In ``cdk-iam-floyd`` the `account`, `region` and `partition` default to the values provided by the stack. In ``iam-floyd`` the `partition` defaults to ``aws`` and the `account` and `region` default to ``*``. The ``on*()`` methods take optional parameters to override the default values: .. example:: resource-default-override If you want to override the defaults for the whole statement, see `in (ARN defaults)`_. **in** (ARN defaults) --------------------- The `on*`__ methods generate ARNs which contain `partition` and potentially `region` and `account`. The ``in()*`` methods can be used to override the defaults for all **consecutively** added resources. You allow/deny something on resources **in** a specific account, region and partition. __ `on (Resource)`_ .. NOTE:: The ``in*()`` methods do not by themselves modify the statement. They just set the defaults for the resource added **consecutively** to the statement. Therefore make sure to call the ``in*()`` methods before adding resources via ``on*()``. .. example:: arn-defaults-separate There also is a shorthand function to set all defaults at once: .. example:: arn-defaults-combined Since these methods set defaults for consecutively added resources, you can also override the defaults for additional resource in the same statement: .. example:: arn-defaults-override **for** (Principal) ------------------- .. NOTE:: If you use the CDK variant of the package, don't attempt to create an assume policy with this package. Assume policies have to be of type ``IPrincipal`` and can easily be created with the `iam `_ package. Every possible `principal `_ is represented by a distinct method. These methods start with ``for``. You allow/deny something **for** a specific principal. .. example:: principal Some of the ``for*`` methods accept multiple values at once: .. example:: principal-multiple The CDK variant of the package has an additional method ``forCdkPrincipal``, which takes any number of `iam.IPrincipal `_ objects: .. example:: principal.cdk **not** (notAction, notResource and notPrincipal) ------------------------------------------------- .. WARNING:: Make sure, you well understand the concepts of `notAction `_, `notResource `_ and `notPrincipal `_. This is where things quickly go wrong, especially when used in combination. notAction ^^^^^^^^^ Switches the policy provider to use `NotAction`_. .. example:: notAction notResource ^^^^^^^^^^^ Switches the policy provider to use `NotResource`_. .. example:: notResource notPrincipal ^^^^^^^^^^^^ Switches the policy provider to use `NotPrincipal`_. .. example:: notPrincipal **compact** ----------- This method can be used to convert a list of actions down to a list of wildcard patterns. This can be handy to reduce the policy size, especially when you work with `Access levels`_. .. ATTENTION:: When AWS later adds new actions, the patterns might match additional actions. .. example:: compact