RestApiCategories.platformAdministration.desc

platform_administration

2024.03

2023.10

2024.10

2024.11

2024.09

2024.08

2024.12

Manages authorization rules and makes authorization decisions. <details> <summary>Overview:</summary> The Authorization API encapsulates all activities that affect access to system functions and resources. This is a summary of the functional scope of this API: <ul> <li>This API enables authorized users to define access by creating and managing authorization rules and shares.</li> <li>This API enables any principal that has the Secure permission for a particular object to create and manage authorization rules that directly target that object.</li> <li>This API enables any principal that has the Secure permission for a particular object to share that object. If re-sharing is enabled, each share recipient can extend the access that they receive to other users and groups.</li> <li>This API enforces authorization rules by making authorization decisions. Each decision is evaluated for a specific authorization context. The decision process is transparent to end users.</li> <li>This API enables authorized principals to define capabilities that create a role based authorization model.</li> <li>This API explains its authorization decisions by listing all of the rules and shares that contribute to each decision.</li> <li>This API does not manage access to CAS data (caslibs and tables) or CAS actions.</li> </ul> </details> <details> <summary>Security</summary> The Authorization API automatically protects any endpoints of any API that includes dependencies on it. This dependency intercepts calls to the endpoints and builds an authorization context, which is then sent to the Authorization API for evaluation. If the context is granted permission to perform the request action on that endpoint, it returns an HTTP status code of 200 and allows the request to proceed. If the context is prohibited, it returns an HTTP status code of 403 and the request does not continue further. This access is controlled by authorization rules that can be created through bootstrapping, by an administrative user, or by other methods. </details> <details> <summary>Terminology:</summary> <ul> <li>authorization: the process by which a set of principals is evaluated against defined rules and a requested action to determine whether the user can perform the action.</li> <li>authorization context: information about an authorization request (for example, a target URI, the HTTP headers and verb, the requestor's group memberships, or the time of the request).</li> <li>condition: a logical Spring Expression Language (SpEL) expression that evaluates to either true or false. A rule that includes a condition applies only when the condition is true. For example, you can use a condition to make a rule applicable to only to the creator of an object.</li> <li>container: an object that logically contains the URI of one or more member objects. In parent-child relationship between objects, a container represents a parent.</li> <li>decision: a yes or no answer to an authorization request to perform a particular action. Each authorization decision is based on a specific authorization context.</li> <li>permission: a specific action that a rule affects (for example read, update, delete, create, secure, add, or remove).</li> <li>principal: an entity that represents an individual user or a group.</li> <li>rule: an action or set of actions that is either permitted or prohibited for a given principal or set of principals. A rule can include a condition that limits the circumstances under which the rule applies.</li> <li>share: a simplified abstraction of an authorization rule. Each share identifies a target object (resource), a recipient (principal), and a level of access (type). Each share is backed by a corresponding authorization rule. Shares can help users easily make resources available to each other.</li> <li>capability: an association between a principal and a collection of authorization rules, providing the ability to grant role based access control (RBAC) for various actions.</li> </ul> </details> <details> <summary>API Version</summary> This is version 8 of the Authorization API. Changes since version 7 <ul> <li>Added product to capability media types</li> </ul> Changes since version 6 <ul> <li>Added parameterizedLinks for bulk decisions</li> </ul> Changes since version 5 <ul> <li>Added capabilities endpoints</li> </ul> Changes since version 4 <ul> <li>Added the 'enabled' flag to the share media type</li> </ul> Changes since version 3 <ul> <li>Added sharing endpoints</li> <li>Added media type matching flags for explanation endpoints</li> <li>Added includeShares flag for explanation endpoints</li> </ul> </details> <details> <summary>Error Codes</summary> <table> <tr> <th>HTTP Status Code</th> <th>Error Code</th> <th>Description</th> </tr> <tr> <td>400</td> <td>12600</td> <td>The patch 'test' operation failed.</td> </tr> <tr> <td>400</td> <td>12601</td> <td>Attempt to parse expression failed.</td> </tr> <tr> <td>400</td> <td>12700</td> <td>Request cannot be satisfied because sharing is disabled. </td> </tr> <tr> <td>500</td> <td>12800</td> <td>Cannot retrieve group membership info for group. </td> </tr> <tr> <td>500</td> <td>12801</td> <td>Cannot retrieve group membership info for user. </td> </tr> <tr> <td>404</td> <td>12802</td> <td>Capability could not be found.</td> </tr> <tr> <td>400</td> <td>12803</td> <td>Cannot assign principal to capability because principal is not a group.</td> </tr> <tr> <td>400</td> <td>12804</td> <td>Request has mismatched capability name.</td> </tr> <tr> <td>400</td> <td>12805</td> <td>Request includes an unsupported principal type.</td> </tr> <tr> <td>500</td> <td>12806</td> <td>Unable to convert authorization rule to capability.</td> </tr> <tr> <td>404</td> <td>12807</td> <td>Request to remove non-existent authorization rule.</td> </tr> <tr> <td>400</td> <td>12808</td> <td>Request to remove non-existent group.</td> </tr> <tr> <td>500</td> <td>12809</td> <td>Request from an unrecognized user ID.</td> </tr> <tr> <td>403</td> <td>12810</td> <td>Illegal attempt to elevate own permissions.</td> </tr> <tr> <td>415</td> <td>12811</td> <td>The Accept Item header sprecified an unsupported media type.</td> </tr> <tr> <td>428</td> <td>12812</td> <td>The request is missing the If-Match header.</td> </tr> <tr> <td>428</td> <td>12813</td> <td>The ETag is out-of-date.</td> </tr> </table> </details>

Authorization

2023.03

Manages authorization rules and makes authorization decisions. <details> <summary>Overview:</summary> The Authorization API encapsulates all activities that affect access to system functions and resources. This is a summary of the functional scope of this API: <ul> <li>This API enables authorized users to define access by creating and managing authorization rules and shares.</li> <li>This API enables any principal that has the Secure permission for a particular object to create and manage authorization rules that directly target that object.</li> <li>This API enables any principal that has the Secure permission for a particular object to share that object. If re-sharing is enabled, each share recipient can extend the access that they receive to other users and groups.</li> <li>This API enforces authorization rules by making authorization decisions. Each decision is evaluated for a specific authorization context. The decision process is transparent to end users.</li> <li>This API enables authorized principals to define capabilities that create a role based authorization model.</li> <li>This API explains its authorization decisions by listing all of the rules and shares that contribute to each decision.</li> <li>This API does not manage access to CAS data (caslibs and tables) or CAS actions.</li> </ul> </details> <details> <summary>Security</summary> The Authorization API automatically protects any endpoints of any API that includes dependencies on it. This dependency intercepts calls to the endpoints and builds an authorization context, which is then sent to the Authorization API for evaluation. If the context is granted permission to perform the request action on that endpoint, it returns an HTTP status code of 200 and allows the request to proceed. If the context is prohibited, it returns an HTTP status code of 403 and the request does not continue further. This access is controlled by authorization rules that can be created through bootstrapping, by an administrative user, or by other methods. </details> <details> <summary>Terminology:</summary> <ul> <li>authorization: the process by which a set of principals is evaluated against defined rules and a requested action to determine whether the user can perform the action.</li> <li>authorization context: information about an authorization request (for example, a target URI, the HTTP headers and verb, the requestor's group memberships, or the time of the request).</li> <li>condition: a logical Spring Expression Language (SpEL) expression that evaluates to either true or false. A rule that includes a condition applies only when the condition is true. For example, you can use a condition to make a rule applicable to only to the creator of an object.</li> <li>container: an object that logically contains the URI of one or more member objects. In parent-child relationship between objects, a container represents a parent.</li> <li>decision: a yes or no answer to an authorization request to perform a particular action. Each authorization decision is based on a specific authorization context.</li> <li>permission: a specific action that a rule affects (for example read, update, delete, create, secure, add, or remove).</li> <li>principal: an entity that represents an individual user or a group.</li> <li>rule: an action or set of actions that is either permitted or prohibited for a given principal or set of principals. A rule can include a condition that limits the circumstances under which the rule applies.</li> <li>share: a simplified abstraction of an authorization rule. Each share identifies a target object (resource), a recipient (principal), and a level of access (type). Each share is backed by a corresponding authorization rule. Shares can help users easily make resources available to each other.</li> <li>capability: an association between a principal and a collection of authorization rules, providing the ability to grant role based access control (RBAC) for various actions.</li> </ul> </details> <details> <summary>API Version</summary> This is version 6 of the Authorization API. Changes since version 5 <ul> <li>Added capabilities endpoints</li> </ul> Changes since version 4 <ul> <li>Added the 'enabled' flag to the share media type</li> </ul> Changes since version 3 <ul> <li>Added sharing endpoints</li> <li>Added media type matching flags for explanation endpoints</li> <li>Added includeShares flag for explanation endpoints</li> </ul> </details> <details> <summary>Error Codes</summary> <table> <tr> <th>HTTP Status Code</th> <th>Error Code</th> <th>Description</th> </tr> <tr> <td>400</td> <td>12600</td> <td>The patch 'test' operation failed.</td> </tr> <tr> <td>400</td> <td>12601</td> <td>Attempt to parse expression failed.</td> </tr> <tr> <td>400</td> <td>12700</td> <td>Request cannot be satisfied because sharing is disabled. </td> </tr> <tr> <td>500</td> <td>12800</td> <td>Cannot retrieve group membership info for group. </td> </tr> <tr> <td>500</td> <td>12801</td> <td>Cannot retrieve group membership info for user. </td> </tr> <tr> <td>404</td> <td>12802</td> <td>Capability could not be found.</td> </tr> <tr> <td>400</td> <td>12803</td> <td>Cannot assign principal to capability because principal is not a group.</td> </tr> <tr> <td>400</td> <td>12804</td> <td>Request has mismatched capability name.</td> </tr> <tr> <td>400</td> <td>12805</td> <td>Request includes an unsupported principal type.</td> </tr> <tr> <td>500</td> <td>12806</td> <td>Unable to convert authorization rule to capability.</td> </tr> <tr> <td>404</td> <td>12807</td> <td>Request to remove non-existent authorization rule.</td> </tr> <tr> <td>400</td> <td>12808</td> <td>Request to remove non-existent group.</td> </tr> <tr> <td>500</td> <td>12809</td> <td>Request from an unrecognized user ID.</td> </tr> <tr> <td>403</td> <td>12810</td> <td>Illegal attempt to elevate own permissions.</td> </tr> <tr> <td>415</td> <td>12811</td> <td>The Accept Item header sprecified an unsupported media type.</td> </tr> <tr> <td>428</td> <td>12812</td> <td>The request is missing the If-Match header.</td> </tr> <tr> <td>428</td> <td>12813</td> <td>The ETag is out-of-date.</td> </tr> </table> </details>

Viya_35

Manages authorization rules and makes authorization decisions. <details> <summary>Overview:</summary> The Authorization API encapsulates all activities that affect access to system functions and resources. Here is a summary of the functional scope of this API: <ul> <li>This API enables authorized users to define access by creating and managing authorization rules.</li> <li>This API enables any principal that has the Secure permission for a particular object to create and manage authorization rules that directly target that object.</li> <li>This API enforces authorization rules by making authorization decisions. Each decision is evaluated for a specific authorization context. The decision process is transparent to end users.</li> <li>This API explains its authorization decisions by listing all of the rules that contribute to each decision.</li> <li>This API does not manage access to CAS data (caslibs and tables) or CAS actions.</li> </ul> </details> <details> <summary>Security</summary> The Authorization API automatically protects any endpoints of any API that includes dependencies on it. This dependency intercepts calls to the endpoints and builds an authorization context, which is then sent to the Authorization API for evaluation. If the context is granted permission to perform the request action on that endpoint, it returns an HTTP status code of 200 and allows the request to proceed. If the context is prohibited, it returns an HTTP status code of 403 and the request does not continue further. This access is controlled by authorization rules that can be created through bootstrapping, by an administrative user, or by other methods. </details> <details> <summary>Terminology:</summary> <ul> <li>authorization: the process by which a set of principals is evaluated against defined rules and a requested action to determine whether the user can perform the action.</li> <li>authorization context: information about an authorization request (for example, a target URI, the HTTP headers and verb, the requestor's group memberships, or the time of the request).</li> <li>condition: a logical Spring Expression Language (SpEL) expression that evaluates to either true or false. A rule that includes a condition applies only when the condition is true. For example, you can use a condition to make a rule applicable to only to the creator of an object.</li> <li>container: an object that logically contains the URI of one or more member objects. In parent-child relationship between objects, a container represents a parent.</li> <li>decision: a yes or no answer to an authorization request to perform a particular action. Each authorization decision is based on a specific authorization context.</li> <li>permission: a specific action that a rule affects (for example read, update, delete, create, secure, add, or remove).</li> <li>principal: an entity that represents an individual user or a group.</li> <li>rule: an action or set of actions that is either permitted or prohibited for a given principal or set of principals. A rule can include a condition that limits the circumstances under which the rule applies.</li> </ul> </details> <details> <summary>API Version</summary> This is version 3 of the Authorization API. </details> <details> <summary>Error Codes</summary> <table> <tr> <th>HTTP Status Code</th> <th>Error Code</th> <th>Description</th> </tr> <tr> <td>400</td> <td>12600</td> <td>The patch 'test' operation failed.</td> </tr> <tr> <td>400</td> <td>12601</td> <td>Attempt to parse expression failed.</td> </tr> <tr> <td>400</td> <td>12700</td> <td>Request cannot be satisfied because sharing is disabled. </td> </tr> <tr> <td>500</td> <td>12800</td> <td>Cannot retrieve group membership info for group. </td> </tr> <tr> <td>500</td> <td>12801</td> <td>Cannot retrieve group membership info for user. </td> </tr> <tr> <td>400</td> <td>12805</td> <td>Request includes an unsupported principal type.</td> </tr> <tr> <td>404</td> <td>12807</td> <td>Request to remove non-existent authorization rule.</td> </tr> <tr> <td>400</td> <td>12808</td> <td>Request to remove non-existent group.</td> </tr> <tr> <td>500</td> <td>12809</td> <td>Request from an unrecognized user ID.</td> </tr> <tr> <td>403</td> <td>12810</td> <td>Illegal attempt to elevate own permissions.</td> </tr> <tr> <td>415</td> <td>12811</td> <td>The Accept Item header sprecified an unsupported media type.</td> </tr> <tr> <td>428</td> <td>12812</td> <td>The request is missing the If-Match header.</td> </tr> <tr> <td>428</td> <td>12813</td> <td>The ETag is out-of-date.</td> </tr> </table> </details>

Performs a set of rule management actions as specified in a JSON patch. The actions are performed synchronously and transactionally. A resource collection of all created and revised rules is returned. If the patch is not successfully applied, changes are rolled back.

  For every action, the patch must specify an operation (add, replace, remove,
test, or copy) and a target URI (for example, /authorization/rules/{ruleId} or, to create a new rule, /authorization/rules). Each add and replace operation requires a valid rule representation. Each copy operation requires a 'from' URI that identifies the original rule.

  You cannot save duplicate rules, so a patch that includes a copy operation
must also include an operation that modifies or deletes either the original rule or the new rule.

  You can combine operations to migrate existing rules. For example, you might
copy a rule, then update the new rule (using the 'replace' operation), and then delete the original rule.

  New rules that do not yet have known rule IDs are added to a zero-indexed
ordered list. To reference such rules, use the substitution token @CREATED#@ (where '#' is the index of the target rule).

Array of patch operations to apply to the existing rules.

JSON patch describing operations to perform and identifying the target rules.

An example of using a condition to set permissions and the objectUri for a defined rule. The key data in this example are the following <ul> <li>The condition is named 'test'.</li> <li>The condition indicates the existing rule must have type=grant, permissions=[read,update], objectUri=/identities/**, and principalType=authenticated-users.</li> </ul> If all of these values match, the patch is applied and the following is set: <ul> <li>The permissions are set to Read, Update, Delete, and Secure.</li> <li>The objectUri is set to '/identities/*'.</li> </ul> If any of these values do not match, the patch is not applied.

Patch a Collection of Rules Using a Condition

An example of using a combination of defined JSON patch operations to migrate existing rules. <ul> <li>The `copy` operation copies the existing rule and any changes that might have been applied to it.</li> <li>The `add` or `replace` operation updates the target rule.</li> <li>The `remove` operation must delete either the original rule or the new rule.</li> <ul> To target a rule that does not have a known ID, use the simple token substitution system that this API provides. In a single patch, each new rule that is created by an `add` or `copy` operation is added to a zero-indexed, ordered list. Note: An `add` operation can be either a create or an update, depending on whether a rule with the given ID already exists. A rule that is updated is not added to the list of created rules. If you know the order in which rules are created within a patch, you can reference any such rule by its index. Use the token @CREATED#@, where '#' is the index of the rule that you are targeting. This example assumes that a rule already exists with ID = 'sourceId' and modifies the rule before removing the source rule.

Migrate Existing Rules with a PATCH Request

Instructions for a set of actions to be performed asynchronously. Consists of a state that describes how the overall asynchronous job is performing and a set of actions to perform on defined rules.

Rule Job

The request succeeded. Returned if the patch was applied successfully.

Error

The request was invalid. Returned if the specified rule patch is invalid.

Returned if the patch request is syntactically valid but would result in a resource state that is inconsistent or invalid.

Patch authorization rules

This is a base schema used to define paginated collections of resources. This base schema is extended by other schemas in APIs by adding an 'items' array property. These extensions define the application/vnd.sas.collection media type (version 2)

baseCollection

A link to a related operation or resource.

Link

A link to a related operation or resource with a map of parameter names to values for use in authorization evaluations.

ParameterizedLink

Selection

The response from a pre-flight validation request. For APIs which support validation, the client can run operations (typically on resources in the `/commons/validation`) with `application/vnd.sas.validation+json` as the requested response type (via the `Accept:` request header). The service will validate the request but not execute the request, and return this response to indicate if the request was valid at the time it was made.

Validation Response

property values that specify how sharing is configured. sas.authorization.share.enabled determines whether sharing is enabled at all in the system while sas.authorization.share.reshare.enabled determines whether users are allowed to grant reshare permission on objects.

Share Properties

An authorization rule that does not have a known ID. The rule has not been saved or the ID is unavailable for some other reason. Compare with SavedAuthorizationRule.

Authorization Rule

Any authorization rule that can be referenced by a unique identifier. This can be a savedAuthorizationRule or an unsaved authorization rule that has a client-specified identifier.

Identifiable Authorization Rule

An authorization rule that has a known rule ID and has been persisted.

Saved Authorization Rule

A collection of saved authorization rules.

Resource Collection of Authorization Rules

Principal

A collection of principals (users and/or groups).

Resource Collection of Principals

Contextual information about an action that a principal is attempting. Represented by media type application/vnd.sas.authorization.context+json.

Authorization Context

An authorization context where the permission field is required

Authorization Context Permission Required

Contextual information about an action that a principal is attempting, including one or more links that should be authorized against a supplied permission. Represented by media type application/vnd.sas.authorization.bulk.context+json.
Note: Use of either bulkLinks or parameterizedLinks is required. Use of both is allowed.

Bulk Authorization Context

A map of permissions to link arrays. The keys of this map are the permissions that the link values are authorized for.

Permissions to Links

A map of permissions to parameterized link arrays. The keys of this map are the permissions that the link values are authorized for.  During authorization of the link the parameters will be added to the list of parameters supplied on the context.  The parameters are used in authorization conditional expressions.  If there is a conflict the parameters specified for the link will override.

Permissions to Parameterized Links

A description of the HTTP request that is associated with an authorization request.

Authorization Context Request

A map of relative URI keys to an array of Explanation values. Each explanation in each array explains authorization decisions for one principal.

Explanations

An explanation of access for one principal.

Explanation

An explanation of access for one principal and permission.

Individual Explanation

An explanation of access for one principal and permission. Includes explanations for permissions conveyed by containing objects.

Permission Explanation

Information about the source or cause of the result. Includes a list of applicable rules, indication of whether any of those rules has a condition, and whether the result is direct (a rule directly targets the defined object and is directly assigned to the defined principal).

Factor

Describes an action to be performed asynchronously on a rule.

Rule Action

An operation to be performed on the defined rule.

Rule Patch Operation

Zero or more links that are to related resources and actions.

Links

Resource Collection of Localized Values

A name-value pair of the form (value: localizedValue).

Localized Value

The result of a bulk authorization request. For each type of link in the request (bulkLinks, parameterizedLinks) two arrays containing the granted and prohibited links will be returned.

Authorized Links

An authorization explanation, using new additional rules that aren't yet persisted in the service

Hypothetical

A share that does not have a known ID or sharedBy value. The share has not been saved or the ID is unavailable for some other reason. Compare with SavedShare.

Share

Any share that can be referenced by a unique identifier and has been persisted.

Saved Share

Resource Collection of Shares

An operation to be performed on the defined share.

Share Patch Operation

Capability summary collection

Capabilties provide an abstraction layer on top of authorization rules, providing the ability to associate users and groups with specific application capabilities, and perform license checks to ensure users are authorized to access various areas of the software

Status	Meaning	Description
200	OK	The request succeeded. Returned if the patch was applied successfully.	Schema
400	Bad Request	The request was invalid. Returned if the specified rule patch is invalid.	Schema
412	Precondition Failed	Precondition failed	Schema
422	Unprocessable Entity	Returned if the patch request is syntactically valid but would result in a resource state that is inconsistent or invalid.	Schema
428	Precondition Required	Precondition required	Schema

Patch authorization rules

Request Samples

Response Samples

Request Body

Responses

Name	Type	Required	Description
value	Authorization Rule	false	An authorization rule that does not have a known ID. The rule has not been saved or the ID is unavailable for some other reason. Compare with SavedAuthorizationRule.
op	string	true	The type of operation to perform on the defined rule. Allowed values: addreplaceremovetestcopy
path	string	true	The URI of the rule.