Skip to content

Documentation for new configuration options #127

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
johanlundberg merged 2 commits into from
Jul 31, 2017
Merged

Documentation for new configuration options #127

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a7937dd
Add documentation for entityid_endpoint config option
Jul 28, 2017
6d3fa85
Add documentation for acr_mapping availability on the backend
Jul 28, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 31 additions & 24 deletions doc/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,8 @@ Common configuration parameters:
| `cert_file` | string | `pki/cert.pem` | path to certificate for the public key associated with the private key in `key_file` |
| `metadata["local"]` | string[] | `[metadata/entity.xml]` | list of paths to metadata for all service providers (frontend)/identity providers (backend) communicating with the proxy |
| `attribute_profile` | string | `saml` | attribute profile to use for mapping attributes from/to response
| `entityid_endpoint` | bool | `true` | whether `entityid` should be used as a URL that serves the metadata xml document
| `acr_mapping` | dict | `None` | custom Authentication Context Class Reference

The metadata could be loaded in multiple ways in the table above it's loaded from a static
file by using the key "local". It's also possible to load read the metadata from a remote URL.
Expand All @@ -172,7 +174,36 @@ see the
[documentation of the underlying library pysaml2](https://github.com/rohe/pysaml2/blob/master/doc/howto/config.rst).


##### Providing `AuthnContextClassRef`

SAML2 frontends and backends can provide a custom (configurable) *Authentication Context Class Reference*.
For the frontend this is defined in the `AuthnStatement` of the authentication response, while,
for the backend this is defined in the `AuthnRequest`.

This can be used to describe for example the Level of Assurance, as described for example by [eIDAS](https://ec.europa.eu/cefdigital/wiki/jdisplay/CEFDIGITAL/eIDAS+Profile?preview=/46992719/47190128/eIDAS%20Message%20Format_v1.1-2.pdf).

The `AuthnContextClassRef`(ACR) can be specified per target provider in a mapping under the
configuration parameter `acr_mapping`. The mapping must contain a default ACR value under the key `""`
(empty string), each other ACR value specific per target provider is specified with key-value pairs, where the
key is the target providers identifier (entity id for SAML IdP behind SAML2 backend, authorization endpoint
URL for OAuth AS behind OAuth backend, and issuer URL for OpenID Connect OP behind OpenID Connect backend).

If no `acr_mapping` is provided in the configuration, the ACR received from the backend plugin will
be used instead. This means that when using a SAML2 backend, the ACR provided by the target
provider will be preserved, and when using a OAuth or OpenID Connect backend, the ACR will be
`urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified`.

**Example**

config:
[...]
acr_mapping:
"": default-LoA
"https://accounts.google.com": LoA1


#### Frontend

The SAML2 frontend act as a SAML Identity Provider (IdP), accepting
authentication requests from SAML Service Providers (SP). The default
configuration file can be found [here](../example/plugins/frontends/saml2_frontend.yaml.example).
Expand Down Expand Up @@ -202,30 +233,6 @@ For the simple case where an SP does not support discovery it's also possible to
`SP -> SAMLFrontend -> SAMLBackend -> discovery to select target IdP -> target IdP`


##### Providing `AuthnContextClassRef`
Copy link
Member Author

@c00kiemon5ter c00kiemon5ter Jul 28, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

moved out as it now applies to both frontend and backend.

The SAML2 frontends can provide a custom (configurable) *Authentication Context Class Reference* in in the
`AuthnStatement` of in the authentication response. This can be used to describe for example the Level of Assurance,
as described for example by [eIDAS](https://ec.europa.eu/cefdigital/wiki/display/CEFDIGITAL/eIDAS+Profile?preview=/46992719/47190128/eIDAS%20Message%20Format_v1.1-2.pdf).

The `AuthnContextClassRef`(ACR) can be specified per target provider in a mapping under the
configuration parameter `acr_mapping`. The mapping must contain a default ACR value under the key `""`
(empty string), each other ACR value specific per target provider is specified with key-value pairs, where the
key is the target providers identifier (entity id for SAML IdP behind SAML2 backend, authorization endpoint
URL for OAuth AS behind OAuth backend, and issuer URL for OpenID Connect OP behind OpenID Connect backend).

If no `acr_mapping` is provided in the configuration, the ACR received from the backend plugin will
be used instead. This means that when using a SAML2 backend, the ACR provided by the target
provider will be preserved, and when using a OAuth or OpenID Connect backend, the ACR will be
`urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified`.

**Example**

config:
idp_config: [...]
acr_mapping:
"": default-LoA
"https://accounts.google.com": LoA1

##### 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.
Expand Down