1. OpenRepose
  2. Home
Search

SAML Policy Translation Filter

This version of the docs is a work in progress. If you don’t see what you are looking for check the legacy wiki.

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 headers

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

Required preceding filters

None

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.

None.

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

None.

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 5xx response.

  • If parsing the policy fails.

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.

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. It’s optional and will use the default if unspecified.
6 The endpoint to use for policy acquisition.
7 The connection pool to use when acquiring the policy. It’s optional and will use the default if unspecified.
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.