Migrate Samly v0.7.x to v0.8.0

Migrating from Samly v0.7.x to v0.8.0

Samly v0.8.0 adds support for multiple IdPs. The IdPs used in Samly must now be assigned an id in the config. This idp-id must be present in the endpoint URLs either as URL path segment at the end of the URL or as the subdomain in the DNS hostname in the URL.

• Update dependency version in mix.exs
  • {:samly, "~> 0.8"} when this becomes available on hex.pm
• Switch to the updated config parameters:

config :samly, Samly.Provider,
  idp_id_from: :path_segment,
  service_providers: [
    %{
      id: "sp1",
      #entity_id: "urn:samly.howto:12345",
      certfile: "samly.crt",
      keyfile: "samly.pem",
      contact_name: "Samly Howto SP1 Admin",
      contact_email: "[email protected]",
      org_name: "Samly Howto SP1",
      org_displayname: "Samly Howto SP1 Displayname",
      org_url: "http://samly.howto:4003"
    }
  ],
  identity_providers: [
    %{
      id: "idp1",
      sp_id: "sp1",
      base_url: "http://samly.howto:4003/sso",
      metadata_file: "idp_metadata.xml",
      #pre_session_create_pipeline: SamlyHowtoWeb.Plugs.SamlyPipeline,
      #use_redirect_for_req: true,
      #sign_requests: true,
      #sign_metadata: true,
      #signed_assertion_in_resp: true,
      #signed_envelopes_in_resp: true
    }
  ]

The SAML endpoints will be defined as <base-url>/sp/consume/<idp-id>, <base-url>/sp/logout/<idp-id>, etc.

The sign-in and sign-out links/buttons in the application web UI should use the respective URIs: /sso/auth/signin/<idp-id> and /sso/auth/signout/<idp-id>.

It is possible to use subdomain in the DNS hostname to represent the idp-id. Make sure the subdomain in DNS is used as the id in the identity provider definition. Here is the example config for that:

config :samly, Samly.Provider,
  idp_id_from: :subdomain,
  service_providers: [
    %{
      id: "sp1",
      #entity_id: "urn:samly.howto:12345",
      certfile: "samly.crt",
      keyfile: "samly.pem",
      contact_name: "Samly Howto SP1 Admin",
      contact_email: "[email protected]",
      org_name: "Samly Howto SP1",
      org_displayname: "Samly Howto SP1 Displayname",
      org_url: "http://samly.howto:4003"
    }
  ],
  identity_providers: [
    %{
      id: "idp1",
      sp_id: "sp1",
      base_url: "http://idp1.samly.howto:4003/sso",
      metadata_file: "idp_metadata.xml",
      #pre_session_create_pipeline: SamlyHowtoWeb.Plugs.SamlyPipeline,
      #use_redirect_for_req: true,
      #sign_requests: true,
      #sign_metadata: true,
      #signed_assertion_in_resp: true,
      #signed_envelopes_in_resp: true
    }
  ]

Notice the change in idp_id_from and base_url.

The SAML endpoints in the subdomain model will be defined as <base-url>/sp/consume, <base-url>/sp/logout, etc.

The sign-in and sign-out links/buttons in the application web UI should use the respective URIs: /sso/auth/signin and /sso/auth/signout.

• Update signin/signout URI in your application UI.

idp_id_from: :path_segment	idp_id_from: :subdomain
/sso/auth/signin/<idp-id>	/sso/auth/signin
/sso/auth/signout/<idp-id>	/sso/auth/signout
/sso/sp/metadata/<idp-id>	/sso/sp/metadata

• If entity_id is not defined, Samly will use the metadata URL as the entity id (<base-url>/sso/sp/metadata/<idp-id> or <base-url>/sso/sp/metadata)

• Update the SP SAML endpoint URL (with or without the idp-id) in the service provider registration in IdP

• The signed-in user assertion attributes, custom attributes etc are now binary keys instead of atoms. So, instead of calling Samly.get_attribute(assertion, :uid) use Samly.get_attribute(assertion, "uid")

• If samly_simplesaml repo is used as the development Identity Provider, make sure to use tag v0.2 and above. Run build.sh in that repo to build the Docker image first, update the setup/params/params.yml with appropriate information and start/restart docker-compose.