# Presentation: 575506

## JPL Directory Service

**User Authentication and Authorization**
**For**
**Developers**
- By
- Tom Wolfe

**Notes:**
Welcome.

This is a very high-level overview of using the JPL directory service to authenticate and authorize users.  More detailed information and help pertaining to your particular environment can be obtained from the JPL Directory Service

Authenticate means to verify who the user is using some technology.  Today it is usually a username and password.

Authorize is the verify that a user is allowed access to a resource.  If not allowed, they are prevented access.  One aspect of authorization is what kind of access is allowed.  Read, Modify, List, Search, etc.

## Agenda

- Authentication and Authorization
- Architecture
- SSL/TLS Handshake
- Introduction to LDAP Directories
- Available Code Examples
- Available Apache Security Modules
- MOD_LDAP and MOD_AUTH_LDAP
- Directory Web Site
- Questions and Discussion

- 2005-08-16

## Authentication
JPL standard username and password
Username and password maintained in the JPL directory
Password matching the username’s directory entry is proof of identity
Authorization
Role based access control
Groups maintained in the JPL Directory
Group membership allows access to web content

- JPL standard username and password
- Username and password maintained in the JPL directory
- Password matching the username’s directory entry is proof of identity
- Authorization
- Role based access control
- Groups maintained in the JPL Directory
- Group membership allows access to web content

- Authentication and Authorization

- 2005-08-16

## Architecture

- 2005-08-16

## SSL/TLS handshake:

- The client ask the server for a secure connection.
- The server sends the client it’s digital certificate to identify itself along with it’s public key.
**The client verifies the server’s identity (certificate).**
- The client sends the server a random session key encrypted with the server’s public key.
- The server decrypts the session key using it’s private key and establishes a secure session.

- 2005-08-16

**Notes:**
This a is greatly simplified version of the SSL/TLS handshake.  It’s purpose is to demonstrate the overall steps.

The import thing here is the client verifying the server identity.

Third party trust.  The CA is the third party.

## Verifying the server’s identity:

- The client checks the digital signature of the certificate sent by the server to identify itself. It uses a CA certificate from a list of trusted CA’s.  If everything is correct, the server’s certificate is valid and it has not been modified.  **The server’s certificate is trusted**.
- The client checks the name in the server’s certificate to verify it is who they wanted to connect to.  **The client is connected to the right server.**

- 2005-08-16

**Notes:**
No all LDAP security modules do both steps.

Some modules have the ability to turn off one or both of these steps.  Some do not.

## Introduction to LDAP Directories

- Generic
- Directory Information Tree (DIT)

- Each entry has attributes
- Each attribute has a name, type, ACI, and one or more values
- Each entry is defined by an attribute and a value
- Intermediate entry must exist for a leaf entry to exist

- 2005-08-16

**Notes:**
For a leaf node to exist all of the nodes to the root must exist, even if the contain no useful information.  This is much like a file system.  For a sub-directory to exist the parent directory must exist.

From a users point of view, the node contains only attributes.  The defining attribute/value if just on of them. 

Attributes contain one or more values.  If an attribute has no values it does not exist.  That is to say, when querying an attribute with no values, it is NOT found instead of returning the attribute with no values in.

## Introduction to LDAP Directories

- JPL LDAP Directory
- Directory Information Tree (DIT)

- The Distinguished Name (DN) of the entry for joeuer is:
- uid=joeuse, ou=personnel, dc=dir, dc=jpl, dc=nasa, dc=gov

- dc=gov

- dc=nasa

- dc=jpl

- ou=personnel

- dc=dir

- uid=joeuser

- cn=groupx

- The Distinguished Name (DN) of the entry for groupx is:
- cn=groupx, ou=personnel, dc=dir, dc=jpl, dc=nasa, dc=gov

- 2005-08-16

**Notes:**
All nodes have Distinguished names (DN) the distinguish it (give it a unique name) from all other nodes in the tree.

The DN is the path from a note to the root of the tree.

## Introduction to LDAP Directories

