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 whether a new authorization rule meets completeness and uniqueness requirements.

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

Validate the request but do not execute the request, and return this response to indicate if the request was valid at the time it was made

Determine whether the passed value is valid

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

Content-Type

Location

Validate a new rule

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

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

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

Name	Type	Required	Description
condition	string	false	A Spring Expression Language (SpEL) expression that limits the applicability of the rule. The rule applies only in authorization contexts in which the expression evaluates to 'true'.
containerUri	string	false	A relative URI that represents the container aspect of a container object, such as a folder. Rules that target a container URI affect access that the container conveys to its child members.
expirationTimeStamp	string<date-time>	false	The date and time at which the rule expires. Expired rules should be disregarded and deleted.
filter	string	false	Filter criteria for the rule's target object (or objects). This property is not currently in use.
contentType	string	false	Media type of the object that is handled by an endpoint. If set, rules will only apply to endpoints that consume resources of this type. Most rules do not specify a content type.
acceptType	string	false	Media type of the object returned by an endpoint. If set, rules will only apply to endpoints that produce resources of this type. Most rules do not specify an accept type.
acceptItemType	string	false	Media type of object in a resource collection that is returned by an endpoint. If set, rules will only apply to endpoints that produce a resource collection containing resources of this type. Most rules do not specify an accept item type.
objectUri	string	true	A relative URI or ANT-path pattern that represents a resource or set of resources. Most rules target an object URI.
permissions	array [string]	true	The specific actions that the rule affects (for example: read, update, delete, create, secure, add, or remove). Allowed values: addcreatedeletereadremovesecureupdate
principal	string	true	Specifies the ID of a user or group to which the rule applies. Use this property in conjunction with the principalType property.
principalType	string	true	The type of principal or construct to which the rule applies. Allowed values: usergroupauthenticatedUserseveryoneguest
reason	string	false	Information that a client can display to end users for diagnostic purposes. For example, a prohibit rule’s reason could be displayed to an end user as part of an 'access denied' message.
type	string	true	Indicates whether the rule blocks (prohibit) or attempts to provide (grant) access to the specified principal. Allowed values: grantprohibit
version	integer<int32>	false	The version of the rule representation. The current representation version is 8.
description	string	false	Information that documents the rule for administrative purposes.
enabled	boolean	false	Indicates whether the rule is enabled. Default: true
matchParams	boolean	false	Indicates whether the rule applies to only those requests whose query parameters exactly match the rule target. Default: false
links	array [Link]	false	Zero or more links that are to related resources and actions.

Status	Meaning	Description
200	OK	The request succeeded.	Headers	Schema
400	Bad Request	The request was invalid.

Validate a new rule

Request Samples

Response Samples

Request Body

Responses