Skip to content

Latest commit

 

History

History
159 lines (122 loc) · 7.52 KB

README.md

File metadata and controls

159 lines (122 loc) · 7.52 KB
Raw

Ueberauth SAML

Contributor Covenant

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: "[email protected]",
      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 [email protected] 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.