Merge pull request #377 from IdentityPython/msdocs

Documentation for recently added micro-services

Author: c00kiemon5ter

doc/README.md

@@ -5,30 +5,33 @@ This document describes how to install and configure the SATOSA proxy.
 # Installation
 
 ## <a name="docker" style="color:#000000">Docker</a>
+
 A pre-built Docker image is accessible at the [Docker Hub](https://hub.docker.com/r/satosa/), and is the
 recommended ways of running the proxy.
 
 ## <a name="manual_installation" style="color:#000000">Manual installation</a>
 
 ### <a name="dependencies" style="color:#000000">Dependencies</a>
+
 SATOSA requires Python 3.4 (or above), and the following packages on Ubuntu:
-```
+
+```bash
 apt-get install libffi-dev libssl-dev xmlsec1
 ````
 
 ### <a name="install_instructions" style="color:#000000">Instructions</a>
+
 1. Download the SATOSA proxy project as a [compressed archive](https://github.com/IdentityPython/SATOSA/releases)
    and unpack it to `<satosa_path>`.
 
-1. Install the application:
+2. Install the application:
 
    ```bash
    pip install <satosa_path>
    ```
 
 Alternatively the application can be installed directly from PyPI (`pip install satosa`), or the [Docker image](https://hub.docker.com/r/satosa/) can be used.
 
-
 ### <a name="install_external" style="color:#000000">External micro-services</a>
 
 Micro-services act like plugins and can be developed by anyone. Other people
@@ -53,8 +56,8 @@ The extentions include:
 
 and more.
 
-
 # Configuration
+
 SATOSA is configured using YAML.
 
 All default configuration files, as well as an example WSGI application for the proxy, can be found
@@ -74,7 +77,7 @@ the value from the process environment variable of the same name. If the
 process environment has been set with `LDAP_BIND_PASSWORD=secret_password` then
 the configuration value for `bind_password` will be `secret_password`.
 
-```
+```yaml
 bind_password: !ENV LDAP_BIND_PASSWORD
 ```
 
@@ -90,12 +93,12 @@ process environment has been set with
 `LDAP_BIND_PASSWORD_FILE=/etc/satosa/secrets/ldap.txt` then the configuration
 value for `bind_password` will be `secret_password`.
 
-```
+```yaml
 bind_password: !ENVFILE LDAP_BIND_PASSWORD_FILE
 ```
 
-
 ## <a name="proxy_conf" style="color:#000000">SATOSA proxy configuration</a>: `proxy_conf.yaml.example`
+
 | Parameter name | Data type | Example value | Description |
 | -------------- | --------- | ------------- | ----------- |
 | `BASE` | string | `https://proxy.example.com` | base url of the proxy |
@@ -109,10 +112,10 @@ bind_password: !ENVFILE LDAP_BIND_PASSWORD_FILE
 | `MICRO_SERVICES` | string[] | `[statistics_service.yaml]` | list of plugin configuration file paths, describing enabled microservices |
 | `LOGGING` | dict | see [Python logging.conf](https://docs.python.org/3/library/logging.config.html) | optional configuration of application logging |
 
-
 ## <a name="attr_map" style="color:#000000">Attribute mapping configuration:</a> `internal_attributes.yaml`
 
 ### attributes
+
 The values directly under the `attributes` key are the internal attribute names.
 Every internal attribute has a map of profiles, which in turn has a list of
 external attributes names which should be mapped to the internal attributes.
@@ -124,14 +127,15 @@ internal attribute.
 Sometimes the external attributes are nested/complex structures. One example is
 the [address claim in OpenID connect](http://openid.net/specs/openid-connect-core-1_0.html#AddressClaim)
 which consists of multiple sub-fields, e.g.:
+
 ```json
 "address": {
   "formatted": "100 Universal City Plaza, Hollywood CA 91608, USA",
   "street_address": "100 Universal City Plaza",
   "locality": "Hollywood",
   "region": "CA",
   "postal_code": "91608",
-  "country": "USA",
+  "country": "USA"
 }
 ```
 
@@ -166,28 +170,29 @@ attributes (in the proxy backend) <-> internal <-> returned attributes (from the
 * Any plugin using the `saml` profile will use the attribute value from `postaladdress`
   delivered from the target provider as the value for `address`.
 
-
 ### user_id_from_attrs
+
 The subject identifier generated by the backend module can be overridden by
 specifying a list of internal attribute names under the `user_id_from_attrs` key.
 The attribute values of the attributes specified in this list will be
 concatenated and used as the subject identifier.
 
-
 ### user_id_to_attr
+
 To store the subject identifier in a specific internal attribute, the internal
 attribute name can be specified in `user_id_to_attr`.
 When the [ALService](https://github.com/its-dirg/ALservice) is used for account
 linking, the `user_id_to_attr` configuration parameter should be set, since that
 service will overwrite the subject identifier generated by the proxy.
 
-
 ## Plugins
+
 The authentication protocol specific communication is handled by different plugins,
 divided into frontends (receiving requests from clients) and backends (sending requests
 to target providers).
 
 ### Common plugin configuration parameters
+
 Both `name` and `module` must be specified in all plugin configurations (frontends, backends, and micro services).
 The `name` must be unique to ensure correct functionality, and the `module` must be the fully qualified name of an
 importable Python module.
@@ -230,7 +235,6 @@ For more detailed information on how you could customize the SAML entities,
 see the
 [documentation of the underlying library pysaml2](https://github.com/rohe/pysaml2/blob/master/docs/howto/config.rst).
 
-
 #### Providing `AuthnContextClassRef`
 
 SAML2 frontends and backends can provide a custom (configurable) *Authentication Context Class Reference*.
@@ -252,12 +256,13 @@ provider will be preserved, and when using a OAuth or OpenID Connect backend, th
 
 **Example**
 
-    config:
-        [...]
-        acr_mapping:
-            "": default-LoA
-            "https://accounts.google.com": LoA1
-
+```yaml
+config:
+    [...]
+    acr_mapping:
+        "": default-LoA
+        "https://accounts.google.com": LoA1
+```
 
 #### <a name="saml_frontend" style="color:#000000">Frontend</a>
 
@@ -296,8 +301,8 @@ An example configuration can be found [here](../example/plugins/frontends/saml2_
 
    `SP -> Virtual CO SAMLFrontend -> SAMLBackend -> optional discovery service -> target IdP`
 
-
 ##### Custom attribute release
+
 In addition to respecting for example entity categories from the SAML metadata, the SAML frontend can also further
 restrict the attribute release with the `custom_attribute_release` configuration parameter based on the SP entity id.
 
@@ -349,13 +354,14 @@ Overrides per SP entityID is possible by using the entityID as a key instead of
 in the yaml structure. The most specific key takes presedence. If no policy overrides are provided
 the defaults above are used.
 
-
 #### <a name="saml_backend" style="color:#000000">Backend</a>
+
 The SAML2 backend act as a SAML Service Provider (SP), making authentication
 requests to SAML Identity Providers (IdP). The default configuration file can be
 found [here](../example/plugins/backends/saml2_backend.yaml.example).
 
 ##### <a name="name_id" style="color:#000000">Name ID Format</a>
+
 The SAML backend can indicate which *Name ID* format it wants by specifying the key
 `name_id_format` in the SP entity configuration in the backend plugin configuration:
 
@@ -368,6 +374,7 @@ The SAML backend can indicate which *Name ID* format it wants by specifying the
  ```
 
 ##### Use a discovery service
+
 To allow the user to choose which target provider they want to authenticate with, the configuration
 parameter `disco_srv`, must be specified if the metadata given to the backend module contains more than one IdP:
 
@@ -433,6 +440,7 @@ config:
 ### <a name="openid_plugin" style="color:#000000">OpenID Connect plugins</a>
 
 #### <a name="openid_backend" style="color:#000000">Backend</a>
+
 The OpenID Connect backend acts as an OpenID Connect Relying Party (RP), making
 authentication requests to OpenID Connect Provider (OP). The default
 configuration file can be found [here](../example/plugins/backends/openid_backend.yaml.example).
@@ -444,8 +452,8 @@ When using an OP that only supports statically registered clients, see the
 and make sure to provide the redirect URI, constructed as described in the
 section about Google configuration below, in the static registration.
 
-
 #### <a name="openid_frontend" style="color:#000000">Frontend</a>
+
 The OpenID Connect frontend acts as and OpenID Connect Provider (OP), accepting requests from OpenID
 Connect Relying Parties (RPs). The default configuration file can be found
 [here](../example/plugins/frontends/openid_connect_frontend.yaml.example).
@@ -477,10 +485,12 @@ The configuration parameters available:
 The other parameters should be left with their default values.
 
 ### <a name="social_plugins" style="color:#000000">Social login plugins</a>
+
 The social login plugins can be used as backends for the proxy, allowing the
 proxy to act as a client to the social login services.
 
 #### Google
+
 The default configuration file can be
 found [here](../example/plugins/backends/google_backend.yaml.example).
 
@@ -495,7 +505,7 @@ It should use the available variables, `<base_url>` and `<name>`, where:
 
 1. `<base_url>` is the base url of the proxy as specified in the `BASE` configuration parameter
 in `proxy_conf.yaml`, e.g. "https://proxy.example.com".
-1. `<name>` is the plugin name specified in the `name` configuration parameter defined in the plugin configuration file.
+2. `<name>` is the plugin name specified in the `name` configuration parameter defined in the plugin configuration file.
 
 The example config in `google_backend.yaml.example`:
 
@@ -507,14 +517,15 @@ config:
       redirect_uris: [<base_url>/<name>]
 [...]
 ```
+
 together with `BASE: "https://proxy.example.com"` in `proxy_conf.yaml` would
 yield the redirect URI `https://proxy.example.com/google` to register with Google.
 
 A list of all claims possibly released by Google can be found [here](https://developers.google.com/identity/protocols/OpenIDConnect#obtainuserinfo),
 which should be used when configuring the attribute mapping (see above).
 
-
 #### Facebook
+
 The default configuration file can be
 found [here](../example/plugins/backends/facebook_backend.yaml.example).
 
@@ -549,7 +560,7 @@ pre-configured (static) attributes, see the
 
 The static attributes are described as key-value pairs in the YAML file, e.g:
 
-```
+```yaml
 organisation: Example Org.
 country: Sweden
 ```
@@ -574,15 +585,18 @@ The filters are applied such that all attribute values matched by the regular ex
 non-matching attribute values will be discarded.
 
 ##### Examples
+
 Filter attributes from the target provider `https://provider.example.com`, to only preserve values starting with the
 string `"foo:bar"`:
+
 ```yaml
 "https://provider.example.com":
     "":
         "": "^foo:bar"
 ```
 
 Filter the attribute `attr1` to only preserve values ending with the string `"foo:bar"`:
+
 ```yaml
 "":
     "":
@@ -591,6 +605,7 @@ Filter the attribute `attr1` to only preserve values ending with the string `"fo
 
 Filter the attribute `attr1` to the requester `https://provider.example.com`, to only preserver values containing
 the string `"foo:bar"`:
+
 ```yaml
 "":
     "https://client.example.com":
@@ -601,6 +616,7 @@ the string `"foo:bar"`:
 
 Attributes delivered from the target provider can be filtered based on a list of allowed attributes per requester
 using the `AttributePolicy` class:
+
 ```yaml
 attribute_policy:
     <requester>:
@@ -610,11 +626,25 @@ attribute_policy:
 ```
 
 #### Route to a specific backend based on the requester
+
 To choose which backend (essentially choosing target provider) to use based on the requester, use the
 `DecideBackendByRequester` class which implements that special routing behavior. See the
 [example configuration](../example/plugins/microservices/requester_based_routing.yaml.example).
 
+#### Route to a specific backend based on the target entity id
+
+Use the `DecideBackendByTargetIssuer` class which implements that special routing behavior. See the
+[example configuration](../example/plugins/microservices/target_based_routing.yaml.example).
+
+#### Route to a specific backend based on the discovery service response
+
+If a Discovery Service is in use and a target entity id is selected by users, you may want to use the
+`DiscoToTargetIssuer` class together with `DecideBackendByTargetIssuer` to be able to select a
+backend (essentially choosing target provider) based on the response from the discovery service.
+See the [example configuration](../example/plugins/microservices/disco_to_target_issuer.yaml.example).
+
 #### Filter authentication requests to target SAML entities
+
 If using the `SAMLMirrorFrontend` module and some of the target providers should support some additional SP's, the
 `DecideIfRequesterIsAllowed` micro service can be used. It provides a rules mechanism to describe which SP's are
 allowed to send requests to which IdP's. See the [example configuration](../example/plugins/microservices/allowed_requesters.yaml.example).
@@ -625,6 +655,7 @@ Metadata containing all SP's (any SP that might be allowed by a target IdP) must
 The rules are described using `allow` and `deny` directives under the `rules` configuration parameter.
 
 In the following example, the target IdP `target_entity_id1` only allows requests from `requester1` and `requester2`.
+
 ```yaml
 rules:
     target_entity_id1:
@@ -635,6 +666,7 @@ SP's are by default denied if the IdP has any rules associated with it (i.e, the
 However, if the IdP does not have any rules associated with its entity id, all SP's are by default allowed.
 
 Deny all but one SP:
+
 ```yaml
 rules:
     target_entity_id1:
@@ -643,6 +675,7 @@ rules:
 ```
 
 Allow all but one SP:
+
 ```yaml
 rules:
     target_entity_id1:
@@ -679,6 +712,16 @@ persistent NameID may also be obtained from attributes returned from the LDAP di
 LDAP microservice install the extra necessary dependencies with `pip install satosa[ldap]` and then see the
 [example config](../example/plugins/microservices/ldap_attribute_store.yaml.example).
 
+#### Support for IdP Hinting
+
+It's possible to hint an IdP to SaToSa using the `IdpHinting` micro-service.
+
+With this feature an SP can send a hint about the IdP that should be used, in order to skip the discovery service.
+The hint as a parameter in the query string of the request.
+The hint query parameter value must be the entityID of the IdP.
+The hint query parameter name is specified in the micro-service configuation.
+See the [example configuration](../example/plugins/microservices/idp_hinting.yaml.example).
+
 ### Custom plugins
 
 It's possible to write custom plugins which can be loaded by SATOSA. They have to be contained in a Python module,
@@ -716,9 +759,11 @@ full featured general purpose web server (in a reverse proxy architecture) such
 Apache HTTP Server to help buffer slow clients and enable more sophisticated error page rendering.
 
 Start the proxy server with the following command:
+
 ```bash
 gunicorn -b<socket address> satosa.wsgi:app --keyfile=<https key> --certfile=<https cert>
 ```
+
 where
 * `socket address` is the socket address that `gunicorn` should bind to for incoming requests, e.g. `0.0.0.0:8080`
 * `https key` is the path to the private key to use for HTTPS, e.g. `pki/key.pem`
@@ -734,4 +779,3 @@ set SATOSA_CONFIG=/home/user/proxy_conf.yaml
 ## Using Apache HTTP Server and mod\_wsgi
 
 See the [auxiliary documentation for running using mod\_wsgi](mod_wsgi.md).
-