Configuring Oracle Business Intelligence Enterprise Edition to act as a SAML 2.

0 Service Provider for SSO

An Oracle White Paper August 2011

1. Purpose......................................................................3 2. Scope.........................................................................3 3. Prerequisites..............................................................4 4. Configuring the BI Domain as a SAML 2.0 Service Provider....................................5 4.1. Creating SAML Identity Asserter.............................6 4.2. Configuring the BI Domain as a SAML 2.0 Service Provider.................................6 4.3. Configuring SAML 2.0 Federation properties for the domain...............................6 5. Configuring BI Domain as a Partner with the Identity Provider...............................8 5.1. (Only applicable if using a Weblogic IdP) Configuring BI Domain Service Provider Metadata on a Weblogic Identity Provider.......8 5.2. Configuring Identity Provider Metadata on the BI Domain (SAML Service Provider).........................................................................8 6. Configure BI for SSO...................................................9 6.1. Configure BI Analytics App to require authentication...........................................9 6.2. Configure BI for SSO.............................................12 7. BI Publisher and BI Office Configuration..................13 8. Testing your setup...................................................13 9. Troubleshooting.......................................................13 10. References.............................................................14

Configuring Oracle Business Intelligence Enterprise Edition to act as a SAML 2.0 Service Provider for SSO Page 2

Configuring Oracle Business Intelligence Enterprise Edition to act as a SAML 2.0 Service Provider for SSO

1. PURPOSE

This paper examines how to configure Oracle Business Intelligence Enterprise Edition (Oracle BI EE) 11.1.1.5.0 as a SAML 2.0 Service Provider (SP) in a SAML 2.0 Federation for Single Sign-On (SSO).
2. SCOPE

This document describes the steps required to integrate Oracle BI Enterprise Edition with SAML for asserting users in order to provide single-sign on and secure access to the Oracle BI /analytics URL. The approach described involves configuring the Weblogic domain hosting BI as a SAML Service Provider. The Service Provider will redirect requests for protected resources to a third-party Identity Provider which will authenticate the user and produce a SAML token to present back to the Service Provider. A SAML Asserter is configured on the BI domain to accept a SAML assertion provided by a third-party SAML Identity Provider. The UserID is extracted from the Subject of the SAML assertion and passed to a Weblogic Authenticator that is supported for use with BI 11g. The Weblogic Authenticator is used to lookup the UserID in an underlying Identity Store in order to populate the java principal in Weblogic. This principal is then made available as the authenticated user to applications hosted in the Weblogic domain.
IMPORTANT N OTE : C HECK THE BI CERTIFICATION M ATRIX FOR A LIST OF S UPPORTED W EBLOGIC AUTHENTICATORS . THE SAML A UTHENTICATOR IS NOT SUPPORTED FOR USE WITH BI 11.1.1.5, BUT THE SAML A SSERTER IS SUPPORTED . T HEREFORE IT IS NOT POSSIBLE TO USE THE SAML AUTHENTICATOR WITH BI 11.1.1.5 AND CONSEQUENTLY ANY FUNCTIONALITY THAT THIS AUTHENTICATOR PROVIDES IS NOT AVAILABLE.

This document is aimed at Oracle BI professionals familiar with Oracle BI Enterprise Edition 11g. However, in order to implement this approach successfully, familiarity

Configuring Oracle Business Intelligence Enterprise Edition to act as a SAML 2.0 Service Provider for SSO Page 3

