Securing Web Services

This chapter covers the following topics:

• Overview
• Managing Function Security and Data Security
• Managing Role-Based Access Control Security
• Managing MOAC Security
• Managing Web Service Security

Overview

Security is the most critical feature that is designed to guard service content from unauthorized access.

To ensure secure access to Web service content and the execution of integration interfaces and services, Oracle E-Business Suite integrated SOA Gateway uses the following approaches to enforce the security:

• Function Security and Data Security

• Role-Based Access Control (RBAC) Security

• Multiple Organization Access Control Security (MOAC Security)

• WS-Service Security (Web Service Security)

Managing Function Security and Data Security

By leveraging Oracle User Management function security and data security, Oracle E-Business Suite Integrated SOA Gateway provides a security feature which only allows users with authorized privileges to access or execute certain methods of an integration interface exposed through Oracle Integration Repository. This protects application data from unauthorized access or execution of the Java methods or functions within an API without security checks.

Function security is the basic access control in Oracle E-Business Suite. It restricts user access to individual menus and menu options within the system regardless of which application data in the row. Regardless of the interface types, APIs are stored procedures that enable you to insert and update data in Oracle E-Business Suite. When having the function security layer enforced on the access to an API, it actually implicitly restricts the data access to the application.

Building on function security, data security provides another layer of security control to model and enforce security authorizations of specific data records. In other words, data security further refines the security of accessing application records down to the data level.

To allow appropriate users with right privileges to execute certain methods within an API, the concept of security grant is used to reinforce the security with a flexible mechanism. This approach enables the data access privileges to be granted to an appropriate user, user group, or all users. To accomplish this, the interface methods of an inbound API are precreated as permissions and stored in AOL's function repository. An Integration Repository Administrator can select one or more methods contained in an API and then grant the selected method(s) to appropriate users.

An integration repository administrator can create security grants in the following ways:

• If an inbound service-enabled interface has only one method, then this single method will be the default selection in creating grants.

  Concurrent Program interface type contains only one method. User security for XML Gateway interface is managed in Oracle XML Gateway user interface.

• If there is more than one method contained in an interface, then the administrator can have a choice in either granting one method to appropriate users or granting multiple methods simultaneously to the users.

  Interface types containing multiple methods are PL/SQL, Business Service Object, Java interface, and Open Interface Table and View.

Creating Security Grants

Only integration repository administrators (or users who have the Integration Repository Administrator role) can create security grants by authorizing the access permission of a selected interface method or procedure and function to an appropriate user, user group, or all users.

Security grants are managed in the Grants tab for the interface types that can be exposed as REST services. These interfaces include PL/SQL APIs, Concurrent Programs, Business Service Objects, Java Bean Services, Application Module Services, and Open Interface Tables and Views. See: Managing Grants for Interfaces with Support for SOAP and REST Services.

Note: XML Gateway interfaces can be exposed as SOAP services only, but the user security is managed in the Oracle XML Gateway user interface through the Trading Partner User Setup form. See: Managing XML Gateway User Security in the Trading Partner User Setup Form.

For more information on function security and data security, refer to the Oracle Application Object Library Security chapter, Oracle E-Business Suite Security Guide.

Managing Role-Based Access Control Security

To allow only authorized users to perform certain administrative tasks, Oracle E-Business Suite Integrated SOA Gateway leverages Oracle User Management Role-Based Access Control (RBAC) security to build another layer of security. This RBAC security is enforced through user roles. As a result, whether a user can perform certain tasks, such as downloading a composite service from the application server, is determined by the roles granted to the user.

This approach builds upon Data Security and Function Security, but it goes beyond both of them.

Role-Based Access Control Security

As described earlier, function security is the base layer of access control in Oracle E-Business Suite. It restricts user access to individual menus and menu options within the system, but it does not restrict access to the data contained within those menus. Data security provides access control on the application data, and the actions a user can perform on the data. With data security, users can be restricted by security rules to access or view only certain types of data on the screen once they have selected a menu while an administrator can have more data access to the same page.

