Samly

SAML 2.0 SP SSO made easy. This is a Plug library that can be used to enable SAML 2.0 Single Sign On authentication in a Plug/Phoenix application.

This library uses Erlang esaml to provide plug enabled routes.

Setup

# mix.exs

defp deps() do
  [
    # ...
    {:samly, "~> 0.9"},
  ]
end

If you are usig Samly v0.7.x, checkout: Migrating from v0.7.x to v0.8.0.

Supervision Tree

Add Samly.Provider to your application supervision tree.

# application.ex

children = [
  # ...
  worker(Samly.Provider, []),
]

Router Change

Make the following change in your application router.

# router.ex

# Add the following scope ahead of other routes
# Keep this as a top-level scope and **do not** add
# any plugs or pipelines explicitly to this scope.
scope "/sso" do
  forward "/", Samly.Router
end

Certificate and Key for Samly

Samly needs a private key and a corresponding certificate. These are used when communicating with the Identity Provider.

A convenient script, gencert.sh, is provided in samly_howto to generate the key and certificate. Make sure openssl is available on your system. The name of the key file and certificate file generated should be provided as part of the Samly configuration.

Identity Provider Metadata

Samly expects information about the Identity Provider including information about its SAML endpoints in an XML file. Most Identity Providers have some way of exporting the IdP metadata in XML form. Some may provide a web UI to export/save the XML locally. Others may provide a URL that can be used to fetch the metadata.

For example, SimpleSAMLPhp IdP provides a URL for the metadata. You can fetch it using wget.

wget http://samly.idp:8082/simplesaml/saml2/idp/metadata.php -O idp_metadata.xml