- uid=joeuser,ou=personnel,dc=dir,dc=jpl,dc=nasa,dc=gov
- uid = joeuser , ou=    personnel , dc   =dir , dc  =  jpl  ,
- dc   =   nasa ,    dc = gov

- Distinguished Names (DN) are a unique directory data type.  They are not strings and therefore comparison of their string representation can be tricky.  Like integers, and other data types, they have their own matching rule.  For example, the following DNs are the same (equal).

- 2005-08-16

## Introduction to LDAP Directories

-          dn: uid=joeuser, ou=personnel, dc=dir, dc=jpl, dc=nasa, dc=gov
- Attribute: jplmailstop
-     Value: 230-305
- Attribute: postalAddress
-     Value: 4800 Oak Grove Drive $ M/S 230-305 $ Pasadena, CA 91109
- Attribute: departmentNumber
-     Value: 373G
- Attribute: givenName
-     Value: Joe
- Attribute: sn
-       Value: User
- Attribute: jplService
-     Value: docushare
-     Value: RAS
**        ****...**

- _User Directory Entry Example_

- 2005-08-16

**Notes:**
Each attribute and a name and abbreviation.  For example the attribute directoryComponent has the abbreviation DC.

Not all attributes are available to everyone.  Some are available with an anonymous bind. Sow with authenticated bund and some with specific authentication.  For example JPLService is only settable with special credentials.

## Introduction to LDAP Directories

-          dn: cn=groupx, ou=personnel, dc=dir, dc=jpl, dc=nasa, dc=gov
- Attribute: uniqueMember
-     Value: uid=joeuser,ou=personnel,dc=dir,dc=jpl,dc=nasa,dc=gov
-     Value: uid=janeuser,ou=personnel,dc=dir,dc=jpl,dc=nasa,dc=gov
- Attribute: cn
-     Value: groupx
- Attribute: owner
-     Value: cn=eis.ops,ou=personnel,dc=dir,dc=jpl,dc=nasa,dc=gov
-     Value: uid=joeuser,ou=personnel,dc=dir,dc=jpl,dc=nasa,dc=gov
- Attribute: objectClass
-     Value: top
-     Value: jplgroup
-     Value: groupOfUniqueNames

- _Group Directory Entry Example_

- 2005-08-16

**Notes:**
Groups have entries in the uniqueMember attribute.  The DNs of the members of the group.

This is where the problem is DN comparisons occurs.  It is best to do a server side compare rather than compare string in the client.

## Available Code Examples

- Apache Web Server
- C
- ColdFusion
- Java
- Perl
- Python

- LDAP Tools
- ldapsearch
- ldapcompare
- Microsoft
- C#
- VBasic

- 2005-08-16

## Available Apache Security Modules

- Apache authentication and authorization using a LDAP Directory
- C modules
- mod_ldap
- mod_auth_ldap
- Others
- Mod_Perl modules
- AuthenLDAP
- Gatekeeper
- Others
- Mod_Python modules
- PHP
- Others

- 2005-08-16

**Notes:**
When using Apache basic authentication (Username/password), the password is sent to the LDAP server in the clear.  This requires the connection to the LDAP server to be secure. 

SSL and TLS provide secure connections form the client to the server.

SSL is the older standard.  The LDAP server listens for SSL connection on port 389.

TLS in the newer standard.  TLS uses port 80. 

## MOD_LDAP and MOD_AUTH_LDAP

- LoadModule  mod_ldap  modules/util_ldap.so
- LoadModule  mod_auth_ldap  modules/mod_auth_ldap.so
- LDAPTrustedCA  /usr/local/cert/cacert.pm
- LDAPTrustedCAType  BASE64_FILE
- LDAPSharedCacheSize  200000
- LDAPCacheEntries  1024
- LDAPCacheTTL  600
- LDAPOpCacheEntries  1024
- LDAPOpCacheTTL  600

- httpd.conf

- 2005-08-16

