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>

Patches the specified capability based on the representation in the request body.

Capability Summary

application/vnd.sas.authorization.capability.summary

The partial representation of a capability.

ETag header. If the ETag does not match, the update will fail.

If-Match

The respresentation to use for the returned capabilities.

Accept

capabilityName

An example of using a known capability name to obtain the capability.

ETag

Error

Forbidden. The user does not have the required sas.capability.create capability.

The specified capability representation cannot be processed.

Update an existing capability

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

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

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	OK	Headers	Schema
400	Bad Request	The request was invalid.		Schema
403	Forbidden	Forbidden. The user does not have the required sas.capability.create capability.		Schema
412	Precondition Failed	Precondition failed		Schema
422	Unprocessable Entity	The specified capability representation cannot be processed.		Schema
428	Precondition Required	Precondition required		Schema

Update an existing capability

Request Samples

Response Samples

Path Parameters

Header Parameters

Request Body

Responses

Name	Type	Required	Description
Accept	string	false	The respresentation to use for the returned capabilities. Allowed values: application/vnd.sas.authorization.capability.summaryapplication/vnd.sas.authorization.capability.summary;version=1application/vnd.sas.authorization.capability.summary;version=2 Default: application/vnd.sas.authorization.capability.summary;version=2
If-Match	string	false	ETag header. If the ETag does not match, the update will fail.

Name	Type	Required	Description
id	string	false	The system-assigned unique ID for this capability.
name	string	true	The full stop separated name for this capability e.g. sas.document.edit
description	string	true	The description of the capability
product	string	false	The product associated with the capability.
version	integer<int32>	false	The schema version for the capability.
links	array [Link]	false	Zero or more link objects relevant to the capability.