With RBAC, access control is defined through roles, and a role can be configured to consolidate the responsibilities, permissions, permission sets, and function security policies that users require to perform a specific function. This simplifies mass updates of user permissions because changes can be done through roles which will inherit the new sets of permissions automatically. Based on the job functions, each role can be assigned a specific permission or permission set if needed. For example, an organization may include 'Analyst', 'Developer', and 'Administrator' roles. The 'Administrator' role would include a permission set that contains all administrative related tasks or functions allowing the administrator role to perform a job function while the Analyst and Developer roles may not have the access privileges.

Role-Based Access Control (RBAC) Security for Oracle E-Business Suite Integrated SOA Gateway

By leveraging the concept of permission sets, each Integration Repository administrative function used in Oracle E-Business Suite Integrated SOA Gateway is first created as a permission and then relevant permissions are grouped into a permission set. Permission sets will then be associated with appropriate function roles and assigned to appropriate users through security grants.

Oracle E-Business Suite Integrated SOA Gateway uses the following seeded permission sets to restrict administrative privileges only to authorized users:

• Integration Repository Administrator Permission Set (FND_REP_ADMIN_PERM_SET)

• Integration Repository Download Composite Service (FND_REP_DOWNLOAD_PERM_SET)

Integration Repository Administrator Permission Set

The Integration Repository Administrator Permission Set (FND_REP_ADMIN_PERM_SET) contains almost all administrative tasks performed by the Integration Repository Administrator role. It consists of the following administrative permissions:

Integration Repository Administrator Permission Set

Privilege	Permission	Permission Display Name
Generate/Regenerate	FND_REP_GENERATE	Generate Web Service
Deploy/Redeploy	FND_REP_DEPLOY	Deploy Web Service
Undeploy	FND_REP_UNDEPLOY	Undeploy Web Service
Subscribe to Agent	FND_REP_SUBSCRIBE	Subscribe to Agent
Create Grants	FND_REP_METHOD_GRNT	Grant execute privileges to methods

Please note that the Deploy/Redeploy and Undeploy privileges are intentionally kept as separate permissions. This allows further security restriction on the service undeployment if needed.

Integration Repository Download Composite Service Permission Set

Because the download composite service feature can be performed by appropriate users not limited to the users with administrator or developer role, this feature has it own permission set called Integration Repository Download Composite Service Permission Set (FND_REP_DOWNLOAD_PERM_SET) which is separated from the Integration Repository Administrator Permission Set described earlier. This approach allows the download feature to be granted separately to appropriate users through the Integration Repository Administrator role, System Integration Developer role, or System Integration Analyst role if necessary.

Integration Repository Download Composite Service Permission Set

Privilege	Permission	Permission Display Name
Download Composite Service	FND_REP_DOWNLOAD_CS	Download Composite Service

Managing MOAC Security

Multiple organizations can be sets of books, business groups, legal entities, operating units, or inventory organizations. You can define multiple organizations and the relationships between them in a single installation of Oracle E-Business Suite.

To have a secured way for users to only access data for the operating units they have access to, Oracle E-Business Suite Integrated SOA Gateway uses the MOAC security feature to determine the operating unit access and derive the Organization ID based on relevant profile values.

With MOAC, a system administrator can predefine the scope of access privileges as a security profile, and then use the profile option MO: Security Profile to associate the security profile with a responsibility. By using this approach, multiple operating units are associated with a security profile and the security profile is assigned to a responsibility. Therefore, through the access control of security profiles, users can access data in multiple operating units without changing responsibility.

Security profiles are defined based on organization hierarchies. For example, a sales company consists of USA and UK operating units; the USA operating unit has Western Region Sales and East Region Sales. Sales managers are responsible for both USA and UK sales, supervisors are responsible for either USA or UK, and sales representatives are only responsible for their designated sales regions. The Sales organization hierarchy can be illustrated as follows:

Sales Organization Hierarchy

