Cowboy2 migration

Author: handnot2

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All changes are in the `main` branch (`master` remains unchanged).
 
+### v4.0.0
+
++   Fixed issue: #11 - Support for Cowboy 2
+    
 ### v3.6.1
 
 +   Fixed issue: #9 - HTTP-REDIRECT wrong case

README.md

@@ -1,4 +1,4 @@
-An implementation of the Security Assertion Markup Language (SAML) in Erlang. So far this supports enough of the standard to act as a Service Provider (SP) to perform authentication with SAML. It has been tested extensively against the SimpleSAMLPHP IdP and can be used in production.
+An implementation of the Security Assertion Markup Language (SAML) in Erlang. So far this supports enough of the standard to act as a Service Provider (SP) to perform authentication with SAML. It has been tested extensively against the SimpleSAMLphp IdP and can be used in production.
 
 ### Supported protocols
 
@@ -15,98 +15,36 @@ Single log-out protocols:
  * SP: send LogoutRequest (REDIRECT) -> receive LogoutResponse (REDIRECT or POST)
  * SP: receive LogoutRequest (REDIRECT OR POST) -> send LogoutResponse (REDIRECT)
 
-esaml supports RSA+SHA1/SHA256 signing of all SP payloads, and validates signatures on all IdP responses. Compatibility flags are available to disable verification where IdP implementations lack support (see the [esaml_sp record](http://arekinath.github.io/esaml/esaml.html#type-sp), and members such as `idp_signs_logout_requests`).
+`esaml` supports RSA+SHA1/SHA256 signing of all SP payloads, and validates signatures on all IdP responses. Compatibility flags are available to disable verification where IdP implementations lack support (see the [esaml_sp record](http://arekinath.github.io/esaml/esaml.html#type-sp), and members such as `idp_signs_logout_requests`).
 
 ### API documentation
 
 Edoc documentation for the whole API is available at:
 
-http://arekinath.github.io/esaml/
+https://hexdocs.pm/esaml/4.0.0/
 
 ### Licensing
 
 2-clause BSD
 
 ### Getting started
 
-The simplest way to use esaml in your app is with the `esaml_cowboy` module. There is an example under `examples/sp` that shows how to make a simple SAML SP in this way.
+The simplest way to use `esaml` in your app is with the `esaml_cowboy` module. There are two SAML Server Provider (SP) applications included in the repo under `examples` directory.
 
-Point your browser to: http://127.0.0.1:8080/saml/auth
+The application in `examples/sp` directory shows how you can use `esaml` to enabled Single-Sign-On (SSO) in your application. This application enables an endpoint that supports Server Provider metadata request, SAML authentication request as well as the ability to consume the response from IdP.
 
-Each of the protocols you wish to support will normally require at least one distinct URL endpoint, plus one additional URL for the SAML SP metadata. In the `sp` example, only one protocol is used: the single-sign-on SP AuthnRequest -> Response + Assertion protocol.
-
-The typical approach is to use a single Cowboy route for all SAML endpoints:
-
-```erlang
-Dispatch = cowboy_router:compile([
-    {'_', [
-        {"/saml/:operation", sp_handler, []}
-    ]}
-])
-```
-
-Then, based on the value of the `operation` binding, you can decide which protocol to proceed with, by matching these up with the URIs you supply to `esaml_sp:setup/1`.
-
-```erlang
-init(_Transport, Req, _Args) ->
-    ...
-    SP = esaml_sp:setup(#esaml_sp{
-        consume_uri = Base ++ "/consume",
-        metadata_uri = Base ++ "/metadata",
-        ...
-    }),
-    ...
-
-handle(Req, S = #state{}) ->
-    {Operation, Req2} = cowboy_req:binding(operation, Req),
-    {Method, Req3} = cowboy_req:method(Req2),
-    handle(Method, Operation, Req3, S).
-
-handle(<<"GET">>, <<"metadata">>, Req, S) ->
-    ...
-
-handle(<<"POST">>, <<"consume">>, Req, S) ->
-    ...
-```
-
-The functions on the `esaml_cowboy` module can either parse and validate an incoming SAML payload, or generate one and reply to the request with it.
-
-For example, the way the metadata endpoint is handled in the example is to unconditionally call `esaml_cowboy:reply_with_metadata/2`, which generates the SP metadata and replies to the request:
-
-```erlang
-handle(<<"GET">>, <<"metadata">>, Req, S = #state{sp = SP}) ->
-    {ok, Req2} = esaml_cowboy:reply_with_metadata(SP, Req),
-    {ok, Req2, S};
-```
-
-On the other hand, the consumer endpoint (which handles the second step in the SSO protocol, receiving the Response + Assertion from the IdP) has to validate its payload before replying:
-
-```erlang
-handle(<<"POST">>, <<"consume">>, Req, S = #state{sp = SP}) ->
-    case esaml_cowboy:validate_assertion(SP, Req) of
-        {ok, Assertion, RelayState, Req2} ->
-            % authentication success!
-            ...;
-
-        {error, Reason, Req2} ->
-            {ok, Req3} = cowboy_req:reply(403, [{<<"content-type">>, <<"text/plain">>}],
-                ["Access denied, assertion failed validation\n"], Req2),
-            {ok, Req3, S}
-    end;
-```
-
-More complex configurations, including multiple IdPs, dynamic retrieval of IdP metadata, and integration with many kinds of application authentication systems are possible.
-
-The second esaml example, `sp_with_logout` demonstrates the addition endpoints necessary to enable Single Log-out protocol support. It also shows how you can build a bridge from esaml to local application session storage, by generating session cookies for each user that logs in (and storing them in ETS).
+The second application in `example/sp_with_logout` shows how Single Logout can be enabled. It also shows how you can build a bridge from `esaml` to local application session storage, by generating session cookies for each user that logs in (and storing them in ETS).
 
 ### More advanced usage
 
-You can also tap straight into lower-level APIs in esaml if `esaml_cowboy` doesn't meet your needs. The `esaml_binding` and `esaml_sp` modules are the interface used by `esaml_cowboy` itself, and contain all the basic primitives to generate and parse SAML payloads.
+You can also tap straight into lower-level APIs in `esaml` if `esaml_cowboy` doesn't meet your needs. The `esaml_binding` and `esaml_sp` modules are the interface used by `esaml_cowboy` itself, and contain all the basic primitives to generate and parse SAML payloads.
 
 This is particularly useful if you want to implement SOAP endpoints using SAML.
 
+> The Elixir library `Samly` is one such implementation. It dose not use `esaml_cowboy`. Instead it relies on the lower-level APIs and uses Elixir `Plug` and `Cowboy` directly for endpoints/routing.
+
 ### Contributions
 
-Pull requests are always welcome for bug fixes and improvements. Fixes that enable compatibility with different IdP implementations are usually welcome, but please ensure they do not come at the expense of compatibility with another IdP. esaml prefers to follow as closely to the SAML standards as possible.
+Pull requests are always welcome for bug fixes and improvements. Fixes that enable compatibility with different IdP implementations are usually welcome, but please ensure they do not come at the expense of compatibility with another IdP. `esaml` prefers to follow as closely to the SAML standards as possible.
 
 Bugs/issues opened without patches are also welcome, but might take a lot longer to be looked at. ;)

examples/sp/.gitignore

@@ -1,2 +1,3 @@
 .swp
 deps
+_checkouts

examples/sp/rebar.config

@@ -1,4 +1,4 @@
 {deps, [
-    {esaml, ".*", {git, "https://github.com/K2InformaticsGmbH/esaml", "HEAD"}},
-    {cowboy, "1.0.3", {git, "https://github.com/K2InformaticsGmbH/cowboy", {tag, "1.0.3"}}}
+    {esaml, "4.0.0"},
+    {cowboy, "2.6.0"}
 ]}.

examples/sp/src/sp.app.src

@@ -1,7 +1,7 @@
 {application, sp,
  [
-  {description, "SAML for erlang"},
-  {vsn, "1"},
+  {description, "SAML SP for erlang"},
+  {vsn, "2"},
   {registered, []},
   {included_applications, [
   ]},

examples/sp/src/sp_app.erl

@@ -14,14 +14,14 @@
 -export([stop/1]).
 
 start(_Type, _Args) ->
+    HostMatch = '_',
+    PathMatch = "/saml/:operation",
+    InitialState = #{},
     Dispatch = cowboy_router:compile([
-        {'_', [
-            {"/saml/:operation", sp_handler, []}
-        ]}
-    ]),
-    {ok, _} = cowboy:start_http(http, 100, [{port, 8080}], [
-        {env, [{dispatch, Dispatch}]}
+        {HostMatch, [{PathMatch, sp_handler, InitialState}]}
     ]),
+    {ok, _} = cowboy:start_clear(sp_http_listener, [{port, 8080}],
+        #{env => #{dispatch => Dispatch}}),
     sp_sup:start_link().
 
 stop(_State) ->

examples/sp/src/sp_handler.erl

@@ -9,10 +9,17 @@
 -module(sp_handler).
 -include_lib("esaml/include/esaml.hrl").
 
--record(state, {sp, idp}).
--export([init/3, handle/2, terminate/3]).
+-export([init/2, terminate/3]).
 
-init(_Transport, Req, _Args) ->
+init(Req, State = #{initialized := true}) ->
+    Operation = cowboy_req:binding(operation, Req),
+    Method = cowboy_req:method(Req),
+    io:format("[Method] ~p~n", [Method]),
+    io:format("[Operation] ~p~n", [Operation]),
+    io:format("[State] ~p~n", [State]),
+    handle(Method, Operation, Req, State);
+
+init(Req, State) ->
     % Load the certificate and private key for the SP
     PrivKey = esaml_util:load_private_key("priv/test.key"),
     Cert = esaml_util:load_certificate("priv/test.crt"),
@@ -41,44 +48,40 @@ init(_Transport, Req, _Args) ->
     % (this call will cache after the first time around, so it will be fast)
     IdpMeta = esaml_util:load_metadata("https://some.idp.com/idp/saml2/idp/metadata.php"),
 
-    {ok, Req, #state{sp = SP, idp = IdpMeta}}.
-
-handle(Req, S = #state{}) ->
-    {Operation, Req2} = cowboy_req:binding(operation, Req),
-    {Method, Req3} = cowboy_req:method(Req2),
-    handle(Method, Operation, Req3, S).
+    State1 = State#{sp => SP, idp => IdpMeta, initialized => true},
+    init(Req, State1).
 
 % Return our SP metadata as signed XML
-handle(<<"GET">>, <<"metadata">>, Req, S = #state{sp = SP}) ->
-    {ok, Req2} = esaml_cowboy:reply_with_metadata(SP, Req),
-    {ok, Req2, S};
+handle(<<"GET">>, <<"metadata">>, Req, State = #{sp := SP}) ->
+    Req2 = esaml_cowboy:reply_with_metadata(SP, Req),
+    {ok, Req2, State};
 
 % Visit /saml/auth to start the authentication process -- we will make an AuthnRequest
 % and send it to our IDP
-handle(<<"GET">>, <<"auth">>, Req, S = #state{sp = SP,
-        idp = #esaml_idp_metadata{login_location = IDP}}) ->
-    {ok, Req2} = esaml_cowboy:reply_with_authnreq(SP, IDP, <<"foo">>, Req),
-    {ok, Req2, S};
+handle(<<"GET">>, <<"auth">>, Req, State = #{sp := SP,
+        idp := #esaml_idp_metadata{login_location = IDP}}) ->
+    Req2 = esaml_cowboy:reply_with_authnreq(SP, IDP, <<"foo">>, Req),
+    {ok, Req2, State};
 
 % Handles HTTP-POST bound assertions coming back from the IDP.
-handle(<<"POST">>, <<"consume">>, Req, S = #state{sp = SP}) ->
+handle(<<"POST">>, <<"consume">>, Req, State = #{sp := SP}) ->
     case esaml_cowboy:validate_assertion(SP, fun esaml_util:check_dupe_ets/2, Req) of
         {ok, Assertion, RelayState, Req2} ->
             Attrs = Assertion#esaml_assertion.attributes,
             Uid = proplists:get_value(uid, Attrs),
             Output = io_lib:format("<html><head><title>SAML SP demo</title></head><body><h1>Hi there!</h1><p>This is the <code>esaml_sp_default</code> demo SP callback module from eSAML.</p><table><tr><td>Your name:</td><td>\n~p\n</td></tr><tr><td>Your UID:</td><td>\n~p\n</td></tr></table><hr /><p>RelayState:</p><pre>\n~p\n</pre><p>The assertion I got was:</p><pre>\n~p\n</pre></body></html>", [Assertion#esaml_assertion.subject#esaml_subject.name, Uid, RelayState, Assertion]),
-            {ok, Req3} = cowboy_req:reply(200, [{<<"Content-Type">>, <<"text/html">>}], Output, Req2),
-            {ok, Req3, S};
+            Req3 = cowboy_req:reply(200, #{<<"Content-Type">> => <<"text/html">>}, Output, Req2),
+            {ok, Req3, State};
 
         {error, Reason, Req2} ->
-            {ok, Req3} = cowboy_req:reply(403, [{<<"content-type">>, <<"text/plain">>}],
+            Req3 = cowboy_req:reply(403, #{<<"content-type">> => <<"text/plain">>},
                 ["Access denied, assertion failed validation:\n", io_lib:format("~p\n", [Reason])],
                 Req2),
-            {ok, Req3, S}
+            {ok, Req3, State}
     end;
 
-handle(_, _, Req, S = #state{}) ->
-    {ok, Req2} = cowboy_req:reply(404, [], <<"Not found">>, Req),
-    {ok, Req2, S}.
+handle(_, _, Req, State = #{}) ->
+    Req2 = cowboy_req:reply(404, #{}, <<"Not found">>, Req),
+    {ok, Req2, State}.
 
 terminate(_Reason, _Req, _State) -> ok.

examples/sp/start.sh

@@ -1,36 +1,38 @@
 #!/bin/bash
 
-unamestr=`uname`
-host=127.0.0.1
-name=sp@$host
-if [[ "$unamestr" == 'Linux' || "$unamestr" == 'Darwin' ]]; then
-     exename=erl
+HOST="${host:=127.0.0.1}"
+APP_NAME="esaml_example_sp"
+COOKIE="${APP_NAME}"
+NODE_NAME="${APP_NAME}@${HOST}"
+UNAME_STR=`uname`
+if [[ "${UNAME_STR}" == 'Linux' || "${UNAME_STR}" == 'Darwin' ]]; then
+    EXE_NAME=erl
 else
-    exename='start //MAX werl.exe'
+    EXE_NAME='start //MAX werl.exe'
     #exename='erl.exe'
 fi
 
 # Node name
-node_name="-name $name"
+NODE_NAME_OPT="-name ${NODE_NAME}"
 
 # Cookie
-cookie="-setcookie $ck"
+COOKIE_OPT="-setcookie ${COOKIE}"
 
 # PATHS
-paths="-pa"
-paths=$paths" ebin"
-paths=$paths" deps/*/ebin"
+PATHS_OPT="-pa"
+PATHS_OPT="${PATHS_OPT} _build/default/lib/*/ebin"
+PATHS_OPT="${PATHS_OPT} _checkouts/*/ebin"
 
-start_opts="$paths $cookie $node_name"
+START_OPTS="${PATHS_OPT} ${COOKIE_OPT} ${NODE_NAME_OPT}"
 
 # DDERL start options
 echo "------------------------------------------"
-echo "Starting ESaml (SP)"
+echo "Starting ESaml Example (SP)"
 echo "------------------------------------------"
-echo "Node Name : $node_name"
-echo "Cookie    : $cookie"
-echo "EBIN Path : $paths"
+echo "Node Name : ${NODE_NAME}"
+echo "Cookie    : ${COOKIE}"
+echo "EBIN Path : ${PATHS_OPT}"
 echo "------------------------------------------"
 
 # Starting dderl
-$exename $start_opts -eval "application:ensure_all_started(sp)."
+${EXE_NAME} ${START_OPTS} -eval "application:ensure_all_started(sp)."

examples/sp_with_logout/.gitignore

@@ -0,0 +1 @@
+_checkouts

examples/sp_with_logout/priv/test.crt

@@ -0,0 +1,19 @@
+-----BEGIN CERTIFICATE-----
+MIIC/TCCAeWgAwIBAgIJAOrjLRGkHGpYMA0GCSqGSIb3DQEBBQUAMBQxEjAQBgNV
+BAMMCWxvY2FsaG9zdDAgFw0xNjA0MjYwNzU4MDVaGA8yMTE2MDQwMjA3NTgwNVow
+FDESMBAGA1UEAwwJbG9jYWxob3N0MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB
+CgKCAQEAzxk42NUZyenAl3JComTM03Z/MOzO8os5BZDjSOcK9JGSpCUzlFU/hGxG
+ZNCuykrX6QhCcBAdu9cM/BT+AO3QCoXyEKQHdMpu+EisAhTBJFu0mTOeeoATLJEa
+CrUL7Wgf/8UB2HQd+43S0HQnGDqSHBE5oHmzJmiTQ0pd1VWTvCOx/VYvBjkrnzfe
+0C8DZMiZ6cNDMcnS/M10YvuD9/PZ0w9202mImfB2lVPYaMPYd3qjU++nuwpYHQUz
+MO8enJOVgMtRvV6xTlAV2Cu2yAXQjJWZw8ZA7AarF2GrjGicGcGCvnm8FTpHEqL7
+Wii0FzT6fOMPZmRw00sErWhQ5PxrgQIDAQABo1AwTjAdBgNVHQ4EFgQUTzIbssmF
+/pGgV7+D1A7kf+6Wn7swHwYDVR0jBBgwFoAUTzIbssmF/pGgV7+D1A7kf+6Wn7sw
+DAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQUFAAOCAQEAzZy2R85R1pJ6dwgt12Yo
+3iaXuH2D5jIzhFDDIdeUakrMOMKUq4At8OFToNl/F2WtZiBDyoCX4t+UVzybJl1A
+8CRsw0lz/ayF6UjAbFlLxESFKRa6tgkhrcBc9gFq/tO8bLRGT+ZKGoysFMu2lgtS
+LjZbr1lknxql7yXRjtAd5Tcz6GYGfOHJeVXkJMtueZUgmWkKUc6h7C6SP0scfLMG
+a4ucPXkQWi/QyF8Bziq1owR0aRMQyBO97Ua9eARYKCqReUP1WRMM4KJ0DKW0du/v
+l7f7o63DOOIp5cO5OnGUCsRfnGk7/NgvPpe0k1wE/alJTx9vfQfk2MLXWrhfO7ZJ
+rA==
+-----END CERTIFICATE-----