View Source Smee (Smee v0.5.0)

Smee is a pragmatic library for handling SAML metadata with Elixir, Erlang or any other BEAM language.

Features

Download remote SAML metadata or load local files, with effective caching
Manage and compare metadata files and individual entity metadata
MDQ API (which can also emulate MDQ style lookups with aggregate files)
A focus on streaming with reliable and surprisingly low memory usage
Filter entity streams by various criteria
Validate XML signatures, automatically download and confirm signing certificates
Transform metadata using XSLT, or extract data
Access XML using Erlang's Xmerl library (sweetened by SweetXML)
Recombine entity streams into aggregates or other data formats
Can be used with applications or in simple .exs scripts

Modules

The top level Smee module contains a few simplified, top level functions better suited to simpler scripts. Other modules in Smee contain more tools for handling SAML metadata, such as:

Smee.Source - define sources of metadata
Smee.Metadata - functions for handling metadata aggregates
Smee.Entity - individual SAML entity definitions
Smee.Extract - processing metadata to extract information
Smee.Fetch - downloading metadata sources
Smee.MDQ - functions for MDQ clients (and emulating MDQ clients)
Smee.Filter - filtering streams of entity records
Smee.Transform - processing and editing entity XML
Smee.Publish - Formatting and outputting metadata in various formats
Smee.Stats - Simple stats for entity streams
Smee.Lint - XML validation and reformatting

Summary

Functions

entity_ids(source)

Lists the IDs of every entity in the metadata.

fetch!(source)

Downloads a source of metadata (local or remote) and returns a %Metadata{} struct containing XML and information.

lookup!(source, entity_id)

Retrieves information for a single entity from an MDQ service (real or emulated) and returns an %Entity{} struct.

source(url)

Defines a source of metadata

source(url, options)

Defines a source of metadata

stream_entities(source)

Streams all entities in the specified metadata or source.

Functions

entity_ids(source)

@spec entity_ids(source :: Smee.Source.t() | Smee.Metadata.t()) :: [binary()]

Lists the IDs of every entity in the metadata.

This version of the function can accept either a %Source{} or a %Metadata{} struct containing already-loaded Metadata.

Example

iex> Smee.source("http://metadata.ukfederation.org.uk/ukfederation-metadata.xml")
iex> |> Smee.entity_ids()

fetch!(source)

@spec fetch!(source :: Smee.Source.t()) :: Smee.Metadata.t()

Downloads a source of metadata (local or remote) and returns a %Metadata{} struct containing XML and information.

Example

iex> "http://metadata.ukfederation.org.uk/ukfederation-metadata.xml"
iex> |> Smee.source()
iex> |> Smee.fetch!()

lookup!(source, entity_id)

@spec lookup!(source :: Smee.Source.t() | Smee.Metadata.t(), entity_id :: binary()) ::
  Smee.Entity.t()

Retrieves information for a single entity from an MDQ service (real or emulated) and returns an %Entity{} struct.

This version of the function can accept either a %Source{} or a %Metadata{} struct containing already-loaded Metadata.

Example

iex> "http://mdq.ukfederation.org.uk/"
iex> |> Smee.source(type: :mdq)
iex> |> Smee.lookup!("https://cern.ch/login")

iex> "http://metadata.ukfederation.org.uk/ukfederation-metadata.xml"
iex> |> Smee.source(type: :aggregate)
iex> |> Smee.lookup!("https://cern.ch/login")

source(url)

@spec source(url :: binary()) :: Smee.Source.t()

Defines a source of metadata

Sources of metadata include online aggregate XML, local aggregate files, individual entities, and MDQ services. This function will only define sources of aggregate XML.

Example

iex> Smee.source("http://metadata.ukfederation.org.uk/ukfederation-metadata.xml")
iex>

source(url, options)

@spec source(url :: binary(), options :: keyword()) :: Smee.Source.t()

Defines a source of metadata

Sources of metadata include online aggregate XML, local aggregate files, individual entities, and MDQ services. This function allows a lot of customisation, particularly the type. Types are:

:aggregate (a file containing a collection of entityDescriptor fragments inside a entitiesDescriptor tag, as used by federations)
:single (a file with a single entityDescriptor, as used for individual metadata records)
:mdq (an online MDQ service)

URLs may be remote (http:// and https://) or local (file://). Local files can be specified as bare paths.

See Smee.Source.new for full details

Example

iex> Smee.source("http://mdq.ukfederation.org.uk/", type: :mdq, retries: 1, label: "UK MDQ Service")
iex> Smee.source("support/static/valid.xml", type: :single, retries: 1, label: "My IdP")

stream_entities(source)

@spec stream_entities(source :: Smee.Source.t() | Smee.Metadata.t()) :: Enumerable.t()

Streams all entities in the specified metadata or source.

This version of the function can accept either a %Source{} or a %Metadata{} struct containing already-loaded Metadata.

Example

iex> Smee.stream_entities("http://metadata.ukfederation.org.uk/ukfederation-metadata.xml")
iex> |> Stream.take(1)
iex> |> Enum.to_list