ash-project/ash
1
0
Fork 0
mirror of https://github.com/ash-project/ash.git synced 2024-09-20 05:23:03 +12:00
Code Issues Projects Releases Packages Wiki Activity

docs: refactor security guides

Browse source
This commit is contained in:
Zach Daniel 2024-04-06 17:40:05 -04:00
parent 35c6d6e144
commit f9eff8810f
15 changed files with 135 additions and 108 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
documentation/dsls/DSL:-Ash.Domain.md
View file

@ -215,7 +215,7 @@ end
## authorization
Options for how requests are authorized using this domain. See the [security guide](/documentation/topics/security.md) for more.
Options for how requests are authorized using this domain. See the [Sensitive Data guide](/documentation/topics/security/sensitive-data.md) for more.

6
documentation/dsls/DSL:-Ash.Policy.Authorizer.md
View file

@ -20,7 +20,7 @@ A resource can be given a set of policies, which are enforced on each call to a
For reads, policies can be configured to filter out data that the actor shouldn't see, as opposed to
resulting in a forbidden error.
See the [policies guide](/documentation/topics/policies.md) for practical examples.
See the [policies guide](/documentation/topics/security/policies.md) for practical examples.
Policies are solved/managed via a boolean satisfiability solver. To read more about boolean satisfiability,
see this page: https://en.wikipedia.org/wiki/Boolean_satisfiability_problem. At the end of
@ -38,7 +38,7 @@ A section for declaring authorization policies.
Each policy that applies must pass independently in order for the
request to be authorized.
See the [policies guide](/documentation/topics/policies.md) for more.
See the [policies guide](/documentation/topics/security/policies.md) for more.
### Nested DSLs
@ -120,7 +120,7 @@ policy always() do
end
```
See the [policies guide](/documentation/topics/policies.md) for more.
See the [policies guide](/documentation/topics/security/policies.md) for more.
### Nested DSLs

30
documentation/dsls/DSL:-Ash.Resource.md
View file

@ -86,14 +86,14 @@ end
|------|------|---------|------|
| [`constraints`](#attributes-attribute-constraints){: #attributes-attribute-constraints } | `keyword` | | Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md). |
| [`description`](#attributes-attribute-description){: #attributes-attribute-description } | `String.t` | | An optional description for the attribute. |
| [`sensitive?`](#attributes-attribute-sensitive?){: #attributes-attribute-sensitive? } | `boolean` | `false` | Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more. |
| [`sensitive?`](#attributes-attribute-sensitive?){: #attributes-attribute-sensitive? } | `boolean` | `false` | Whether or not the attribute value contains sensitive information, like PII. See the [Sensitive Data guide](/documentation/topics/security/sensitive-data.md) for more. |
| [`source`](#attributes-attribute-source){: #attributes-attribute-source } | `atom` | | If the field should be mapped to a different name in the data layer. Support varies by data layer. |
| [`always_select?`](#attributes-attribute-always_select?){: #attributes-attribute-always_select? } | `boolean` | `false` | Whether or not to ensure this attribute is always selected when reading from the database, regardless of applied select statements. |
| [`primary_key?`](#attributes-attribute-primary_key?){: #attributes-attribute-primary_key? } | `boolean` | `false` | Whether the attribute is the primary key. Composite primary key is also possible by using `primary_key? true` in more than one attribute. If primary_key? is true, allow_nil? must be false. |
| [`allow_nil?`](#attributes-attribute-allow_nil?){: #attributes-attribute-allow_nil? } | `boolean` | `true` | Whether or not the attribute can be set to nil. If nil value is given error is raised. |
| [`generated?`](#attributes-attribute-generated?){: #attributes-attribute-generated? } | `boolean` | `false` | Whether or not the value may be generated by the data layer. |
| [`writable?`](#attributes-attribute-writable?){: #attributes-attribute-writable? } | `boolean` | `true` | Whether or not the value can be written to. Non-writable attributes can still be written with `Ash.Changeset.force_change_attribute/3`. |
| [`public?`](#attributes-attribute-public?){: #attributes-attribute-public? } | `boolean` | `false` | Whether or not the attribute should be shown over public interfaces. See the [security guide](/documentation/topics/security.md) for more. |
| [`public?`](#attributes-attribute-public?){: #attributes-attribute-public? } | `boolean` | `false` | Whether or not the attribute should be shown over public interfaces. See the [sensitive data guide](/documentation/topics/security/sensitive-data.md) for more. |
| [`default`](#attributes-attribute-default){: #attributes-attribute-default } | `(-> any) \| mfa \| any` | | A value to be set on all creates, unless a value is being provided already. |
| [`update_default`](#attributes-attribute-update_default){: #attributes-attribute-update_default } | `(-> any) \| mfa \| any` | | A value to be set on all updates, unless a value is being provided already. |
| [`filterable?`](#attributes-attribute-filterable?){: #attributes-attribute-filterable? } | `boolean` | `true` | Whether or not the attribute can be referenced in filters. |
@ -147,14 +147,14 @@ create_timestamp :inserted_at
| [`type`](#attributes-create_timestamp-type){: #attributes-create_timestamp-type } | `module` | `Ash.Type.UtcDatetimeUsec` | The type of the attribute. See `Ash.Type` for more. |
| [`constraints`](#attributes-create_timestamp-constraints){: #attributes-create_timestamp-constraints } | `keyword` | | Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md). |
| [`description`](#attributes-create_timestamp-description){: #attributes-create_timestamp-description } | `String.t` | | An optional description for the attribute. |
| [`sensitive?`](#attributes-create_timestamp-sensitive?){: #attributes-create_timestamp-sensitive? } | `boolean` | `false` | Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more. |
| [`sensitive?`](#attributes-create_timestamp-sensitive?){: #attributes-create_timestamp-sensitive? } | `boolean` | `false` | Whether or not the attribute value contains sensitive information, like PII. See the [Sensitive Data guide](/documentation/topics/security/sensitive-data.md) for more. |
| [`source`](#attributes-create_timestamp-source){: #attributes-create_timestamp-source } | `atom` | | If the field should be mapped to a different name in the data layer. Support varies by data layer. |
| [`always_select?`](#attributes-create_timestamp-always_select?){: #attributes-create_timestamp-always_select? } | `boolean` | `false` | Whether or not to ensure this attribute is always selected when reading from the database, regardless of applied select statements. |
| [`primary_key?`](#attributes-create_timestamp-primary_key?){: #attributes-create_timestamp-primary_key? } | `boolean` | `false` | Whether the attribute is the primary key. Composite primary key is also possible by using `primary_key? true` in more than one attribute. If primary_key? is true, allow_nil? must be false. |
| [`allow_nil?`](#attributes-create_timestamp-allow_nil?){: #attributes-create_timestamp-allow_nil? } | `boolean` | `false` | Whether or not the attribute can be set to nil. If nil value is given error is raised. |
| [`generated?`](#attributes-create_timestamp-generated?){: #attributes-create_timestamp-generated? } | `boolean` | `false` | Whether or not the value may be generated by the data layer. |
| [`writable?`](#attributes-create_timestamp-writable?){: #attributes-create_timestamp-writable? } | `boolean` | `false` | Whether or not the value can be written to. Non-writable attributes can still be written with `Ash.Changeset.force_change_attribute/3`. |
| [`public?`](#attributes-create_timestamp-public?){: #attributes-create_timestamp-public? } | `boolean` | `false` | Whether or not the attribute should be shown over public interfaces. See the [security guide](/documentation/topics/security.md) for more. |
| [`public?`](#attributes-create_timestamp-public?){: #attributes-create_timestamp-public? } | `boolean` | `false` | Whether or not the attribute should be shown over public interfaces. See the [sensitive data guide](/documentation/topics/security/sensitive-data.md) for more. |
| [`default`](#attributes-create_timestamp-default){: #attributes-create_timestamp-default } | `(-> any) \| mfa \| any` | `&DateTime.utc_now/0` | A value to be set on all creates, unless a value is being provided already. |
| [`update_default`](#attributes-create_timestamp-update_default){: #attributes-create_timestamp-update_default } | `(-> any) \| mfa \| any` | | A value to be set on all updates, unless a value is being provided already. |
| [`filterable?`](#attributes-create_timestamp-filterable?){: #attributes-create_timestamp-filterable? } | `boolean` | `true` | Whether or not the attribute can be referenced in filters. |
@ -209,14 +209,14 @@ update_timestamp :updated_at
| [`type`](#attributes-update_timestamp-type){: #attributes-update_timestamp-type } | `module` | `Ash.Type.UtcDatetimeUsec` | The type of the attribute. See `Ash.Type` for more. |
| [`constraints`](#attributes-update_timestamp-constraints){: #attributes-update_timestamp-constraints } | `keyword` | | Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md). |
| [`description`](#attributes-update_timestamp-description){: #attributes-update_timestamp-description } | `String.t` | | An optional description for the attribute. |
| [`sensitive?`](#attributes-update_timestamp-sensitive?){: #attributes-update_timestamp-sensitive? } | `boolean` | `false` | Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more. |
| [`sensitive?`](#attributes-update_timestamp-sensitive?){: #attributes-update_timestamp-sensitive? } | `boolean` | `false` | Whether or not the attribute value contains sensitive information, like PII. See the [Sensitive Data guide](/documentation/topics/security/sensitive-data.md) for more. |
| [`source`](#attributes-update_timestamp-source){: #attributes-update_timestamp-source } | `atom` | | If the field should be mapped to a different name in the data layer. Support varies by data layer. |
| [`always_select?`](#attributes-update_timestamp-always_select?){: #attributes-update_timestamp-always_select? } | `boolean` | `false` | Whether or not to ensure this attribute is always selected when reading from the database, regardless of applied select statements. |
| [`primary_key?`](#attributes-update_timestamp-primary_key?){: #attributes-update_timestamp-primary_key? } | `boolean` | `false` | Whether the attribute is the primary key. Composite primary key is also possible by using `primary_key? true` in more than one attribute. If primary_key? is true, allow_nil? must be false. |
| [`allow_nil?`](#attributes-update_timestamp-allow_nil?){: #attributes-update_timestamp-allow_nil? } | `boolean` | `false` | Whether or not the attribute can be set to nil. If nil value is given error is raised. |
| [`generated?`](#attributes-update_timestamp-generated?){: #attributes-update_timestamp-generated? } | `boolean` | `false` | Whether or not the value may be generated by the data layer. |
| [`writable?`](#attributes-update_timestamp-writable?){: #attributes-update_timestamp-writable? } | `boolean` | `false` | Whether or not the value can be written to. Non-writable attributes can still be written with `Ash.Changeset.force_change_attribute/3`. |
| [`public?`](#attributes-update_timestamp-public?){: #attributes-update_timestamp-public? } | `boolean` | `false` | Whether or not the attribute should be shown over public interfaces. See the [security guide](/documentation/topics/security.md) for more. |
| [`public?`](#attributes-update_timestamp-public?){: #attributes-update_timestamp-public? } | `boolean` | `false` | Whether or not the attribute should be shown over public interfaces. See the [sensitive data guide](/documentation/topics/security/sensitive-data.md) for more. |
| [`default`](#attributes-update_timestamp-default){: #attributes-update_timestamp-default } | `(-> any) \| mfa \| any` | `&DateTime.utc_now/0` | A value to be set on all creates, unless a value is being provided already. |
| [`update_default`](#attributes-update_timestamp-update_default){: #attributes-update_timestamp-update_default } | `(-> any) \| mfa \| any` | `&DateTime.utc_now/0` | A value to be set on all updates, unless a value is being provided already. |
| [`filterable?`](#attributes-update_timestamp-filterable?){: #attributes-update_timestamp-filterable? } | `boolean` | `true` | Whether or not the attribute can be referenced in filters. |
@ -272,13 +272,13 @@ integer_primary_key :id
| [`type`](#attributes-integer_primary_key-type){: #attributes-integer_primary_key-type } | `module` | `:integer` | The type of the attribute. See `Ash.Type` for more. |
| [`constraints`](#attributes-integer_primary_key-constraints){: #attributes-integer_primary_key-constraints } | `keyword` | | Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md). |
| [`description`](#attributes-integer_primary_key-description){: #attributes-integer_primary_key-description } | `String.t` | | An optional description for the attribute. |
| [`sensitive?`](#attributes-integer_primary_key-sensitive?){: #attributes-integer_primary_key-sensitive? } | `boolean` | `false` | Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more. |
| [`sensitive?`](#attributes-integer_primary_key-sensitive?){: #attributes-integer_primary_key-sensitive? } | `boolean` | `false` | Whether or not the attribute value contains sensitive information, like PII. See the [Sensitive Data guide](/documentation/topics/security/sensitive-data.md) for more. |
| [`source`](#attributes-integer_primary_key-source){: #attributes-integer_primary_key-source } | `atom` | | If the field should be mapped to a different name in the data layer. Support varies by data layer. |
| [`always_select?`](#attributes-integer_primary_key-always_select?){: #attributes-integer_primary_key-always_select? } | `boolean` | `false` | Whether or not to ensure this attribute is always selected when reading from the database, regardless of applied select statements. |
| [`primary_key?`](#attributes-integer_primary_key-primary_key?){: #attributes-integer_primary_key-primary_key? } | `boolean` | `true` | Whether the attribute is the primary key. Composite primary key is also possible by using `primary_key? true` in more than one attribute. If primary_key? is true, allow_nil? must be false. |
| [`generated?`](#attributes-integer_primary_key-generated?){: #attributes-integer_primary_key-generated? } | `boolean` | `true` | Whether or not the value may be generated by the data layer. |
| [`writable?`](#attributes-integer_primary_key-writable?){: #attributes-integer_primary_key-writable? } | `boolean` | `false` | Whether or not the value can be written to. Non-writable attributes can still be written with `Ash.Changeset.force_change_attribute/3`. |
| [`public?`](#attributes-integer_primary_key-public?){: #attributes-integer_primary_key-public? } | `boolean` | `true` | Whether or not the attribute should be shown over public interfaces. See the [security guide](/documentation/topics/security.md) for more. |
| [`public?`](#attributes-integer_primary_key-public?){: #attributes-integer_primary_key-public? } | `boolean` | `true` | Whether or not the attribute should be shown over public interfaces. See the [sensitive data guide](/documentation/topics/security/sensitive-data.md) for more. |
| [`default`](#attributes-integer_primary_key-default){: #attributes-integer_primary_key-default } | `(-> any) \| mfa \| any` | | A value to be set on all creates, unless a value is being provided already. |
| [`update_default`](#attributes-integer_primary_key-update_default){: #attributes-integer_primary_key-update_default } | `(-> any) \| mfa \| any` | | A value to be set on all updates, unless a value is being provided already. |
| [`filterable?`](#attributes-integer_primary_key-filterable?){: #attributes-integer_primary_key-filterable? } | `boolean` | `true` | Whether or not the attribute can be referenced in filters. |
@ -332,13 +332,13 @@ uuid_primary_key :id
| [`type`](#attributes-uuid_primary_key-type){: #attributes-uuid_primary_key-type } | `module` | `:uuid` | The type of the attribute. See `Ash.Type` for more. |
| [`constraints`](#attributes-uuid_primary_key-constraints){: #attributes-uuid_primary_key-constraints } | `keyword` | | Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md). |
| [`description`](#attributes-uuid_primary_key-description){: #attributes-uuid_primary_key-description } | `String.t` | | An optional description for the attribute. |
| [`sensitive?`](#attributes-uuid_primary_key-sensitive?){: #attributes-uuid_primary_key-sensitive? } | `boolean` | `false` | Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more. |
| [`sensitive?`](#attributes-uuid_primary_key-sensitive?){: #attributes-uuid_primary_key-sensitive? } | `boolean` | `false` | Whether or not the attribute value contains sensitive information, like PII. See the [Sensitive Data guide](/documentation/topics/security/sensitive-data.md) for more. |
| [`source`](#attributes-uuid_primary_key-source){: #attributes-uuid_primary_key-source } | `atom` | | If the field should be mapped to a different name in the data layer. Support varies by data layer. |
| [`always_select?`](#attributes-uuid_primary_key-always_select?){: #attributes-uuid_primary_key-always_select? } | `boolean` | `false` | Whether or not to ensure this attribute is always selected when reading from the database, regardless of applied select statements. |
| [`primary_key?`](#attributes-uuid_primary_key-primary_key?){: #attributes-uuid_primary_key-primary_key? } | `boolean` | `true` | Whether the attribute is the primary key. Composite primary key is also possible by using `primary_key? true` in more than one attribute. If primary_key? is true, allow_nil? must be false. |
| [`generated?`](#attributes-uuid_primary_key-generated?){: #attributes-uuid_primary_key-generated? } | `boolean` | `false` | Whether or not the value may be generated by the data layer. |
| [`writable?`](#attributes-uuid_primary_key-writable?){: #attributes-uuid_primary_key-writable? } | `boolean` | `false` | Whether or not the value can be written to. Non-writable attributes can still be written with `Ash.Changeset.force_change_attribute/3`. |
| [`public?`](#attributes-uuid_primary_key-public?){: #attributes-uuid_primary_key-public? } | `boolean` | `true` | Whether or not the attribute should be shown over public interfaces. See the [security guide](/documentation/topics/security.md) for more. |
| [`public?`](#attributes-uuid_primary_key-public?){: #attributes-uuid_primary_key-public? } | `boolean` | `true` | Whether or not the attribute should be shown over public interfaces. See the [sensitive data guide](/documentation/topics/security/sensitive-data.md) for more. |
| [`default`](#attributes-uuid_primary_key-default){: #attributes-uuid_primary_key-default } | `(-> any) \| mfa \| any` | `&Ash.UUID.generate/0` | A value to be set on all creates, unless a value is being provided already. |
| [`update_default`](#attributes-uuid_primary_key-update_default){: #attributes-uuid_primary_key-update_default } | `(-> any) \| mfa \| any` | | A value to be set on all updates, unless a value is being provided already. |
| [`filterable?`](#attributes-uuid_primary_key-filterable?){: #attributes-uuid_primary_key-filterable? } | `boolean` | `true` | Whether or not the attribute can be referenced in filters. |
@ -991,7 +991,7 @@ argument :password_confirmation, :string
| [`constraints`](#actions-action-argument-constraints){: #actions-action-argument-constraints } | `keyword` | `[]` | Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md). |
| [`allow_nil?`](#actions-action-argument-allow_nil?){: #actions-action-argument-allow_nil? } | `boolean` | `true` | Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised. |
| [`public?`](#actions-action-argument-public?){: #actions-action-argument-public? } | `boolean` | `true` | Whether or not the argument should appear in public interfaces |
| [`sensitive?`](#actions-action-argument-sensitive?){: #actions-action-argument-sensitive? } | `boolean` | `false` | Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more. |
| [`sensitive?`](#actions-action-argument-sensitive?){: #actions-action-argument-sensitive? } | `boolean` | `false` | Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security/sensitive-data.md) for more. |
| [`default`](#actions-action-argument-default){: #actions-action-argument-default } | `any` | | The default value for the argument to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value |
@ -1184,7 +1184,7 @@ argument :password_confirmation, :string
| [`constraints`](#actions-create-argument-constraints){: #actions-create-argument-constraints } | `keyword` | `[]` | Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md). |
| [`allow_nil?`](#actions-create-argument-allow_nil?){: #actions-create-argument-allow_nil? } | `boolean` | `true` | Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised. |
| [`public?`](#actions-create-argument-public?){: #actions-create-argument-public? } | `boolean` | `true` | Whether or not the argument should appear in public interfaces |
| [`sensitive?`](#actions-create-argument-sensitive?){: #actions-create-argument-sensitive? } | `boolean` | `false` | Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more. |
| [`sensitive?`](#actions-create-argument-sensitive?){: #actions-create-argument-sensitive? } | `boolean` | `false` | Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security/sensitive-data.md) for more. |
| [`default`](#actions-create-argument-default){: #actions-create-argument-default } | `any` | | The default value for the argument to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value |
@ -1329,7 +1329,7 @@ argument :password_confirmation, :string
| [`constraints`](#actions-read-argument-constraints){: #actions-read-argument-constraints } | `keyword` | `[]` | Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md). |
| [`allow_nil?`](#actions-read-argument-allow_nil?){: #actions-read-argument-allow_nil? } | `boolean` | `true` | Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised. |
| [`public?`](#actions-read-argument-public?){: #actions-read-argument-public? } | `boolean` | `true` | Whether or not the argument should appear in public interfaces |
| [`sensitive?`](#actions-read-argument-sensitive?){: #actions-read-argument-sensitive? } | `boolean` | `false` | Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more. |
| [`sensitive?`](#actions-read-argument-sensitive?){: #actions-read-argument-sensitive? } | `boolean` | `false` | Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security/sensitive-data.md) for more. |
| [`default`](#actions-read-argument-default){: #actions-read-argument-default } | `any` | | The default value for the argument to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value |
@ -1711,7 +1711,7 @@ argument :password_confirmation, :string
| [`constraints`](#actions-update-argument-constraints){: #actions-update-argument-constraints } | `keyword` | `[]` | Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md). |
| [`allow_nil?`](#actions-update-argument-allow_nil?){: #actions-update-argument-allow_nil? } | `boolean` | `true` | Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised. |
| [`public?`](#actions-update-argument-public?){: #actions-update-argument-public? } | `boolean` | `true` | Whether or not the argument should appear in public interfaces |
| [`sensitive?`](#actions-update-argument-sensitive?){: #actions-update-argument-sensitive? } | `boolean` | `false` | Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more. |
| [`sensitive?`](#actions-update-argument-sensitive?){: #actions-update-argument-sensitive? } | `boolean` | `false` | Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security/sensitive-data.md) for more. |
| [`default`](#actions-update-argument-default){: #actions-update-argument-default } | `any` | | The default value for the argument to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value |
@ -1951,7 +1951,7 @@ argument :password_confirmation, :string
| [`constraints`](#actions-destroy-argument-constraints){: #actions-destroy-argument-constraints } | `keyword` | `[]` | Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md). |
| [`allow_nil?`](#actions-destroy-argument-allow_nil?){: #actions-destroy-argument-allow_nil? } | `boolean` | `true` | Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised. |
| [`public?`](#actions-destroy-argument-public?){: #actions-destroy-argument-public? } | `boolean` | `true` | Whether or not the argument should appear in public interfaces |
| [`sensitive?`](#actions-destroy-argument-sensitive?){: #actions-destroy-argument-sensitive? } | `boolean` | `false` | Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more. |
| [`sensitive?`](#actions-destroy-argument-sensitive?){: #actions-destroy-argument-sensitive? } | `boolean` | `false` | Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security/sensitive-data.md) for more. |
| [`default`](#actions-destroy-argument-default){: #actions-destroy-argument-default } | `any` | | The default value for the argument to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value |

4
documentation/home.md
View file

@ -33,6 +33,10 @@ Welcome to the Ash Framework documentation! Here you will find everything you ne
- [Glossary](documentation/topics/glossary.md)
### Security
- [Actors & Authorization](documentation/topics/security/actors-and-authorization.md)
### Development
- [Development Utilities](documentation/topics/development/development-utilities.md)

10
documentation/topics/glossary.md
View file

@ -19,7 +19,7 @@ The entity that performs an action. Most actions are run on direct user request,
Actors can be used in a number of places, from modifying the behavior of an action to auditing who did what in your system. They are most prominent, however, when writing [policies](#policy).
See the [Security guide](/documentation/topics/security.md#actors) for more.
See the [Actors & Authorization guide](/documentation/topics/security/actors-and-authorization.md) for more.
## Aggregate
@ -41,6 +41,12 @@ A piece of data belonging to a resource. The most basic building block; an attri
See the [Attributes guide](/documentation/topics/attributes.md) for more.
## Authorizer
An authorizer is an extension that can be added to a resource that will be given the opportunity to modify and/or prevent requests to a resource. In practice, you will almost always be using `Ash.Policy.Authorizer`, but you can still write your own if you need to.
See the [Actors & Authorization](documentation/topics/security/actors-and-authorization.md) and [Policies](documentation/topics/security/policies.md) guides for more.
## Calculation
A calculation is a special type of field for a resource, one that is not directly stored in the data layer but generated on-demand. Typically it will derive from other information on the record, but it may come from some other data source entirely.
@ -89,7 +95,7 @@ A set of rules defining who is authorized to perform specific actions on a resou
- Forbidding anyone other than the user who wrote a blog post, from editing it
- Allowing only admins to update site-wide settings
See the [Policies guide](/documentation/topics/policies.md) for more.
See the [Policies guide](/documentation/topics/security/policies.md) for more.
## Query

74
documentation/topics/security.md
View file

@ -1,74 +0,0 @@
# Security
## Authorization Configuration
### `d:Ash.Domain.Dsl.authorization|require_actor?`
Requires that an actor is set for all requests.
Important: `nil` is still a valid actor, so this won't prevent providing `actor: nil`.
### `d:Ash.Domain.Dsl.authorization|authorize`
When to run authorization for a given request.
- `:by_default` sets `authorize?: true` if the `authorize?` option was not set (so it can be set to `false`). This is the default.
- `:always` forces `authorize?: true` on all requests to the domain.
- `:when_requested` sets `authorize?: true` whenever an actor is set or `authorize?: true` is explicitly passed. This is the default behavior.
## Sensitive Attributes
Using `sensitive? true` will cause the argument to be `** Redacted **` from the resource when logging or inspecting. In filter statements, any value used in the same expression as a sensitive attribute will also be redacted. For example, you might see: `email == "** Redacted **"` in a filter statement if `email` is marked as sensitive.
## Authorization
Authorization in Ash is done via authorizers. Generally, you won't need to create your own authorizer, as the builtin policy authorizer `Ash.Policy.Authorizer` should work well for any use case. Authorization is performed with a given actor and a query or changeset.
### Actors
An actor is the "entity performing the action". This is generally a user, but could potentially be an organization, a group, whatever makes sense for your use case. By default, when using Ash in code, authorization does not happen.
```elixir
# Does not perform authorization
Ash.read!(User)
```
However, if you either 1. provide an actor or 2. use the `authorize?: true` option, then authorization will happen.
```elixir
# Authorize with a `nil` actor (which is valid, i.e if no one is logged in and they are trying to list users)
Ash.read!(User, actor: nil)
# Authorize with a `nil` actor
Ash.read!(User, authorize?: true)
# Authorize with an actor
Ash.read!(User, actor: current_user)
# Authorize with an actor, but being explicit
Ash.read!(User, actor: current_user, authorize?: true)
# Skip authorization, but set an actor. The actor can be used in other things than authorization
# so this may make sense depending on what you are doing.
Ash.read!(User, actor: current_user, authorize?: false)
```
#### Where to set the actor
When setting an actor, if you are building a query or changeset, you should do so at the time that you call the various `for_*` functions. This makes the actor available in the context of any change that is run. For example:
```elixir
# DO THIS
Resource
|> Ash.Query.for_read(:read, input, actor: current_user)
|> Ash.read()
# DON'T DO THIS
Resource
|> Ash.Query.for_read(:read, input)
|> Ash.read(actor: current_user)
```
The second option "works" in most cases, but not all, because some `change`s might need to know the actor and will instead get `nil`.

70
documentation/topics/security/actors-and-authorization.md Normal file
View file

@ -0,0 +1,70 @@
# Actors & Authorization
Authorization in Ash involves three things:
* actor - the entity (i.e user, organization, device) performing a given action
* authorize? - a flag that tells Ash to run authorization.
* authorizers - the extensions on a resource that can modify or forbid the action.
## Setting `actor` and `authorize?`
All functions in Ash that may perform authorization and/or wish to use the actor accept an `actor` and an `authorize?` option. For example:
Building a changeset/query/input is the best time to provide the actor option
```elixir
Ash.Changeset.for_create(Post, %{title: "Post Title"}, actor: current_user, authorize?: true)
```
If calling a function without changeset/query/input, you can provide the `actor` option at that point.
```elixir
Ash.count!(Post, actor: current_user, authorize?: true)
```
Functions created with the code interface also accept an `actor` option.
```elixir
MyDomain.create_post!(Post, authorize?: true)
```
> ### Set the actor on the query/changeset/input {: .warning}
> The hooks on a query/changeset/input to an action may need to know the actor, so you
> need to set the actor when building them, not when calling the action.
> ```elixir
> # DO THIS
>
> Post
> |> Ash.Query.for_read(:read, actor: current_user)
> |> Ash.read!()
>
> # DON'T DO THIS
>
> Post
> |> Ash.Query.for_read!(:read)
> |> Ash.read!(actor: current_user)
> ```
## Default value of `authorize?`
The default value of `authorize?` is determined by by the `authorization` configuration of the relevant domain. By default, `authorize?` is set to `true` (and so can be ommitted in all of the examples above). If a resource has no authorizers, then all requests will be allowed.
## Authorizers
Authorizers are in control of what happens during authorization. Generally, you won't need to create your own authorizer, as the builtin policy authorizer `Ash.Policy.Authorizer` works well for any use case. See the [Policies guide](documentation/topics/security/policies.md) for more.
## Domain Authorization Configuration
### `d:Ash.Domain.Dsl.authorization|require_actor?`
Requires that an actor is set for all requests.
Important: `nil` is still a valid actor, so this won't prevent providing `actor: nil`. It only requires that the option itself is provided.
### `d:Ash.Domain.Dsl.authorization|authorize`
When to run authorization for a given request.
- `:by_default` sets `authorize?: true` if the `authorize?` option was not set (so it can be set to `false`). This is the default.
- `:always` forces `authorize?: true` on all requests to the domain.
- `:when_requested` sets `authorize?: true` whenever an actor is set or `authorize?: true` is explicitly passed. This is the default behavior.

2
documentation/topics/policies.md → documentation/topics/security/policies.md
View file

@ -4,7 +4,7 @@ Policies determine what actions on a resource are permitted for a given actor, a
To restrict access to specific fields (attributes, aggregates, calculations), the section on field policies.
Read and understand the [Security](/documentation/topics/security.md) guide before proceeding, which explains actors, how to set them, and other relevant configurations.
Read and understand the [Actors & Authorization guide](/documentation/topics/security/actors-and-authorization.md) before proceeding, which explains actors, how to set them, and other relevant configurations.
## Setup

17
documentation/topics/security/sensitive-data.md Normal file
View file

@ -0,0 +1,17 @@
# Sensitive Data
## Public & Private Attributes
By default, attributes, calculations, aggregates and relationships are *private* (they are marked `public?: false`). If you are working with Ash in code, the public/private status of an attribute is not relevant. However, when working with api extensions like `AshGraphql` and `AshJsonApi`, they will only include public fields in their interfaces. This helps avoid accidentally exposing data over "public" interfaces.
## Public & Private Arguments
Public/private arguments work the same way as public/private fields, except that they default to `public?: true`. This is because arguments to an action being usedin a public interface would naturally be expected to be `public`. If an argument is marked as `public?: false`, it can only be set with `Ash.Query.set_argument/3` or `Ash.Changeset.set_argument/3`
## Sensitive Attributes
Using `sensitive? true` will cause an attribute, calculation or argument to show as `"** Redacted **"` when inspecting records. In filter statements, any value used in the same expression as a sensitive field will also be redacted. For example, you might see: `email == "** Redacted **"` in a filter statement if `email` is marked as sensitive.
## Field Policies
Field policies are a way to control the visibility of individual fields (except for relationships) as a part of authorization flow, for those using `Ash.Policy.Authorizer`. If a field is not visible, it will be populated with `%Ash.ForbiddenField{}`, or will be not shown (or may show an error) in public interfaces. See the [Policies guide](documentation/topics/security/policies.md#field-policies) for more.

2
documentation/tutorials/get-started.md
View file

@ -605,7 +605,7 @@ Check out [AshJsonApi](https://hexdocs.pm/ash_json_api) and [AshGraphql](https:
#### Authorize access and work with users
See the [Policies guide](/documentation/topics/policies.md) for information on how to authorize access to your resources using actors and policies.
See the [Policies guide](/documentation/topics/security/policies.md) for information on how to authorize access to your resources using actors and policies.
#### Clean up your code that uses Ash?

2
lib/ash/domain/dsl.ex
View file

@ -51,7 +51,7 @@ defmodule Ash.Domain.Dsl do
@authorization %Spark.Dsl.Section{
name: :authorization,
describe: """
Options for how requests are authorized using this domain. See the [security guide](/documentation/topics/security.md) for more.
Options for how requests are authorized using this domain. See the [Sensitive Data guide](/documentation/topics/security/sensitive-data.md) for more.
""",
examples: [
"""

6
lib/ash/policy/authorizer/authorizer.ex
View file

@ -134,7 +134,7 @@ defmodule Ash.Policy.Authorizer do
end
```
See the [policies guide](/documentation/topics/policies.md) for more.
See the [policies guide](/documentation/topics/security/policies.md) for more.
""",
schema: [
description: [
@ -184,7 +184,7 @@ defmodule Ash.Policy.Authorizer do
Each policy that applies must pass independently in order for the
request to be authorized.
See the [policies guide](/documentation/topics/policies.md) for more.
See the [policies guide](/documentation/topics/security/policies.md) for more.
""",
examples: [
"""
@ -355,7 +355,7 @@ defmodule Ash.Policy.Authorizer do
For reads, policies can be configured to filter out data that the actor shouldn't see, as opposed to
resulting in a forbidden error.
See the [policies guide](/documentation/topics/policies.md) for practical examples.
See the [policies guide](/documentation/topics/security/policies.md) for practical examples.
Policies are solved/managed via a boolean satisfiability solver. To read more about boolean satisfiability,
see this page: https://en.wikipedia.org/wiki/Boolean_satisfiability_problem. At the end of

2
lib/ash/resource/actions/argument.ex
View file

@ -54,7 +54,7 @@ defmodule Ash.Resource.Actions.Argument do
type: :boolean,
default: false,
doc: """
Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more.
Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security/sensitive-data.md) for more.
"""
],
default: [

4
lib/ash/resource/attribute.ex
View file

@ -70,7 +70,7 @@ defmodule Ash.Resource.Attribute do
type: :boolean,
default: false,
doc: """
Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more.
Whether or not the attribute value contains sensitive information, like PII. See the [Sensitive Data guide](/documentation/topics/security/sensitive-data.md) for more.
"""
],
source: [
@ -118,7 +118,7 @@ defmodule Ash.Resource.Attribute do
type: :boolean,
default: false,
doc: """
Whether or not the attribute should be shown over public interfaces. See the [security guide](/documentation/topics/security.md) for more.
Whether or not the attribute should be shown over public interfaces. See the [sensitive data guide](/documentation/topics/security/sensitive-data.md) for more.
"""
],
default: [

12
mix.exs
View file

@ -48,6 +48,8 @@ defmodule Ash.MixProject do
"documentation/topics/about_ash/contributing-to-ash.md",
"documentation/topics/development/development-utilities.md",
"documentation/topics/development/upgrading-to-3.0.md",
"documentation/topics/security/actors-and-authorization.md",
"documentation/topics/security/sensitive-data.md",
"CHANGELOG.md",
"documentation/how_to/define-idiomatic-actions.md",
"documentation/how_to/defining-manual-relationships.md",
@ -75,11 +77,10 @@ defmodule Ash.MixProject do
"documentation/topics/multitenancy.md",
"documentation/topics/notifiers.md",
"documentation/topics/pagination.md",
"documentation/topics/policies.md",
"documentation/topics/security/policies.md",
"documentation/topics/pub_sub.md",
"documentation/topics/reactor.md",
"documentation/topics/relationships.md",
"documentation/topics/security.md",
"documentation/topics/testing.md",
"documentation/topics/timeouts.md",
"documentation/topics/validations.md",
@ -101,6 +102,11 @@ defmodule Ash.MixProject do
Topics: [
"documentation/topics/glossary.md"
],
"Security": [
"documentation/topics/security/actors-and-authorization.md",
"documentation/topics/security/policies.md",
"documentation/topics/security/sensitive-data.md",
],
"Development": [
"documentation/topics/development/development-utilities.md",
"documentation/topics/development/upgrading-to-3.0.md"
@ -150,11 +156,9 @@ defmodule Ash.MixProject do
"documentation/topics/multitenancy.md",
"documentation/topics/notifiers.md",
"documentation/topics/pagination.md",
"documentation/topics/policies.md",
"documentation/topics/pub_sub.md",
"documentation/topics/reactor.md",
"documentation/topics/relationships.md",
"documentation/topics/security.md",
"documentation/topics/testing.md",
"documentation/topics/timeouts.md",
"documentation/topics/validations.md"