of the existing SAML Identity Provider (IdP) environment is required. In particular, you should have familiarity with SAML concepts and the flow of control during a SAML assertion. You should also be able to determine the requirements of your SAML IdP with regards to supported bindings and protocols such as support for signing assertions. Setup is required in both the Oracle BI Weblogic domain (acting as the SAML Service Provider) and the SAML Identity Provider (the third-party product that creates the SAML Assertion). This document assumes that a suitable SAML 2.0 Identity Provider is already in place. An assumption is made that the SAML configuration on the IdP requires signed assertions and the relevant certificate information is included in the metadata being passed between IdP and SP as part of the configuration described in this document. Equally, an assumption is made that Authentication Requests from the SP to the IdP will be signed and the relevant certificate information is included in the metadata passed from the SP to the IdP as part of the configuration described in this document.. You should be aware that there are some limitations of this approach. The known limitations are as follows: Virtual Users are not permitted since it is not possible to use the SAML Authenticator with BI 11.1.1.5 SAML Assertions containing a Transient UserID in the Subject are not permitted since BI requires the actual UserID in the Subject Additional attributes passed via the SAML Assertion cannot be used since this requires the SAML Authenticator SAML assertion to access BI Publisher directly via the xmlpserver url rather than via BI is not covered in this document SAML assertion to access RTD is not covered in this document This approach has been tested against the following release versions: Oracle BI EE 11.1.1.5.0 Weblogic Server 11g Release 1 (10.3.5) Oracle HTTP Server (when using a clustered BI domain)

3. PREREQUISITES

Before performing this integration, you are encouraged to review the following documentation:

Configuring Oracle Business Intelligence Enterprise Edition to act as a SAML 2.0 Service Provider for SSO Page 4

Oracle Fusion Middleware Securing Oracle WebLogic Server 11g Release 1 (10.3.5): o Configuring Single Sign-On with Web Browsers and HTTP Clients.

o Configuring SAML 2.0 Services

http://download.oracle.com/docs/cd/E21764_01/web.1111/e13707/saml. htm#BEIEIGDB http://download.oracle.com/docs/cd/E21764_01/web.1111/e13707/saml. htm#i1107165

The following prerequisites must be satisfied before you configure Oracle BI 11g for SAML authentication Oracle Business Intelligence 11.1.1.5 must be installed and running
IMPORTANT N OTE : THE REQUIREMENT FOR W EBLOGIC WHEN USING SAML 2.0 SERVICES RUNNING IN MORE THAN ONE W EB LOGIC S ERVER INSTANCE IN THE DOMAIN ( I. E . A CLUSTER ) IS TO USE AN RDBMS SECURITY STORE . THE RDBMS SECURITY STORE IS REQUIRED BY THE SAML 2.0 SECURITY PROVIDERS SO THAT THE DATA THEY MANAGE CAN BE SYNCHRONIZED ACROSS ALL THE W EB LOGIC S ERVER INSTANCES THAT SHARE THAT DATA . N OTE THAT ORACLE DOES NOT RECOMMEND UPGRADING AN EXISTING DOMAIN IN PLACE TO USE THE RDBMS SECURITY STORE . IF YOU WANT TO USE THE RDBMS SECURITY STORE , YOU SHOULD CONFIGURE THE RDBMS SECURITY STORE AT THE TIME OF DOMAIN CREATION . F OR A BI INSTALLATION , THIS REQUIRES THE USE OF A S OFTWARE O NLY INSTALLATION ON THE FIRST NODE OF THE CLUSTER USING THE OPTION TO E XTEND AN ORACLE W EB LOGIC S ERVER DOMAIN WITH ORACLE B USINESS INTELLIGENCE , FOLLOWED BY ENTERPRISE INSTALLS WITH THE EXTEND D OMAIN O PTION ON SUBSEQUENT NODES IN THE CLUSTER . FOR INFORMATION , SEE ORACLE FUSION M IDDLEWARE S ECURING ORACLE W EB LOGIC S ERVER 11 G R ELEASE 1 (10.3.5) Chapter 10, "Managing the RDBMS Security Store."

An existing SAML 2.0 Federation with an Identity Provider is already configured. Creating such a Federation is out of scope of this document. The Identity Provider must populate the Subject in the SAML assertion with the cleartext UserID to be used as the BI UserID rather than using a transient ID.

4. CONFIGURING THE BI DOMAIN AS A SAML 2.0 SERVICE PROVIDER

