Article donated by: Simon Godik, Hernan Cunico

Login Domain

According to the SAML specification a Principal is a system entity whose identity can be authenticated. Identity Provider is a service provider that creates, maintains, and manages identity information for principals [and provides principal authentication to other service providers (not to get too entangled)];

A principal can have any number of attributes; identity is just one of them; Other attributes are groups, locations, etc; Logically these values are asserted by the Attribute Authority based on the identity; In practice Identity Provider and the Attribute Authority are usually collocated (although in complex SOA models providers can form a federation for identities and attributes);

Note that the reliance on Identity Provider and Attribute Provider implies certain level of trust between the Geronimo server and service providers. How trust is established is out of scope here, but it could be implicit, by agreement, by assertion, etc.

What is described here as the Identity Provider and Attribute Authority together with the established trust relationship Geronimo calls Login Domain; JAAS login modules (that abstract login domains) query for the identity and group attributes of a principal and believe that they are authentic.

On example of Login Domain is LDAP directory server.It combines maintenance of identity information and other attributes (such as groups etc); Relational Database with tables for users and groups is another.

Security Realm
Security realm configures and enforces application-specific authentication policy and is the entry point into login domains; Security realm implements pluggable authentication framework allowing for a combination of authentication protocols with different properties and different trust relationships that match application requirements;

Authentication policy for the security realm is expressed as a statement over authentication outcome of configured login domains;

For example, we can configure security realm with 2 login domains: kerberos , and active directory, and require that both of them succeed for the authentication to succeed. Or we can configure security realm with the LDAP directory login domain without any regard for the authentication outcome from it (maybe because we do not trust it); The point here is that we express authentication policy and have security realm enforce it;

Of course security realm authentication policy emulates JAAS login module combination semantics. In fact, security realm implementation is wired with the JAAS login modules that are configured with the familiar attributes such as control flag and options; Authentication procedure is driven by the Login Module JAAS API and authentication result is computed over control flag values and authentication outcomes of individual login modules;

Authentication and Principals
As authentication proceeds each login domain (implemented by the login module) creates it's own principals that implement java.security.Principal interface.

There are many implementations of the java.security.Principal interface in Geronimo:

• org.apache.geronimo.security.RealmPrincipal
• org.apache.geronimo.secuirty.PrimaryRealmPrincipal
• org.apache.geronimo.security.DomainPrincipal
• org.apache.geronimo.security.IdentificationPrincipal
• org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal
• org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal

Principals are created by the login domains, so ideally a principal must be associated with the login domain. To that end, org.apache.geronimo.security.DomainPrincipal will wrap every principal created by the login module (login domain) and in turn it will be wrapped by the org.apache.geronimo.security.RealmPrincipal if security realm is configured to wrap login modules.

Despite it's name org.apache.geronimo.security.realm.providers.GeronimoCallerPrincipal interface is just a marker and is implemented by the org.apache.geronimo.security.providers.GeronimoUserPrincipal; This type of principal is added to the set of principals of the Subject within login modules distributed with Geronimo. There is no interface that would assure GeronimoUserPrincipal is indeed included, so do not forget about it if you write your own login module. In fact, some of the Geronimo login modules do not include this type of principal (eg FileAuditLoginModule)

There are some special types of Principal's that are created after authentication procedure succeeds and used by Geronimo to track authenticated subject through it's lifetime in the container.