5 SecurityService

Note:

For information on debugging applications built with BI Publisher Web services, see Section 1.3, "Debugging Web Service Applications."

This chapter provides details on the SecurityService methods that you can use to manage BI Publisher server security operations, such as authentication, impersonation, login, logout, and account management.

This chapter contains the following sections:

Section 5.1, "assignRolesToUser() Method"
Section 5.2, "createRole() Method"
Section 5.3, "createUser() Method"
Section 5.4, "deleteRole() Method"
Section 5.5, "deleteUser() Method"
Section 5.6, "getBIPHTTPSessionInterval() Method"
Section 5.7, "getObjectSecurityXML() Method"
Section 5.8, "getSecurityModel() Method"
Section 5.9, "hasObjectAccess() Method"
Section 5.10, "hasObjectAccessInSession() Method"
Section 5.11, "impersonate() Method"
Section 5.12, "isUserExists() Method"
Section 5.13, "login() Method"
Section 5.14, "logout() Method"
Section 5.15, "notifyBIEEPreferencesUpdated() Method"
Section 5.16, "notifyBIEEPreferencesUpdatedWithString() Method"
Section 5.17, "removeRolesFromUser() Method"
Section 5.18, "updateRole() Method"
Section 5.19, "updateUser() Method"
Section 5.20, "validateLogin() Method"

Note:

SecurityService is available to the BI Publisher Security Model only. If your BI Publisher deployment uses another security model (for example, LDAP, Oracle E-Business Suite, or Oracle Fusion Apps), you cannot use the SecurityService API.

5.1 assignRolesToUser() Method

Use assignRolesToUser() method to assign new roles to a user in BI Publisher.

Signature

String[] assignRolesToUser(String userName, String[] roleNames, String adminUser, String adminPassword);

Table 5-1 Parameters for assignRolesToUser() Method

Parameter	Description
String userName	The user to which to add the role or roles.
String[] roleNames	The name of the role to add to the user. For example, "Financial Users".
String adminUser	Specifies a BI Publisher user name for a user with administration privileges.
String adminPassword	Specifies the password for the administration user name.

5.2 createRole() Method

Use createRole() method to create a role in BI Publisher.

Signature

boolean createRole(String roleName, String description, String adminUser, String adminPassword);

Table 5-2 Parameters for createRole() Method

Parameter	Description
String roleName	The name of the role to create. For example, "Financial Users".
String description	The description of the role.
String adminUser	Specifies a BI Publisher user name for a user with administration privileges.
String adminPassword	Specifies the password for the administration user name.

5.3 createUser() Method

Use createUser() method to create a user in BI Publisher. This method returns a boolean value of the success of the method.

Signature

boolean createUser(String userName, String password, String adminUser, String adminPassword);

Table 5-3 Parameters for createUser() Method

Parameter	Description
String userName	The user name to create.
String password	The password for the newly created user.
String adminUser	Specifies a BI Publisher user name for a user with administration privileges.
String adminPassword	Specifies the password for the administration user name.

5.4 deleteRole() Method

Use deleteRole() method to delete a role from BI Publisher. This method returns a boolean value of the success of the method.

Signature

boolean deleteRole(String roleName, String adminUser, String adminPassword);

Table 5-4 Parameters for deleteRole() Method

Parameter	Description
String roleName	The user name to delete.
String adminUser	Specifies a BI Publisher user name for a user with administration privileges.
String adminPassword	Specifies the password for the administration user name.

5.5 deleteUser() Method

Use deleteUser() method to delete a user from BI Publisher. This method returns a boolean value of the success of the method.

Signature

boolean deleteUser(String userName, String adminUser, String adminPassword);

Table 5-5 Parameters for deleteUser() Method

Parameter	Description
String userName	The user name to delete.
String adminUser	Specifies a BI Publisher user name for a user with administration privileges.
String adminPassword	Specifies the password for the administration user name.

5.6 getBIPHTTPSessionInterval() Method

This method returns the number of seconds an HTTP session interval is.

Signature

int getBIPHTTPSessionInterval(void);

5.7 getObjectSecurityXML() Method

This method extracts the report-level permissions (from security.xml) for a BIEE integrated catalog.

Signature

byte[] getObjectSecurityXML(String adminUsername, String adminPassword, String objectAbsolutePath, boolean isRecursive);

Table 5-6 Parameters for getObjectSecurityXML() Method

Parameter	Description
String adminUsername	The user name for a BI Publisher user with administrator privileges.
String adminPassword	The password associated with the adminUserName.
String objectAbsolutePath	The absolute path to security.xml.
boolean isRecursive	Whether or not objectAbsolutePath is recursive.

5.8 getSecurityModel() Method

This method returns BI Publisher's security model in place.

Signature

String getSecurityModel(void);

5.9 hasObjectAccess() Method

This method verifies if the specified user has access to the report object referenced by reportAbsolutePath. This method first authenticates user with the specified credentials. Upon successful authentication, it verifies the user's privileges to access the report object.

Signature

boolean hasObjectAccess(String reportAbsolutePath, String roleName, String userID, String password);

Table 5-7 Parameters for hasObjectAccess() Method

Parameter	Description
String reportAbsolutePath	The path to the report object for which you want to verify the user's access privileges. For example: /HR Manager/Employee Reports/Employee Listing.xdo
String roleName	For future use. Ignore this parameter as it is not yet functional.
String userID	Specifies the BI Publisher user name.
String password	Specifies the password for the user name.

