Directory

This tutorial describes how to integrate JOSSO with a Directory server. User will be authenticated by JOSSO with an LDAP Bind (connection) to the server using the retrieved user credentials (user identifier and password). In order to use a Directory server as the identity source for user and role information, an LDAP server accessible from the JOSSO 2 Server. The TCP/IP ports involved in an LDAP session are the 389 and the 636 for SSL. JOSSO will work with any LDAPv3 supporting server.

Prerequisites

Before starting, make sure that the following prerequisites are meet.

• JOSSO 2.4.x instance

• LDAP Server

• LDAP Service account, used by JOSSO to retrieve user and role information.

• Partner application (can be the sample application provided by JOSSO)

You may want to set the password expiration policy to never to prevent future problems.

Defining Identity Appliance Elements

The first step is to define the elements that represent the Identity Provider (IdP) in the Identity Appliance. The following components must be added to the model:

• SAML Identity Provider: represents the core set of identity services.

• LDAP Identity Source: represents the user repository, and the rules to retrieve user and role information.

• Directory Service Authentication: represents the repository used to authenticate users by performing binds.

• JOSSO 1 Resource: The resource represents the sample application, it holds information about the application base URL

• Tomcat Execution Environment: This elements represents the Tomcat server where the application is running. Here you can specify the server version, etc.

LDAP Identity Source

This element representes the directory server where user and role information is stored. The following properties need to be configured:

Property	Description
Name	Name for the directory server
Description	Additional information about the directory server.
Initial Context Factory	Default Java Naming Directory Interface (JNDI) component, normally this value is never chaged.
Provider URL	The ldap server URL, normally in the form: , where protocol can be ldap or ldaps (for secure connections). Make sure that the port matches the protocol.
Security Principal	the DN of the user to be used by to bind to the LDAP Server when retrieving user and role information (service account).
Security Credential	the Security Principal password to be used for binding to the LDAP Server.
Security Authentication	the security level to be used with the LDAP Server session. Its value is one of the following strings: "none", "simple", "strong".
User DN	the fixed distinguished name for the context to search for user accounts, when SUBTREE is set as Search Scope, users will also be searched in sub-contexts.
Principal UID Attribute	the name of the attribute that contains the user identifier. This is used to locate the user.
Search Scope	the search scope used for querying the LDAP server. Valid values are SUBTREE and ONELEVEL. See User DN bellow.
Role Matching Mode	Default to distinguish name. Allows to configure how roles refer to users: Full DN, only the user identifier or principal name.
UID Attribute ID	the name of the attribute that, in the object containing the user roles, references role members (users). The attribute value should be the DN (or UID, see Role Matching Mode above) of the user associated with the role. This is used to locate the user roles.
Roles DN	The fixed distinguished name to the context to search for user roles.
Role Attribute ID	The attribute containing the role name
Updatable Credential Attr.	Reserved for future use
Credential Query	The query string to obtain user credentials. It should have the following format : user_attribute_name=credential_attribute_name,… For example : uid=username,userPassword=password This is ONLY used when Directory authentication is not present.
User Properties Query	The query string to obtain user properties. It should have the following format : ldap_attribute_name=user_attribute_name,… For example : mail=mail,cn=description

Since JOSSO relays on Java JNDI support, you must ensure that the server certificate is configured as trusted in the JDK instace used by JOSSO when using LDAPS (SSL).

When using Active Directory, we must use the following values:

• Security Principal : either the service account full DN, or in the form of DOMAIN/user

• Principal UID Attribute : sAMAccountName

• UID Attribute ID : member

• Role Attribute ID : sAMAccountName

In our example, we’re using OpenLDAP, so we must modify: * Provider URL * Security Principal and Credential * User and context DN

Directory Service Authentication

This element is used when we want to delegate the credential validation process to the LDAP Server. This may or may not be the same server used to retrieve user information. It is important to DISABLE the basic authentication settings for the identity provider when using LDAP Bind based authentication. (IdP, Authentication section).

When this element is not present, JOSSO will try to retrieve username and password using the Credentials Query settings on the LDAP Identity Source, and will then validate them based on the Basic Authentication settings, available in the Identity Provider.

The set of properties available is actually a sub-set of those available for LDAP Identity Sources

Property	Description
Name	Name for the directory server
Description	Additional information about the directory server.
Initial Context Factory	Default Java Naming Directory Interface (JNDI) component, normally this value is never chaged.
Provider URL	The ldap server URL, normally in the form: where protocol can be ldap or ldaps (for secure connections). Make sure that the port matches the protocol.
Perform DN Search	Useful when the username does not match the UID attribute (i.e. using emails)
	Security Principal
the DN of the user to be used by to bind to the LDAP Server when retrieving user and role information (service account).	Security Credential
the Security Principal password to be used for binding to the LDAP Server.	Security Authentication
the security level to be used with the LDAP Server session. Its value is one of the following	User DN
the fixed distinguished name for the context to search for user accounts, when SUBTREE is set as Search Scope, users will also be searched in sub-contexts.	Principal UID Attribute
the name of the attribute that contains the user identifier. This is used to locate the user.	Search Scope

In our example, we’re using OpenLDAP, so we must modify. In this case, this values will match those configured in the LDAP Identity Source. * Provider URL * Security Principal and Credential * User and context DN

When using active directory, this element is mandatory. AD does not allow applications to retrieve user credentials, this prevents JOSSO from reading passwords for validation.

SAML Identity Provider

This element represents SAML 2 identity services backed by the Directory service. For details on how to modify the default SAML options refer to JOSSO 2.4 reference guide.

In this tutorial we are focusing on the Authenticaiton section of the IdP. Since we’re using LDAP Bind authentication, we must disable the Basic Authentication mechanism built-in the IdP.

JOSSO 1 Resource

This elements represents a web resource/application that uses a JOSSO agent as SSO enabling mechanism. In this case, this represents our ASP application. The key properties are name and location. The name should also be a meaningful value describing the application (i.e. crm). It is also a good practice using a value similar to the one selected for the Service Provider (SP). For this tutorial partnerapp was selected. The location property refers to the application base URL (i.e. ). In this tutorial the application is actually not the entire site, but resources under the /partnerapp path. The configured location is:

Tomcat Execution Environment

The final element is the execution environment. The Tomcat Execution Environment has information used to install the JOSSO Tomcat Agent, like the server location and version.