**Notes:**
Goes in the httpd.conf file
(or one of the other config file if you are using SuSE Linux which broke the httpd.conf file in to multiple, smaller, config files) 

Load modules in necessary.  This depends on the apache installed.

TTL – Time To Live

LDAPSharedCacheSize – cache size in bytes
LDAPCacheEntries - entries
LDAPOpCacheEntries - compare operations entries

## MOD_LDAP and MOD_AUTH_LDAP

- <Directory /usr/local/mydocs>
-    AuthType  Basic
-    AuthName  "JPLIS Directory Authentication“
-    AuthLDAPURL  ldaps://ldap.jpl.nasa.gov/ou=personnel,
-                              dc=dir,dc=jpl,dc=nasa,dc=gov?uid?sub
-    AuthLDAPEnabled  on
-    AuthLDAPAuthoritative  on
-    Options  –indexes
-    AuthLDAPGroupAttributeIsDN  on
-    AuthLDAPCompareDNOnServer  on
-    require group  cn=mygroup,ou=personnel,dc=dir,
-                            dc=jpl,dc=nasa,dc=gov
- </Directory>

- httpd.conf
- .htaccess

- 2005-08-16

**Notes:**
Directory container

## Directory information
Code examples
Create and maintain groups
And much more

- Directory information
- Code examples
- Create and maintain groups
- And much more

- Code examples are temporarily available at
-    http://eis.jpl.nasa.gov/~tlwolfe/directory-code-examples/
-    directory_code_examples_main.html
- until the can be transferred to the official directory web site.

- Directory Web Site

- 2005-08-16

## Questions

- and
-  Discussion

- Help with using the directory for authentication and
- authorization is available from the JPL Directory Service.

- 2005-08-16

## Are there more languages you would like to add to the directory (LDAP) code examples?
Would you like a class on LDAP programming?
Which language should the class use?
How long a class?  Hours, days?
What more would you like to see?

- Would you like a class on LDAP programming?
- Which language should the class use?
- How long a class?  Hours, days?
- What more would you like to see?

- My Questions

- 2005-08-16

## Supplemental Slides

- 2005-08-16

## Definitions

| attribute | Attributes contain the information about an entry in the directory. |
| --- | --- |
| Attribute type | Each type of attribute has an associated syntax that defines what kind of information is allowed to be stored in the attribute’s values and how those values behave during searches and other directory operations. |
| authentication | A method used to establish the identity of a user, program, process, or system. |
| authorization | The method used to grant a user, program, process, or system access to data, programs, processes, or systems. |
|  |  |
|  |  |

- 2005-08-16

## Definitions

| DIT | Directory Information Tree structure |
| --- | --- |
| LDAP | Light Weight Directory Access Protocol |
| SSL | Secure Socket Layer. It run just above TCP/IP and below high-level protocols like HTTP or IMAP. |
| TLS | Transport Layer Security.  A new standard based on SSL. |
|  |  |

- 2005-08-16

## A PKI certificate is:
A data record that contains
Certificate format
Identity of the issuing CA
Identity of the subscriber
The public key corresponding to a private key under the control of the subscriber
Date issued
Date expires
Certificate serial number
Certificate usage
Digitally signed by the issuing CA 

- A data record that contains
- Certificate format
- Identity of the issuing CA
- Identity of the subscriber
- The public key corresponding to a private key under the control of the subscriber
- Date issued
- Date expires
- Certificate serial number
- Certificate usage
- Digitally signed by the issuing CA

- PKI Certificate

- 2005-08-16

## 1. What are your security requirements?
What web content requires controlled access?
ITAR/EAR
JPL confidential
Project sensitive
Other
What kind of access is needed?
Read only
Read/write
Other

- What web content requires controlled access?
- ITAR/EAR
- JPL confidential
- Project sensitive
- Other
- What kind of access is needed?
- Read only
- Read/write
- Other

- Web Server HowTo

- 2005-08-16

## 1. What are your security requirements (cont)?
Who or what needs access to web content?
General public
JPL employees
Foreign nationals
Project members
Subtask members
Administrators
Systems
Applications
Processes
Others

