Ueberauth SAML

Ueberauth plugin for SAML-based identity providers

What is this?

Ueberauth is an authentication framework for Elixir applications that specializes in OAuth. This library is one of many plugins (called Strategies) that allow Ueberauth to integrate with different identity providers. Specifically, this one adapts Ueberauth to integrate with SAML-based identity providers. SAML is a separate protocol from OAuth that can also be used for single sign-on applications.

This library does not provide a full SAML service or identity provider implementation. For that, see Samly.

Installation

This application is not currently available on Hex.pm. In the meantime, install it directly from GitHub:

def deps do
  [
    {:ueberauth_saml, github: "codesandbox/ueberauth_saml"}
  ]
end

Configuration

This strategy uses Samly and its sub-dependency esaml to interact with SAML Identity Providers. As a result, using this strategy requires two sets of configuration.

Strategy Configuration

First, configure this strategy as an Ueberauth provider. This configuration should occur at compile time:

# config/config.exs

config :ueberauth, Ueberauth,
  providers: [
    # ...
    saml:
      {Ueberauth.Strategy.SAML,
       [
         allow_idp_initiated_flow: true,
         callback_methods: ["POST"]
       ]}
  ]

Here, the saml key is the provider ID that will be used in routes (for example /auth/saml). This provider ID must match an identity provider ID used in the next configuration block.

Below are the available configuration keys that can be passed directly to the strategy:

Key	Type	Description
allow_idp_initiated_flow	boolean	Whether to allow logins that start from the Identity Provider (ex. Google app sheet or Okta tile). Defaults to false.
callback_methods	List of HTTP verbs	HTTP methods used by the Identity Provider to complete a login. Many providers require ["POST"]. Defaults to ["GET"].

Samly Configuration

Second, configure the Samly library. This requires configuring the service provider (your app) and identity provider(s) (like Google, Okta, etc.). Runtime configuration is often appropriate for this:

# config/runtime.exs

config :samly, Samly.Provider,
  service_providers: [
    %{
      id: "my_app",
      entity_id: "urn:example.com:production",
      certfile: "/path/to/cert.pem",
      keyfile: "/path/to/key.pem",
      contact_name: "My Company Support",
      contact_email: "support@example.com",
      org_name: "My Company",
      org_displayname: "My Co.",
      org_url: "https://example.com"
    }
  ],
  identity_providers: [
    %{
      id: "google_saml",
      sp_id: "my_app",
      metadata_file: "/path/to/idp-metadata.xml",
      sign_requests: true,
      signed_assertion_in_resp: false,
      signed_envelopes_in_resp: false
    }
  ]

Remember that the identity provider id must match the provider ID given to Ueberauth. Meanwhile, the sp_id given to the identity provider should match the id of a service provider above.

Note that not all Samly configuration is useful with this strategy. The following keys are used:

Service Provider

At least one service provider must be configured.

Key	Type	Example	Description
id	string	"my_app"	Required. Identifier for your application.
entity_id	string	"urn:example.com:production"	Required. Unique identifier for your application across all service providers configured with your identity provider. Must match the entity provider configured with your identity provider.
certfile	file path	"/path/to/cert.pem"	Path to a PEM-formatted certificate that will be used to sign data from your application to the identity provider. Setting this is strongly recommended for production deployments. If unset, ensure the identity provider is configured with sign_requests: false.
keyfile	file path	"/path/to/key.pem"	Path to a PEM-formatted private key that will be used to sign data form your application to the identity provider. Setting this is strongly recommended for production deployments. If unset, ensure the identity provider is configured with sign_requests: false.
contact_name	string	My Company Support	Optional technical contact name for your application.
contact_email	string	support@example.com	Optional technical contact email for your application.
org_name	string	My Company	Optional name of your application's organization.
org_displayname	string	My Co.	Optional display name of your application's organization.
org_url	string	My Co.	Optional web URL of your application's organization.

Identity Provider

One identity provider should be configured for each Ueberauth provider (with the same id).

Key	Type	Example	Description
id	string	"google_saml"	Required. Identifier for the identity provider. Must match the name of the corresponding provider configured with Ueberauth.
sp_id	string	"my_app"	Required. Identifier for your application / the service provider to use with this identity provider. Must match an id given to a service provider above.
metadata_file	file path	"/path/to/idp-metadata.xml"	Required if metadata is not set. Path to an XML file provided by your identity provider with information about the provider.
metadata	string	XML contents	Required if metadata_file is not set. Inline XML contents provided by your identity provider with information about the provider.
sign_requests	boolean	true	Whether to sign requests sent from your application to the identity provider. This may be required by your identity provider, and is strongly recommended for production deployments. Must be false if a certfile and keyfile are not provided in the corresponding service provider. Defaults to true.
signed_assertion_in_resp	boolean	true	Whether your application should expect the identity provider to sign assertions in its responses. Identity providers may sign the envelope without signing the assertion. Defaults to true.
signed_envelopes_in_resp	boolean	true	Whether your application should expect the identity provider to sign the envelopes of its responses. Identity providers may sign the envelope without signing the assertion. Defaults to true.

For example configurations, see configuration.

Attribute Mapping

SAML allows communicating additional information via mapped attributes. The following attribute names will be passed through to the Ueberauth Auth struct:

• birthday
• description
• email (if not mapped, and the SAML Name ID format is email, then the SAML name will be used instead)
• first_name
• last_name
• location
• name (if first_name and last_name are mapped, these will be used instead)
• nickname
• phone

Acknowledgments

Thank you to CodeSandbox for updates and maintenance of this library.

License

Please see LICENSE for licensing details.