Before you start, you will need the SAML 2.0 Identity Provider metadata file from your SAML Federation Identity Provider. The metadata file should be in a standard format, compliant with the SAML 2.0 specification. Consult your vendor documentation for further information on how to obtain the SAML 2.0 IdP metadata from your Identity Provider.

Configuring Oracle Business Intelligence Enterprise Edition to act as a SAML 2.0 Service Provider for SSO Page 5

4.1. CREATING SAML IDENTITY ASSERTER

1. Log into Weblogic Admin console on the BI Domain (i.e. the Service Provider in SAML terminology) 2. Go to Security Realms -> myrealm -> Providers -> Authentication 3. Click the Lock and Edit button in the top-left hand corner 4. In the Authentication SAML2IdentityAsserter. Providers screen, click the New button and select

5. Name the new asserter SAML2IA (or similar) and click OK there is no provider specific config required for this Asserter. 6. Activate Changes 7. Restart the server
4.2. CONFIGURING THE BI DOMAIN AS A SAML 2.0 SERVICE PROVIDER

Repeat this section for each Managed Server in the cluster. 1. Log into Weblogic Admin console on the BI Domain 2. Go to Environment -> Servers -> bi_server1 (or Adminserver if using a Simple Install) -> Federation Services -> SAML 2.0 Service Provider 3. Most fields can be left as default except those noted below Enabled Checked Always Sign Authentication Requests Checked Force Authentication Unchecked Preferred Binding POST Default URL http://<biserverhostname>:<ManagedServerPort>/analytics http://mybiserver:9704/analytics e.g.

4. Save 5. Activate Changes

4.3. CONFIGURING SAML 2.0 FEDERATION PROPERTIES FOR THE DOMAIN

Repeat this section for each Managed Server in the cluster. Note that if you are running BI on a Weblogic Cluster, the SP metadata on all nodes of the cluster need to be identical. Therefore, only one set of SP metadata is supplied to the IdP. This means that the Published Site URL needs to be a single point of entry into the cluster and the same certificate needs to be used for signing (if signing is enabled).

Configuring Oracle Business Intelligence Enterprise Edition to act as a SAML 2.0 Service Provider for SSO Page 6

