Was this helpful?

Apigee Edge stores profile data for a range for "entities", such as developers, apps, and API products. The AccessEntity policy enables developers to retrieve those profiles during API proxy message processing. As such, the AccessEntity policy functions as a policy-based runtime database lookup. The profile information returned by this policy can be used to enable dynamic behavior, such as conditional endpoint routing, flow execution, policy enforcement, and so on.

For example, you could use the AccessEntity policy to get the profile for an app, and then extract a custom field (such as a department name) from the app profile. Using the department name as a variable, you could route the request to a specific backend service, or you could forward the department name to Analytics to enable data accounting.

When a policy of type AccessEntity is enforced:

  1. The policy sets an entity as an XML-formatted flow variable. The variable that is set is usually consumed by an ExtractVariable or AssignMessage policy, as illustrated in Extract message content using ExtractVariables and Generate or modify messages using AssignMessage .
  2. XPath is used to parse the desired properties from the profile. For examples see Retrieving entity profiles using the Platform API.
  3. If the specified entity is not found, the policy returns ResourceNotFoundException.

AccessEntity can be used to access profiles for the following entities:

  • App
  • API product
  • Company
  • Company developer
  • Consumer key
  • Developer

The basic of structure of an AccessEntity policy is:

<AccessEntity name="{policy_name}">
  <EntityType  value="{entity_type}"/>
  <EntityIdentifier ref="{entity_identifier}" type="identifer_type"/> 
  <SecondaryIdentifier ref="{secondary_identifier}" type="identifer_type"/>
</AccessEntity>

You can access multiple entities of the same type as follows:

<AccessEntity name="name_of_the_policy">
  <EntityType  value="type_of_entity"/>
  <Identifiers>
    <Identifier>
      <EntityIdentifier ref="reference_to_entity_identifier" type*=”identifer_type”/> 
      <SecondaryIdentifier ref="reference_to_secondary_entity_identifier" type="identifer_type"/><!-- optional -->
    </Identifier >
    <Identifier>
      <EntityIdentifier ref="reference_to_entity_identifier" type*=”identifer_type”/> 
      <SecondaryIdentifier ref="reference_to_secondary_entity_identifier" type="identifer_type"/><!-- optional -->
    </Identifier >
  </Identifiers>
</AccessEntity>

Where multiple matches exist for a given EntityIdentifier and SupportingIdentifier combination, the first match will be populated in the Flow. An example of such a potential conflict is retrieving an apiproduct based on appid. For example:

  • EntityType is set to apiproduct
  • EntityIdentifier is set to appid

Since an app can be associated with multiple API products, only the first matched API product will be available in the Flow.

To resolve such potential conflicts, you can use a SecondaryIdentifier. For example, during an OAuth 2.0 exchange, appname and developerid variables are populated by default in the Flow. Those two variables can therefore be used by an AccessEntity policy to get profile details on the requesting app. To prevent conflicts, set the EntityIdentifier to appname and developerid as the SecondaryIdentifier.

AccessEntity variables

When the entity profile specified in the AccessEntity policy is retrieved, the XML-formatted profile object is added to the message context as a variable. It can be accessed like any other variable, with reference to the variable name. The user-provided name of the AccessEntity policy is set as the variable prefix of the variable name.

For example, if an AccessEntity policy with name of GetDeveloper is executed, then the XML-formatted profile is stored in the variable named AccessEntity.GetDeveloper. The XML-formatted profile can then be parsed using an XPath defined in an ExtractVariables policy that specifies AccessEntity.GetDeveloper as its source.

EntityType specification

EntityType EntityIdentifiers SecondaryIdentifiers
apiproduct
  • apiproductname
  • appname
  • appid
  • consumerkey
  • developeremail
  • developerid
  • companyname
  • apiresource

The SecondaryIdentifiers developeremail, developerid and companyname are used only when the EntityIdentifier is appname.

TheSecondaryIdentifier apiresource is used only when the EntityIdentifier is appname, appid, or consumerkey.

app
  • appname
  • appid
  • consumerkey
  • developeremail
  • developerid
  • companyname

Used only when identifier is appname, because the value of appname is not guaranteed to be unique across an organization.

company
  • companyname
  • appid
  • consumerkey
None
companydeveloper
  • companyname
None
consumerkey
  • consumerkey
None
developer
  • developeremail
  • developerid
  • appid
  • consumerkey
None

Configuring an AccessEntity policy

AccessEntity policies expose the following configuration settings:

