Single Sign-On API

From Apache OpenOffice Wiki
Jump to: navigation, search


Users of a client application that can communicate with a variety of services on a network may need to enter several passwords during a single session to access different services. This situation can be further exacerbated if the client application also requires the user to enter a password each time a particular network service is accessed during a session.

As most network users must authenticate to an OS at login time, it would make sense to access some of the required network services at this time as well. A solution to this problem is provided by the Single Sign-On (SSO) methodology, which is the ability to login in once and access several protected network services.

The best known SSO is the Kerberos network authentication protocol (see rfc1510). Kerberos functionality is commonly accessed through the Generic Security Service Application Program Interface (GSS-API, see rfc2743). Central to GSS-API is the concept of a security context, which is the "state of trust" that is initiated when a client (also known as source or initiator) identifies itself to a network service (also known as target or acceptor). If mutual authentication is supported, then the service can also authenticate itself to the client. To establish a security context, security tokens are exchanged, processed, and verified between the client and the service. The client always initiates this exchange. Once established, a security context can be used to encrypt or decrypt subsequent client-service communications.

The SSO API is based on GSS-API. The SSO API supports the creation of security contexts on the client and the service side as well as the generation of the security tokens that are required for the exchange to complete the security context based authentication. The SSO API does not support the actual exchange of security tokens or the encryption or decryption of client-service communications in an established security context. implements SSO in two different ways to authenticate with an LDAP server for configuration purposes. The first is Kerberos based and the second is a simple non-standard "cached username/password" SSO. The latter is provided as a fallback to support scenarios where no Kerberos server is available.

Implementing the SSO API

Implementing the SSO API involves creating security context instances (see XSSOInitiatorContext and XSSOAcceptorContext below) and using these instances to create and process security tokens. All of the SSO interfaces are available from the ::com::sun::star::auth namespace. The major interfaces are shown in Illustration 7.22 and described below.


Represents the starting point for interaction with the SSO API. This interface is responsible for providing XSSOManager (described below) instances based on the user's configured security mechanism e.g. "KERBEROS".


This interface is responsible for the creation of unestablished security contexts for clients (XSSOInitiatorContext) and services (XSSOAcceptorContext). An XSSOManager instance "supports" a single security mechanism, that is, the context instances that are created by an XSSOManager instance only interact with a single security mechanism implementation.


This interface represents a client-side security context that is unestablished when it is created. A single method, init(), is provided so that you can create an initial client-side security token that can be delivered to the relevant service and for processing or validating returned service-side security tokens (if mutual authentication is supported). The expected sequence of events for this client-side security context is:

  • The client calls init(), passes NULL as the parameter, receives an appropriate client-side security token in return.
  • The client sends the security token to the relevant service.
  • If the service successfully processes this token, the client is authenticated.
  • If mutual authentication is not supported, the client-side authentication sequence is now complete.
  • If mutual authentication is supported, the service sends a service-side security token to the client.
  • The client calls init() a second time and passes the returned service-side security token as a parameter. If the token is successfully passed, the service is authenticated.

This interface represents a service-side security context that is not established when it is created. A single method, accept(), is provided and is responsible for processing an initial client-side security token. If mutual authentication is supported, the method also generates a service-side security token for the client. The expected sequence of events for this service-side security context is:

  • The service receives the client-side security token.
  • The service calls accept(), passes the client-side security token as a parameter, and if successful, the client is authenticated.
  • If mutual authentication is not supported, the service-side authentication sequence is now complete.
  • If mutual authentication is supported, accept() returns a non-zero length service-side security token.
  • The service sends the service-side security token to the client to authenticate the service.
Major Interfaces of the SSO

The following example is a sample usage of the SSO API that provides the authenticate() method of the fictitious client--side MySSO class. For simplicity, assume that MySSO has the following members:

  • mSourceName identifies a client-side user that needs to authenticate to a network service.
  • mTargetName identifies the service to which the user needs to authenticate.
  • mTargetHost identifies the network host where the service of interest is running.
  namespace auth    = ::com::sun::star::auth;
  namespace lang    = ::com::sun::star::lang;
  namespace uno     = ::com::sun::star::uno;
  void MySSO::authenticate(void) {
      static const rtl::OUString kSSOService( 
      uno::Reference< lang::XMultiServiceFactory > theServiceFactory =
      // Create an SSO Manager Factory.
      uno::Reference< auth::XSSOManagerFactory > theSSOFactory(
          theServiceFactory->createInstance(kSSOService), uno::UNO_QUERY);
      if (! {
      // Ask the SSO Manager Factory for an SSO Manager.
      uno::Reference<auth::XSSOManager> theSSOManager =
      if (! {
      // Ask the SSO Manager to create an unestablished client/initiator side 
      // security context based on user name, service name and service host.
      uno::Reference<auth::XSSOInitiatorContext> theInitiatorContext =
          theSSOManager->createInitiatorContext(mSourceName, mTargetName, mTargetHost);
      // Now create the client side security token to send to the service.
      uno::Sequence<sal_Int8> theClientToken = theInitiatorContext->init(NULL);
      // The client should now send 'theClientToken' to the service.
      // If mutual authentication is supported, the service will return a service
      // side security token.
      uno::Sequence<sal_Int8> theServerToken = ''sendToken(theClientToken);''
      if (theInitiatorContext->getMutual()) {

The SSO Password Cache

When you implement the SSO API, you may require access to user passwords, especially if you are relying on a preexisting underlying security mechanism. If you do not know how to gain such access, you can use the SSO password cache. This cache provides basic support for maintaining a list of user name or password entries. Individual entries have a default lifetime corresponding to a single user session, but can optionally exist for multiple sessions. Support is provided for adding, retrieving, and deleting cache entries. Only one entry per user name can exist in the cache at any time. If you add an entry for an existing user name, the new entry replaces the original entry.The SSO password cache is represented by a single interface, namely the XSSOPasswordCache interface, available in the ::com::sun::star::auth namespace.

Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages