SAML2.0 Single Sign On (SSO) for Agents with Oracle Service Cloud (RightNow) and Microsoft ADFS

Like many applications, Oracle Service Cloud (previously RightNow) includes support for Single Sign On (SSO). Setting up SSO can be a cumbersome process. Especially cloud applications with limited access to debug output can prove to be challenging. In this article I will share my experiences setting up SAML2.0 SSO on Oracle Service Cloud in combination with Microsoft Active Directory Federation Services (ADFS) 3.0. The ADFS side of the matter will only be described globally, since this part is usually taken care of by dedicated administrators. The intended audience of this article consists of Oracle Service Cloud consultants who have been assigned the seemingly daunting task of setting up SAML2.0 SSO.

Let me first introduce you to two key definitions. Wikipedia provides us with a definition for Single Sign-on: “Single sign-on (SSO) is a property of access control of multiple related, but independent software systems. With this property a user logs in with a single ID and password to gain access to a connected system or systems without using different usernames or passwords, or in some configurations seamlessly sign on at each system”. The other import definition concerns SAML 2.0. SAML stands for Security Assertion Markup Language. It is a standard for achieving Single Sign On functionality. An excellent introduction to the subject can be found on YouTube: https://www.youtube.com/watch?v=S9BpeOmuEz4

SAML2.0 support in Oracle Service Cloud

Oracle Service Cloud supports SAML2.0 Single Sign On. However, official documentation is a bit thin on the details. Unofficial sources, although useful, are sometimes conflicting and not all of sufficient quality. This write up aims to fill in the blanks.
A common way of setting up SAML SSO is through exchange of federation metadata XML files. These are files containing all the configuration settings necessary to make the service provider (the application) “talk SSO” with the identity provider (ADFS). MS ADFS supports this rather convenient feature. Unfortunately, Oracle Service Cloud does not. This means that we need to be well prepared to perform some manual configuration.

Preparation: What we need from Oracle

First thing for SSO to function on Oracle Service Cloud is for Oracle to enable SSO for the site. Request this from your Oracle representative. Once this step is completed, the “SSO Log-in (SAML 2.0)” tickbox becomes available in Profile Permissions, under Staff Management in the RightNow client:

Things the ADFS administrator needs from the Oracle Service Cloud consultant

1. The name of the LDAP user attribute containing the username that Oracle Service Cloud will use for login. Typically this will be something like “cn” or ”sAMAccountName”. The exact attribute needs to be explored together with the LDAP/domain administrator.
   If no users have been created in Oracle Service Cloud yet (or the existing users can be discarded), it makes sense to use the same attribute as is used for Windows login.
   However, if users already exist in Service Cloud, these users cannot be discarded and their login names do not match anything that is currently present in LDAP, a new LDAP user attribute may need to be created for the Service Cloud login name.
2. For setup of the federation, the ADFS administrator will want to know the name of the item in the SAML token (the subject) that the previously mentioned username attribute will map to. Typically this is “NameID”.
3. The Federation Protocol, which in this case is SAML2.0.
4. Whether the application supports Service Provider initiated SSO. To the best of my knowledge, Oracle Service Cloud does not. IdP (Identity Provider) initiated SSO is used. This means that users visit a link provided by ADFS, where they provide their credentials (or are automatically recognized based on earlier authentication, hence SSO). Upon authentication, a redirect takes place to the Service Cloud endpoint URL.
5. The token encryption type. Oracle Service Cloud does not support decryption of SAML tokens. Therefore tokens cannot be encrypted. This means that information in the token will be out in the open if SSL is not used. An HTTPS endpoint URL is therefore highly recommended.
6. An endpoint URL. This is the URL that authenticated users will be redirected to, in order to open the application. For SAML2.0 Agent Login, this is typically https://<SITENAME>.custhelp.com/cgi-bin/<INSTANCE>.cfg/php/admin/sso_launch.php?p_subject=Account.Login . The “subject” parameter determines the mapping of the “NameID” from the SAML token to a user-identifying attribute in Oracle Service Cloud. In this case, the value from “NameID” will be mapped to the Login field on the Account object. This is possible due to the fact that Account.Login is a unique key.

Things the Oracle Service Cloud consultant needs from the ADFS administrator