- Who or what needs access to web content?
- General public
- JPL employees
- Foreign nationals
- Project members
- Subtask members
- Administrators
- Systems
- Applications
- Processes
- Others

- Web Server HowTo

- 2005-08-16

## Web Server HowTo

- 2. Create LDAP groups to match your security requirements

| Type of
Access | Web Content
Type A | Web Content
Type B | Web Content
Type C |
| --- | --- | --- | --- |
| Read | LDAP
Group 1 | LDAP
Group 2 | LDAP
Group 3 |
| Read
Write | LDAP
Group 4 | LDAP
Group 5 | LDAP
Group 6 |
| Other | LDAP
Group 7 | LDAP
Group 8 | LDAP
Group 9 |

- 2005-08-16

## 3. Create a file system directory tree for your web content
Each kind of access should have it’s own sub-tree
Kind of access = web content type + type of access
Each sub-tree should be protected it’s own LDAP group
4. Define an Apache <Directory> or <Location> container for each sub-tree
Each container has a LDAP group defined in it that is used to control access to the web content in the sub-tree
httpd.conf
.htaccess
5. Create web content in the appropriate sub-trees

- Each kind of access should have it’s own sub-tree
- Kind of access = web content type + type of access
- Each sub-tree should be protected it’s own LDAP group
- 4. Define an Apache <Directory> or <Location> container for each sub-tree
- Each container has a LDAP group defined in it that is used to control access to the web content in the sub-tree
- httpd.conf
- .htaccess
- 5. Create web content in the appropriate sub-trees

- Web Server HowTo

- 2005-08-16

## Auth/Auth Pseudo Code

- The following pseudo code has two parts.  The first part creates and maintains session information for a user.  The second part test for group membership using information found in the session.
- The group allowed access to web content is “hard coded” in the web server configuration (files).  For example, in the <Directory> container using the mod_auth_ldap module or the Application.cfm files used by cold fusion.
- The group stored in the session is the last group the user was found to be a member of.  This provides a “one deep” look aside list that reduces the need to query the directory every time group membership is tested.
- The user’s DN is also stored in the session for group membership testing.

- 2005-08-16

## Auth/Auth Pseudo Code

**if (a session does not exist or has expired)**
**{**
**    ****loop-forever:**
**    ****{**
**        ****ask the user for a username and password**
**        ****search the directory for the username entered by the user**
**        ****if (only one entry was returned from the search)**
**        ****{**
**            ****bind to the directory using the DN returned from**
**            ****the search and the password entered by the user**
**            ****if (the bind was successful)**
**            ****{**
**               ****create a session**
**               ****store the DN-returned-from-the-search in the session**
**               ****set the group in the session to “” (empty string)**
**               ****exit loop-forever**
**}   }   }   }**
**<continued on next slide>**

- 2005-08-16

**Notes:**
Creating an maintaining a session is different from testing for group membership, but they depend on each other.
A look aside list (cache?) is useful. It speeds things up by reducing the number of times the directory must be accessed.  It also reduces network traffic.
The use of a look aside list (cache?) has a latency problem when things change.
A longer look aside list (cache?) means less trips to the directory.
Group membership is public (non-sensitive) information and does not require a secure connection to the directory. (Unless you are afraid of a man-in-the-middle attack.)
If multiple directory servers are used and the session is kept on the server, the session must be shared between the servers.  For example, in a database, shared disk space, shared memory, etc.

## Auth/Auth Pseudo Code

**if (the group-stored-in-the-session is not equal to**
**    ****the group-allowed-access-to-web-content)**
** ****{**
**    ****if (the DN-stored-in-the-session is not in the directory entry **
**        ****group-allowed-access-to-web-content)**
**    ****{**
**        ****return “Access Denied” to the user**
**    ****}**
**    ****replace the session’s group with**
**    ****the group-allowed-access-to-web-content**
**}**
**return the web content to the user**

- 2005-08-16