To secure sales data within the company, relevant operating units can be associated with predefined security profiles. For example, all sales data access privileges are grouped into the Vision Sales security profile. A USA Sales security profile is for USA related data, and a regional security profile is for designated regional data. The system administrator can associate these security profiles containing multiple operating units with users through appropriate responsibilities. Therefore, sales supervisors can easily access sales data in the Eastern or Western region without changing their responsibilities. The following diagram illustrates the relationship between security profiles, responsibilities, and operating units for this sales company:

Relationship Diagram Between Security Profiles, Responsibilities, and Operating Units

Responsibility Determines Operating Units

Because responsibilities are associated with security profiles that are linked to operating units, your responsibility is the key to determine which operating units you will have the access privileges.

In addition to the MO: Security Profile profile option, MOAC security uses the following profile options to regulate the operating units access in a multi-organization environment:

• MO: Operating Unit

  Use this profile option if you want to access only one operating unit through a single responsibility. In this case, the responsibility determines the Organization ID.

  However, if you also define the MO: Security Profile profile option, then the MO: Operating Unit profile option will be ignored.

• MO: Security Profile

  Use this profile option if you want to access multiple operating units through a single responsibility.

  Because you can access multiple operating units without changing your responsibility, you need to set this profile value with multiple operating units. In addition, you must set the default operating unit in the MO: Default Operating Unit profile option. This allows the default Organization ID can be identified and entered to default organization for the context sensitive applications without requiring you to explicitly specify the Organization ID.

  Additional Information: The security profile allows you to assign multiple operating units for the same business group; global security profile allows you to assign multiple operating units across business groups. Based on your HR implementation and how you want to partition the data, you can decide which security profile would be good for you and meet your business needs.

• MO: Default Operating Unit

  Use this profile option in conjunction with the MO: Security Profile profile option to specify a default operating unit. This profile value determines the application entries once you log on to the system.

The following diagram illustrates how Oracle E-Business Suite uses the profile options in a multi-organization environment.

Applications Context for Multiple Organizations

1. When the system integrator runs, the process achieves the integration with Oracle E-Business Suite using PL/SQL APIs.

2. The Apps.Initialize process takes the parameters of Username and Responsibility.

3. With these parameters, a lookup on all System Profile Values assigned to that responsibility is done to determine the Operating Unit within a multi-organization environment.

4. The Operating Unit is modeled as Organization ID derived from the security profile values, such as the values in MO: Operating Unit or MO: Security Profile profile options.

5. The data is read and written into the Oracle E-Business Suite with the parameters of Username, Responsibility and Organization ID.

Managing Web Service Security

Web service security (WS-Security) is a specification to enable applications to conduct secure message exchanges. It proposes a standard set of extensions that can be used when building secure Web services to implement message content integrity and confidentiality. It also provides support for multiple security tokens, the details of which are defined in the associated profile documents.

To secure Web service content and authenticate Web service operation, Oracle E-Business Suite Integrated SOA Gateway supports multiple authentication types for inbound service requests through the following security mechanisms:

• For SOAP Services

  • UsernameToken Based Security

  • SAML Sender-Vouches Token Based Security

  At design time, an integration repository administrator must select one authentication type before deploying a service. If no authentication type is identified for the service, then a validation error occurs.

  SOA Provider supports the selected authentication type(s) during the service deployment cycle. When a SOAP request message is received through SOA Provider, the SOAP message is passed on to OC4J Web Service Framework for authentication based on the selected authentication type(s).

  If the authentication type of a deployed SOAP service needs to be changed, the administrator must first undeploy the SOAP service, make appropriate changes, regenerate the SOAP service, and then deploy it again. For more information on how to deploy and undeploy SOAP services, see: Deploying and Undeploying SOAP Web Services.

• For REST Services

  • HTTP Basic Authentication

  • Token Based Authentication

  All REST services are secured by either HTTP Basic Authentication (username and password) or Token Based Authentication (username and a valid token, such as Oracle E-Business Suite session ID).

UsernameToken Based Security

