Access Control Lists/Functional Security
Access control is a general security term for grouping application permissions together for the purpose of being granted or denied to a user. This capability is referred to as Authorization, which is the definition of what business functions the user is permitted to perform, after they have been authenticated. The Oracle Transportation Management service has a concept of Access Control Lists (ACL) for authorization. This functionality is also referred to as Functional Security. Within the service, an ACL is a grouping of service specific entry points. These specific entry points include servlets, user interface actions, user interface queries, workflow topics, session beans and the session bean’s public methods, Mbeans and Mbean methods, Log IDs, and a miscellaneous group of Other. Please note that the Other is a catch all list which is used by the service for web service, REST, and specific Power Data entry points.
The most important entry points to be concerned about are both of the types of web services, servlets, user interface actions, user interface queries and the log IDs. The Mbeans and Mbean methods entry points are generated, but not currently checked within the service so they should be ignored. Due to the nature of any web application it is necessary to manage access to functionality at a more granular level than what a user sees on a menu, otherwise users would be able to access functions by entering the corresponding URL directly into the web browser. All of the access control entry points for the service are staged with the Oracle Transportation Management service and are grouped by default into numerous ACLs to help clients use these default ACLs to build up their own custom ACLs.
The Access Control Lists within the service are a very configurable way to control security. The Access Control Lists (ACLs) are hierarchical so an ACL can contain specific entry points and/or other ACLs.
Note: An ACL cannot contain itself, and the same ACL cannot be added more than once to the same ACL hierarchy.
Note: The same ACL can be added more than once through the User / User Role ACL hierarchy. This is redundant, strongly discouraged, and can cause performance overhead.
Within the service, the access control lists are generally user role based, meaning that they are granted or denied at the user role level. This means the permissions that are established or taken away by the ACL would apply to all users that have been assigned the user role. However, individual users can additionally have other ACL granted or denied at the User level. For example, a user with the DEFAULT user role that has the DEFAULT ACL assigned to it could get an additional ACL assigned to them for access to a custom UI action that the rest of the users with the same user role would not have. In addition, the same user with the same user role and ACL could also be denied access to a certain user interface action for shipment manipulation.
Listed below are some important ACLs that need to be understood.
| Access Control List ID | Description |
|---|---|
| COMMON | List common entry points that every user will need. This should be a child ACL of another ACL that would be assigned to a user. |
| everyone | List that contains basic entry points that are required for all users. Do not assign this ACL. |
| Administration | List of administrator-like entry points |
| Diagnostics | List of *most application diagnostic entry points |
| ADMIN | Top Level Parent ACL for all DBA.ADMIN and ADMIN user roles |
| DEFAULT | Top Level Parent ACL for DEFAULT user role. This is the default list of all ACLs. |
| OTM_SYSTEM | ACL for only the otmSystem user and OTM-SYSTEM user role. |
| OTM_GUEST | ACL for only the guest user and OTM-GUEST user role. |
| Power Data - Update | Child ACL for all generic Power Data entry points for record updating |
| INTEGRATION | Top Level Parent ACL that contains all the child External Integration ACL for the external Integration entry points. This ACL is intended for use only for the INTEGRATION user role. |
| External Integration | Child ACL that contains all external Integration entry points. This ACL is intended for use for users and/or user roles other than the INTEGRATION user role that require the ability for external Integration entry points. |
| StackTrace - View | ACL that controls visibility to see application Stack Traces. |
| Mobile Application REST | Parent ACL for the Mobile Application RESTFul web services |
| Common Interface Layer | ACL for the Common Interface Layer RESTFul web services schema metadata. |
| USER_ADMINISTRATION | Top Level Parent ACL for only the USER-ADMINISTRATION user role. |
The COMMON ACL is the default grouping of entry points. Most of the entry points that exist in the COMMON ACL are needed for just the basic navigation capabilities of the application. When creating a new custom ACL, make sure to include the COMMON ACL as a child ACL if it is not already included in a child ACL of another ACL you have included. For example, if I created a new custom ACL that was called MY_CUSTOM_ACL and it included the ADMIN ACL, then COMMON is not required to be included. Yet if MY_CUTOM_ACL only included Shipment – View then COMMON is required.
The ‘everyone’ ACL is another special ACL that needs to be explained. The ‘everyone’ ACL is the ACL which contains specific entry points that every user has and needs access to. The ‘everyone’ ACL does not need to be included as a child ACL in any customer-defined ACL that is created, and may cause exceptions if it is.
The Diagnostics ACL is a grouping of diagnostic and performance monitoring related entry points. For example, the Diagnostics ACL entry points include the Cache and Event Diagnostic servlets. This ACL should only be given to users who need to do diagnostic and performance monitoring.
The Administration ACL contains administration user interfaces and actions. For example, the Administration ACL includes entry points for the properties, scalability topology, and account-related user interfaces. This Administration ACL by default is granted to the ADMIN ACL. The ADMIN ACL is a top level parent ACL that is staged by the service and by default is granted to the DBA.ADMIN and ADMIN user roles that are installed with the service. Care should be given in who is given access to this ACL.
The ADMIN ACL is top level parent ACL and has all of the child ACLs, except for the child ACLs for REST. The ADMIN ACL is granted to the DBA.ADMIN and ADMIN user role that is staged with the product. The ADMIN ACL basically contains access to everything in the service, should only be given to ADMIN type users and never given to individual end service users.
The DEFAULT ACL is another top level parent ACL and has the same child ACLs as the ADMIN ACL, except for the child ACLs of Administration and Diagnostics. The DEFAULT ACL is granted to the DEFAULT user role that is staged with the service. Both the ADMIN and DEFAULT ACLs contain numerous other child ACLs that are groupings of similar functional areas of the service.
The OTM_SYSTEM ACL is only for the otmSystem user and OTM-SYSTEM user role.
The OTM_GUEST ACL is only for the guest user and OTM-GUEST user role.
The StackTrace – View ACL is an ACL that should be used as a child ACL. No default user, user role, or top level parent ACL is granted the StackTrace – View ACL by default.
Oracle Transportation Management Service Entry Points
There are all kinds of different Oracle Transportation Management Service entry points. It is important to understand how to determine what the underlying entry point is for a particular part of service functionality. The next sections will try to describe the format and / or what entry points are available.
Oracle Transportation Management Service User Interface Action Control
The Oracle Transportation Management Service provides a security entry point for each individual Oracle Transportation Management user interface action. The action entry points is based on their ACTION_GID of the underlying action.
The User Interface Action Entry Point will be in this format:
glog.webserver.util.QueryResponseServlet.action.<lower case ACTION_GID>
Oracle Transportation Management Service Web Service Control
The Oracle Transportation Management Service provides a security entry point for each individual Oracle Transportation Management inbound Integration web service. The web service entry points is based on their web service name.
Oracle Transportation Management Service Web Service Access Control Entry Points:
- CommandService
- AgentService
- DriverService
- GtmRestrictedPartyService
- OrderMovementService
- OrderReleaseService
- SellSideShipmentService
- ShipmentService
- GtmSanctionedTerritoryService
- IntXmlService
- MessageService
- IntGtmXmlService
All of the Oracle Transportation Management Service Web Service Access Control Entry Points are grouped into the child "External Integration" Access Control List by default.
Oracle Transportation Management Service REST Control
The Oracle Transportation Management Service provides a security entry point for each individual REST API URI in combination with the individual Oracle Transportation Management Service Business Entity. The RESTFul Web Service Entry Points are based on their URI path and HTTP Request Method, instead of being based on underlying code classes and classname; as is done with most of the other resources.
Please see the Resource Paths and the All REST Endpoints sections of the REST API for Transportation and Global Trade Management Cloud Guide for more information about determining relative REST API URIs.
The version 2 REST Entry Points will be in this format:
/resources/{version}/(Resource URI Path)(SPACE)(DASH)(SPACE)(HTTP Request Method)
Examples of Version 2 of the Oracle Transportation Management Service Business Entity REST Access Control Entry Points:
/resources/{version}/shipments – GET/resources/{version}/shipments – POST/resources/{version}/shipments - PATCH/resources/{version}/shipments - DELETE
Examples of Oracle Transportation Management Mobile Service REST Access Control Entry Points:
/api/shipment/add_event - POST/api/shipment/tender - POST/api/shipment – GET
The version 1 of the REST Entry Points will be in this format:
/api/sdo/(Resource URI Path)(SPACE)(DASH)(SPACE)(HTTP Request Method)
Examples of Deprecated Version 1 of the Oracle Transportation Management Service Business Entity REST Access Control Entry Points:
/api/sdo/Shipment – GET/api/sdo/Shipment - PUT/api/sdo/Shipment – POST/api/sdo/Shipment – DELETE
All of the Mobile Oracle Transportation Management Service REST Access Control Entry Points are grouped into child ACLs of the “Mobile Application REST” Access Control List. The “Common Interface Layer” Access Control List only contains the Oracle Transportation Management Service Business Entity REST API Schema Metadata retrieval related entry points. While each individual REST Oracle Transportation Management Service Business Entity supported, has its own corresponding Access Control List. These REST Oracle Transportation Management Service Business Entity Access Control Lists are not granted to any user role or user by default.
Examples of Oracle Transportation Management Service Business Entity REST Access Control Lists:
- REST - Shipment – View
- REST - Shipment – Update
- REST - Item – View
- REST - Item – Update
Important Warning!
There are Access Control Lists that must be granted to User, User Roles, or Access Control Lists for any end user to gain access to use these Oracle Transportation Management REST APIs. These Access Control Lists are "Mobile Application REST" and "Common Interface Layer" and numerous other Oracle Transportation Management Business Entity specific ACL ("REST - <BUSINESS ENTITY> – View"). The "Mobile Application REST" ACL is for all of the Mobile related APIs, while the "Common Interface Layer" ACL only contains the Oracle Transportation Management Business Entity REST API Schema Metadata retrieval related entry points. The "REST - <BUSINESS ENTITY> - View" or "REST - <BUSINESS ENTITY> - Update" Access Control Lists will contain the entry points needed for the HTTP Method operations on that specific Oracle Transportation Management Service Business Entity.
Access Control Lists will need to be granted to whatever end users that needs to use these RESTFul web services for both Mobile and the Oracle Transportation Management Service Business Entity REST APIs. See below for details.
Regarding the "Mobile Application" ACL APIs:
For any user, user role, or ACL that requires use of the Mobile REST APIs, you will have to add the new 'Mobile Application REST' Access Control List to your user, user role, or ACL hierarchy.
Regarding REST Oracle Transportation Management Service Business Entity Access Control Lists:
For any user, user role, or ACL that requires use of the Oracle Transportation Management Service Business Entity REST APIs, you will have to add the correct "REST - <BUSINESS ENTITY> - View" or "REST - <BUSINESS ENTITY> - Update" Access Control List to your user, user role, or ACL hierarchy.
Regarding the "Common Interface Layer" ACL APIs:
Most users will not need the "Common Interface Layer" ACL. If you use a user that uses the default "ADMIN" user role or "ADMIN" ACL and you want to Oracle Transportation Management Service Business Entity REST API Schema, you will be fine for the Common Interface Layer web service APIs. There is nothing for you to do. If you have a customer-defined user role or customer-defined ACL, you will need to add the new "Common Interface Layer" Access Control List to your user role or ACL hierarchy.
Customer-Defined User Interface Action Control
Customers can control access for customer-defined User Interface actions. The customer-defined actions capabilities include a customer-defined action for a report, a custom action that runs an agent action, a customer-defined action that is set up for a customer-defined RIQ screen and any other configurable action. There is a UI action called "Secure Action" is available from the Action Manager UI. This action should be used to create the required security entry point and to ensure proper Access Control List Role assignment. The required entry point records are created when the "Secure Action" action is ran.
The new Custom Action Entry Point created will be in this format:
glog.webserver.util.QueryResponseServlet.action.<custom_action_gid>
Individual Generic Power Data User Interface Control
The Oracle Transportation Management Service provides a security entry point for each
individual generic power data edit screen. Currently, there are two access control
lists that control all of access to the generic power data screens. These are "Power
Data – View" and "Power Data – Update". These ACLs control use of all of the generic
power data at a very high level and provide access to all power data screens or no
power data screens. This high level is at a generic servlet level that provides the
generic capability of power data screens. These generic servlets used for power data
are the glog.webserver.powerdata.GenericManagementServlet
and glog.webserver.powerdata.GenericSaveServlet. In addition to
the all or nothing option, you could also restrict generic power data via the
corresponding UI query security entry point to prevent new records and editing of
records. However, there is certain data that end users need to be able to query from
the UI in a picklist or dropList and denying access to the query would not have
allowed this. This is why there is functional security for each individual generic
Power data screen to provide extra granularity of control.
The Generic Power Data Entry Points will be in this format:
glog.webserver.powerdata.GenericSaveServlet.powerdata.<(typically)lower_case_table_name>
List of a few examples:
glog.webserver.powerdata.GenericSaveServlet.powerdata.equipment_refnum_qualglog.webserver.powerdata.GenericSaveServlet.powerdata.s_ship_unit_refnum_qualglog.webserver.powerdata.GenericSaveServlet.powerdata.sku_cost_type
All of the individual related generic Power Data entry points are grouped into the "Power Data – Update" access control list.
glog.webserver.powerdata.GenericManagementServlet
glog.webserver.powerdata.GenericSaveServlet.Individual Process Control Topic Control
The Oracle Transportation Management Service provides a security entry point for each individual process control topic screen menu. Access is checked using the entry point format below when actually rendering the process control menu. These menus have the URL format of:
glog.webserver.processcontrol.ProcessServlet?[application=<a>]&[userLevel=<ul>]
There are access entry points records that will have a similar format of
processcontrol.level.<ul>[.<a>] to match these URLs. If
the <ul> is missing, then "default" will be assumed.
For each of these new entry points, an access entry point record is added as follows:
- If the
<a>is missing, the entry point is assigned to Administration. - If
<ul>is "default", the entry point is assigned to COMMON. - Otherwise, the entry point is assigned to Administration.
This Topic access check will occur during the rendering of the topic parameters and not during topic submission. The user will get an access violation (if any), when they click on a process control topic they do not access to.