Name Description Default Required?
AccessEntity A policy used to retrieve entity profiles from Apigee Edge's data store.
Name The unique name of the policy. Characters you can use in the name are restricted to: A-Z0-9._\-$ %. However, the Management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

N/A Yes
EntityType The name of the type of entity to be retrieved. For a reference of entity types, see the EntityType specification N/A Yes
EntityIdentifier

The value that identifies the specific entity whose profile should be retrieved.

The ref attribute identifies the variable that provides the source of the identifier, for example, request.queryparam.apikey

.

The type identifies the EntityType populated by the referenced variable, such as consumerkey.

N/A No
SecondaryIdentifier

Use when EntityIdentifier is not guaranteed unique, as with appname.

Also use to filter queries that return multiple results.

The ref attribute identifies the variable that provides the source of the identifier, for example, request.queryparam.apikey.

The type identifies the entity type populated by the referenced variable, such as consumerkey. The use of multiple SecondaryIdentifier elements is not supported. This element is optional to support backward-compatibility with existing deployments.

N/A No

Configuring ExtractVariables to use AccessEntity lookup

When an AccessEntity policy executes, the result is a Flow variable populated with an XML-formatted profile object. The XML-formatted profile object can be used as a source of data for a Flow by configuring an ExtractVariables policy to parse the profile.

In the following example, an ExtractVariables policy is used to parse a developer profile retrieved by AccessEntity to obtain the value of a custom attribute. The source is set to point to the variable where the developer profile is stored by the AccessEntity policy: AccessEntity.{policy_name}. The profile can be parsed using XPath, just as any other XML document. Sample profiles for entities managed by Apigee Edge are provided below.

Convert profile to a message

Before the profile can be parsed by Apigee Edge, it must be converted into a request message using an AssignMessage policy.

<AssignMessage name="ConvertXmlToMessageRequest"> 
    <DisplayName>ConvertXmlToMessageRequest</DisplayName> 
    <Set> 
      <Payload type="text/xml">{AccessEntity.GetDeveloper}</Payload> 
    </Set> 
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> 
  <AssignTo createNew="true" transport="http" type="request">accessentity.typed</AssignTo> 
</AssignMessage> 

Once the profile has been converted to an XML message, you can populate the necessary variables using an ExtractVariables, policy. For example:

<ExtractVariables name="GetDeveloperAttribute">
  <Source>AccessEntity.GetDeveloper</Source> 
  <VariablePrefix>developer_attribute</VariablePrefix>
  <XMLPayload>
    <Variable name="developer_attribute" type="string">
      <XPath>/Developer/Attributes/Name</XPath>
    </Variable>
  </XMLPayload>
</ExtractVariables>

Retrieving entity profiles using the management API

When configuring an AccessEntity policy, it can be useful to retrieve sample entity profiles to assist in selection of appropriate identifiers. For details, refer to the Gateway Services API reference

For example:

Apps

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/apps/{app_id} \
-u myname:mypass

Or:

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/{developer_email}/apps/{app_name} \
-u myname:mypass

Sample profile:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<App name="thomas-app">
    <AccessType>read</AccessType>
    <ApiProducts/>
    <Credentials>
        <Credential>
            <Attributes/>
            <ConsumerKey>wrqOOOiPArFI0WRoB1gAJMRbOguekJ5w</ConsumerKey>
            <ConsumerSecret>WvOhDrJ8m6kzz7Ni</ConsumerSecret>
            <ApiProducts>
                <ApiProduct>
                    <Name>FreeProduct</Name>
                    <Status>approved</Status>
                </ApiProduct>
            </ApiProducts>
            <Scopes/>
            <Status>approved</Status>
        </Credential>
    </Credentials>
    <AppFamily>default</AppFamily>
    <AppId>ab308c13-bc99-4c50-8434-0e0ed1b86075</AppId>
    <Attributes>
        <Attribute>
            <Name>DisplayName</Name>
            <Value>Tom's Weather App</Value>
        </Attribute>
    </Attributes>
    <CallbackUrl>http://tom.app/login</CallbackUrl>
    <CreatedAt>1362502872727</CreatedAt>
    <CreatedBy>admin@apigee.com</CreatedBy>
    <DeveloperId>PFK8IwOeAOW01JKA</DeveloperId>
    <LastModifiedAt>1362502872727</LastModifiedAt>
    <LastModifiedBy>admin@apigee.com</LastModifiedBy>
    <Scopes/>
    <Status>approved</Status>
</App>

API product

$ curl  -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/apiproducts/{apiproduct_name} \
-u myname:mypass

Sample XPath, retrieves the second API resource (URI) from the API product named weather_free:

