AWS.VerifiedPermissions — AWS SDK for JavaScript (original) (raw)

We recommend that you migrate to AWS SDK for JavaScript v3. For dates, additional details, and information on how to migrate, please refer to the linked announcement.

Inherits:

AWS.Service

Identifier:

verifiedpermissions

API Version:

2021-12-01

Defined in:

(unknown)

Overview

Constructs a service interface object. Each API operation is exposed as a function on service.

Service Description

Amazon Verified Permissions is a permissions management service from Amazon Web Services. You can use Verified Permissions to manage permissions for your application, and authorize user access based on those permissions. Using Verified Permissions, application developers can grant access based on information about the users, resources, and requested actions. You can also evaluate additional information like group membership, attributes of the resources, and session context, such as time of request and IP addresses. Verified Permissions manages these permissions by letting you create and store authorization policies for your applications, such as consumer-facing web sites and enterprise business systems.

Verified Permissions uses Cedar as the policy language to express your permission requirements. Cedar supports both role-based access control (RBAC) and attribute-based access control (ABAC) authorization models.

For more information about configuring, administering, and using Amazon Verified Permissions in your applications, see the Amazon Verified Permissions User Guide.

For more information about the Cedar policy language, see the Cedar Policy Language Guide.

When you write Cedar policies that reference principals, resources and actions, you can define the unique identifiers used for each of those elements. We strongly recommend that you follow these best practices:

Several operations return structures that appear similar, but have different purposes. As new functionality is added to the product, the structure used in a parameter of one operation might need to change in a way that wouldn't make sense for the same parameter in a different operation. To help you understand the purpose of each, the following naming convention is used for the structures:

Sending a Request Using VerifiedPermissions

