Create Policies to Control Access to Network and API Gateway-Related Resources

When API Gateway users define a new API gateway and new API deployments, they have to specify a compartment for those API Gateway-related resources. Users can only specify a compartment that the groups to which they belong have been granted access. To enable users to specify a compartment, you must create an identity policy to grant the groups access.

To create a policy to give users access to API Gateway-related resources in the compartment that will own those resources:

1. Log in to the Console as a tenancy administrator.
2. Open the navigation menu and click Identity & Security. Under Identity, click Policies. A list of the policies in the compartment you're viewing is displayed.
3. Select the compartment that will own API Gateway-related resources from the list on the left.
4. Click Create Policy.

5. Enter the following:

   • Name: A meaningful name for the policy (for example, acme-apigw-developers-manage-access). The name must be unique across all policies in your tenancy. You cannot change this later. Avoid entering confidential information.
   • Description: A meaningful description (for example, Gives api-gateway developers access to all resources in the acme-apigw-compartment). You can change this later if you want to.

   • Statement: The following policy statement to give the group access to all API Gateway-related resources in the compartment:

     As Statement 1:, enter the following policy statement to give the group access to all API Gateway-related resources in the compartment:

     Allow group <group-name> to manage api-gateway-family in compartment <compartment-name>

     For example:

     Allow group acme-apigw-developers to manage api-gateway-family in compartment acme-apigw-compartment

   • Tags: If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you're not sure whether to apply tags, skip this option or ask an administrator. You can apply tags later.
6. Click Create to create the policy giving API Gateway users access to API Gateway-related resources in the compartment.

When API Gateway users define a new API gateway, they have to specify a VCN and a subnet in which to create the API gateway. Users can only specify VCNs and subnets that the groups to which they belong have been granted access. To enable users to specify a VCN and subnet, you must create an identity policy to grant the groups access. In addition, if you want to enable users to create public API gateways, the identity policy must allow the groups to manage public IP addresses in the compartment that owns the network resources.

To create a policy to give API Gateway users access to network resources:

1. Log in to the Console as a tenancy administrator.
2. Open the navigation menu and click Identity & Security. Under Identity, click Policies. A list of the policies in the compartment you're viewing is displayed.
3. Select the compartment that owns the network resources from the list on the left.
4. Click Create Policy.

5. Enter the following:

   • Name: A meaningful name for the policy (for example, acme-apigw-developers-network-access). The name must be unique across all policies in your tenancy. You cannot change this later. Avoid entering confidential information.
   • Description: A meaningful description (for example, Gives api-gateway developers access to all network resources in the acme-network compartment). You can change this later if you want to.

   • Statement: The following policy statement to give the group access to network resources in the compartment (including the ability to manage public IP addresses):

     Allow group <group-name> to manage virtual-network-family in compartment <compartment-name>

     For example:

     Allow group acme-apigw-developers to manage virtual-network-family in compartment acme-network

   • Tags: If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you're not sure whether to apply tags, skip this option or ask an administrator. You can apply tags later.
6. Click Create to create the policy giving API Gateway users access to network resources and public IP addresses in the compartment.

When API Gateway users define a new API gateway, one option is to specify a serverless function defined in OCI Functions as the API back end. Users can only specify functions that the groups to which they belong have been granted access. If you want to enable users to specify functions as API back ends, you must create an identity policy to grant the groups access. Note that in addition to this policy for the user group, to enable users to specify functions as API back ends you also have to create a policy to give API gateways access to OCI Functions (see Create a Policy to Give API Gateways Access to Functions).

Another reason to create an identity policy that grants groups access to OCI Functions is if you want to enable users to use the Console (rather than a JSON file) to define an authentication request policy and specify an authorizer function defined in OCI Functions (see Passing Tokens to Authorizer Functions to Add Authentication and Authorization to API Deployments).

To create a policy to give API Gateway users access to functions defined in OCI Functions:

1. Log in to the Console as a tenancy administrator.
2. Open the navigation menu and click Identity & Security. Under Identity, click Policies. A list of the policies in the compartment you're viewing is displayed.
3. Select the compartment that owns the functions from the list on the left.
4. Click Create Policy.

