Lookups

Lookup Keys allow the DreamFactory administrator to store any number of "key value" pairs that can be attached to an app, a user, a role, or to the global system configuration of the instance itself. The key names can be used in a variety of DreamFactory interfaces by any API client, and the key values are automatically substituted on the server. Any Lookup Key can be marked as private, which causes the key's value to be securely stored on the server-side and not retrievable by the client, even with admin credentials. See DreamFactory 1.5 Introduces Lookup Keys | this blog post for a high-level overview of lookup keys:

System Keys

DreamFactory provides some "automatic" system-created Lookup Keys that are always available. These keys include information from the current user session, user information, role information, and the current instance name and versioning are also provided. These automatic Lookup Keys simplify many use case scenarios. For example, connecting a user by email address in an external database is easy. There is no need to create an email Lookup Key for each user.

• **session.token**
• **user.id**
• **user.email**
• **user.display_name**
• **user.first_name**
• **user.last_name**
• **role.id**
• **role.name**
• **app.id**
• **app.name**
• **app.api_key**
• **df.name**
• **df.api_version**
• **df.version**
• **df.host_url**
• **df.confirm_invite_url**
• **df.confirm_register_url**
• **df.confirm_reset_url**

Provisioning

Lookup keys and values can be provisioned via the Admin console on the App, Role, and User tabs, as well as the Config tab in the Lookups menu option. There's a hierarchy to lookup keys, starting from global system keys, then to app keys, then role keys, and finally, user keys. The system will use the most specific one provisioned for the value in play. This allows you to create a system of default settings and, if needed, overrides for special cases. Consider the case of using lookup keys for configuring credentials on a database service. Some basic read-only credentials may be set as global system keys. Another set of credentials with read and write access may be provisioned on a particular role. And more admin-like credentials can be provisioned for a single user of that role. As long as the keys are named the same, the hierarchy allows for overriding of how the database is accessed without creating a different service for each scenario.

In Global Config

For those not in Role A or Role B these credentials will be used. These users have no lookup key at the user or role level.


In Role Config

For those users in Role A or Role B these credentials will be used. Since these users have a lookup key at the role level, the one at the global level will never be used.


In User Config

There is a special user in Role A who requires admin level database permissions. You can add a user lookup key that will override the role lookup key only for that one user. All other users in Role A get the role level credentials.


Usage

Lookup keys can be used in several interfaces of the DreamFactory instance. Typically, lookup keys are designated by wrapping the key name in curly braces, i.e. {some_name}. Lookup keys can be used in the following interfaces...

• in service credentials and configuration fields - Private keys only! For example, the username and password fields required to hook up a SQL database.
• in Email Services & Templates in the subject line and message body - For example, using the user's name or instance name or URL.
• in Remote Web Services as parameters or headers - **Private keys only!**
• in Server-Side Filters in the Role Service Access provisioning.
• in posted data records or parameters in filters in SQL and NoSQL Database services.

One simple yet important use of Lookup Keys is to hide the master credentials required for integration with an external system. For example, if you are using Amazon S3 then you will have an Access Key and Secret Key provided by AWS. Both of these values could be saved as private Lookup Keys. Then you can use the key names in place of the actual credentials in the Admin Console. Later, if you wanted to connect to another Amazon service like Dynamo DB, you could just reuse the same key names. In this manner, your secret keys are encrypted and only used on the server-side for authentication with an external system. Private keys must be used for credentials and passwords and cannot be used elsewhere.

Here's how you would use the lookup keys for username and password on a database service. The system will replace {db_username} and {db_password} with the most specific lookup keys defined for the user making the API call.