Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
tutorial:adm:modules_openam [2018/06/15 15:33]
apeterova multiple instances, realms 		tutorial:adm:modules_openam [2020/06/22 16:52]
apeterova mostly moved to admin guide, added info about OpenAM version
Line 1: Line 1:
 ====== Modules - OpenAM: installation and configuration ====== ====== Modules - OpenAM: installation and configuration ======
  
-The module uses [[https://wikis.forgerock.org/confluence/display/openam/Use+OpenAM+RESTful+Services#UseOpenAMRESTfulServices-Authentication|OpenAM RESTful API]]. The base URL of the API is a required configuration property of the module. When the module is enabled in the CzechIdM, users can authenticate to CzechIdM with their login and password valid for OpenAM. +This tutorial will help you easily install and configure the OpenAM module for CzechIdM. To read more about the module, please see [[devel:documentation:modules_openam|OpenAM module documentation]].
- +
-===== Authentication token ===== +
-Token for successfully authenticated users is set to the cookie of the (default) name iPlanetDirectoryPro for the current request domain. +
- +
-The cookie is set only for secured (https) connections by default. If you need to set it for unsecured connections, configure the property ''idm.sec.openam.sso.cookie.secure=false''. This is strongly discouraged for production use! +
- +
-===== SSO ===== +
-Single-Sign-On functionality of the OpenAM module is done by a new authentication filter. When unauthenticated users come to CzechIdM and have the cookie with OpenAM token, the value of the token is validated against OpenAM. If the token is valid, the filter retrieves the user's login from OpenAM attributes and logs the user in. +
- +
-===== Multiple instances and realms ===== +
-The module supports multiple instances of OpenAM. The URLs must be configured in the property ''idm.sec.openam.base.url'' separated by a comma. Authentication or token validation uses the configured instances one by one. The first instance that returns a success is the winner (no more calls are made to remaining instances). +
- +
-The module also supports authentication realms in OpenAM. If configured, the realm(s) are used during authentication in the same order as the configured URLs of the instances. +
- +
-===== REST endpoint ===== +
-The module also provides a REST endpoint ''/get-attributes'' for retrieving OpenAM attributes for given SSO token. When calling the endpoint, the user's session by OpenAM can be refreshed (this is an optional parameter, default is false). +
- +
-The attributes are returned in lower case.+
  
 ===== Installation ===== ===== Installation =====
-Download the openam distribution package. The package contains a backend folder. Your IdM Tomcat installation we call IDM in the following example.+Download the idm-openam module distribution package. The package contains a backend folder. Your IdM Tomcat installation we call IDM in the following example.
   - Copy content of the backend folder into your tomcat IdM installation - [IDM]/WEB-INF/lib   - Copy content of the backend folder into your tomcat IdM installation - [IDM]/WEB-INF/lib
   - Set correct access rights to the files if needed (''chown tomcat:tomcat [IDM]/WEB-INF/lib/*'')   - Set correct access rights to the files if needed (''chown tomcat:tomcat [IDM]/WEB-INF/lib/*'')
   - Restart the IdM application server (''service tomcat restart'')   - Restart the IdM application server (''service tomcat restart'')
   - Log in to CzechIdM as an privileged user and go to Settings -> Modules and enable the openam module.   - Log in to CzechIdM as an privileged user and go to Settings -> Modules and enable the openam module.
-  - Go to the configuration and configure the OpenAM base url configuration property (see below).+  - Go to the configuration and configure the properties needed for the communication with OpenAM (see below). 
 + 
 +===== Basic configuration ===== 
 + 
 +First, you need to know the address of your running OpenAM instance (or instances) and its version. 
 + 
 +Based on that, set the following configuration properties: 
 +  * ''idm.sec.openam.base.url'': if your OpenAM instance runs at ''https://amhost.domain.tld'', this property should be either ''https://amhost.domain.tld/openam/json'' (for OpenAM 13 and newer), or ''https://amhost.domain.tld/openam/identity'' (for OpenAM 12 and older). 
 +  * ''idm.sec.openam.api.type'': set ''OPENAM13'' or ''OPENAM12'' based on the OpenAM version 
 + 
 +If your OpenAM installation uses realms for the users, you may need to set ''idm.sec.openam.login.payload'' - e.g. ''uri=realm=/customers'' for the realm "/customers". But the information about realm may be already included in the URL of the OpenAM instance (for OpenAM v. 13 and newer), so you may not need to set this property.
  
-===== Configuration ===== +If you run multiple instances (or need to support multiple realms), set as many values as you need to the above mentioned properties and separate the values with a comma.
-The module provides following configuration properties: +
-^ Property     ^ Description ^ +
-|idm.sec.openam.base.url | REQUIRED. Base URL of the REST API (e.g. ''https://amhost.domain.tld/openam/identity''). The property may contain multiple instances comma-separated.| +
-|idm.sec.openam.login.payload|The string that is appended to the authentication request, usually realm (e.g. ''uri=realm=/customers''). If multiple URLs are configured, configure this property also as multivalued and in the order corresponding to those URLs. (default: //empty//)| +
-|idm.sec.openam.login.attr.name |Name of the OpenAM attribute which holds user login (default: uid) | +
-|idm.sec.openam.sso.cookie.name |Name of the cookie which holds OpenAM token (default: iPlanetDirectoryPro)| +
-|idm.sec.openam.sso.cookie.domain|Domain, for which the cookie will be set. If empty, request root domain will be used.| +
-|idm.sec.openam.sso.cookie.httponly|Whether the cookie should have Http-Only sign (default: true)| +
-|idm.sec.openam.sso.cookie.secure|Whether the cookie should be sent for encrypted sessions only (https) (default: true)| +
-|idm.sec.openam.returned.attributes|Which attributes will be returned by /get-attributes endpoint, written in lower case (default: uid,dn,destinationindicator,ou)| +
-|idm.sec.openam.connect.timeout |The time limit to establish the connection in ms (default: 2000), change requires restart | +
-|idm.sec.openam.socket.timeout |The time limit waiting for data after the connection was established in ms (default: 2000), change requires restart |+
  
-==== Notes ==== +That's it! You probably don't need to set anything else. 
-Note that the module doesn't provide "Single-Sign-Off" - it doesn't check the validity of the users' sessions when they are already authenticated to CzechIdM.+
  
-The module has only the backend part.+All available properties are documented in the [[devel:documentation:adm:openam#configuration|Admin guide]].
  • by apeterova