5. Enter the following:

   • Name: A meaningful name for the policy (for example, acme-apigw-developers-functions-access). The name must be unique across all policies in your tenancy. You cannot change this later. Avoid entering confidential information.
   • Description: A meaningful description (for example, Gives api-gateway developers access to all functions in the acme-functions-compartment). You can change this later if you want to.

   • Statement:The following policy statement to give the group access to the functions in the compartment:

     Allow group <group-name> to use functions-family in compartment <compartment-name>

     For example:

     Allow group acme-apigw-developers to use functions-family in compartment acme-functions-compartment

   • Tags: If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you're not sure whether to apply tags, skip this option or ask an administrator. You can apply tags later.
6. Click Create to create the policy giving API Gateway users access to functions in the compartment.

API Gateway users can use a Certificates service certificate resource to set up a custom domain name for an API gateway. To enable users to associate a Certificates service certificate resource with an API gateway, you must create an identity policy to allow the groups to which the users belong to create certificate associations.

To create a policy to enable API Gateway users to associate a Certificates service certificate resource with an API gateway:

1. Log in to the Console as a tenancy administrator.
2. Open the navigation menu and click Identity & Security. Under Identity, click Policies. A list of the policies in the compartment you're viewing is displayed.
3. Select the compartment that owns the API gateway from the list on the left.
4. Click Create Policy.

5. Enter the following:

   • Name: A meaningful name for the policy (for example, acme-apigw-developers-certificate-association). The name must be unique across all policies in your tenancy. You cannot change this later. Avoid entering confidential information.
   • Description: A meaningful description (for example, Gives api-gateway developers the ability to create certificate associations). You can change this later if you want to.

   • Statement: The following policy statement to enable the group to associate a Certificates service certificate resource with an API gateway in the compartment:

     Allow group <group-name> to manage certificate-associations in compartment <compartment-name>

     For example:

     Allow group acme-apigw-developers to manage certificate-associations in compartment acme-apigw-compartment

   • Tags: If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you're not sure whether to apply tags, skip this option or ask an administrator. You can apply tags later.
6. Click Create to create the policy enabling API Gateway users to associate Certificates service certificate resources with API gateways in the compartment.

In addition to the default certificate authority (CA) and CA bundle, API Gateway users can choose to add the root certificates of other CAs, and other CA bundles (referred to as custom CAs and custom CA bundles) to an API gateway's trust store. To customize an API gateway's trust store by adding a custom CA or CA bundle, users have to first create a CA resource or CA bundle resource in the Certificates service. See Customizing Trust Stores for TLS Certificate Verification.

To enable users to add custom CAs and custom CA bundles to custom trust stores, you must create an identity policy to allow the groups to which the users belong to manage certificate authorities in the Certificates service.

To create a policy to enable API Gateway users to add custom CAs and custom CA bundles to custom trust stores:

1. Log in to the Console as a tenancy administrator.
2. Open the navigation menu and click Identity & Security. Under Identity, click Policies. A list of the policies in the compartment you're viewing is displayed.
3. Select the compartment that owns the API gateway from the list on the left.
4. Click Create Policy.

5. Enter the following:

   • Name: A meaningful name for the policy (for example, acme-apigw-developers-custom-ca-bundle). The name must be unique across all policies in your tenancy. You cannot change this later. Avoid entering confidential information.
   • Description: A meaningful description (for example, Gives api-gateway developers the ability to add custom CAs and CA bundles). You can change this later if you want to.

   • Statement: The following policy statement to enable the group to add custom CAs and custom CA bundles to the custom trust store of API gateways in the compartment:

     Allow group <group-name> to manage certificate-authority-family in compartment <compartment-name>

     For example:

     Allow group acme-apigw-developers to manage certificate-authority-family in compartment acme-apigw-compartment

   • Tags: If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you're not sure whether to apply tags, skip this option or ask an administrator. You can apply tags later.
6. Click Create to create the policy enabling API Gateway users to add custom CAs and custom CA bundles to custom trust stores.

When API Gateway users define a new API gateway, one option is to specify a serverless function defined in OCI Functions as the API back end. Before creating the API gateway, the API Gateway service verifies that the new API gateway will have access to the specified function through an IAM policy.

