Implementation Guide for Oracle Self-Service E-Billing > Customizing User Management >

Customizing Spring Security

Oracle Self-Service E-Billing uses the Spring Security framework for authentication and user access control. You can customize the Spring Security configuration for your implementation. Spring Security settings are maintained in the spring-security.xml file.

The following code defines the UsernamePasswordAuthenticationFilter filter that handles form authentication in the spring-security.xml file:

<security:http access-decision-manager-ref="accessDecisionManager">

<security:logout logout-success-url="/nonAuth/logout.action"/> <security:access-denied-handler error-page="/accessDenied.action"/> <security:form-login login-page="/nonAuth/login.action" default-target-url="/reporting/reportStart.action" authentication-failure-url="/nonAuth/login.action?login_error=1"/>

......

......

</security:http>

Spring Security maintains a filter chain internally where each filter has a particular responsibility and filters can be added or removed from the configuration depending on which services are required. The ordering of the filters is important as there are dependencies between them. If you are using namespace configuration, then the filters are configured automatically.

The form-login element invokes the UsernamePasswordAuthenticationFilter. Spring Security adds the filter in the filter chain automatically, and adds an LoginUrlAuthenticationEntryPoint to the application context to provide authentication on demand.

DaoAuthenticationProvider from Spring Security is implemented for authentication. DaoAuthenticationProvider leverages a UserDetailsService in order to lookup the username, password and GrantedAuthority[]s. IBillingUserDetailsService extends UserDetailsService and the implementation class implements loadUserByUsername(String userId) method to provide the authentication mechanism. This method returns the IBillingUserDetails object.

Customizing Authorization

Authorization in Oracle Self-Service E-Billing is based on roles and permissions. Each user is assigned a role. Authorization to access a particular resource is determined by the permissions for a user's role. These permissions are defined in the azpolicy file. Permission is represented by an object called EBillingPermission.

User roles are grouped to form high-level roles, called azPolicyRoles, and permissions are assigned to the azPolicyRoles.

Role mapping is defined in the WEB-INF/classes/azcfg.properties subdirectory, under the application directories for the EAR and WAR files.

The following examples show how to map azPolicyRoles:

com.edocs.common.security.rolemappers.secrole.ALL_USERS=Admin,User, Payer,Manager, Subscriber,CSR,CSRAdministrator

com.edocs.common.security.rolemappers.secrole.ADMIN=Admin

com.edocs.common.security.rolemappers.secrole.MANAGER=Manager

com.edocs.common.security.rolemappers.secrole.SUBSCRIBER=Subscriber

com.edocs.common.security.rolemappers.secrole.CSR=CSR

com.edocs.common.security.rolemappers.secrole.CSR_ADMIN=CSRAdministrator

Once user roles are mapped to azPolicyRoles, define permissions for resources in the azpolicy.xml file, found in the /WEB-INF/classes/azcfg/policy subdirectory, under the application directories for the EAR and WAR files.

Example of sample permission code:

<permission>

<name>perm_company_tab</name> <cpath>com.edocs.common.security.authorize.az.permissions.EBillingPermission</ cpath>

<rule>

<name>admin</name> <!--Defines the name of the rule -->

<type>SecurityRole</type> <!-- Type of the rule -->

<values>ADMIN</values> <!-- The role(s) which can access this resource, comma separated. Note it can be an alias defined in azcfg.properties -->

</rule>

</permission>

A permission called perm_company_tab is defined to control the company UI tab. This permission specifies that the company tab is accessible for the azPolicyRole ADMIN. ADMIN is mapped to a user role administrator, making company tab accessible for users whose role is administrator.

After permissions are defined, the code or resources that must be authorized are surrounded by a tag called <authz:authorize>.

This example shows how to use this tag:

<authz:authorize ifAnyGranted="perm_company_tab">

<li class="sts"><span ><a href="companyProfile.action" title="<bean:message key="global.myAccount.subNavTab3"/>"><bean:message key="global.myAccount.subNavTab3"/></a></span></li>

</authz:authorize>

You can have a list of permissions separated by commas in the ifAnyGranted attribute. If any of the permissions in the list are granted, then the body of the tag is written.

The authz:authorize tag can have the following attributes:

• ifAllGranted. All the listed permissions must be granted for the tag to output its body.
• ifAnyGranted. Any of the listed permissions must be granted for the tag to output its body.
• ifNotGranted. None of the listed permissions must be granted for the tag to output its body.

Customizing Authentication URLs

You can customize the default URLs for the authentication pages listed in Table 4.

To customize Spring Security default URLs

1. Open the spring-security.xml file, found in the EDX_HOME/config/security/ebilling directory (or the EDX_HOME\config\security\ebilling directory on Windows).
2. In the security:http section of the spring-security.xml file, edit the appropriate URL attribute, shown in the following table.

   Feature URL	Spring Configuration Attribute	Mapping Details
   Login Page	login-page	The login-page attribute maps to the loginFormUrl property of the LoginUrlAuthenticationEntryPoint.
   Default Login Target	default-target-url	The default-target-url attribute maps to the defaultTargetUrl property of UsernamePasswordAuthenticationFilter code.
   Access Denied Page	error-page	None.
   Log Out Target Page	logout-success-url	None.
   Login Failure Target	authentication-failure-url	The authentication-failure-url attribute maps to the authenticationFailureUrl property of the UsernamePasswordAuthenticationFilter code.

Authentication Request Processing

The preconfigured AuthenticationManager property in the spring-security.xml file processes each authentication request.

If authentication is successful, then Spring Security places the resulting Authentication object into the Security Context Holder and redirects the browser to the defaultTargetUrl property, which you can customize.

If authentication fails, then Spring Security places AuthenticationException into the HttpSession attribute indicated by WebAttributes.AUTHENTICATION_EXCEPTION, and displays an error page with a reason. This attribute contains well-known keys that are used to store Spring Security information in request or session scope. If authentication fails, the browser displays the authentication failure URL, then which you can also customize.