Digital-Identity-Labs / smee

SAML Metadata Entity Extractor (etc)
Apache License 2.0
1 stars 0 forks source link
elixir metadata metadata-extraction metadata-management saml

Smee

Smee Logo

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

Smee started life as an sprawling mess of code used over five years in an internal application to download and process SAML metadata. It's now been extracted, restructured and cleaned up, with the aim of reusing it in other projects. Smee can be used within applications or in simpler scripts for processing metadata.

Hex pm API Docs Github Elixir CI

Run in Livebook

Features

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

Extensions and Extras

Examples

Getting entity details from an MDQ service

alias Smee.MDQ

cern_idp = 
  MDQ.source("http://mdq.ukfederation.org.uk/")
  |> MDQ.lookup!("https://cern.ch/login")

Downloading and streaming a metadata aggregate to output a list of all IdP entityIDs

alias Smee.{Source, Fetch, Filter, Metadata}

"http://metadata.ukfederation.org.uk/ukfederation-metadata.xml"
|> Source.new()
|> Fetch.remote!()
|> Metadata.stream_entities()
|> Filter.idp()
|> Stream.map(fn e -> e.uri end)
|> Enum.to_list()

Create an aggregate that only contains SPs with SIRTFI, that were registered over the previous 12 months

alias Smee.{Source, Fetch, Filter, Metadata, Publish}

"http://metadata.ukfederation.org.uk/ukfederation-metadata.xml"
|> Source.new()
|> Fetch.remote!()
|> Metadata.stream_entities()
|> Filter.days(365)
|> Filter.sp()
|> Filter.assurance("https://refeds.org/sirtfi")
|> Publish.write_aggregate()

Munge XML with XSLT

alias Smee.{Source, Fetch, Transform, Metadata}

## Using a builtin function

new_xml = Source.new("adfs.xml")
|> Fetch.local!()
|> Transform.decruft_sp!()
|> Metadata.xml()

File.save!("adfs_new.xml", new_xml)

## Or any XSLT stylesheet

{:ok, updated_metadata} = Transform.transform(metadata, stylesheet, [exampleParam: "example value"])

Installation

If available in Hex, the package can be installed by adding Smee to your list of dependencies in mix.exs:

def deps do
  [
    {:Smee, "~> 0.4.1"}
  ]
end

Backend tools

Please note: Smee does not do all processing itself using Elixir - it sometimes cheats (OK, it often cheats) by sending data to external programs for processing. At the moment it requires the following commandline utilities:

Smee now includes a Mix task to install the default backend software - just run:

mix deps.smee

(Currently only tested on Macs with Homebrew, but it should also work on Debian, Ubuntu, Red Hat and Alpine Linux)

A future version of Smee will support alternative sets of backends.

Rambo and Rust

Smee uses an Elixir library called Rambo to run external utilities like xsltproc. Rambo relies on a small compiled shim that is provided pre-compiled for various architectures or automatically built during installation.

Uses

Metadata Database: Smee was extracted from an application that downloads, processes and stores SAML metadata in a database for access with an API. The original code had become rather messy and was very difficult to test - hopefully Smee will be an improvement and will be used to replace the original code. Smee doesn't currently handle digestion and storage.

MDQ Service: We've made a streaming MDQ service using Smee that should soon be available

Reports: We've generated reports for clients using Smee

Possible Alternatives

These aren't quite the same but are mature, widely used projects that are a lot more stable than Smee. In many cases you should definitely use these instead of Smee.

References

SAML Metadata

MDQ

Unusual types of SAML metadata

Contributors and Sources

Various Github repositories have been plundered in a search for XSLT stylesheets, in particular:

The use of the Apache2 license in the above projects led to the Apache2 license for Smee.

Other sources and inspirations:

Smee temporarily includes a copy of EasySSL (MIT Licensed) that was required to fix an Erlang 26 compatibility issue. This will revert to a normal dependency when an update is released.

Documentation

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/smee.

Contributing

You can request new features by creating an issue, or submit a pull request with your contribution.

If you are comfortable working with Python but Smee's Elixir code is unfamiliar then this blog post may help: Elixir For Humans Who Know Python

Copyright and License

Copyright (c) 2023, 2024 Digital Identity Ltd, UK

Smee is Apache 2.0 licensed.

Disclaimer

Smee is not endorsed by The Shibboleth Foundation or any of the NREN's that may have had their XSLT borrowed. The API will definitely change considerably in the first few releases after 0.1.0 - it is not stable!