SAML

The saml block lets you configure the saml_sso_url() function and an access control for a SAML Assertion Consumer Service (ACS) endpoint. Like all access control types, the saml block is defined in the definitions block and can be referenced in all configuration blocks by its required label.

Block name	Context	Label
`saml`	Definitions Block	⚠ required

Example

A complete example can be found here.

Using a metadata file

saml "SSO" {
  idp_metadata_file = "idp-metadata.xml"
  sp_entity_id = env.SP_ENTITY_ID
  sp_acs_url = "http://localhost:8080/saml/acs"
  array_attributes = ["eduPersonAffiliation"] # or ["memberOf"]
}

Using a metadata URL with automatic refresh

saml "SSO" {
  idp_metadata_url = "https://idp.example.com/metadata"
  metadata_ttl = "1h"
  metadata_max_stale = "1h"
  sp_entity_id = env.SP_ENTITY_ID
  sp_acs_url = "http://localhost:8080/saml/acs"
  array_attributes = ["eduPersonAffiliation"]
}

Using a metadata URL with a custom backend

saml "SSO" {
  idp_metadata_url = "https://idp.example.com/metadata"
  metadata_ttl = "30m"
  sp_entity_id = env.SP_ENTITY_ID
  sp_acs_url = "http://localhost:8080/saml/acs"

  backend {
    origin = "https://idp.example.com"
    timeout = "10s"
  }
}

Attributes

Name	Type	Default	Description
`array_attributes`	tuple (string)	`[]`	A list of assertion attributes that may have several values. Results in at least an empty array in `request.context.<label>.attributes.<name>`
`backend`	string	-	References a backend in definitions for IdP metadata requests. Mutually exclusive with `backend` block.
`custom_log_fields`	object	-	Log fields for custom logging. Inherited by nested blocks.
`idp_metadata_file`	string	-	File reference to the Identity Provider metadata XML file. Mutually exclusive with `idp_metadata_url`.
`idp_metadata_url`	string	-	URL to fetch the Identity Provider metadata XML. Mutually exclusive with `idp_metadata_file`.
`metadata_max_stale`	duration	`"1h"`	Time period the cached IdP metadata stays valid after its TTL has passed.
`metadata_ttl`	duration	`"1h"`	Time period the IdP metadata stays valid and may be cached.
`sp_acs_url`	string	-	The URL of the Service Provider’s ACS endpoint. Relative URL references are resolved against the origin of the current request URL. The origin can be changed with the `accept_forwarded_url` attribute if Couper is running behind a proxy.
`sp_entity_id`	string	-	The Service Provider’s entity ID.

Some information from the assertion consumed at the ACS endpoint is provided in the context at request.context.<label>:

the NameID of the assertion’s Subject (request.context.<label>.sub)
the session expiry date SessionNotOnOrAfter (as UNIX timestamp: request.context.<label>.exp)
the attributes (request.context.<label>.attributes.<name>)

Nested Blocks

Name	Description
`backend`	Configures a backend for IdP metadata requests. Mutually exclusive with `backend` attribute.
`error_handler`	Configures an error handler (zero or more).