Add default params file

README.rst

@@ -80,8 +80,9 @@ shib_request_set <variable> <value>
    documentation.
 
    This directive can be used to introduce Shibboleth attributes into the
-   environment of the backend application.  See the `Configuration`_
-   documentation for an example.
+   environment of the backend application, such as `$_SERVER` for a FastCGI
+   PHP application and is the recommended method of doing so.  See the
+   `Configuration`_ documentation for an example.
 
 shib_request_use_headers on|off
    | **Context:** ``http``, ``server``, ``location``
@@ -134,8 +135,8 @@ To compile Nginx with this module statically, pass the following option to
 
     --add-module=<path>
 
-No additional loading is required as the module is built-in with this
-configuration.
+With a static build, no additional loading is required as the module is
+built-in to Nginx.
 
 
 Configuration
@@ -173,8 +174,12 @@ An example consists of the following::
     # environment variables for the backend application. In this example, we
     # set ``fastcgi_param`` but this could be any type of Nginx backend that
     # supports parameters (by using the appropriate *_param option)
+    #
+    # The ``shib_fastcgi_params`` is an optional set of default parameters,
+    # available in this repository.
     location /secure-environment-vars {
         shib_request /shibauthorizer;
+        include shib_fastcgi_params;
         shib_request_set $shib_commonname $upstream_http_variable_commonname;
         shib_request_set $shib_email $upstream_http_variable_email;
         fastcgi_param COMMONNAME $shib_commonname;
@@ -182,13 +187,25 @@ An example consists of the following::
         fastcgi_pass unix:/path/to/backend.socket;
     }
 
-
 Note that we use the `headers-more-nginx-module
 <https://github.com/openresty/headers-more-nginx-module>`_ to clear
 potentially dangerous input headers and avoid the potential for spoofing.  The
 latter example with environment variables isn't susceptible to header
 spoofing, as long as the backend reads data from the environment parameters
-only.
+**only**.  Bear in mind that some applications will try to read a
+Shibboleth attribute from the environment and then fall back to headers, so
+review your application's code even if you are not using
+``shib_request_use_headers``.
+
+With use of ``shib_request_set``, a `default params
+<https://github.com/nginx-shib/nginx-http-shibboleth/blob/master/config/shib_fastcgi_params>`_
+file is available which you can use as an nginx ``include`` to ensure all core
+Shibboleth variables get passed from the FastCGI authorizer to the
+application. Numerous default attributes are included so remove the ones that
+aren't required by your application and add Federation or IDP attributes that
+you need. This default params file can be re-used for upstreams that aren't
+FastCGI by simply changing the ``fastcgi_param`` directives to
+``uwsgi_param``, ``scgi_param`` or so forth.
 
 Gotchas
 ~~~~~~~

includes/shib_fastcgi_params

+# vim: set filetype=conf :
+
+# Replace `fastcgi_param` with `sgci_param`, `uwsgi_param` or similar
+# directive for use with different upstreams. Consult the relevant upstream
+# documentation for more information on environment parameters.
+
+shib_request_set $shib_auth_type $upstream_http_variable_auth_type;
+fastcgi_param Auth-Type $shib_auth_type;
+
+shib_request_set $shib_shib_application_id $upstream_http_variable_shib_application_id;
+fastcgi_param Shib-Application-Id $shib_shib_application_id;
+
+shib_request_set $shib_shib_authentication_instant $upstream_http_variable_shib_authentication_instant;
+fastcgi_param Shib-Authentication-Instant $shib_shib_authentication_instant;
+
+shib_request_set $shib_shib_authentication_method $upstream_http_variable_shib_authentication_method;
+fastcgi_param Shib-Authentication-Method $shib_shib_authentication_method;
+
+shib_request_set $shib_shib_authncontext_class $upstream_http_variable_shib_authncontext_class;
+fastcgi_param Shib-Authncontext-Class $shib_shib_authncontext_class;
+
+shib_request_set $shib_shib_identity_provider $upstream_http_variable_shib_identity_provider;
+fastcgi_param Shib-Identity-Provider $shib_shib_identity_provider;
+
+shib_request_set $shib_shib_session_id $upstream_http_variable_shib_session_id;
+fastcgi_param Shib-Session-Id $shib_shib_session_id;
+
+shib_request_set $shib_shib_session_index $upstream_http_variable_shib_session_index;
+fastcgi_param Shib-Session-Index $shib_shib_session_index;
+
+shib_request_set $shib_remote_user $upstream_http_variable_remote_user;
+fastcgi_param Remote-User $shib_remote_user;
+
+
+# Uncomment any of the following core attributes. Consult your Shibboleth
+# Service Provider (SP) attribute-map.xml file for details about attribute
+# IDs.  Add additional directives for any Shibboleth attributes released to
+# your SP.
+
+# shib_request_set $shib_eppn $upstream_http_variable_eppn;
+# fastcgi_param EPPN $shib_eppn;
+#
+# shib_request_set $shib_affliation $upstream_http_variable_affiliation;
+# fastcgi_param Affiliation $shib_affiliation;
+#
+# shib_request_set $shib_unscoped_affliation $upstream_http_variable_unscoped_affiliation;
+# fastcgi_param Unscoped-Affiliation $shib_unscoped_affiliation;
+#
+# shib_request_set $shib_entitlement $upstream_http_variable_entitlement;
+# fastcgi_param Entitlement $shib_entitlement;
+
+
+# shib_request_set $shib_targeted_id $upstream_http_variable_targeted_id;
+# fastcgi_param Targeted-Id $shib_targeted_id;
+#
+# shib_request_set $shib_persistent_id $upstream_http_variable_persistent_id;
+# fastcgi_param Persistent-Id $shib_persistent_id;
+#
+# shib_request_set $shib_transient_name $upstream_http_variable_transient_name;
+# fastcgi_param Transient-Name $shib_transient_name;
+
+
+# shib_request_set $shib_commonname $upstream_http_variable_commonname;
+# fastcgi_param Commonname $shib_commonname;
+#
+# shib_request_set $shib_displayname $upstream_http_variable_displayname;
+# fastcgi_param DisplayName $shib_displayname;
+#
+# shib_request_set $shib_email $upstream_http_variable_email;
+# fastcgi_param Email $shib_email;
+#
+# shib_request_set $shib_organizationname $upstream_http_variable_organizationname;
+# fastcgi_param OrganizationName $shib_organizationname;