If you are using the SimpleSAMLPhp administrative Web UI, login with you admin credentials (http://samly.idp:8082/simplesaml). Go to the Federation tab. At the top there will be a section titled "SAML 2.0 IdP Metadata". Click on the Show metadata link. Copy the metadata XML from this page and save it in a local file (idp_metadata.xml for example).

Make sure to save this XML file and provide the path to the saved file in Samly configuration.

Identity Provider ID in Samly

Samly has the ability to support multiple Identity Providers. All IdPs that Samly needs to talk to must have an identifier (idp_id). This IdP id will be used in the service provider URLs. This is how Samly figures out which SAML request corresponds to what IdP so that it can perform relevant validation checks and process the requests/responses.

There are two options when it comes to how the idp_id is represented in the Service Provider SAML URLs.

URL Path Segment

In this model, the idp_id is present as a URL path segment. Here is an example URL: http://do-good.org/sso/auth/signin/affiliates. The idp_id in this URL is "affiliates". If you have more than one IdP, only this last part changes. The URLs for this model are:

Description	URL
Sign-in button/link in Web UI	/sso/auth/signin/affiliates
Sign-out button/link in Web UI	/sso/auth/signout/affiliates
SP Metadata URL	http://do-good.org/sso/sp/metadata/affiliates
SAML Assertion Consumer Service	http://do-good.org/sso/sp/consume/affiliates
SAML SingleLogout Service	http://do-good.org/sso/sp/logout/affiliates

The path segment model is the default one in Samly. If there is only one Identity Provider, use this mode.

These URL routes are automatically created based on the configuration information and the above mentioned router scope definition.

Use the Sign-in and Sign-out URLs shown above in your application's Web UI buttons/links. When the end-user clicks on these buttons/links, the HTTP GET request is handled by Samly which internally does a POST that in turn sends the appropriate SAML request to the IdP.

Subdomain in Host Name

In this model, the subdomain name is used as the idp_id. Here is an example URL: http://ngo.do-good.org/sso/auth/signin. Here "ngo" is the idp_id. The URLs supported by Samly in this model look different.

Description	URL
Sign-in button/link in Web UI	/sso/auth/signin
Sign-out button/link in Web UI	/sso/auth/signout
SP Metadata URL	http://ngo.do-good.org/sso/sp/metadata
SAML Assertion Consumer Service	http://ngo.do-good.org/sso/sp/consume
SAML SingleLogout Service	http://ngo.do-good.org/sso/sp/logout

Take a look at samly_howto - a reference/demo application on how to use this library.

Make sure to use HTTPS URLs in production deployments.

Samly Configuration

# config/dev.exs

config :samly, Samly.Provider,
  idp_id_from: :path_segment,
  service_providers: [
    %{
      id: "do-good-affiliates-sp",
      entity_id: "urn:do-good.org:affiliates-app",
      certfile: "path/to/samly/certfile.crt",
      keyfile: "path/to/samly/keyfile.pem",
      #contact_name: "Affiliates Admin",
      #contact_email: "[email protected]",
      #org_name: "Do Good",
      #org_displayname: "Goodly, No evil!",
      #org_url: "http://do-good.org"
    }
  ],
  identity_providers: [
    %{
      id: "affiliates",
      sp_id: "do-good-affiliates-sp",
      base_url: "http://do-good.org/sso",
      metadata_file: "idp_metadata.xml",
      #pre_session_create_pipeline: MySamlyPipeline,
      #use_redirect_for_req: false,
      #sign_requests: true,
      #sign_metadata: true,
      #signed_assertion_in_resp: true,
      #signed_envelopes_in_resp: true,
      #allow_idp_initiated_flow: false,
      #allowed_target_urls: ["http://do-good.org"]
    }
  ]

Parameters	Description
idp_id_from	(optional):path_segment or :subdomain. Default is :path_segment.
Service Provider Parameters
id	(mandatory)
identity_id	(optional) If omitted, the metadata URL will be used
certfile	(optional) This is needed when SAML requests/responses from Samly need to be signed. Make sure to set this in a production deployment. Could be omitted during development if your IDP is setup to not require signing. If that is the case, the following Identity Provider Parameters must be explicitly set to false: sign_requests, sign_metadata
keyfile	(optional) Similar to certfile
contact_name	(optional) Technical contact name for the Service Provider
contact_email	(optional) Technical contact email address
org_name	(optional) SAML Service Provider (your app) Organization name
org_displayname	(optional) SAML SP Organization displayname
org_url	(optional) Service Provider Organization web site URL
Identity Provider Parameters
id	(mandatory) This will be the idp_id in the URLs
sp_id	(mandatory) The service provider definition to be used with this Identity Provider definition
base_url	(optional) If missing Samly will use the current URL to derive this. It is better to define this in production deployment.
metadata_file	(mandatory) Path to the IdP metadata XML file obtained from the Identity Provider.
pre_session_create_pipeline	(optional) Check the customization section.
use_redirect_for_req	(optional) Default is false. When this is false, Samly will POST to the IdP SAML endpoints.
sign_requests, sign_metadata	(optional) Default is true.
signed_assertion_in_resp, signed_envelopes_in_resp	(optional) Default is true. When true, Samly expects the requests and responses from IdP to be signed.
allow_idp_initiated_flow	(optional) Default is false. IDP initiated SSO is allowed only when this is set to true.
allowed_target_urls	(optional) Default is []. Samly uses this only when allow_idp_initiated_flow parameter is set to true. Make sure to set this to one or more exact URLs you want to allow (whitelist). The URL to redirect the user after completing the SSO flow is sent from IDP in auth response as relay_state. This relay_state target URL is matched against this URL list. Set the value to nil if you do not want this whitelist capability.

Assertion State

This package supports configuration of Assertion State implementations. Currently there are two provided by the package:

1. State.Ets - State is stored in ETS table (default).
2. State.Conn - State is stored in Plug.Conn.Session, which allows it to be shared among nodes in the cluster in a stateless fashion.

The behaviour implementation can be set in the Application config:

# config/config.exs

config :samly, 
  :state_provider, Samly.State.Conn

SAML Assertion

Once authentication is completed successfully, IdP sends a "consume" SAML request to Samly. Samly in turn performs its own checks (including checking the integrity of the "consume" request). At this point, the SAML assertion with the authenticated user subject and attributes is available.

The subject in the SAML assertion is tracked by Samly so that subsequent logout/signout request, either service provider initiated or IdP initiated would result in proper removal of the corresponding SAML assertion.

Use the Samly.get_active_assertion function to get the SAML assertion for the currently authenticated user. This function will return nil if the user is not authenticated.

Avoid using the subject in the SAML assertion in UI. Depending on how the IdP is setup, this might be a randomly generated id.

You should only rely on the user attributes in the assertion. As an application working with an IdP, you should know which attributes will be made available to your application and out of those attributes which one should be treated as the logged in userid/name. For example it could be "uid" or "email" depending on how the authentication source is setup in the IdP.

Customization

Samly allows you to specify a Plug Pipeline if you need more control over the authenticated user's attributes and/or do a Just-in-time user creation. The Plug Pipeline is invoked after the user has successfully authenticated with the IdP but before a session is created.

This is just a vanilla Plug Pipeline. The SAML assertion from the IdP is made available in the Plug connection as a "private". If you want to derive new attributes, create an Elixir map data (%{}) and update the computed field of the SAML assertion and put it back in the Plug connection private with Conn.put_private call.

Here is a sample pipeline that shows this:

defmodule MySamlyPipeline do
  use Plug.Builder
  alias Samly.{Assertion}

  plug :compute_attributes
  plug :jit_provision_user

  def compute_attributes(conn, _opts) do
    assertion = conn.private[:samly_assertion]

    first_name = Map.get(assertion.attributes, "first_name")
    last_name  = Map.get(assertion.attributes, "last_name")

    computed = %{"full_name" => "#{first_name} #{last_name}"}

    assertion = %Assertion{assertion | computed: computed}

    conn
    |>  put_private(:samly_assertion, assertion)

    # If you have an error condition:
    # conn
    # |>  send_resp(404, "attribute mapping failed")
    # |>  halt()
  end

  def jit_provision_user(conn, _opts) do
    # your user creation here ...
    conn
  end
end

Make this pipeline available in your config:

config :samly, Samly.Provider,
  identity_providers: [
    %{
      # ...
      pre_session_create_pipeline: MySamlyPipeline,
      # ...    
    }
  ]

Security Related

• Samly initiated sign-in/sign-out requests send RelayState to IdP and expect to get that back. Mismatched or missing RelayState in IdP responses to SP initiated requests will fail (with HTTP 403 access_denied).
• Besides the RelayState, the request and response idp_ids must match. Reponse is rejected if they don't.
• Samly makes the original request ID that an auth response corresponds to in Samly.Subject.in_response_to field. It is the responsibility of the consuming application to use this information along with the validity period in the assertion to check for replay attacks. The consuming application should use the pre_session_create_pipeline to perform this check. You may need a database or a distributed cache such as memcache in a clustered setup to keep track of these request IDs for their validity period to perform this check. Be aware that in_response_to field is not set when IDP initialized authorization flow is used.
• OOTB SAML requests and responses are signed.
• Signature digest method supported: SHA256.

  Some Identity Providers may be using SHA1 by default. Make sure to configure the IdP to use SHA256. Samly will reject (access_denied) IdP responses using SHA1.

• esaml provides additional checks such as trusted certificate verification, recipient verification among others.
• By default, Samly signs the SAML requests it sends to the Identity Provider. It also expects the SAML reqsponses to be signed (both assertion and envelopes). If your IdP is not configured to sign, you will have to explicitly turn them off in the configuration. It is highly recommended to turn signing on in production deployments.
• Make sure to use HTTPS URLs in production deployments.

FAQ

How to setup a SAML 2.0 IdP for development purposes?

Docker based setup of SimpleSAMLPhp is made available at samly_simplesaml Git Repo.

git clone https://github.com/handnot2/samly_simplesaml
cd samly_simplesaml

# Ubuntu 16.04 based
./build.sh

# Follow along README.md (skip SAML Service Provider registration part for now)
# Edit setup/params/params.yml with appropriate information
# Add the IDP host name to your /etc/hosts resolving to 127.0.0.1
# 127.0.0.1 samly.idp
# Compose exposes and binds to port 8082 by default.

docker-compose up -d
docker-compose restart

You should have a working SAML 2.0 IdP that you can work with.

Any sample Phoenix application that shows how to use Samly?

Clone the samly_howto Git Repo.

git clone https://github.com/handnot2/samly_howto

# Add the SP host name to your /etc/hosts resolving to 127.0.0.1
# 127.0.0.1 samly.howto

cd samly_howto

# Use gencert.sh to create a self-signed certificate for the SAML Service Provider
# embedded in your app (by `Samly`). We will register this and the `Samly` URLs
# with IdP shortly. Take a look at this script and adjust the certificate subject
# if needed.

./gencert.sh

# Get NPM assets

cd assets && npm install && cd ..

# Fetch the IdP metadata XML. `Samly` needs this to make sure that it can
# validate the request/responses to/from IdP.

wget http://samly.idp:8082/simplesaml/saml2/idp/metadata.php -O idp_metadata.xml

mix deps.get
mix compile

HOST=samly.howto PORT=4003 iex -S mix phx.server

Important: Make sure that your have registered this application with the IdP before you explore this application using a browser.

Open http://samly.howto:4003 in your browser and check out the app.

It is recommended that you use the SamlyHowto application to sort out any configuration issues by making this demo application work successfully with your Identity Provider (IdP) before attempting your application.

This demo application supports experimentation with multiple IdPs.

How to register the service provider with IdP

Complete the setup by registering samly_howto as a Service Provider with the IdP.

mkdir -p samly_simplesaml/setup/sp/samly_howto # use the correct path
cp samly.crt samly_simplesaml/setup/sp/samly_howto/sp.crt
cd samly_simplesaml
docker-compose restart

The IdP related instructions are very specific to the docker based development setup of SimpleSAMLphp IdP. But similar ideas work for your own IdP setup.