Wednesday, January 31, 2007

Implementing Single Sign On (SSO) with a WebLogic Identity Asserter

I worked on an interop project this week that required me to do something I haven't done in a while - develop an SSO solution for WebLogic Server or WebLogic Portal. In this case, my WebLogic Portal 9.2 instance needed to consume a token in the request header and derive Identity from that. In the WebLogic world, an Identity Asserter is the tool for the job. This blog entry details the steps to implement a custom Identity Asserter with WebLogic Server (or WebLogic Portal).

NOTE: this blog entry was originally posted February 1st, 2007 on my previous blogging system (


Identity Asserters and Single Sign On

An Identity Asserter is a pluggable WebLogic component that can determine the identity of a user through inspection of a token in a request header, a cookie, or other mechanisms. This is a useful feature to employ when implementing Single Sign On for your WebLogic project. It allows for an external entity to authenticate a user, and enables WebLogic to honor that authentication.

Identity Asserters aren't new. They have been with WebLogic for years. Out of the box, WebLogic provides an Identity Asserter that supports a variety of token types: X509 certificates, SPNEGO tokens, SAML assertion tokens, and CORBA Common Secure Interoperability version 2 (CSIv2). In addition, 3rd party Identity Management vendors will typically have a pre-built WebLogic Identity Asserter available for you.

However, there are times when a custom Identity Asserter is required. This is the approach I pursued on my project. In my case, an external proxy server has authentication capabilities, and places a token on the request to WLP that identifies the user. I needed a custom Identity Asserter that could look for that token, and decode it. To build my custom Identity Asserter, I took the sample from dev2dev and modified it to suit my needs. I have deployed this on WebLogic Portal 9.2 (which is built on WebLogic Server 9.2). The rest of this blog explains the development and configuration steps.


Development and Configuration of a Custom Identity Asserter

Below is the list of steps to build and configure the Identity Asserter:

0. Download the sample Identity Asserter from dev2dev

  • Available on dev2dev Codeshare here (as of 2009, no longer available. see comments)
  • Look for a project called "Sample Security Providers"
  • The samples may not be for your exact version of Weblogic, but they will likely be compatible from 8.1 onwards.
  • The download will contain a build system as well as samples of other types of providers

1. Unpack and alter the SimpleSampleIdentityAsserter code and descriptor

  • Look in src\providers\identityassertion\simple, you will need to modify both .java and .xml files
  • Search and replace "SamplePerimeterAtnToken" in all files with the name of your custom token/request header
  • In make these changes:
    Where the sample code is working with TOKEN_PREFIX in the assertIdentity method, you will need to change the code to parse the value of the token, perhaps decrypting it, and derive the username. The work done here is very specific to the type of token you are expecting.
  • If you don't want the container to automatically decode the token payload using Base64 decoding, make sure you have this in the .xml descriptor:
    Name = "Base64DecodingRequired"
    Type = "boolean"
    Writeable = "false"
    Default = "false"

2. Go to your WLS/WLP domain home/bin, and execute setDomainEnv.cmd/sh in your command line shell.

3. Navigate back to the root dir of the SSPI sample directory where build.xml exists.

4. Compile with default Ant task ("ant"). The build puts the jar in BEA_HOME/weblogic92/lib/mbeantypes/wlSecurityProviders.jar

5. Edit web.xml of the webapp that will participate in the Identity Assertion and add/update the login-config element:





6. Launch WLS/WLP (startWebLogic.cmd/sh).

7. Launch the WLS console (usually http://localhost:7001/console), and create a new instance of this Identity Asserter.

  • Navigate to Security Realms -> My Realm -> Providers tab -> Authentication sub tab

  • Click "Lock & Edit"

  • Click "New"

  • Name = [give it a meaningful name] Type = SimpleSampleIdentityAsserter

  • Click "Release Configuration"

8. Restart the server.

9. Target any resource in the web application with a browser in a way that properly populates the token. You should see output from the debug in the Identity Asserter indicating that the user has been identified. If the username exists in a configured authentication provider, the request will be authenticated.

Next Steps: Left as an exercise to the reader:

Rename SimpleSampleIdentityAsserter to something more appropriate

  • Change SimpleSampleIdentityAsserter references in .java and .xml files

  • Update the build to reflect the name change

Additional Resources

SSO Related:


Sam said...

hi peter,

Can you please post the source files for custom identity assertion? I am not able to get it from the link provided by you.

Thank you.


Peter Laird said...


I no longer work for Oracle. While I was still there, I wasn't able to locate that download after the BEA acquisition. Its a shame, it was a convenient package that made it fast to get going.

I think the only option now is to setup your own dev environment using the information on this page:

Identity Asserter Documentation

Sam said...

Ok. Thank you Peter. I will try of my own.

james henry said...

Nice post, very helpful to know about single sign on. can you please share open source for it like sam said

single sign on