/ApiProduct['@name=weather_free']/ApiResources/ApiResource[1]/text()

Sample profile:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ApiProduct name="weather_free">
    <ApiResources>
        <ApiResource>/forecastrss, /reports</ApiResource>
    </ApiResources>
    <ApprovalType>auto</ApprovalType>
    <Attributes>
        <Attribute>
            <Name>description</Name>
            <Value>Introductory API Product</Value>
        </Attribute>
        <Attribute>
            <Name>developer.quota.interval</Name>
            <Value>1</Value>
        </Attribute>
        <Attribute>
            <Name>developer.quota.limit</Name>
            <Value>1</Value>
        </Attribute>
        <Attribute>
            <Name>developer.quota.timeunit</Name>
            <Value>minute</Value>
        </Attribute>
        <Attribute>
            <Name>servicePlan</Name>
            <Value>Introductory</Value>
        </Attribute>
    </Attributes>
    <CreatedAt>1355847839224</CreatedAt>
    <CreatedBy>andrew@apigee.com</CreatedBy>
    <Description>Free API Product</Description>
    <DisplayName>Free API Product</DisplayName>
    <Environments/>
    <LastModifiedAt>1355847839224</LastModifiedAt>
    <LastModifiedBy>andrew@apigee.com</LastModifiedBy>
    <Proxies/>
    <Scopes/>
</ApiProduct>

Company

$ curl   -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/companies/{company_name} \
-u myname:mypass

Sample profile:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Company name="theramin">
    <Apps/>
    <DisplayName>Theramin Corporation</DisplayName>
    <Organization>apigee-pm</Organization>
    <Status>active</Status>
    <Attributes>
        <Attribute>
            <Name>billing_code</Name>
            <Value>13648765</Value>
        </Attribute>
    </Attributes>
    <CreatedAt>1349208631291</CreatedAt>
    <CreatedBy>andrew@apigee.com</CreatedBy>
    <LastModifiedAt>1349208631291</LastModifiedAt>
    <LastModifiedBy>andrew@apigee.com</LastModifiedBy>
</Company>

Company developer

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/companies/{company_name}/developers/{developer_name} \
-u myname:mypass

Sample profile:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Developers>
    <Developer>
        <Email>ntesla@theramin.com</Email>
        <Role>developer</Role>
    </Developer>
</Developers>

Consumer key

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/{developer_email}/apps/{app_name}/keys/{consumer_key} \
-u myname:mypass

Sample XPath:

/Credential/ApiProducts/ApiProduct[Name='weather_free']/Status/text()

Sample profile:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Credential>
    <Attributes/>
    <ConsumerKey>XLotL3PRxNkUGXhGAFDPOr6fqtvAhuZe</ConsumerKey>
    <ConsumerSecret>iNUyEaOOh96KR3YL</ConsumerSecret>
    <ApiProducts>
        <ApiProduct>
            <Name>weather_free</Name>
            <Status>approved</Status>
        </ApiProduct>
    </ApiProducts>
    <Scopes/>
    <Status>approved</Status>
</Credential>

Developer

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/{developer_email} \
-u myname:mypass

Sample XPath:

/Developer/Attributes/Attribute[Name='my_custom_attribute']/Value/text()
/Developer/Email/text()

Sample profile:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Developer>
    <Apps>
        <App>weatherappx</App>
        <App>weatherapp</App>
    </Apps>
    <Email>ntesla@theramin.com</Email>
    <DeveloperId>4Y4xd0KRZ1wmHJqu</DeveloperId>
    <FirstName>Nikola</FirstName>
    <LastName>Tesla</LastName>
    <UserName>theramin</UserName>
    <OrganizationName>apigee-pm</OrganizationName>
    <Status>active</Status>
    <Attributes>
        <Attribute>
            <Name>project_type</Name>
            <Value>public</Value>
        </Attribute>
    </Attributes>
    <CreatedAt>1349797040634</CreatedAt>
    <CreatedBy>rsaha@apigee.com</CreatedBy>
    <LastModifiedAt>1349797040634</LastModifiedAt>
    <LastModifiedBy>rsaha@apigee.com</LastModifiedBy>
</Developer>

Policy-specific error codes

The default format for error codes returned by Policies is:

{
  "code" : " {ErrorCode} ",
  "message" : " {Error message} ",
  "contexts" : [ ]
}

The AccessEntity Policy type defines the following error codes:

Error Code Message
InvalidEntityType Invalid type {0} in ACCESSENTITYStepDefinition {1}

Policy schema

Each policy type is defined by an XML schema (.xsd). For reference, policy schemas are available on GitHub.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)