SAML 2.0 and Kerberos Single Sign-On Configuration for Oracle Analytics Server

March 17, 2021 | 9 minute read
Veera Raghavendra Rao Koka
Consulting Member of Technical Staff
Text Size 100%:

Authors Veera Raghavendra Rao Koka and Moustafa Morssy (configUI)

 

Introduction

You can configure SAML 2.0 and Kerberos Single Sign-On (SSO) for Oracle Analytics Server using a hybrid approach. The steps for configuring SAML 2.0 and Kerberos SSO for Oracle Analytics Server are different from the steps you follow for Oracle Business Intelligence Enterprise Edition.

Oracle Analytics Server doesn’t allow you to modify or customize binaries such as EAR files and domain home configuration files for SSO.

 

Approach

This SSO solution is based on deploying an Apache HTTP Server ("httpd") with the mod_shib_24 shibboleth service provider module (for SAML2.0) and mod_auth_kerb module (for Kerberos) in front of Oracle Analytics Server.

The Apache HTTP Server performs the SAML2.0 or Kerberos-based SSO authentication and passes the user ID of the successfully authenticated user to the Oracle WebLogic Server where Oracle Analytics Server is deployed. Oracle WebLogic Server is configured with an Identity Asserter (such as OAMIdentityAsserter) to receive the user ID and assert the user just like a regular Oracle Access Manager (OAM) based SSO configuration. Consequently, this approach is a regular OAM (that is, HTTP Header based Single Sign-On) solution as far as Oracle Analytics Server is aware, meaning that all functionality certified for regular SSO also works with this approach.

The resulting solution runs inside a Docker which can run on the same Oracle Analytics Server host or a different host in front of Oracle Analytics Server. A basic Oracle Linux Docker image and accompanying scripts are supplied as a starting point. The base Docker image is called oralnx7 and includes the Oracle Linux 7 slim docker image and the necessary Apache, Shibboleth-SP, and Kerberos configuration files.

Scripts are used to prepare the Docker image by orchestrating the downloading and installation of Apache HTTP Server and the required Shibboleth-SP (SAML2.0 Service Provider) and Kerberos modules. These open-source software components are installed through scripts so that the implementer can read and agree to the relevant open-source license agreements. The initial steps to prepare the Docker image need to be performed on a host that has internet/network access to Yum repositories capable of installing the open-source components. Once the Docker image has been prepared you may move it to a host (which will be the host for the SSO docker) that does not have internet/network access to install these components.

The resulting Docker image named "oasso" is used to create a docker container. The "oasso" Docker image includes the base Oracle Linux plus Apache HTTP Server and Shibboleth-Service Provider installed.

 A GUI-based configuration utility is provided to configure the docker container to provide Web-SSO using a suitable SAML2 IdP or Kerberos domain.

 

License

Before implementing this approach that includes Apache and Shibboleth Service Provider (open-source software), check the third-party licensing requirements for your usage:

https://wiki.shibboleth.net/confluence/display/SP3/Home

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/foundation/license-faq.html

 

Scope

This document is aimed at Oracle Analytics professionals familiar with SAML Authentication or Kerberos Authentication SSO flow using an Oracle WebLogic Identity Asserter.  This docker-container approach is targeted to work on Oracle Linux 7, RedHat Linux 7, CentOS 7 with Docker Engine Version 19.03.11-ol. Familiarity with docker containers is useful for implementing this approach.

 

About the Kerberos Authentication Flow

This sequence diagram shows the authentication flow during Kerberos SSO, and all the communication that happens between the Kerberos client, a browser, OASSO Docker, and the Oracle WebLogic Server in which Oracle Analytics Server is deployed. This diagram doesn’t cover the detailed communication between the Kerberos client, the browser, and the Key Distribution Center (KDC) server.

  1. The user signs in to the Windows client associated with the Active Directory domain and opens a browser.
  2. The user accesses the Oracle Analytics Server URL in the browser (/dv or /analytics).
  3. The web server in the docker container with the mod_auth_kerb module challenges the user with a 401 unauthorized message.
  4. The browser sends an authentication request to the Authentication Service (AS) in the Key Distribution Center (KDC).
  5. The Ticket Granting Service (TGS) in the Key Distribution Center (KDC) responds with a ticket and a session key.
  6. The browser sends the ticket and session key (negotiate token) obtained from the Key Distribution Center (KDC) to the web server.
  7. The web server, using the mod_auth_kerb module, extracts the user ID from the negotiate token, and sends the user ID in a HTTP Header such as OAM_REMOTE_USER to the Oracle WebLogic Server where Oracle Analytics Server is running.
  8. The Oracle WebLogic Server extracts the user ID from the HTTP header using Oracle Access Manager Identity Asserter (OAMIdentityAsserter). If the user exists, Oracle Analytics Server grants the application roles to the user and allows access to the requested resource (/dv or /analytics).
  9. The web server serves the requested resource to the user.

 