5.10 hasObjectAccessInSession() Method

This method verifies if a pre-authenticated bipSession has the privilege to access the report object relative to reportAbsolutePath.

For more information about in-session methods, see Section 1.2, "About In-Session Methods."

Signature

boolean hasObjectAccessInSession(string reportAbsolutePath, string roleName, string bipSessionToken);

Table 5-8 Parameters for hasObjectAccessInSession() Method

Parameter	Description
String reportAbsolutePath	The absolute path to the report object.
String roleName	The role associated with the given user.
String bipSessionToken	The proprietary token string generated for the user by the BI Publisher server. With the bipSessionToken string, the user no longer needs to provide user credentials. The BI Publisher server can validate this token string and restore the BI Publisher server session to perform needed operation.

5.11 impersonate() Method

This method enables an admin account to act on the behalf of a user account. This is very useful if the user doesn't have a known password to be authenticated by BI Publisher server. This method logs in using admin account privilege, then switches the owner of the BI Publisher server session to the passed-in username. Therefore, bipSession token later will be verified by passed-in username. All further BI Publisher operations are performed through give n username.

Signature

String impersonate(String adminUsername, String adminPassword,String username);

Table 5-9 Parameters for impersonate() Method

Parameter	Description
String adminUserName	Specifies a BI Publisher user name for a user with administration privileges
String adminPassword	Specifies the password for the administration user name.
String username	The username of the user account that will be granted administrator privileges.

5.12 isUserExists() Method

Use isUserExists() method to test if a user name exists in the BI Publisher security model. This method returns the result as a boolean value.

Signature

boolean isUserExists(String userName, String adminUser, String adminPassword);

Table 5-10 Parameters for isUserExists() Method

Parameter	Description
String userName	The user name to test.
String adminUser	Specifies a BI Publisher user name for a user with administration privileges.
String adminPassword	Specifies the password for the administration user name.

5.13 login() Method

Use the login() method to log in to BI Publisher and perform other BI Publisher actions using Web Services. The login() method returns a String, which will become the BI Publisher session ID

Signature

String login(String userID, String password);

Table 5-11 Parameters for login() Method

Parameter	Description
String userID	Specifies the BI Publisher user name.
String password	Specifies the password for the user name.

5.14 logout() Method

This method, in effect, logs the specified user out of the system by invalidating the user's bipSessionToken. After successful logout, the bipSessionToken string is no longer valid.

Signature

boolean logout(String bipSessionToken);

Table 5-12 Parameters for logout() Method

Parameter	Description
String bipSessionToken	The BI Publisher session ID.

5.15 notifyBIEEPreferencesUpdated() Method

This method is provided for BIEE user preference integration purpose only.

Signature

boolean notifyBIEEPreferencesupdated(bieeSessionID);

Table 5-13 Parameters for notifyBIEEPreferencesUpdated() Method

Parameter	Description
String bieeSessionID	The session ID for Oracle Business Intelligence/BI Publisher integration.

5.16 notifyBIEEPreferencesUpdatedWithString() Method

This method is provided for BIEE user preference integration purpose only.

Signature

boolean notifyBIEEPreferencesUpdatedWithString(String bieeSessionID, String userPrefesXML);

Table 5-14 Parameters for notifyBIEEPreferencesUpdatedWithString() Method

Parameter	Description
String bieeSessionID	The session ID for Oracle Business Intelligence/BI Publisher integration.
String userPrefesXML	The XML data that contain user preferences.

5.17 removeRolesFromUser() Method

Use removeRolesFromUser() method to remove roles from a user in BI Publisher.

Signature

String[] removeRolesFromUser(String userName, String[] roleNames, String adminUser, String adminPassword);

Table 5-15 Parameters for removeRolesFromUser() Method

Parameter	Description
String userName	The user from which to delete the role or roles.
String[] roleNames	The name of the role to delete from the user. For example, "Financial Users".
String adminUser	Specifies a BI Publisher user name for a user with administration privileges.
String adminPassword	Specifies the password for the administration user name.

5.18 updateRole() Method

Use updateRole() method to update the description of a role that currently exists in BI Publisher.

Signature

boolean updateRole(String currentRoleName, String newDescription, String adminUser, String adminPassword);

Table 5-16 Parameters for updateRole() Method

Parameter	Description
String currentRoleName	The name of the role to update.
String newDescription	The updated description of the role to apply.
String adminUser	Specifies a BI Publisher user name for a user with administration privileges.
String adminPassword	Specifies the password for the administration user name.

5.19 updateUser() Method

Use updateUser() method to update a user's password in BI Publisher. This method returns a boolean value of the success of the method.

Signature

boolean updateUser(String currentUsername, String newPassword, String adminUser, String adminPassword);

Table 5-17 Parameters for updateUser() Method

Parameter	Description
String currentUserName	The user name to update.
String newPassword	The new password to assign to the user name.
String adminUser	Specifies a BI Publisher user name for a user with administration privileges.
String adminPassword	Specifies the password for the administration user name.

5.20 validateLogin() Method

Use the validateLogin() method to validate that a UserID and Password have the privilege to access the Oracle BI Publisher report server.

Signature

boolean validateLogin(String userID, String password);

Table 5-18 Parameters for validateLogin() Method

Parameter	Description
String userID	Specifies the BI Publisher user name.
String password	Specifies the password for the user name.