There are many different types of configuration objects (policies) within the Forum Sentry WebAdmin interface. Many of these policy objects can be reusable and may have associations or references to other policy objects. For an example of how the different policy objects are associated to each other, please see:
This article provides recommendations for naming conventions for the different types of Sentry policies.
The primary benefits of following an established naming convention are:
- Configuration management - quickly and easily find the policies you need to review and/or edit
- Logs, Alerts, Monitoring - the policy names show up in the Sentry logs and so alerting and monitoring rules (and dashboards) can be built based on these names
- Versioning - versioning of policies may be necessary when several versions of APIs are exposed via Sentry and or when you have different environments for the APIs (e.g. test/dev, UAT, prod) and corresponding Sentry policies for each
- REST API - the Sentry REST API allows for scripting the management of Sentry policies and having a consistent naming convention can simplify the scripts, which may utilize variables
Labels and Searching
Sentry allows for adding labels (tags) to many different types of policies. These allow for filtering policies by label (e.g. only show policies tagged with a specific label). The searching functionality found on many WebAdmin pages can be combined with the labeling to quickly find the policy you are looking for.
Any Sentry naming convention should also utilize the Label options where applicable. Note that multiple labels can be associated to the same policy.
While the labeling will help to group policies within the WebAdmin interface, labels are not shown in the logs, so using only generic policy names with specific labels is not advisable if you plan to build alerts and dashboards from the Sentry logging information.
Generic vs Specific Policy Names
Some types of policies will be shared across different APIs defined within Sentry. Other policies may be specific to a particular API. How policies are ultimately used should be considered when developing the naming convention.
Example of a Generic Policy Name:
An HTTPS Listener policy, which specifies a listening IP and port, IP ACL, and SSL Termination policy (among other things) may be utilized by several APIs. As several different (unrelated) APIs might all utilize the same HTTPS Listener Policy, it often makes more sense to use a generic policy name (i.e. HTTPS_443) rather than a name that is API specific.
Example of a Specific Policy Name:
An HTTP Remote policy, which specifies the endpoint (IP and Port) that Sentry will forward traffic to, is usually specific for each API. In this case, the name of the HTTP Remote policy might indicate the API, the name of the remote server, and the environment in use (i.e. RemoteServerA_InventoryQueryAPI_Dev).
System Default Policies
Factory default Sentry configurations include some system default policies that are automatically associated to other types of new policies when they are built. This is important to understand in the context of a naming convention scheme because these system default policies are already named - and in most cases, they can't be changed.
For example, Sentry ships with a default set of IDP Groups (and associated IDP Rules) that are enabled on new WSDL and Content policies when they are built via their respective wizards. While the associated IDP Group can be changed to a custom group after policy generation, in many cases the default groups are used in perpetuity.
Whether to use the system default policies or customer policies is outside the scope of this article. There are pros and cons to both approaches and we recommend contacting Forum Systems Support to discuss further. However, when the default policies are used, note that the policy names are generic in nature.
Default policies that are commonly used include: IDP Groups, IDP Rules, IP ACLs, Error Templates, Pattern Match policies, and Request Filters.
If any of these policy types will be API specific, new policies should be created and named appropriately.
Types of Sentry Policies to Apply a Naming Convention To
The following is a list of Sentry policy types that will benefit greatly from an established naming convention. Also included are naming convention recommendations for each.
Network Policies - Most Sentry configs ultimately contain a combination of generic and specific network policies. For example, when a listener is to be used by multiple APIs, generic is best. However, if a listener is specific for an API a specific name may be appropriate. In either case, including the protocol and port number in the name can be useful.
WSDL Policies - When a WSDL policy is built from a single WSDL, a specific name is usually appropriate as the WSDL defines a single service. However, when a WSDL policy is built from a library that contains several WSDLs from different services, a more generic name may be appropriate.
XML Policies - Usually named specific to an XML service/API.
REST Policies - Usually named specific to a RESTful API.
JSON Policies - Usually named specific to a JSON service/API.
HTML Policies - Usually named specific to a web portal secured by Sentry.
Virtual Directories - Content Policies often include multiple virtual directories, which process transactions in different ways for different reasons. The virtual directories are usually named specifically for the operation or directory in use.
Examples: API_Auth_v1 (generic)
STS Policies - Usually named specific to the service consuming the SAML assertions generated by the STS policy.
OAuth Policies - When the OAuth policy will generate tokens that are used by several APIs, the name is usually generic. If the OAuth tokens are only used for certain APIs, the name might be specific.
Task Lists - When the Task List is going to be used by multiple APIs, the name is usually generic. When the Task List is applicable to a particular API workflow, the name is usually specific. Appending TL to the end helps distinguish between Task List Groups that might be named similarly.
Task List Groups - When the Task List Group contains generic task lists and will be used by multiple APIs, the name is usually generic. If the Task List Group is only applicable to a particular API the name is usually specific. Appending TLG to the end helps distinguish between Task Lists that might be named similarly.
Redirect Policies - Usually named specific to the Content Policies they are associated to.
Request Filters - If a custom Request Filter is created, it is usually named generically if it will be used by multiple APIs. If the custom Request Filter is specific to a single API, a specific name is used.
Keys - The names usually indicate the key pair name itself, the environment, and the purpose.
Signer Groups - When the group includes CA certs from multiple CAs, the name might be generic. If the group contains CA certs from only a certain CA, the name is usually specific. The purpose of the policy may also be included as well as the type of CRL policy associated.
SSL Termination Policies - Usually named specific to the key pair associated with indication of mutual auth settings.
SSL Initiation Policies - When no authentication options are enabled, the name is usually generic and includes the protocol. When specific certs and Signer Groups are used, the name is usually specific.
Encryption Policies - Usually named specifically for the cert associated or generically for the dynamic encryption mode.
Decryption Policies - Usually named specifically for the key pair associated.
Signature Policies - Usually named specifically for the key pair associated.
Verification Policies - Usually named specifically for the cert associated or generically for the dynamic verification mode.
Error Templates - When the template will be used for multiple APIs the name is usually generic. When the template is specific to an API or workflow task, the name is usually specific.
Documents - Documents are used within Task Lists and can also be reused across APIs or specific to particular API. When the document is a generic structure, a generic name should be used. When the document is specific to an API workflow, a specific name should be used.
IDP Rules - Usually named specific to the type of IDP rule and might include the threshold or enforcement settings.
IDP Groups - Usually named specifically for the API or group of APIs the IDP Group will be applied to.
IDP Actions - Usually named specifically for the action itself with indication of threshold and alerting mechanism.
User ACLs - Usually named specifically for the type of associated access policies and the groups included.
IP ACLs - Usually named specifically for the IP ranges defined and the Allow or Deny designation.
User Groups - Usually named specifically for the type of users within the group.
LDAP Policies - Usually named specifically for the LDAP Root DN (or group) with a designation of type.
Kerberos Policies - Usually names specifically for the Windows domain.