Shin

Shin is a simple Elixir client for the Shibboleth IdP's admin features. Currently it can collect metrics and trigger service reloads, fetch metadata and show released user attributes.

Shin can be used to gather information about your IdP servers such as Java version and IdP version, and can also collect any other information defined as a metric within the IdP. Shin can return the raw data or reformat it into simpler reports.

The Shibboleth IdP will automatically reload valid configuration files but may stop retrying if passed an incorrect file. Shin can be used to prompt the IdP to immediately reload parts of its configuration.

Shin can also fetch entity metadata via the IdP and lookup user attribute information for specified SPs.

Installation

The package can be installed by adding shin to your list of dependencies in mix.exs:

def deps do
  [
    {:shin, "~> 0.2.0"}
  ]
end

Overview

Defining an IdP target

To define an IdP using a default configuration you only need the base URL of the IdP service

{:ok, idp} = Shin.idp("https://idp.example.com/idp")
# => 
#{:ok,
#  %Shin.IdP{
#    base_url: "https://idp.example.com/idp",
#    metric_groups: [:core, :idp, :logging, :access, :metadata, :nameid,
#      :relyingparty, :registry, :resolver, :filter, :cas, :bean],
#    metrics_path: "profile/admin/metrics",
#    no_dns_check: false,
#    reload_path: "profile/admin/reload-service",
#    reloadable_services: %{
#      access_control: "shibboleth.ReloadableAccessControlService",
#      attribute_filter: "shibboleth.AttributeFilterService",
#      attribute_registry: "shibboleth.AttributeRegistryService",
#      attribute_resolver: "shibboleth.AttributeResolverService",
#      cas_registry: "shibboleth.ReloadableCASServiceRegistry",
#      managed_beans: "shibboleth.ManagedBeanService",
#      metadata_resolver: "shibboleth.MetadataResolverService",
#      nameid_generator: "shibboleth.NameIdentifierGenerationService",
#      relying_party_resolver: "shibboleth.RelyingPartyResolverService"
#    },
#    timeout: 2000
#  }}

If your IdP has different paths, metrics groups or reloadable services you can specify them as options.

Functions in the top-level Shin module can also be passed a base URL if no configuration is needed.

Downloading raw metrics

{:ok, metrics} = Shin.metrics(idp)

{:ok, metrics} = Shin.metrics(idp, :core)

list_of_gauges = Shin.Metrics.gauge_ids(metrics)
hostname = Shin.Metrics.gauge(metrics, "host.name")

Producing a simplified report

{:ok, report} = Shin.report(idp, :system_info)

report.cores
#=> 4

Triggering a service reload

{:ok, message} = Shin.reload_service(idp, "shibboleth.AttributeFilterService")

{:ok, message} = Shin.reload_service(idp, :attribute_filter)

Listing a user's attribute data released to an SP

{:ok, attr_data} = Shin.attributes(idp, "https://test.ukfederation.org.uk/entity", "pete")
Shin.Attributes.values(attr_data, "eduPersonEntitlement")
# => ["urn:mace:dir:entitlement:common-lib-terms"]
Shin.Attributes.names(attr_data)
#=> ["eduPersonEntitlement", "eduPersonPrincipalName", "eduPersonScopedAffiliation",
# "eduPersonUniqueID", "o"]

Viewing a simulated SAML2 assertion containing user attributes

{:ok, saml_assertion_xml} = Shin.assertion(idp, "https://test.ukfederation.org.uk/entity", "pete")

Fetching an SP's metadata

{:ok, metadata_xml} = Shin.metadata(idp, "https://test.ukfederation.org.uk/entity")

Example Script

This script outputs a small table showing the Java version used by each IdP

#!/usr/bin/env elixir

Mix.install(
  [
    {:shin, "~> 0.2"},
    {:table_rex, "~> 3.1.1"}
  ]
)

urls = [
  "https://idp1.example.com/idp",
  "https://idp2.example.com/idp",
]

urls
|> Enum.map(
     fn url -> Shin.report(url)
               |> case do
                    {:ok, report} -> [url, report.java_version, report.java_vendor]
                    {:error, _msg} -> [url, "error", "error"]
                  end
     end
   )
|> TableRex.quick_render!(["IdP", "Java Version", "Java Vendor"])
|> IO.puts

Requirements

• Shibboleth IdP v3 or above (Shin is only tested against v4)
• IP address access control enabled for the client's IP address for the IdP's admin endpoints
• Elixir 12 or greater, Erlang 24 or greater

Limitations

• Only IP address-based authnz is supported, but other methods may be added in later versions.

API Documentation

Full API documentation can be found at https://hexdocs.pm/shin.

Contributing

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

References

• Shibboleth IdP v4 Metrics Docs
• Shibboleth IdP v4 Reloadable Services Docs
• Shibboleth IdP v4 Access Control
• Shin is named after the twenty-first letter of the Semitic abjads

Copyright and License

Copyright (c) 2022 Digital Identity Ltd, UK

Shin is MIT licensed.