In the UsernameToken based security mechanism, the username/password is sent in the SOAP header. The SOA Provider authenticates the user based on this information. The username/password sent with the SOAP header is associated with the User created in Oracle E-Business Suite.

Username is a clear text; password is the most sensitive part of the UsernameToken profile. In this security model, the supported password type is plain text password (or PasswordText).

Note: The PasswordText password type is the password written in clear text. SOAP requests invoking the Web services should include security header consisting of Username and plain text password. Encryption is not supported in this release.

When a SOAP request message is received through SOA Provider, the SOAP message is passed on to OC4J Web Service Framework for authentication. The framework authenticates the SOAP message based on the wsse:security Web Security headers.

A basic UsernameToken security header can be explained as follows:

<S11:Envelope xmlns:S11="..." xmlns:wsse="...">
 <S11:Header>
...
   <wsse:Security>
   <wsse:UsernameToken>
     <wsse:Username>sysadmin</wsse:Username>
     <wsse:Password>password</wsse:Password>
     </wsse:UsernameToken>
   </wsse:Security>
...
  </S11:Header>
...
</S11:Envelope>

A typical WS-Security header in the SOAP message from Oracle E-Business Suite can be as follows:

<xml version="1.0" encoding="UTF-8"> 
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 
 <env:Header>

        <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wsswssecurity-secext-1.0.xsd>
         <wsse:UsernameToken>
     <wsse:Username>sysadmin</wsse:Username>
     <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">password</wsse:Password>
     </wsse:UsernameToken>
  </wsse:Security>
 </env:Header>

 <env:Body>
...
 </env:Body> 
</evn:Envelope>  

SAML Sender-Vouches Token Based Security

To authenticate Web services relying on sending an username only through SAML assertion, Oracle E-Business Suite Integrated SOA Gateway supports SAML Token (Sender Vouches) based Web service security.

Security Assertion Markup Language (SAML) is an XML-based standard for exchanging authentication and authorization data between security domains, that is, between an identity provider and a service provider.

How to Authenticate Users through a Trusted Sender-Vouches SAML Token

A SAML token uses SAML assertions as security tokens. One type of SAML token is the sender-vouches SAML token. This token uses a method called a sender-vouches method to establish the correspondence between a SOAP message and the SAML assertions added to the SOAP message.

When a Web application invokes a service that uses SAML as its authentication mechanism, this SOAP request message containing or referencing SAML assertions is received through SOA Provider and passed on to OC4J Web Service Framework for authentication. The framework authenticates the SOAP message based on the wsse:security Web Security headers. As part of the validation and processing of the assertions, the receiver or authentication framework must establish the relationship between the subject, claims of the referenced SAML assertions, and the entity providing the evidence to satisfy the confirmation method defined for the statements.

In other words, in order to validate and authenticate a non-Oracle E-Business Suite user, but logged on to the enterprise information system, a trusted sender-vouches SAML token security mechanism must be used to establish the correspondence between the SOAP message and the SAML assertions added to the SOAP message.

Note: Since anyone can send a SAML Token with valid conditions, the authentication framework only trusts certain SAML token sources and stores the public key of each of these sources in a common key store. This Public Key Infrastructure (PKI) based security provides more sophisticated trusted rules to authenticate Web services.

Important: To ensure SAML Token security works properly, necessary setup steps need to be performed. For setup instructions, see Installing Oracle E-Business Suite Integrated SOA Gateway, Release 12, My Oracle Support Knowledge Document 556540.1. For more SAML Token security information, see Oracle E-Business Suite Integrated SOA Gateway Release Notes for Release 12.1.3, My Oracle Support Knowledge Document 1096553.1.

To authenticate users, any entity that establishes a PKI trust with Oracle E-Business Suite Integrated SOA Gateway can send the SAML Assertion with a valid Username. A PKI trusted entity will send a SAML token profile with the username embedded with it and that must be digitally signed. Once the SAML token is validated by the OC4J authentication framework (SAMLLoginModule), the SAML principal (username in NameIdentifier) will be obtained and verified against LDAP for Single Sign-On (SSO) users or Oracle E-Business Suite FND_USER for non-SSO users.