1. The ADFS Token Signing certificate. The SAML token that is sent by ADFS on user login contains the assertion that a certain user is genuine and authenticated. Since this information is crucial for access to the service, the token needs to be verified for its integrity. Verification is done by means of checking the certificate by which the token was signed. Your ADFS administrator will be able to provide the certificate used for token signing. Oracle Service Cloud accepts Base64 encoded certificates in “.pem” format. For more information on certificates, please refer to Wikipedia article https://en.wikipedia.org/wiki/X.509 .
2. If the certificate is not self signed, possibly a root and/or intermediate certificate needs to be provided. Ask your ADFS administrator about this. Root and intermediate certificates need to be in Base64 encoded “.pem” format as well.
3. A SHA1 hash of the token signing certificate is needed for Oracle Service Cloud configuration. Possibly, the ADFS administrator has already provided the SHA1 hash (often called fingerprint) with the certificate. If this is not the case, there are multiple ways to obtain it:
   * On Windows, make a copy of the certificate “.pem” file and change the extension to “.cer”. Then double click the file to open it. In the Details tab, scroll to “thumbprint”. The value shown here is the SHA1 hash of the certificate.
   * If you are working on Linux, you can use openssl. Use the following command: “openssl x509 -fingerprint -in certificate.pem”. The SHA1 hash value of the certificate will show.Regardless of what method was used to obtain the hash, remove all spaces and colons. The remaining string should be 40 characters long, similar to “2346AD27D7532CA9896F1B7DB6B8341251DEBFG2”. Save this string somewhere for future reference.

Make sure that the ADFS server and the Oracle Service Cloud server are time-synced, since time mismatches may lead to problems that are difficult to troubleshoot.

Configuration

With all preparation done, we can configure both the ADFS and Oracle Service Cloud sides.

ADFS side

The ADFS administrator will need to create a Relying Party Trust. Use the preparation items as input for this:

1. Manual configuration.
2. ADFS2.0
3. No token encryption.
4. Use the WebSSO protocol.
5. Endpoint url from the preparation step, typically https://<SITENAME>.custhelp.com/cgi-bin/<INSTANCE>.cfg/php/admin/sso_launch.php?p_subject=Account.Login .
6. Add a claim rule to send an LDAP attribute as a claim.
7. Map the username LDAP attribute to the NameID claim.

This should suffice to set up the ADFS side. After completion, the ADFS administrator should provide an IdP authentication URL, where end users can identify themselves before being redirected to Oracle Service Cloud.

Oracle Service Cloud side

The Oracle Service Cloud consultant also needs to perform some steps.

1. First, verify the certificate. Many common SSO problems are certificate related. Since Oracle Service Cloud is a cloud product with limited access to debug output, it is important to get this right, since troubleshooting can be a pain. With OpenSSL the certificate can be verified (example on Linux machine):
   

   openssl verify certificate.pem

   If it complains that the issuer cannot be verified, an additional root and/or intermediate certificates need to be added as a certificate authority (CA). Multiple certificates in the chain can be concatenated into a single chain “.pem” file which can be used as CA. Verify again:

   openssl verify –CAfile rootcert.pem certificate.pem

   Something similar to the following should result:

   certificate.pem: OK

2. With the certificates verified, we can upload the “.pem” files to Oracle Service Cloud. In the client application, go to “Site Configuration” -> “File Manager”. Upload the “.pem” files to folder “Additional Root Certificates”.
3. In the client application, go to “Site Configuration” -> “Configuration Settings”. Find the “SAML_20_SIGN_CERTS” property. Here we enter the previously obtained SHA1 hash value of the ADFS Token Signing certificate.
4. Then find the “USE_KNOWN_ROOT_CAS” property. If necessary, put it to its default (Yes).
5. Save your configuration.

Testing and troubleshooting

After ADFS configuration completion, the ADFS administrator provided a login URL. Open this URL in your browser and enter your credentials. A redirect should take place to the Oracle Service Cloud application. If this leads you to a cryptic error like “saml18”, check the following:

1. Are the certificates verified and OK?
2. Is the hash value of the certificate entered correctly in the SAML_20_SIGN_CERTS property?
3. Is the endpoint URL configured correctly in ADFS?

Ideally, SSO authentication will succeed, which will lead you to a download page for the RightNow client. The application should start. If it fails with an error message popup at this point, check the following:

1. Is SSO enabled for the profile of your user?
2. Are there any mismatches in usernames between Oracle Service Cloud and the LDAP username attribute? Usernames are case sensitive!

If at this point you still have no luck, there is always the kind people of Oracle Support to lend a hand, but probably by now you will be enjoying the benefits of SSO Agent login on Oracle Service Cloud!