1. Log into Weblogic Admin console on the BI Domain 2. Go to Environment -> Servers -> bi_server1 -> Federation Services -> SAML 2.0 General 3. Lock and Edit 4. Most fields can be left as default except those noted below Replicated Cache Enabled (should be ticked) Contact Person Given Name (Insert your first name) Contact Person Surname (Insert surname) Contact Person Type Select from list (pick one doesn't matter which) Contact Person Company Oracle Contact Person Telephone Number (Insert a phone number) Contact Person Email Address (Your email address) Organization Name (Oracle) Organization URL http://www.oracle.com/ Published Site URL must be in format http://<BI Domain server name>:<Managed server port>/saml2 e.g. http://mybiserver.oracle.com:9704/saml2. If you have a cluster of Managed Servers, this should be the externally visible entry point to all Managed Servers in the cluster. i.e. the url exposed via a web server in front of the Managed Servers. Entity ID Domain name e.g. bifoundation_domain Single Sign-on Signing Key Alias DemoIdentity (this is the demo keystore deployed OOTB with WLS You need to change this if you are not using the demo keystore) Single Sign-on Signing Key Pass Phrase DemoIdentityPassPhrase (assuming the demo keystore is being used) Confirm Single Sign-on Signing Key Pass Phrase DemoIdentityPassPhrase 5. Save 6. Activate Changes 7. Restart the server 8. Go to Environment -> Servers -> bi_server1 -> Federation Services -> SAML 2.0 General 9. Publish the Service provider (SP) metadata to an XML file using the Publish Meta Data button. Keep the file in a safe place it will be used by your Identity Provider to establish your BI Domain as a partner site in the SAML 2.0 Federation 10. Restart the server

Configuring Oracle Business Intelligence Enterprise Edition to act as a SAML 2.0 Service Provider for SSO Page 7

5. CONFIGURING BI DOMAIN AS A PARTNER WITH THE IDENTITY PROVIDER

At this stage, you should take the Service Provider metadata file created in step 4 of the section entitled Configuring SAML 2.0 Federation properties for the domain above and supply it to your Identity Provider. The process for doing this will differ depending on your Identity Provider, but by way of an example, we illustrate below how to achieve this where the Identity Provider is implemented in Weblogic. The method will differ for different vendors implementations.
5.1. (ONLY APPLICABLE IF USING A WEBLOGIC IDP) CONFIGURING BI DOMAIN SERVICE PROVIDER METADATA ON A WEBLOGIC IDENTITY PROVIDER

1. Log into Weblogic Admin console on the Identity Provider domain (i.e. not the BI Domain) 2. Go to Security Realms -> myrealm -> Providers -> Credential Mapping 3. Select the SAML2Credential Mapper and click on the Management tab 4. Create a new Web Single Sign-On Service Provider Partner, named SAML_SSO_SP01 (the name is immaterial but it must match when referenced later) 5. In the file browse screen, select the Service Provider metadata file and click OK 6. Go back to the configuration screen for the Service Provider Partner, SAML_SSO_SP01, and leave most fields as default except those noted below Name SAML_SSO_SP01 Enabled Checked Description SAML_SSO_SP01 Key Info Included Checked 7. Save
5.2. CONFIGURING IDENTITY PROVIDER METADATA ON THE BI DOMAIN (SAML SERVICE PROVIDER)

1. Log into Weblogic Admin console on the Service Provider domain (i.e. the BI Domain) 2. Go to Security Realms -> myrealm -> Providers -> Authentication 3. Select the SAML2IdentityAsserter you created in step 2.1 above and click on the Management tab 4. Create a new Web Single Sign-On Identity Provider Partner, named SAML_SSO_IDP01 (the name is immaterial but it must match when referenced later) 5. In the file browse screen, select the Identity Provider metadata file 6. Go back to the configuration screen for the Identity Provider Partner, SAML_SSO_IDP01, and leave most fields as default except those noted below Name SAML_SSO_IDP01 Enabled Checked

Configuring Oracle Business Intelligence Enterprise Edition to act as a SAML 2.0 Service Provider for SSO Page 8

Description SAML_SSO_IDP01 Redirect URI /analytics/* Only Accept Signed Artifact Requests Checked 7. Save

6. CONFIGURE BI FOR SSO 6.1. CONFIGURE BI ANALYTICS APP TO REQUIRE AUTHENTICATION

Finally on the Weblogic server, we need to change the deployment descriptors for the BI analytics application to apply a security constraint so that it will require clients accessing the application to be authenticated by the container (i.e. Weblogic). This procedure involves securing the analytics web application so that only members of specific groups are permitted access. At runtime, this effectively triggers the analytics web application to request authorization and hence authentication from the container. Note that this approach requires that you assign all BI users to a specific group (either BIUsers or BIAdmins) in the underlying Identity Store (i.e. each BI user will need to be assigned one of these groups in the native Weblogic LDAP or other provider if you have changed from the default configuration).
Locate the analytics.ear in your Oracle BI Home directory. This will be <Oracle BI Install Dir>/Oracle_BI1 (or whatever you chose to name your Oracle BI Home on install)/bifoundation/jee/analytics.ear. So in our example scenario, this would be located at:

C:\OBI\Oracle_BI1\bifoundation\jee\analytics.ear

Make a backup copy of the ear file so that you have a restore point to refer back to (and revert to) if needed Unpack the analytics.ear file to a temporary location, using the Java jar tool (or edit inplace using a zip utility). Use the command line options xvf to extract the contents to the current working directory (e.g. C:\ OBI\jdk160\bin\jar xvf C:\OBI\Oracle_BI1\bifoundation\jee\analytics.ear), so you will probably want to create a temporary directory to hold the unpacked contents and change into that directory before running the command. The ear contains a META-INF directory and two war files, analytics.war and analytics-ws.war In the META-INF directory, there is a MANIFEST.MF file, add the following line to the end of the file:
Weblogic-Application-Version: 11.1.1

Configuring Oracle Business Intelligence Enterprise Edition to act as a SAML 2.0 Service Provider for SSO Page 9

Unpack the analytics.war file to a second temporary location, it contains a default.jsp file and five top-level directories, one of which is called WEB-INF. Create a new deployment descriptor file in WEB-INF called weblogic.xml. It should contain the following:

<?xml version = '1.0' encoding = 'windows-1252'?> <weblogic-web-app xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"xsi:schemaLocation="http://www.bea.com/ns/weblogic/weblogic-web-app http://www.bea.com/ns/weblogic/weblogic-web-app/1.0/weblogic-web-app.xsd" xmlns="http://www.bea.com/ns/weblogic/weblogic-web-app"> <context-root>analytics</context-root> <security-role-assignment> <role-name>SSORole</role-name> <principal-name>BIUsers</principal-name> <principal-name>BIAdmins</principal-name> </security-role-assignment> </weblogic-web-app>

The name of the role is not important, so long as it is consistent in this file and in sections we will add in the web.xml file in the next step. The principal name element(s) should refer to the groups (not Application Roles) from your Identity Store that you wish to allow access to the application. N.B. all BI users will need to be members of at least one of these groups and will need to be accessible in both the Identity Provider and BI Domain. If you have a shared identity store (e.g. both domains are configured with an OID authenticator pointing at the same LDAP server), this will happen automatically; if you have different identity stores in each domain, the same users/groups will need to be configured in each. Also, in the WEB-INF directory, you will find an existing file called web.xml. Edit web.xml and look for a section like this:

<login-config> <auth-method>CLIENT-CERT</auth-method> </login-config>

Replace this section with the following:

<security-constraint> <web-resource-collection> <web-resource-name>BI Analytics</web-resource-name> <url-pattern>/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>SSORole</role-name> </auth-constraint> </security-constraint> <login-config> <auth-method>CLIENT-CERT</auth-method> </login-config> <security-role> <role-name>SSORole</role-name> </security-role>

The name of the role is not important, so long as it is consistent in this file and in the weblogic.xml file.

Configuring Oracle Business Intelligence Enterprise Edition to act as a SAML 2.0 Service Provider for SSO Page 10

Once you have edited both files, repackage the analytics.war file, again using the jar tool (or edit in-place using a zip utility), and, in turn, repackage that back into the analytics.ear file.

Next we need to redeploy the analytics.ear file to Weblogic so that the new security constraint will come into effect. Log into Weblogic Admin Console and click on Deployments In the Change Centre at the top left, click Lock and Edit Find the analytics app and click the tickbox next to it, then click on the Update button Note that in a Weblogic Cluster, you may need to delete and re-install/deploy rather than using the update method.

In the Update Application Assistant screen, make sure the deployment path is the same as the ear file you just updated, if not change the path

Configuring Oracle Business Intelligence Enterprise Edition to act as a SAML 2.0 Service Provider for SSO Page 11

Click Next, then Finish In the Change Centre at the top left, click Activate Changes and wait for the redeployment to complete Check that the analytics application is Active via the Deployments menu in the Weblogic console If you have not already done so, restart the Weblogic Admin Server and all Managed Servers

6.2. CONFIGURE BI FOR SSO

Finally, we must tell the core BI Application to accept SSO-authenticated clients from Weblogic. Log in to Oracle Enterprise Manager (e.g. http://mybiserver.oracle.com:7001/em/) In the menu on the left hand side select Farm-> Business Intelligence -> coreapplication Then on the main screen, select the Security tab Click Lock and Edit Configuration in the Change Centre section at the top of the screen Tick the Enable SSO tickbox and select Generic SSO in the dropdown

. Click Apply at the top right of the Security screen Click Activate Changes in the Change Centre Restart BI Presentation Services

Configuring Oracle Business Intelligence Enterprise Edition to act as a SAML 2.0 Service Provider for SSO Page 12

7. BI PUBLISHER AND BI OFFICE CONFIGURATION

Since the URL /analytics is now protected, it is necessary to point BI Publisher and BI Office to the analytics-ws instead. This URL should remain unprotected. It is configured only to accept SOAP access as used by BI Publisher and BI Office. For BI Publisher, login to BI, go to Administration > Manage BI Publisher > Integration > Oracle BI Presentation Services Change the URL Suffix to point to analytics-ws/saw.dll For BI Office, consider the SAML configuration performed in this document to be the same as setting up BI for SSO. Follow the steps in the delivered documentation: http://download.oracle.com/docs/cd/E21764_01/bi.1111/e10544/appoffice.htm#BIE UG10633

8. TESTING YOUR SETUP

Point your browser at the analytics app on your BI Domain, e.g.: http://mybiserver.oracle.com:9704/analytics You should be prompted for a username/password. Supply the credentials for a user in one of the groups configured in the deployment descriptors in the analytics app (NB as above, the user/groups must exist in either a shared identity store common to both the Identity Provider and BI domains or else if they have separate identity stores, they must exist in both) and you should be granted access to BI as an SSO user.

9. TROUBLESHOOTING

Some common problems and resolutions are listed below. Issue Hints

Configuring Oracle Business Intelligence Enterprise Edition to act as a SAML 2.0 Service Provider for SSO Page 13

/analytics is protected by SAML IdP, but you still just see the BI login page

Is the UserID being passed to BI via the REMOTE_USER server variable? Turn on some logging in instanceconfig.xml
<FilterRecord writerClassGroup="File" disableCentralControl="true" path="saw.httpserver.request" information="16" warning="32" error="32" trace="32" incident_error="32"/> <FilterRecord writerClassGroup="File" disableCentralControl="true" path="saw.httpserver.response" information="16" warning="32" error="32" trace="32" incident_error="32"/>

/analytics is protected by SAML IdP, but you get redirected to /analytics/defau lt.jsp with an authorization error message General SAML issues

Then restart OBIPS. Try to login again and review the end of the OBIPS log. Look for HTTP header variables This allows you to review the http headers and cookie values being received by OBIPS in order to debug SSO Check that you user has either the BIAdmins or BIUsers group via the Authenticator defined in the BI domain.

Follow the steps to enabling debugging for SAML 2.0 http://download.oracle.com/docs/cd/E21764_01/web.1111/e13707/sa ml.htm#CHDFJBCE

10. REFERENCES

[1] Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition 11g Release 1 (11.1.1) http://download.oracle.com/docs/cd/E14571_01/bi.1111/e10543/toc.htm [2] Securing Oracle Weblogic Server http://download.oracle.com/docs/cd/E14571_01/web.1111/e13707/toc.htm

[3] Configuring Single Sign-On with Web Browsers and HTTP Clients http://download.oracle.com/docs/cd/E21764_01/web.1111/e13707/saml.htm#BEIEIGDB

Configuring Oracle Business Intelligence Enterprise Edition to act as a SAML 2.0 Service Provider for SSO Page 14

[4] Oracle Fusion Middleware Securing Oracle WebLogic Server 11g Release 1 (10.3.5) Chapter 10, "Managing the RDBMS Security Store." http://download.oracle.com/docs/cd/E21764_01/web.1111/e13707/rdbms.htm#BABBGEFH

Configuring Oracle Business Intelligence Enterprise Edition to act as a SAML 2.0 Service Provider for SSO Page 15

Configuring Oracle Business Intelligence Enterprise Edition to act as a SAML 2.0 Service Provider for SSO August 2011 Author: Oracle BI Development Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065 U.S.A. Worldwide Inquiries: Phone: +1.650.506.7000 Fax: +1.650.506.7200 www.oracle.com Copyright 2011, Oracle. All rights reserved. This document is provided for information purposes only and the contents hereof are subject to change without notice. This document is not warranted to be error-free, nor subject to any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose. We specifically disclaim any liability with respect to this document and no contractual obligations are formed either directly or indirectly by this document. This document may not be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without our prior written permission. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.