The Federation component of OpenIG is a standards based authentication service used by OpenIG to validate a user and retrieve key attributes of the user in order to log them into the target applications.
There are two ways the Federation Service can be invoked:
IDP initiated SSO, where the remote Identity Provider sends an unsolicited Authentication statement to OpenIG
SP initiated SSO where OpenIG calls the Federation Service to initiate Federated SSO with the Identity provider
In either case, the job of the Federation Service is to validate the user and pass the required attributes to OpenIG to log the user into target applications.
See the Tutorial For the Federation Gateway for hands on experience with the Federation Gateway.
This section is a summary of the steps needed to prepare OpenIG to act as a Federation endpoint for your target application.
Install the OpenIG Federation .war.
Configure OpenIG to log users into the target application. Getting this to work before configuring Federation makes the process much simpler to troubleshoot if anything goes wrong.
Add Federation configuration to the OpenIG configuration file.
Add the assertion and subject mappings, optional redirect URI and optional logout URI to the Federation configuration.
Export the Identity Provider MetaData from the remote Identity Provider or use the meta data from the OpenAM generated fedlet.
Import OpenIG metadata to your Identity Provider.
The Federation service is configured by modifying the OpenIG
config.json and Federation specific XML files located
in the home directory of the effective user running the web application
container housing OpenIG. The home directory of this user is referred to as
$HOME_DIR in this document. By default, the
Federation service looks in $HOME_DIR/.ForgeRock/OpenIG/
for config.json and
$HOME_DIR/.ForgeRock/SAML/ for the Federation XML
configuration.
The following is a description of the files:
$HOME_DIR/.ForgeRock/OpenIG/config.jsonThis is the core configuration file for OpenIG. You must configure
both this file and the XML files specific to the Federation Service.
The reason there are two sets of configuration files is the Federation
Service is based on the openFed library from the OpenAM open source
project. The openFed library and the Federation configuration files are
taken directly from the OpenFM release. In order to get the Federation
Service configured you must tag swap the XML files. If you are familiar
with the workflow in the OpenAM console you can generate a Fedlet and
directly copy the configuration files into
$HOME_DIR/.ForgeRock/SAML/.
$HOME_DIR/.ForgeRock/SAML/FederationConfig.propertiesAdvanced features of the openFed library. The defaults suffice in most deployments.
$HOME_DIR/.ForgeRock/SAML/gateway.cotCircle of trust for OpenIG and the Identity Provider.
$HOME_DIR/.ForgeRock/SAML/idp.xmlThis file is not included with the Federation Service XML. It must be generated by the Identity Provider and copied into the configuration directory.
$HOME_DIR/.ForgeRock/SAML/idp-extended.xmlStandard extensions for the Identity Provider.
$HOME_DIR/.ForgeRock/SAML/sp.xml, $HOME_DIR/.ForgeRock/SAML/sp-extended.xmlThese are the standard metadata and metadata extensions for the OpenIG Federation Service.
The simplest way to configure the OpenIG Federation Gateway is to use
the OpenAM task wizard to generate a Fedlet and then use the Fedlet
configuration files in the Gateway configuration directory. If you use the
Fedlet configuration files, simply unpack Fedlet.war
and copy all the files listed above into
$HOME_DIR/.ForgeRock/SAML/. You do not have to modify
the files to do basic IDP and SP initiated SSO with OpenIG. Note that the
sample Federation Gateway config.json templates uses
/saml as the URI so your Fedlet endpoint should be
specified as protocol://host.domain:port/saml
If you do not use the Fedlet wizard, then follow the instructions for
the unconfigured Fedlet and then copy the Fedlet configuration files to the
$HOME_DIR/.ForgeRock/SAML/ directory. You must also
export the metadata from the IDP and copy it to idp.xml
in the same directory.
The following sample configuration is from the tutorial on federating WordPress. The sample configuration receives a SAML assertion from OpenAM and then logs the user into WordPress using the user name and password from the assertion.
The following excerpt of the Federation Service JSON is from the OpenIG
config.json file. All fields are mandatory except
logoutURI. The logoutURI is only
necessary if your configuration uses the single logout feature.
{
"name": "FederationServlet",
"type": "org.forgerock.openig.saml.FederationServlet",
"config": {
"assertionMapping": {
"userName":"uid",
"password":"userPassword"
},
"subjectMapping":"subjectName",
"sessionIndexMapping":"sessionIndex",
"redirectURI":"/login",
"logoutURI":"/logout"
"assertionConsumerEndpoint":"fedletapplication",
"SPinitiatedSSOEndpoint":"SPInitiatedSSO",
"singleLogoutEndpoint":"fedletSlo"
}
}Name of the Federation Service within the OpenIG runtime. This value should not be modified.
Classname of the Federation Servlet. This value should not be modified.
The assertionMapping defines how to transform the
attributes from the incoming assertion to attribute value pairs in the
session. Each entry in the assertionMapping is of the
form attributeName:assertionNameattributeName represents the name of the
attribute set in the session. The assertionName
is used to fetch the value from the incoming assertion, which becomes the
value in the session. The following statements correspond to the sample
shown above.
If the incoming assertion contains the statement:
uid = jojo
userPassword = 123456789
Then the following values are set in the session:
userName = jojo
password = 123456789
Notice that you must also modify attributeMap in the
$HOME_DIR/.ForgeRock/SAML/sp-extended.xml to match
the assertion mapping configured in the IDP metadata.
The value contained in the assertion subject is set as the value of
the attribute subjectName in the session.
The redirectURI should be set to the page the
Form-Filter recognizes as the login page for the target application.
This is how OpenIG and the Federation service work together to provide
single sign-on. When OpenIG detects the target application's login page,
it redirects to the Federation Service. Once the Federation Service
validates the SAML exchanges with the IDP and sets the required session
attributes, it redirect back to the target application's login page.
This allows the Form-Filter to finish the job of logging in the user by
retrieving the necessary user data from the session and creating a login
form for the application.
The logoutURI should be set to the URI which logs
the user out of the target application. This attribute is only needed if
your application uses the single log-out feature of the Identity
Provider.
The default value of fedletapplication is the same
as the Fedlet. If you modify this attribute you must change the metadata
to match.
The default value is SPInitiatedSSO. If you
modify this attribute you must change the metadata to match.
The default value of fedletSLO is the same as the
Fedlet. If you modify this attribute you must change the metadata to
match.
Application myportal requires a form with userName and password for
login. The userName for myportal is the mail attribute at the user's Identity
Provider. The password for myportal is the mailPassword at the Identity
Provider. The incoming SAML2 assertion sent by the Identity Provider contains
the mail and mailPassword attributes. The Federation Service validates the
incoming assertion, sets the userName and password in the HttpSession to the
values of mail and mailPassword from the assertion, and redirects the user
to /myportal/login. The LoginRequest Filter then retrieves
the login values from the session and creates the form to log the user into
myportal.
{
"name": "FederationServlet",
"type": "org.forgerock.openig.saml.FederationServlet",
"config": {
"assertionMapping": {
"userName":"mail",
"password":"mailPassword"
}
"redirectURI":"/myportal/login",
"logoutURI":"/myportal/logout"
}
}{
"name": "LoginRequest",
"type": "StaticRequestFilter",
"config": {
"method": "POST",
"uri": "https://10.10.0.5/login",
"form": {
"userName": [${exchange.session.userName}],
"password": [${exchange.session.password}],
}
}
}The Identity Provider metadata must be in
$HOME_DIR/.ForgeRock/SAML/idp.xml directory. See the
documentation for your Identity Provider for instructions on how to get the
metadata.
To export Identity Provider metadata from OpenAM, run a command such as the following.
$ ssoadm export-entity -u amadmin -f /tmp/pass -y http://www.idp.com:8080/openam -m /tmp/idp.xml