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>

Determines which actions a specified principal is authorized to perform in a specified context. Each requested action is evaluated against its associated permission. Granted and prohibited actions are returned in separate lists.

An example of using relevant authorization context, as well as a map of permissions to an array of links, to create a bulk authorization decision.

An example of using relevant authorization context, as well as a map of permissions to an array of parameterized links, to create a bulk authorization decision.

Create a Bulk Authorization Decision using parameterized links

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

The requested actions and contextual details. Bulk information must be included as a map of permissions to arrays of links. These maps must be provided in the bulkLinks or parameterizedLinks members as appropriate for the request. Use of bulkLinks and parameterizedLinks in a single request is supported.
Note: Each of the links provided in the request must identify the resource by populating the uri member of the link. The href member is not used.

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

Content-Type

Location

The request was invalid. Returned if no URIs are provided in the context to authorize.

Obtain multiple authorization decisions

Error

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

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

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

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

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.	Headers	Schema
400	Bad Request	The request was invalid. Returned if no URIs are provided in the context to authorize.

Obtain multiple authorization decisions

Request Samples

Response Samples

Request Body

Responses

Name	Type	Required	Description
bulkLinks	Permissions to Links	false	A map of permissions to link arrays. The keys of this map are the permissions that the link values are authorized for.
parameterizedLinks	Permissions to Parameterized Links	false	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.
request	Authorization Context Request	false	A description of the HTTP request that is associated with an authorization request.
principals	array [Principal]	false	The set of principals representing the actor performing the action.
permission	string	false	A type of access. Allowed values: addcreatedeletereadremovesecureupdate
parameters	object	false	A map of keys to objects that represent the parameters and return object of a method being invoked. This can be null or empty.
matchParams	boolean	false	Whether the authorization service should strictly match query parameters in this context against a rule. Default: false
eachNamed	object	false	Map of parameter names to a new name that should be used in rule condition evaluation for collections. For example, if a parameter being used for evaluation is a collection named 'items', then eachNamed can map 'items' to 'item' so that item in the collection can be evaluated independently against a rule that references the '#item' variable.
version	integer<int32>	false	The authorization context's media type version. The version described here is version 1.