var verifiedpermissions = new AWS.VerifiedPermissions();
verifiedpermissions.batchIsAuthorized(params, function (err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Locking the API Version

In order to ensure that the VerifiedPermissions object uses this specific API, you can construct the object by passing the apiVersion option to the constructor:

var verifiedpermissions = new AWS.VerifiedPermissions({apiVersion: '2021-12-01'});

You can also set the API version globally in AWS.config.apiVersions using the verifiedpermissions service identifier:

AWS.config.apiVersions = {
  verifiedpermissions: '2021-12-01',
  // other service API versions
};

var verifiedpermissions = new AWS.VerifiedPermissions();

Constructor Summarycollapse

Property Summarycollapse

Properties inherited from AWS.Service

apiVersions

Method Summarycollapse

Methods inherited from AWS.Service

makeRequest, makeUnauthenticatedRequest, setupRequestListeners, defineService

Constructor Details

new AWS.VerifiedPermissions(options = {}) ⇒ Object

Constructs a service object. This object has one method for each API operation.

Property Details

endpoint ⇒ AWS.Endpoint

Returns an Endpoint object representing the endpoint URL for service requests.

Method Details

Makes a series of decisions about multiple authorization requests for one principal or resource. Each request contains the equivalent content of an IsAuthorized request: principal, action, resource, and context. Either the principal or the resource parameter must be identical across all requests. For example, Verified Permissions won't evaluate a pair of requests where bob views photo1 and alice views photo2. Authorization of bob to view photo1 and photo2, or bob and alice to view photo1, are valid batches.

The request is evaluated against all policies in the specified policy store that match the entities that you declare. The result of the decisions is a series of Allow or Deny responses, along with the IDs of the policies that produced each decision.

The entities of a BatchIsAuthorized API request can contain up to 100 principals and up to 100 resources. The requests of a BatchIsAuthorized API request can contain up to 30 requests.

Note: The BatchIsAuthorized operation doesn't have its own IAM permission. To authorize this operation for Amazon Web Services principals, include the permission verifiedpermissions:IsAuthorized in their IAM policies.

batchIsAuthorizedWithToken(params = {}, callback) ⇒ AWS.Request

Makes a series of decisions about multiple authorization requests for one token. The principal in this request comes from an external identity source in the form of an identity or access token, formatted as a JSON web token (JWT). The information in the parameters can also define additional context that Verified Permissions can include in the evaluations.

The request is evaluated against all policies in the specified policy store that match the entities that you provide in the entities declaration and in the token. The result of the decisions is a series of Allow or Deny responses, along with the IDs of the policies that produced each decision.

The entities of a BatchIsAuthorizedWithToken API request can contain up to 100 resources and up to 99 user groups. The requests of a BatchIsAuthorizedWithToken API request can contain up to 30 requests.

Note: The BatchIsAuthorizedWithToken operation doesn't have its own IAM permission. To authorize this operation for Amazon Web Services principals, include the permission verifiedpermissions:IsAuthorizedWithToken in their IAM policies.

createIdentitySource(params = {}, callback) ⇒ AWS.Request

Adds an identity source to a policy store–an Amazon Cognito user pool or OpenID Connect (OIDC) identity provider (IdP).

After you create an identity source, you can use the identities provided by the IdP as proxies for the principal in authorization queries that use the IsAuthorizedWithToken or BatchIsAuthorizedWithToken API operations. These identities take the form of tokens that contain claims about the user, such as IDs, attributes and group memberships. Identity sources provide identity (ID) tokens and access tokens. Verified Permissions derives information about your user and session from token claims. Access tokens provide action context to your policies, and ID tokens provide principal Attributes.

Tokens from an identity source user continue to be usable until they expire. Token revocation and resource deletion have no effect on the validity of a token in your policy store

Note: To reference a user from this identity source in your Cedar policies, refer to the following syntax examples.

Note: Verified Permissions is eventually consistent . It can take a few seconds for a new or changed element to propagate through the service and be visible in the results of other Verified Permissions operations.

createPolicy(params = {}, callback) ⇒ AWS.Request

Creates a Cedar policy and saves it in the specified policy store. You can create either a static policy or a policy linked to a policy template.

Note: Creating a policy causes it to be validated against the schema in the policy store. If the policy doesn't pass validation, the operation fails and the policy isn't stored.

Note: Verified Permissions is eventually consistent . It can take a few seconds for a new or changed element to propagate through the service and be visible in the results of other Verified Permissions operations.

createPolicyStore(params = {}, callback) ⇒ AWS.Request

Creates a policy store. A policy store is a container for policy resources.

Note: Verified Permissions is eventually consistent . It can take a few seconds for a new or changed element to propagate through the service and be visible in the results of other Verified Permissions operations.

createPolicyTemplate(params = {}, callback) ⇒ AWS.Request

Creates a policy template. A template can use placeholders for the principal and resource. A template must be instantiated into a policy by associating it with specific principals and resources to use for the placeholders. That instantiated policy can then be considered in authorization decisions. The instantiated policy works identically to any other policy, except that it is dynamically linked to the template. If the template changes, then any policies that are linked to that template are immediately updated as well.

Note: Verified Permissions is eventually consistent . It can take a few seconds for a new or changed element to propagate through the service and be visible in the results of other Verified Permissions operations.

deleteIdentitySource(params = {}, callback) ⇒ AWS.Request

Deletes an identity source that references an identity provider (IdP) such as Amazon Cognito. After you delete the identity source, you can no longer use tokens for identities from that identity source to represent principals in authorization queries made using IsAuthorizedWithToken. operations.

deletePolicy(params = {}, callback) ⇒ AWS.Request

Deletes the specified policy from the policy store.

This operation is idempotent; if you specify a policy that doesn't exist, the request response returns a successful HTTP 200 status code.

deletePolicyStore(params = {}, callback) ⇒ AWS.Request

Deletes the specified policy store.

This operation is idempotent. If you specify a policy store that does not exist, the request response will still return a successful HTTP 200 status code.

deletePolicyTemplate(params = {}, callback) ⇒ AWS.Request

Deletes the specified policy template from the policy store.

This operation also deletes any policies that were created from the specified policy template. Those policies are immediately removed from all future API responses, and are asynchronously deleted from the policy store.

getIdentitySource(params = {}, callback) ⇒ AWS.Request

Retrieves the details about the specified identity source.

getPolicy(params = {}, callback) ⇒ AWS.Request

Retrieves information about the specified policy.

getPolicyStore(params = {}, callback) ⇒ AWS.Request

Retrieves details about a policy store.

getPolicyTemplate(params = {}, callback) ⇒ AWS.Request

Retrieve the details for the specified policy template in the specified policy store.

getSchema(params = {}, callback) ⇒ AWS.Request

Retrieve the details for the specified schema in the specified policy store.

isAuthorized(params = {}, callback) ⇒ AWS.Request

Makes an authorization decision about a service request described in the parameters. The information in the parameters can also define additional context that Verified Permissions can include in the evaluation. The request is evaluated against all matching policies in the specified policy store. The result of the decision is either Allow or Deny, along with a list of the policies that resulted in the decision.

isAuthorizedWithToken(params = {}, callback) ⇒ AWS.Request

Makes an authorization decision about a service request described in the parameters. The principal in this request comes from an external identity source in the form of an identity token formatted as a JSON web token (JWT). The information in the parameters can also define additional context that Verified Permissions can include in the evaluation. The request is evaluated against all matching policies in the specified policy store. The result of the decision is either Allow or Deny, along with a list of the policies that resulted in the decision.

At this time, Verified Permissions accepts tokens from only Amazon Cognito.

Verified Permissions validates each token that is specified in a request by checking its expiration date and its signature.

Tokens from an identity source user continue to be usable until they expire. Token revocation and resource deletion have no effect on the validity of a token in your policy store

listIdentitySources(params = {}, callback) ⇒ AWS.Request

Returns a paginated list of all of the identity sources defined in the specified policy store.

listPolicies(params = {}, callback) ⇒ AWS.Request

Returns a paginated list of all policies stored in the specified policy store.

listPolicyStores(params = {}, callback) ⇒ AWS.Request

Returns a paginated list of all policy stores in the calling Amazon Web Services account.

listPolicyTemplates(params = {}, callback) ⇒ AWS.Request

Returns a paginated list of all policy templates in the specified policy store.

putSchema(params = {}, callback) ⇒ AWS.Request

Creates or updates the policy schema in the specified policy store. The schema is used to validate any Cedar policies and policy templates submitted to the policy store. Any changes to the schema validate only policies and templates submitted after the schema change. Existing policies and templates are not re-evaluated against the changed schema. If you later update a policy, then it is evaluated against the new schema at that time.

Note: Verified Permissions is eventually consistent . It can take a few seconds for a new or changed element to propagate through the service and be visible in the results of other Verified Permissions operations.

updateIdentitySource(params = {}, callback) ⇒ AWS.Request

Updates the specified identity source to use a new identity provider (IdP), or to change the mapping of identities from the IdP to a different principal entity type.

Note: Verified Permissions is eventually consistent . It can take a few seconds for a new or changed element to propagate through the service and be visible in the results of other Verified Permissions operations.

updatePolicy(params = {}, callback) ⇒ AWS.Request

Modifies a Cedar static policy in the specified policy store. You can change only certain elements of the UpdatePolicyDefinition parameter. You can directly update only static policies. To change a template-linked policy, you must update the template instead, using UpdatePolicyTemplate.

Note:

Note: Verified Permissions is eventually consistent . It can take a few seconds for a new or changed element to propagate through the service and be visible in the results of other Verified Permissions operations.

updatePolicyStore(params = {}, callback) ⇒ AWS.Request

Modifies the validation setting for a policy store.

Note: Verified Permissions is eventually consistent . It can take a few seconds for a new or changed element to propagate through the service and be visible in the results of other Verified Permissions operations.

updatePolicyTemplate(params = {}, callback) ⇒ AWS.Request

Updates the specified policy template. You can update only the description and the some elements of the policyBody.

Changes you make to the policy template content are immediately (within the constraints of eventual consistency) reflected in authorization decisions that involve all template-linked policies instantiated from this template.

Note: Verified Permissions is eventually consistent . It can take a few seconds for a new or changed element to propagate through the service and be visible in the results of other Verified Permissions operations.

waitFor(state, params = {}, callback) ⇒ AWS.Request

Waits for a given VerifiedPermissions resource. The final callback or'complete' event will be fired only when the resource is either in its final state or the waiter has timed out and stopped polling for the final state.