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've 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, Log IDs, and a miscellaneous group of Other. 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. Due to the nature of any web application it's necessary to manage access to functionality at a more granular level than what a user sees on a menu, otherwise users can access functions by entering the corresponding URL directly into the web browser. All the access control entry points for the service are staged with the Oracle Transportation Management service and are grouped by default into many 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.
Within the service, the access control lists are generally user role based, meaning that they're 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 wouldn't 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.
Most business entities within the service have 3 separate and distinct staged ACLs for the user interfaces. These 3 separate ACLs per entity consist of a "-View", "- Update", and an "Actions" ACL. For example the business entity of Shipment has a "Shipment – View", "Shipment – Update", and a "Shipment Actions" ACL. The "View" will allow the business entity user interface data to be visible. The "Update" will allow the business entity user interface data to be updatable. The "Actions" will allow the business entity user interface actions to be run. Please note that these business entities aren't all inclusive to contain all the other related business entities. Each business entity is separate.
Listed below are some important ACLs that need to be understood.
Access Control List ID | Description |
---|---|
COMMON | List of common entry points that every user will need. This should be a child ACL of another ACL that would be assigned to a user. |
GTM_COMMON | List of common entry points that every GTM user will need. This is a child ACL of COMMON and does not need to be granted again. |
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 |
GTM_ADMIN | Top Level Parent ACL for all GTM ACLs. This is a child ACL of ADMIN and doesn't need to be granted again to ADMIN users. |
DEFAULT | Top Level Parent ACL for DEFAULT user role. This is the default list of all ACLs. |
GTM_DEFAULT | Top Level Parent ACL for most GTM ACLs. This is a child ACL of DEFAULT and does not need to be granted again to DEFAULT users. |
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 all 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 isn'talready included in a child ACL of another ACL you've included. For example, if I created a new custom ACL that was called MY_CUSTOM_ACL and it included the ADMIN ACL, then COMMON isn'trequired 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 doesn't need to be included as a child ACL in any customer-defined ACL that's created, and might 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's 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's given access to this Administration ACL.
The ADMIN ACL is top level parent ACL and has all the child ACLs, except for the child ACLs for REST. The ADMIN ACL is granted to the DBA.ADMIN and ADMIN user role that's 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's staged with the service. Both the ADMIN and DEFAULT ACLs contain many other child ACLs that are groupings of similar functional areas of the service. The DEFAULT ACL isn't recommended for actual use because it provides access to all business functionality in 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 External Integration ACL is a Child ACL that contains all external Integration entry points. This ACL should be used as a reference when creating users and/or user roles that require the ability for external Integration entry points. A custom External Integration ACL should be created to only allow access to the specific external Integration entry points required.
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 Control
The Oracle Transportation Management Service provides a security entry point for each
individual Oracle Transportation Management user interface. Typically for a business
entity user interface, there will be at least three relevant entry points required
in order for proper access and complete functionality. Please note that they could
be more entry points or even less entry points required depending on each individual
user interfaces. For a business entity interface, there's a "Query" entry point
which typically will contain the underlying database table name. For example,
"glog.server.query.rate.RateGeoQuery
". This "Query" entry point
controls the ability to actually query the records in the table from a query screen
set or a user interface field component. Typically, this "Query" entry point will be
grouped by default into a <Business Entity> - View ACL
. Next,
there will be at least two an associated "Servlet" entry points. These "Servlet"
entry points are a "ManagementServlet" and a "SaveServlet". The "ManagementServlet"
controls the ability to actually view the business entity data and will be grouped
by default into a <Business Entity> - View ACL
. While the
"SaveServlet" controls the ability to save the business entity data and will be
grouped by default into a <Business Entity> - Update ACL
. For
example, the management servlet is
"glog.webserver.rate.RateGeoManagementServlet
" and the save
servlet is "glog.webserver.rate.RateGeoSaveServlet
" There might be
additional entity points related to the user interface like an "Add*Servlet", a
"Delete*Servlet" or an "UpdateServlet". In addition, for more specialized user
interfaces, there may be additional low level code method entry points which are
required for proper functionality.
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>
User-Defined User Interface Action Control
You can control access for user-defined User Interface actions. The user-defined actions capabilities include a user-defined action for a report, a custom action that runs an agent action, a user-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.
glog.webserver.util.QueryResponseServlet.action.<custom_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.
-
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.
<BUSINESS ENTITY>
should be replaced with the actual business
entity.-
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.
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_qual
glog.webserver.powerdata.GenericSaveServlet.powerdata.s_ship_unit_refnum_qual
glog.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 a process control topic they don't access to.
Code Method Entry Points
The Oracle Transportation Management Service provides a security entry point for individual low level code method entry points. These are very difficult to explain and understand. It isn't recommended for you to use these unless these are strongly understood or directed by Oracle Support.