8.8.4.0 | Filters | SAML Policy Translation Filter

This filter takes a SAML Response in the post binding, decodes it, adds a new translated assertion to it and then signs the entire response. It’ll attempt to locate a policy to use for the translation based on the assertion issuer.

General filter information

Name: saml-policy
Default Configuration: saml-policy.cfg.xml
Released: v8.4.0.1
Bundle: repose-extensions-filter-bundle
Schema

Prerequisites & Postconditions

Required Request Headers

Content-Type - Needs a value of application/x-www-form-urlencoded or application/xml

Required Preceding Filters

This filter has no dependencies on other filters.

Request Headers Created

Content-Type - Will be changed to application/xml
Content-Length - Will be removed if present
Transfer-Encoding - Will be set to chunked
Identity-API-Version - 1.0 if the assertion issuer is in the configured list and 2.0 otherwise.

Request Body Changes

The request body will be decoded and replaced with an xml version if the content type is application/x-www-form-urlencoded. If issuer isn’t in the configured bypass list indicating the use of the legacy v1.0 API, then the v2.0 API is assumed and a new assertion will be generated based on the matching issuer policy with http://openrepose.org/filters/SAMLTranslation as the issuer. Additionally the SAML Response will be signed with the configured credentials.

Recommended Follow-On (Succeeding) Filters

This filter is not strictly required by any other filters.

Response Body Changes

If the legacy v1.0 API is in use, then the response body is not modified. However, if the v2.0 API is in use, then the response body will be updated with the additional attributes specified in the original SAML Response issuer’s configured policy.

Response Headers Created

This filter does not create/modify any response headers.

Response Status Codes

Table 1. Status Codes
Status Code	Reasons
`400`	If the `SAMLResponse` parameter cannot be found. If the `SAMLResponse` parameter value is not properly Base64 encoded. If the SAML response is not properly formatted or is unable to be parsed. If all the SAML response assertions aren’t signed and if all the assertions don’t come from the same issuer. If translation of the SAML response fails. If translation of the policy fails.
`401`	If a policy that matches the assertion issuer can not be found. If Identity returns a 404 when the policy is requested. If Identity does not return an IDP ID when requested.
`405`	If the request HTTP method is not `POST`.
`415`	If the request `Content-Type` header does not have a value of `application/x-www-form-urlencoded` or `application/xml`.
`500`	If there is any error in this filter that is not explicitly mapped to a status code. In other words, if an unexpected problem occurs.
`502`	If Identity returns a 413 or 429 response code, indicating that this filter’s request was rate limited. The response from this filter will contain a Retry-After header. If Identity returns a 5xx response. If parsing the policy fails.
`504`	If a connection to Identity times out.

Examples

This configuration exercises all the capabilities of the filter.

saml-policy.cfg.xml

<?xml version="1.0" encoding="UTF-8"?>

<saml-policy xmlns="http://docs.openrepose.org/repose/samlpolicy/v1.0">
    <policy-bypass-issuers> (1)
        <issuer>http://foo.bar</issuer>
        <issuer>http://notmyfirst.rodeo</issuer>
    </policy-bypass-issuers>
    <policy-acquisition>
        <keystone-credentials uri="http://keystone.somewhere.com" (2)
                              username="aUsername" (3)
                              password="somePassword" (4)
                              connection-pool-id="pool1"/> (5)
        <policy-endpoint uri="http://keystone.somewhere.com" (6)
                         connection-pool-id="pool2"/> (7)
        <cache ttl="300" (8)
               atom-feed-id="identity-policy"/> (9)
    </policy-acquisition>
    <signature-credentials keystore-filename="thing.jks" (10)
                           keystore-password="banana" (11)
                           key-name="thingy" (12)
                           key-password="phone"/> (13)
</saml-policy>

1	The list of 1.0 issuers. This is optional.
2	The keystone endpoint to get an authentication token from.
3	The username of the user to use for policy acquisition.
4	The password of the user to use for policy acquisition.
5	The id of the connection pool to use when making the requests. Default: `default`
6	The endpoint to use for policy acquisition.
7	The connection pool to use when acquiring the policy. Default: `default`
8	The time to live in the cache in seconds for policies.
9	The atom feed id of an atom feed that contains policy events to be used for cache evictions. Policies will be evicted from the cache for all three event types (i.e., CREATE, UPDATE, DELETE). This is optional, if unused cache eviction will be purely off ttl.
10	The location of the keystore that contains the certificates for signing the SAML response.
11	The password for using the keystore.
12	The name the certificate is under in the keystore.
13	The password for the certificate in the keystore.

Additional Information

The Keystone user account configured for use in this filter must possess a role of identity:identity-provider-read-only. It is recommended to use a uri-regex in your system model to filter traffic to this filter, because it will fail on non-SAML requests.

Policy Translation

Attribute mapping policies are stored with the IDP (Identity Provider). They will be retrieved and cached by this filter.

Attribute mapping policies will be used to translate the SAML response document contained in the request. For this filter to apply the policy translation, the format (i.e., content type) of the policy must be one of the following:

YAML
JSON
XML