The following diagram illustrates the sender-vouches SAML Token based security authentication process flow:

1. A trusted application authenticates an user and creates a digitally signed SOAP request, containing a SAML Sender-Vouches Token.

   Please note that a trusted application can be any application whose Public Key is known to Oracle E-Business Suite Integrated SOA Gateway and which can send digitally sign SAML Assertions in SOAP requests using that public key.

2. Oracle E-Business Suite Integrated SOA Gateway authentication layer verifies the digital signature and extracts the SAML Token after the verification.

3. OC4J SAMLLoginModule verifies the SAML conditions to ensure that it is a valid SAML Token.

   After the verification, OC4J SAMLLoginModule extract the SAML name identifier from the token. Application LDAPLoginModule connects to LDAP to verify if the name identifier specified in the SAML_SUBJECT_NAMEID exists in OID.

   • If it does exist, the associated orclguid will be retrieved and mapped that to an Oracle E-Business Suite user with an equivalent orclguid for SSO users.

   • If it does not exist, the associated orclguid will be mapped to an actual user in FND_USER table through the connection of OID to locate the user in FND_User table who has the equivalent orclguid. This authenticates the non-SSO users.

   The format of the NameIdentifier indicates if the user has been authenticated against LDAP (SSO user) or Oracle E-Business Suite FND_USER (for non-SSO user). If the format is dn=xxxx, then this is a SSO user that has been authenticated against LDAP. Otherwise, this is a non-SSO user that has been authenticated against Oracle E-Business Suite FND_USER.

A sample sender-vouches SAML assertion for a non-SSO environment can be as follows:

<Assertion AssertionID="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" IssueInstant="2010-02-27T17:26:21.241Z" Issuer="www.oracle.com" MajorVersion="1" MinorVersion="1" xmlns="urn:oasis:names:tc:SAML:1.0:assertion"  xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol"><Conditions NotBefore="2010-02-27T17:26:21.241Z" NotOnOrAfter="2011-02-27T17:26:21.241Z"/>  
        <AuthenticationStatement AuthenticationInstant="2010-02-27T17:26:21.241Z" AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:password">
                <Subject>
                                <NameIdentifier Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" NameQualifier="notRelevant">SYSADMIN</NameIdentifier>
                                <SubjectConfirmation>
                                <ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:sender-vouches</ConfirmationMethod>
                                </SubjectConfirmation>
                </Subject>
        </AuthenticationStatement>
</Assertion>

A sample sender-vouches SAML assertion for a SSO environment can be as follows:

<Assertion
IssueInstant="2010-02-27T17:26:21.241Z" Issuer="www.oracle.com"
MajorVersion="1" MinorVersion="1" 
xmlns="urn:oasis:names:tc:SAML:1.0:assertion"
xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol"><Conditions 
NotBefore="2010-02-27T17:26:21.241Z"
NotOnOrAfter="2011-02-27T17:26:21.241Z"/>
<AuthenticationStatement 
AuthenticationInstant="2010-02-27T17:26:21.241Z" 
AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:password">
                <Subject>
                                <NameIdentifier Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" 
                                 NameQualifier="notRelevant">orclApplicationCommonName=PROD1,cn=EBusiness,cn=Products,cn=OracleContext,dc=us,dc=oracle,dc=com</NameIdentifier>
                                <SubjectConfirmation>
                                <ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:sender-vouches</ConfirmationMethod>
                                </SubjectConfirmation>
                </Subject>
        </AuthenticationStatement>
</Assertion>

• Issuer: The value of this attribute should be defined in the system-jazn-data.xml as part of the LoginModule.

• Conditions: This tag defines the time limit in which this SAML Assertion is valid.

• NameIdentifier: The value of this tag contains the username.

  If the username is of the form of LDAP DN, then the username is verified in the registered OID for SSO user. Otherwise, the username is verified in FND_USER table for non-SSO user.