About the SAML Authentication Flow

This sequence diagram shows the authentication flow during SAML SSO, and all the communication that happens between the browser, OASSO Docker, SAML Identity Provider, and the Oracle WebLogic Server in which Oracle Analytics Server is deployed. This diagram doesn’t cover the detailed communication between the browser, OASSO Docker, Oracle Analytics Server and any SAML 2.0 compatible identity provider.

 

  1. The user accesses the Oracle Analytics Server URL in the browser through OASSO Docker(/dv or /analytics).
  2. The web server in the docker container with the Shibboleth service provider redirects the user to the SAML identity provider for authentication.
  3. The SAML identity provider for authentication displays the SSO login page in the browser or uses the authentication method configured for the SAML identity provider.
  4. The user submits the login credentials to the SAML identity provider.
  5. Upon successful authentication at the SAML identity provider, it sends the authenticated user in a SAML Response to the Shibboleth service provider in OASSO Docker.
  6. The web server, using the Shibboleth service provider, sends the user ID in a HTTP Header such as OAM_REMOTE_USER to the Oracle WebLogic Server where Oracle Analytics Server is running.
  7. The Oracle WebLogic Server extracts the user ID from the HTTP Header using Oracle Access Manager Identity Asserter (OAMIdentityAsserter). If the user exists, Oracle Analytics Server grants the application roles to the user and allows access to the requested resource (/dv or /analytics) through the web server.
  8. The web server serves the requested resource to the user in the browser.

 

Prerequisites for Both SAML and Kerberos SSO

  1. Ensure that Oracle Analytics Server is up and running with version 5.9.0 or higher.
  2. Configure any supported external LDAP with Oracle Analytics Server, which is also associated with the SSO provider for authentication. (This is optional; you can also use Oracle WebLogic Embedded LDAP to maintain the same users that exist in the LDAP configured with the SSO provider.)
  3. Configure the Oracle WebLogic Server domain in which Oracle Analytics Server is deployed with an identity asserter, such as Oracle Access Manager Identity Asserter (OAMIdentityAsserter).
  4. Enable the Oracle WebLogic Plugin for the Oracle WebLogic Server domain in which Oracle Analytics Server is running: bi_server (n) and bi_cluster.
  5. Install the docker engine on the server where the SSO docker container will run.
  6. Configure the Apache HTTP Server of OASSO Docker to act as a web server for Oracle Analytics Server. You can install the docker container on the same host or a different host from Oracle Analytics Server.
  7. Install as root user on the server where the SSO docker container will run Python 3.6 or higher, gunicorn package, lxml package, and flask package.
  8. Configure Apache HTTP Server in OASSO Docker to run in HTTPS mode. Decide on the DNS Name to use for the Apache HTTP Server and obtain the SSL Server Certificate that supports the DNS name.
  9. Ensure that the private key for the Apache HTTP Server of OASSO Docker is used without any passphrase.
  10. Obtain the CA Intermediate and CA Root certificates that signed the Apache HTTP Server Certificate.

Additional Prerequisites for SAML SSO

  1. Obtain the SAML identity provider’s Metadata xml File.
  2. Some SAML identity providers require the service provider’s metadata prior to configuring the SSO application in the identity provider. In such cases, use the configUI utility to obtain the service provider’s metadata or use the sample EntityID, AssertionConsumerService URL, SingleLogoutService URL and SSL Certificates mentioned in this document and replace the apache-or-loadbalancer-hostname.domain.com with the Apache or Load Balancer Hostname.

Additional Prerequisites for Kerberos SSO

  1. Install the Kerberos client and workstation libraries on the host server where OASSO Docker is running.
  2. Access the Oracle Analytics Server URL from a Windows client that is associated with the same Active Directory domain that’s configured as the user store for Oracle Analytics Server.
  3. Configure a client browser for Integrated Windows Authentication.

 

Highlights of Installing and Configuring this SSO Approach

 

In the Administration Console of Oracle WebLogic Server

  • Configure External LDAP
  • Configure OAMIdentityAsserter
  • Enable Oracle WebLogic Plugin

 

