--- title: Unsigned/unencrypted SAML v2.0 assertions description: For examples of the federation configuration files, refer to Example SAML v2.0 Fedlet files. To set up multiple SPs, work through this page and SAML 2.0 and multiple applications. component: pinggateway version: 2025.11 page_id: pinggateway:gateway-guide:federation-setup-handler canonical_url: https://docs.pingidentity.com/pinggateway/2025.11/gateway-guide/federation-setup-handler.html revdate: 2025-11-24T11:06:04Z --- # Unsigned/unencrypted SAML v2.0 assertions For examples of the federation configuration files, refer to [Example SAML v2.0 Fedlet files](federation-example-files.html). To set up multiple SPs, work through this page and [SAML 2.0 and multiple applications](federation-setup-multi-sps-handler.html). 1. Set up the network: Add `sp.example.com` to your `/etc/hosts` file: ```none 127.0.0.1 localhost am.example.com ig.example.com app.example.com sp.example.com ``` Traffic to the application is proxied through PingGateway, using the host name `sp.example.com`. 2. Configure a Java Fedlet: | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The SAML library component validates the SP's AssertionConsumerService Location against the incoming IdP SAML Assertion, based on the request information, including the port. In `sp.xml`, always specify the port in the Location value of `AssertionConsumerService`, even when using defaults of 443 or 80, as follows:```xml ``` | For more information about Java Fedlets, refer to [Creating and configuring the Fedlet](https://docs.pingidentity.com/pingam/8/am-saml2/create-configure-fedlet.html) in AM's *SAML v2.0 guide*. 1. Copy and unzip the fedlet zip file, `Fedlet-8.0.0.zip`, delivered with the AM installation, into a local directory. ```console $ unzip $HOME/openam/Fedlet-8.0.0.zip ``` Output ```none Archive: Fedlet-8.0.0.zip creating: conf/ inflating: README inflating: conf/FederationConfig.properties inflating: conf/fedlet.cot-template inflating: conf/idp-extended.xml-template inflating: conf/sp-extended.xml-template inflating: conf/sp.xml-template inflating: fedlet.war ``` 2. In each file, search and replace the following properties: | Replace this | With this | | ------------------------------------------------------------- | --------------------------------------------------------- | | `IDP_ENTITY_ID` | `openam` | | `FEDLET_ENTITY_ID` | `sp` | | `FEDLET_PROTOCOL://FEDLET_HOST:FEDLET_PORT/FEDLET_DEPLOY_URI` | `http://sp.example.com:8080/saml` | | `fedletcot` and `FEDLET_COT` | `Circle of Trust` | | `sp.example.com:8080/saml/fedletapplication` | `sp.example.com:8080/saml/fedletapplication/metaAlias/sp` | 3. Save the files as .xml, without the `-template` extension, so that the directory looks like this: ``` conf ├── FederationConfig.properties ├── fedlet.cot ├── idp-extended.xml ├── sp-extended.xml └── sp.xml ``` By default, AM as an IdP uses the NameID format `urn:oasis:names:tc:SAML:2.0:nameid-format:transient` to communicate about a user. For information about using a different NameID format, refer to [Non-transient SAML v2.0 NameID format](federation-non-transient-name.html). 3. Set up AM: 1. In the AM admin UI, select [icon: address-card, set=fa]Identities, select the user `demo`, and change the last name to `Ch4ng31t`. Note that, for this example, the last name must be the same as the password. 2. Select Applications > Federation > Circles of Trust, and add a circle of trust called `Circle of Trust`, with the default settings. 3. Set up a remote service provider: 1. Select Applications > Federation > Entity Providers, and add a remote entity provider. 2. Drag in or import `sp.xml` created in the previous step. 3. Select Circles of Trust: `Circle of Trust`. 4. Set up a hosted identity provider: 1. Select Applications > Federation > Entity Providers, and add a hosted entity provider with the following values: * Entity ID: `openam` * Entity Provider Base URL: `http://am.example.com:8088/openam` * Identity Provider Meta Alias: `idp` * Circles of Trust: `Circle of Trust` 2. Select Assertion Processing > Attribute Mapper, map the following SAML attribute keys and values, and then save your changes: * SAML Attribute: `cn`, Local Attribute: `cn` * SAML Attribute: `sn`, Local Attribute: `sn` 3. In a terminal, export the XML-based metadata for the IdP: ```console $ curl -v \ --output idp.xml \ "http://am.example.com:8088/openam/saml2/jsp/exportmetadata.jsp?entityid=openam" ``` The `idp.xml` file is created locally. 4. Set up PingGateway: 1. Copy the edited fedlet files, and the exported `idp.xml` file into the PingGateway configuration, at `$HOME/.openig/SAML`. ```console $ ls -l $HOME/.openig/SAML ``` Output ``` FederationConfig.properties fedlet.cot idp-extended.xml idp.xml sp-extended.xml sp.xml ``` 2. Don't use a `baseURI` setting. Requests to the SamlFederationHandler must not be rebased because the request URI must match the endpoint in the SAML metadata. 3. Make sure PingGateway connects to the sample application over HTTPS with a route to access static resources. Learn more in [Using the sample application](../getting-started/start-sampleapp.html). 4. Add the following route to PingGateway: * Linux `$HOME/.openig/config/routes/saml-handler.json` * Windows `%appdata%\OpenIG\config\routes\saml-handler.json` ```json { "name": "saml-handler", "condition": "${find(request.uri.path, '^/saml')}", "handler": { "type": "SamlFederationHandler", "config": { "useOriginalUri": true, "assertionMapping": { "username": "cn", "password": "sn" }, "subjectMapping": "sp-subject-name", "redirectURI": "/home/federate" } } } ``` Source: [saml-handler.json](../_attachments/config/routes/saml-handler.json) Notice the following features of the route: * The route matches requests to `/saml`. * After authentication, the SamlFederationHandler extracts `cn` and `sn` from the SAML assertion, and maps them to the SessionContext, at `session.username` and `session.password`. * The handler stores the subject name as a string in the session field `session.sp-subject-name`, which is named by the `subjectMapping` property. By default, the subject name is stored in the session field `session.subjectName`. * The handler redirects the request to the `/federate` route. 5. Add the following route to PingGateway: * Linux `$HOME/.openig/config/routes/federate-handler.json` * Windows `%appdata%\OpenIG\config\routes\federate-handler.json` ```json { "name": "federate-handler", "condition": "${find(request.uri.path, '^/home/federate')}", "baseURI": "https://app.example.com:8444", "handler": { "type": "DispatchHandler", "config": { "bindings": [ { "condition": "${empty session.username}", "handler": { "type": "StaticResponseHandler", "config": { "status": 302, "headers": { "Location": [ "http://sp.example.com:8080/saml/SPInitiatedSSO?metaAlias=/sp" ] } } } }, { "handler": { "type": "Chain", "config": { "filters": [ { "type": "HeaderFilter", "config": { "messageType": "REQUEST", "add": { "x-username": ["${session.username[0]}"], "x-password": ["${session.password[0]}"] } } } ], "handler": "ReverseProxyHandler" } } } ] } } } ``` Source: [federate-handler.json](../_attachments/config/routes/federate-handler.json) Notice the following features of the route: * The route matches requests to `/home/federate`. * If the user is not authenticated with AM, the username is not populated in the context. The DispatchHandler then dispatches the request to the StaticResponseHandler, which redirects it to the SP-initiated SSO endpoint. If the credentials are in the context, or after successful authentication, the DispatchHandler dispatches the request to the Chain. * The HeaderFilter adds headers for the first value for the `username` and `password` attributes of the SAML assertion. 6. Restart PingGateway. 5. Test the setup: 1. Log out of AM, and test the setup with the following links: * [IdP-initiated SSO](http://am.example.com:8088/openam/idpssoinit?metaAlias=/idp\&spEntityID=sp) * [SP-initiated SSO](http://ig.example.com:8080/home/federate) 2. Log in to AM with username `demo` and password `Ch4ng31t`. PingGateway returns the response page showing that the the demo user has logged in. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For more control over the URL where the user agent is redirected, use the `RelayState` query string parameter in the URL of the redirect `Location` header. `RelayState` specifies where to redirect the user when the SAML 2.0 web browser SSO process is complete. It overrides the `redirectURI` set in the SamlFederationHandler.The `RelayState` value must be URL-encoded. When using an expression, use a function to encode the value. For example, use `${urlEncodeQueryParameterNameOrValue(contexts.router.originalUri)}`.In the following example, the user is finally redirected to the original URI from the request:```json "headers": { "Location": [ "http://ig.example.com:8080/saml/SPInitiatedSSO?RelayState=${urlEncodeQueryParameterNameOrValue(contexts.router.originalUri)}" ] } ``` |