• SubjectConfirmation: It should be sender-vouches.

For information on how the SAML Token (sender vouches) type is used in SOAP security header to authenticate Web services, see SAML Token-based SOAP Security Header, Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.

HTTP Basic Authentication

Oracle E-Business Suite Integrated SOA Gateway supports HTTP Basic Authentication security to authenticate the users who invoke REST services over secure transport protocol – HTTPS.

When an HTTP client application tries to access an Oracle E-Business Suite REST service, user security credentials (username/password) should be provided as input data in HTTP header as part of the REST request message. The username and password will be routed to LoginModule for authentication and authorization.

The LoginModule in turn extracts the credentials from HTTP header, authenticates user against Oracle E-Business Suite user table, and establishes identity for the authenticated user.

• For the authenticated and authorized user request, a security service is invoked to initialize the applications context, and then the REST service is executed.

• For the unauthenticated or unauthorized user request, a system fault is returned to the client.

The following diagram illustrates the authentication process flow of HTTP Basic Authentication security:

Authentication Process Flow for HTTP Basic Authentication Security

Based on HTTP Basic Authentication defined by W3C, the HTTP client application should use the following header field to send user credentials:

Authorization: Basic <base64 encoded version of username:password>

Please note that if it is a SSO-enabled Oracle E-Business Suite environment, user authentication should be delegated to SSO which performs authentication against information stored in Oracle Internet Directory (an LDAP server).

Token Based Authentication

Token based security authenticates users using security tokens provided by the server. When a user tries to log on to a server with multiple requests, instead of authenticating the user each time with username and password, a unique access token (such as Oracle E-Business Suite session ID) may be sent as Cookie in HTTP header.

For example, when an Oracle E-Business Suite user has initially authenticated on a given username and password, after successful login, the security Login service creates an Oracle E-Business Suite user session and returns the session ID, as shown in the following:

<response>
<data>
<accessToken>xxxxxxxxxxxxxxxxxxxxxxxxxx</accessToken>
<accessTokenName>myEbsInstance</accessTokenName>
<ebsVersion>12.2.0</ebsVersion>
<userName>SYSADMIN</userName>
</data>
</response>

The session ID that points to the user session will be passed as Cookie to HTTP headers of all subsequent Web service calls for user authentication.

POST /webservices/rest/Invoice/create_invoice
Cookie: <accessTokenName>=<accessToken>
Content-Type: application/xml

The LoginModule will interpret and extract the token (session ID) from HTTP headers, and validate the subject or username with token, not password, in the subsequent requests for authentication.

Similar to the HTTP Basic Authentication security, if the request passes the authentication and authorization, a security service is invoked to initialize the applications context, and then the REST service is executed. Otherwise, system fault is returned.

The following diagram illustrates the authentication process flow of Token Based Authentication security:

Authentication Process for Token Based Authentication Security

In this diagram, username/password information is provided and validated in the initial request. A unique token (EBS Token1) is obtained through the Login Service for the valid user. In case a different service is requested in the subsequent call, username along with the token, instead of the password, are provided in the header this time.

In this subsequent request, applications context information that may be required in initializing Oracle E-Business Suite session is also provided in the request. Security LoginModule will be used to interpret and extract the token from the header to authenticate the user and then authorize the request. Applications context session will also be initialized before invoking the REST service. After a successful service invocation, a response message will be sent along with the response payload if it is available.

Advantages of Using Token Based Security

Please note that when token based security is used, applications context information mentioned above does not have to be passed in every request. If the context values are not provided in the consecutive requests, the previously passed values will be used.

This will reduce the size of the payload included in HTTP headers and thus less data bandwidth is required. It is particularly useful for mobile data networks.

For more information on applications context in REST header, see REST Header for Applications Context, Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.

For more information about how to use context values to initialize or re-initialize the Oracle E-Business Suite session, see the Oracle Application Object Library REST Security Services section, Oracle E-Business Suite Security Guide.