Was this Helpful?

 Access Entity policy

About | Samples | Element reference | Usage notes | Flow variables | Error codes | Related topics

What

Apigee Edge stores profile data for a range for "entities", such as developers, apps, and API products. The Access Entity policy lets you retrieve those profiles during API proxy message processing. As such, the Access Entity 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.

Use this policy in conjunction with the Assign Message and Extract Variables policies. See the Samples and Usage notes.

Where

This policy can be attached in the following locations, but see the notes following the table for specific guidance.

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
Request    
    Response
    PostFlow Flow PreFlow PostFlow Flow PreFlow    

Samples

The following samples show Access Entity used in conjunction with the Extract Variables and Assign Message policies to extract a developer's email and add it to the HTTP header.

<AccessEntity name="GetDeveloperProfile">
  <!-- This is the type entity whose profile we need to pull from the Edge datastore. -->
  <EntityType  value="developer"/>
  <!-- We tell the policy to use the API key (presented as query parameter) to identify the developer. -->
  <EntityIdentifier ref="request.queryparam.apikey" type="consumerkey"/> 
</AccessEntity>
<ExtractVariables name="SetDeveloperProfile">
  <!-- The source element points to the variable populated by AccessEntity policy. 
  The format is <policy-type>.<policy-name>.
  In this case, the variable contains the whole developer profile. -->
  <Source>AccessEntity.GetDeveloperProfile</Source> 
  <VariablePrefix>developer</VariablePrefix>
  <XMLPayload>
    <Variable name="email" type="string"> 
	<!-- You parse elements from the developer profile using XPath. -->
      <XPath>/Developer/Email</XPath>
    </Variable>
  </XMLPayload>
</ExtractVariables>
<!-- We'll use this policy to return the variables set in the developer profile, 
just so that we can easily see them in the response. -->
<AssignMessage name="EchoVariables">
  <AssignTo createNew="false" type="response"></AssignTo>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <Set>
    <Headers>
      <Header name="X-Developer-email">{developer.email}</Header>
    </Headers>
  </Set>
</AssignMessage>

Element reference

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

See our Github repository samples for the most recent schemas.


Usage notes

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 can be used to access profiles for the following entities:

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

Example use case: You could use the Access Entity 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 Variables policy and Assign Message policy .
  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.

EntityTypes

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 Extract Variables to use Access Entity lookup

When an Access Entity 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 Extract Variables policy to parse the profile.

In the following example, an Extract Variables policy is used to parse a developer profile retrieved by Access Entity 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 Assign Message 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 Extract Variables, 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 management 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

See also Get App in an Organization by App ID in the Edge management API reference.

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

See also Get Developer App Details in the Edge management API reference.

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

See also Get API Product in the Edge management API reference.

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 returned as XML:

<?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

See also Get Company Details in the Edge management API reference.

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

See also Get Key Details for a Developer App in the Edge management API reference.

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

See also Get Developer in the Edge management API reference.

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>

Flow 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.

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}

Related topics

For working samples of API proxies, see the Samples reference.

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?)