In Enterprise Manager of Oracle WebLogic Server

  • Set Virtualize=true
  • Set OPTIMIZE_SEARCH=true
  • For SAML SSO, set the SSO Logoff URL to /logout.html

 

Generate the SSL Certificates for the Apache HTTP Server of OASSO Docker

 

Requirements for SAML SSO Configuration

After you configure and start OASSO Docker, download the Service Provider Metadata using this URL

https://apache-or-loadbalancer-hostname.domain.com/Shibboleth.sso/Metadata

Some SAML identity providers require the endpoints for the service provider before configuring an SSO application. You can obtain the end points from the configUI tool or use these URLs by replacing the DNS name.

EntityID : https://[Apache-or-LoadBalancer-DNS-Name]/analytics/shibboleth

AssertionConsumerService : https://[Apache-or-LoadBalancer-DNS-Name]/Shibboleth.sso/SAML2/POST

SingleLogoutService : https://[Apache-or-LoadBalancer-DNS-Name]/Shibboleth.sso/SLO/POST

Service Provider Signing & Encryption Certificate: The same certificate that you configured for the Apache HTTP Server.

Using these details for the service provider, configure SSO with the identity provider. SSO is only for authentication; authorization is done by Oracle Analytics Server.

Configure the identity provider to send the same attribute value (that exists in Oracle Analytics Server as UserID) in NameID Format (Unspecified or emailAddress)

Get the SAML Identity Provider’s Metadata XML File. (NOTE: Use the XML file, not the URL).

 

Requirements for Kerberos SSO Configuration

Generating the Keytab file for the Apache HTTP Server of OASSO Docker for Kerberos SSO:

On the Windows Domain Controller or KDC Server where Active Directory runs, create a Service Account for the Apache HTTP Server.

Run the ktpass command to create the keytab file and set the SPN for the account

ktpass -princ HTTP/oas-hostname.company.com@KERBREALMNAME.COM -mapuser ser_oas-hostname -pass Oracle123 -crypto All -ptype KRB5_NT_PRINCIPAL -out C:\oas-hostname.keytab -kvno 0

If there is a load balancer in front of the Apache HTTP Server (running on the docker container), add the service principal name for the load balancer to the service account created for this Oracle Analytics Server instance. 

See this example in which the load balancer host name (FQDN) is  oas.companyname.com

setspn -A HTTP/oas.companyname.com ser_oas-hostname

 

Check if the entry was added correctly:

setspn -L ser_oas-hostname

When using AES 128 and AES 256 Encryptions, select the appropriate check boxes.

Copy the keytab file to the browser machine where the config utility runs.

 

Collect the files needed for Kerberos SSO configuration:

Create the krb5.conf (for Linux) file with the correct details of the KDC Server and Encryption types that you use.

 

Test the configuration:

kinit -k -t oas-hostname.keytab HTTP/oas-hostname.company.com -V

 

Collect this data that’s needed for configuring Kerberos SSO:

Kerberos Authentication Realm (e.g. KERBREALMNAME.COM)

Service Name that’s passed while running the ktpass command (e.g. HTTP/oas-hostname.company.com)

Keytab file generated while running the ktpass command.

 

Install Docker Engine in Oracle Linux Server 7

Non-Root User Requirements

Install Python 3.6 or higher, gunicorn package, lxml package, and flask package required for the configUI utility

Download the Docker Solution tar file

The docker solution tar file oassodocker.tar.gz isn’t available generally from any download portal.

If you need the approach described in this post, file a Support Request and mention the Support Doc ID of this whitepaper and the Support Engineer can provide the link to download the file.

Create OASSO Docker Image

Install SSO Solution and configure using configUI

Configuring WebLogic to prevent direct access to BI

Protecting direct HTTP access to OBIPS

Uninstalling Docker

What is NOT supported for the OASSO Docker

Troubleshooting

You can find the steps to set up SAML 2.0 and Kerberos SSO on My Oracle Support. See Knowledge Document ID 2761678.1

SAML 2.0 and Kerberos Single Sign-On Configuration for Oracle Analytics Server (Doc ID 2761678.1)

Veera Raghavendra Rao Koka

Consulting Member of Technical Staff

Oracle Analytics Service Excellence, CEAL Team


Previous Post

Are you getting the most clarity out of your spend analysis?

Roxanne Bradley | 5 min read

Next Post


Set Up a Vanity URL for Oracle Analytics Cloud on OCI Gen 2