Note that in addition to this policy for API gateways, to enable users to specify functions as API back ends you also have to create a policy to give users access to OCI Functions (see Create a Policy to Give API Gateway Users Access to Functions).

To create a policy to give API gateways access to functions defined in OCI Functions:

1. Log in to the Console as a tenancy administrator.

2. Create a new policy to give API gateways access to functions defined in OCI Functions:

   1. Open the navigation menu and click Identity & Security. Under Identity, click Policies.
   2. Select the compartment containing the function-related resources to which you want to grant access. If the resources are in different compartments, select a common parent compartment (for example, the tenancy's root compartment).
   3. Follow the instructions in To create a policy, and give the policy a name (for example, acme-apigw-gateways-functions-policy).

   4. Enter a policy statement to give API gateways access to the compartment containing functions defined in OCI Functions:

      ALLOW any-user to use functions-family in compartment <functions-compartment-name> where ALL {request.principal.type= 'ApiGateway', request.resource.compartment.id = '<api-gateway-compartment-OCID>'}

      where:

      • <functions-compartment-name> is the name of the compartment containing the functions you want to use as back ends for API gateways.
      • <api-gateway-compartment-OCID> is the OCID of the compartment containing the API gateways that you want to have access to the functions.

      For example:

      ALLOW any-user to use functions-family in compartment acme-functions-compartment where ALL {request.principal.type= 'ApiGateway', request.resource.compartment.id = 'ocid1.compartment.oc1..aaaaaaaa7______ysq'}

   5. Click Create to create the policy giving API gateways access to functions defined in OCI Functions.

If API Gateway users define an API gateway that caches response data in an external cache server (such as a Redis server), the credentials to authenticate with the cache server must be stored in the Vault service. Similarly, if API Gateway users define an API gateway that accesses an authorization server's introspection endpoint to validate tokens, the credentials to authenticate with the authorization server must be stored in the Vault service. To enable API gateways to authenticate with the cache server or the authorization server, you have to create a policy that grants API gateways access to secrets in the Vault service.

To create a policy to give API gateways access to secrets in the Vault service:

1. Log in to the Console as a tenancy administrator.

2. Create a new dynamic group comprising one or more API gateways:

   1. Open the navigation menu and click Identity & Security. Under Identity, click Domains. Under Identity domain, click Dynamic groups.
   2. Follow the instructions in To create a dynamic group, and give the dynamic group a name (for example, acme-apigw-dyn-grp).

   3. When specifying a rule for the dynamic group, consider the following examples:

      • If you want all API gateways in a compartment to be able to access secrets, enter a rule similar to the following that adds all API gateways in the compartment with the specified compartment OCID to the dynamic group:

        ALL {resource.type = 'ApiGateway', resource.compartment.id = 'ocid1.compartment.oc1..aaaaaaaa23______smwa'}

      • If you want a specific API gateway to be able to access secrets, enter a rule similar to the following that adds the API gateway with the specified OCID to the dynamic group:

        ALL {resource.type = 'ApiGateway', resource.id = 'ocid1.apigateway.oc1.iad.aaaaaaaab______hga'}

   4. Click Create Dynamic Group.

   Having created a dynamic group that includes one or more API gateways, you can now create a policy to give the dynamic group access to one or more secrets.

3. Create a new policy to grant the dynamic group access to one or more secrets in the Vault service:

   1. Open the navigation menu and click Identity & Security. Under Identity, click Policies.
   2. Follow the instructions in To create a policy, and give the policy a name (for example, acme-apigw-dyn-grp-policy).

   3. When specifying a policy statement, consider the following examples:

      • If you want API gateways in the acme-apigw-dyn-grp to be able to access all secrets in a compartment, enter a policy statement similar to the following:

        allow dynamic-group acme-apigw-dyn-grp to read secret-bundles in compartment acme-apigw-compartment

      • If you want API gateways in the acme-apigw-dyn-grp to be able to access a specific secret, enter a policy statement similar to the following:

        allow dynamic-group acme-apigw-dyn-grp to read secret-bundles in compartment acme-apigw-compartment where target.secret.id='ocid1.vaultsecret.oc1.iad.amaaaaaa______qia'

   4. Click Create to create the new policy giving API gateways in the dynamic group access to the specified secrets in the Vault service.