lyrebird 0.0.0 → 1.0.0.alpha2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9634bd5e47288132993ae694000573ebe7a74035a43628f74053a68eb26ea785
-  data.tar.gz: 0d733419004764bdf5b5d60cd2ed55fd6b7d4c7531c5fc37725e5c13a6e5eae9
+  metadata.gz: b18c9229d638025f9882d18957a043c890e128ae5cbf9541d97f0cce078ce8e1
+  data.tar.gz: 28ce7ba82169a7fa5b1ac90299eb09af37781adefc74522a6ee43e16f822f740
 SHA512:
-  metadata.gz: 6053439212105edd8ab7b977c42d38a95678ed2f692f6fa19048b0e3dc3b8f822e0896e3a557fc59b3248d0040c71bc766252e2dcfe388b604a0feb0e953a8ad
-  data.tar.gz: 75421cfad59640abbbe5f73729dca6df1dc14b400066cc6e281e0cd6432c8c94fe42cdc647adb25adccf4ffc232a240f6c069d27c6be7bc5008205d6675a8a24
+  metadata.gz: 7edb0e358a6f295f80731bcf2d6544d55843b69c69bd25fcfbffc9a750240af558dfad598ba2939e6b9fa96033b17a7e827715908e08f3005ece03284c75f9a2
+  data.tar.gz: c7ba17cac0ffe23dcc264c52c6b8c6ce8fc44900bc0a302866e9c9aee2f874fd6f12ae5feda573c2d864047aac56a6bb5d67a000f570b018be54062b1e0acaab

data/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ["3.2", "3.3", "3.4", "4.0"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Ruby ${{ matrix.ruby-version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+      - name: Run tests
+        run: bundle exec rake test

data/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.2"
+      - name: Build gem
+        run: gem build lyrebird.gemspec
+      - name: Publish to RubyGems
+        run: gem push lyrebird-*.gem
+        env:
+          GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}

data/README.md

@@ -1,35 +1,166 @@
 # Lyrebird
+A Ruby gem for mimicking SAML Identity Provider (IdP) responses in test
+environments.
 
-TODO: Delete this and the text below, and describe your gem
+## Installation
+```ruby
+gem "lyrebird", group: :test
+```
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/lyrebird`. To experiment with that code, run `bin/console` for an interactive prompt.
+## Basic example
+```ruby
+# test/integration/saml_test.rb
+class SAMLTest < ActionDispatch::IntegrationTest
+  test "consume creates a session" do
+    user = users(:alice)
 
-## Installation
+    response = Lyrebird::Response.build do |r|
+      r.issuer = "https://idp.example.com"
+      r.destination = saml_consume_url
+      r.recipient = saml_consume_url
+      r.audience = root_url
+      r.name_id = user.email
+
+      r.attributes do |a|
+        a.email = user.email
+        a.first_name = user.first_name
+        a.last_name = user.last_name
+      end
+    end
+
+    post saml_consume_path, params: { SAMLResponse: response.mimic }
+
+    assert_redirected_to dashboard_path
+    assert_equal user.id, session[:user_id]
+  end
+end
+```
+
+## Response
+Builds complete SAML responses with embedded assertions.
+
+### Building a response
+Defaults produce an SP-initiated response. See
+[IdP-initiated SSO](#idp-initiated-sso) to omit `InResponseTo` and
+`Destination`.
+```ruby
+# With defaults (SP-initiated)
+response = Lyrebird::Response.build
+
+# With options
+response = Lyrebird::Response.build do |r|
+  r.issuer = "https://idp.example.com"
+  r.destination = "https://sp.example.com/acs"
+  r.in_response_to = "_request_id"
+  r.name_id = "user@example.com"
+  r.name_id_format = Lyrebird::NAMEID_EMAIL
+  r.recipient = "https://sp.example.com/acs"
+  r.audience = "https://sp.example.com"
+  r.authn_context = "urn:oasis:names:tc:SAML:2.0:ac:classes:Password"
+  r.not_before = Time.now.utc
+  r.valid_for = 300 # seconds
+  r.sign_with = idp_cert
+  r.encrypt_with = sp_cert
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+  r.attributes do |a|
+    a.email = "user@example.com"
+    a.groups = ["admin", "users"]
+  end
+end
+```
 
-Install the gem and add to the application's Gemfile by executing:
+### IdP-initiated SSO
+For unsolicited (IdP-initiated) flows where there is no AuthnRequest,
+set `in_response_to` and `destination` to `nil` to omit them from the
+XML entirely:
+```ruby
+response = Lyrebird::Response.build do |r|
+  r.in_response_to = nil
+  r.destination = nil
+  r.name_id = "user@example.com"
+end
+```
 
-```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+### Getting the encoded response
+```ruby
+response.mimic    # Base64-encoded SAML response (for POST binding)
+response.document # REXML::Document for inspection
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+### Signing
+Sign both the assertion and response with an IdP certificate:
+```ruby
+idp_cert = Lyrebird::Certificate.generate
+response = Lyrebird::Response.build(sign_with: idp_cert)
+```
+
+### Encryption
+Encrypt assertions using the SP's certificate so only the SP can decrypt them:
+```ruby
+sp_cert = Lyrebird::Certificate.generate  # In practice, provided by the SP
+response = Lyrebird::Response.build(encrypt_with: sp_cert)
+```
 
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+Signing and encryption can be combined:
+```ruby
+response = Lyrebird::Response.build do |r|
+  r.sign_with = idp_cert
+  r.encrypt_with = sp_cert
+end
 ```
 
-## Usage
+### NameID Formats
+```ruby
+Lyrebird::NAMEID_EMAIL       # emailAddress (default)
+Lyrebird::NAMEID_PERSISTENT  # persistent
+Lyrebird::NAMEID_TRANSIENT   # transient
+Lyrebird::NAMEID_UNSPECIFIED # unspecified
+```
 
-TODO: Write usage instructions here
+## Configuring defaults
+Override defaults globally for all responses/assertions:
+```ruby
+# test/test_helper.rb
+Lyrebird::DEFAULTS.issuer = "https://custom.example.com"
+Lyrebird::DEFAULTS.recipient = "https://custom.example.com/acs"
+Lyrebird::DEFAULTS.audience = "https://custom.example.com"
+Lyrebird::DEFAULTS.name_id = "default@example.com"
+Lyrebird::DEFAULTS.valid_for = 600 # 10 minutes
+Lyrebird::DEFAULTS.attributes = { role: "user" }
+```
 
-## Development
+## Certificate
+Generates and manages X.509 certificates for signing SAML responses.
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+### Generating a new certificate
+```ruby
+# With defaults
+cert = Lyrebird::Certificate.generate
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+# With options
+cert = Lyrebird::Certificate.generate(
+  bits: 4096,                         # RSA key size (default: 2048)
+  cn: "example.com",                  # Common Name
+  o: "Acme",                          # Organization
+  valid_for: 30,                      # Validity in days (default: 365)
+  valid_until: Time.new(2999, 12, 31) # Specific expiration (overrides valid_for)
+)
+```
 
-## Contributing
+### Loading an existing certificate
+```ruby
+cert = Lyrebird::Certificate.load(
+  private_key_pem: File.read("private_key.pem"),
+  certificate_pem: File.read("certificate.pem")
+)
+```
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/lyrebird.
+### Exporting
+```ruby
+cert.private_key     # OpenSSL::PKey::RSA object
+cert.certificate     # OpenSSL::X509::Certificate object
+cert.private_key_pem # PEM-encoded private key
+cert.certificate_pem # PEM-encoded certificate
+cert.base64          # Base64-encoded certificate (for SAML metadata)
+cert.fingerprint     # SHA256 fingerprint
+```

data/Rakefile

@@ -1,4 +1,11 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-task default: %i[]
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs.push("test")
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/lib/lyrebird/assertion.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Lyrebird
+  class Assertion
+    def initialize(
+      issuer: DEFAULTS.issuer,
+      name_id: DEFAULTS.name_id,
+      name_id_format: DEFAULTS.name_id_format,
+      recipient: DEFAULTS.recipient,
+      in_response_to: DEFAULTS.in_response_to,
+      not_before: nil,
+      valid_for: DEFAULTS.valid_for,
+      audience: DEFAULTS.audience,
+      authn_context: DEFAULTS.authn_context,
+      attributes: DEFAULTS.attributes
+    )
+      @issue_instant = Time.now.utc
+      @issuer = issuer
+      @name_id = name_id
+      @name_id_format = name_id_format
+      @recipient = recipient
+      @in_response_to = in_response_to
+      @not_before = not_before || @issue_instant
+      @not_on_or_after = @issue_instant + valid_for
+      @audience = audience
+      @authn_context = authn_context
+      @attributes = attributes
+    end
+
+    def document
+      REXML::Document.new.tap do |d|
+        d.add_element(root)
+      end
+    end
+
+    private
+
+    def root
+      REXML::Element.new("saml:Assertion").tap do |r|
+        r.add_namespace("saml", SAML_ASSERTION_NS)
+        r.add_attribute("ID", ID.generate)
+        r.add_attribute("Version", "2.0")
+        r.add_attribute("IssueInstant", @issue_instant.iso8601)
+        r.add_element("saml:Issuer").text = @issuer
+        r.add_element(subject)
+        r.add_element(conditions)
+        r.add_element(authn_statement)
+        r.add_element(attribute_statement) if @attributes.any?
+      end
+    end
+
+    def subject
+      REXML::Element.new("saml:Subject").tap do |s|
+        name_id = s.add_element("saml:NameID")
+        name_id.add_attribute("Format", @name_id_format)
+        name_id.text = @name_id
+        s.add_element(subject_confirmation)
+      end
+    end
+
+    def subject_confirmation
+      REXML::Element.new("saml:SubjectConfirmation").tap do |sc|
+        sc.add_attribute("Method", CM_BEARER)
+        data = sc.add_element("saml:SubjectConfirmationData")
+        data.add_attribute("NotOnOrAfter", @not_on_or_after.iso8601)
+        data.add_attribute("Recipient", @recipient)
+        data.add_attribute("InResponseTo", @in_response_to) if @in_response_to
+      end
+    end
+
+    def conditions
+      REXML::Element.new("saml:Conditions").tap do |c|
+        c.add_attribute("NotBefore", @not_before.iso8601)
+        c.add_attribute("NotOnOrAfter", @not_on_or_after.iso8601)
+        ar = c.add_element("saml:AudienceRestriction")
+        ar.add_element("saml:Audience").text = @audience
+      end
+    end
+
+    def authn_statement
+      REXML::Element.new("saml:AuthnStatement").tap do |as|
+        as.add_attribute("AuthnInstant", @issue_instant.iso8601)
+        as.add_attribute("SessionIndex", ID.generate)
+        ac = as.add_element("saml:AuthnContext")
+        cr = ac.add_element("saml:AuthnContextClassRef")
+        cr.text = @authn_context
+      end
+    end
+
+    def attribute_statement
+      REXML::Element.new("saml:AttributeStatement").tap do |as|
+        @attributes.each do |name, values|
+          a = as.add_element("saml:Attribute")
+          a.add_attribute("Name", name)
+          a.add_attribute("NameFormat", ATTR_NAME_FORMAT)
+
+          Array(values).each do |value|
+            a.add_element("saml:AttributeValue").text = value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lyrebird/certificate.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Lyrebird
+  class Certificate
+    attr_reader :private_key, :certificate
+
+    def self.generate(bits: 2048, **options)
+      new(OpenSSL::PKey::RSA.new(bits), **options)
+    end
+
+    def self.load(private_key_pem:, certificate_pem:)
+      private_key = OpenSSL::PKey::RSA.new(private_key_pem)
+      certificate = OpenSSL::X509::Certificate.new(certificate_pem)
+      new(private_key, certificate: certificate)
+    end
+
+    def initialize(
+      private_key,
+      cn: nil,
+      o: nil,
+      valid_for: 365,
+      valid_until: nil,
+      certificate: nil
+    )
+      @private_key = private_key
+      @common_name = cn
+      @organization = o
+      @valid_for = valid_for
+      @valid_until = valid_until
+      @certificate = certificate || build_certificate
+    end
+
+    def private_key_pem
+      @private_key.to_pem
+    end
+
+    def certificate_pem
+      @certificate.to_pem
+    end
+
+    def fingerprint
+      OpenSSL::Digest::SHA256.hexdigest(@certificate.to_der)
+    end
+
+    def base64
+      Base64.strict_encode64(@certificate.to_der)
+    end
+
+    private
+
+    def build_certificate
+      now = Time.now
+
+      OpenSSL::X509::Certificate.new.tap do |c|
+        c.public_key = @private_key.public_key
+        c.subject = build_subject
+        c.issuer = c.subject
+        c.not_before = now
+        c.not_after = @valid_until || now + (@valid_for * 86_400)
+        c.sign(@private_key, OpenSSL::Digest::SHA256.new)
+      end
+    end
+
+    def build_subject
+      OpenSSL::X509::Name.new.tap do |name|
+        name.add_entry("CN", @common_name) if @common_name
+        name.add_entry("O", @organization) if @organization
+      end
+    end
+  end
+end

data/lib/lyrebird/defaults.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Lyrebird
+  NAMEID_EMAIL = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
+  NAMEID_PERSISTENT = "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
+  NAMEID_TRANSIENT = "urn:oasis:names:tc:SAML:2.0:nameid-format:transient"
+  NAMEID_UNSPECIFIED = "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
+
+  class Defaults
+    attr_accessor :issuer
+    attr_accessor :name_id
+    attr_accessor :name_id_format
+    attr_accessor :recipient
+    attr_accessor :in_response_to
+    attr_accessor :valid_for
+    attr_accessor :audience
+    attr_accessor :authn_context
+    attr_accessor :attributes
+
+    def initialize
+      @issuer = "https://idp.example.com"
+      @name_id = "user@example.com"
+      @name_id_format = NAMEID_EMAIL
+      @recipient = "https://sp.example.com/acs"
+      @in_response_to = "_request_id"
+      @valid_for = 300 # 5 minutes
+      @audience = "https://sp.example.com"
+
+      @authn_context =
+        "urn:oasis:names:tc:SAML:2.0:ac:classes:" \
+        "PasswordProtectedTransport"
+
+      @attributes = {
+        first_name: "Test",
+        last_name: "User",
+      }
+    end
+  end
+
+  DEFAULTS = Defaults.new
+end

data/lib/lyrebird/encryption.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Lyrebird
+  class Encryption
+    def initialize(element, certificate)
+      @element = element
+      @certificate = certificate
+      @aes_key = SecureRandom.random_bytes(32)
+    end
+
+    def encrypt
+      encrypted_assertion
+    end
+
+    private
+
+    def encrypted_assertion
+      REXML::Element.new("saml:EncryptedAssertion").tap do |ea|
+        ea.add_namespace("saml", SAML_ASSERTION_NS)
+        ea.add_element(encrypted_data)
+      end
+    end
+
+    def encrypted_data
+      REXML::Element.new("xenc:EncryptedData").tap do |ed|
+        ed.add_namespace("xenc", XMLENC_NS)
+        ed.add_attribute("Type", "#{XMLENC_NS}Element")
+        em = ed.add_element("xenc:EncryptionMethod")
+        em.add_attribute("Algorithm", AES256_CBC)
+        ed.add_element(key_info)
+        ed.add_element(cipher_data)
+      end
+    end
+
+    def key_info
+      REXML::Element.new("ds:KeyInfo").tap do |ki|
+        ki.add_namespace("ds", XMLDSIG_NS)
+        ki.add_element(encrypted_key)
+      end
+    end
+
+    def encrypted_key
+      REXML::Element.new("xenc:EncryptedKey").tap do |ek|
+        ek.add_namespace("xenc", XMLENC_NS)
+        em = ek.add_element("xenc:EncryptionMethod")
+        em.add_attribute("Algorithm", RSA_OAEP)
+        ek.add_element(encrypted_key_cipher_data)
+      end
+    end
+
+    def encrypted_key_cipher_data
+      public_key = @certificate.certificate.public_key
+      padding = OpenSSL::PKey::RSA::PKCS1_OAEP_PADDING
+      encrypted_aes_key = public_key.public_encrypt(@aes_key, padding)
+
+      REXML::Element.new("xenc:CipherData").tap do |cd|
+        cv = Base64.strict_encode64(encrypted_aes_key)
+        cd.add_element("xenc:CipherValue").text = cv
+      end
+    end
+
+    def cipher_data
+      cipher = OpenSSL::Cipher.new("AES-256-CBC")
+      cipher.encrypt
+      cipher.key = @aes_key
+      iv = cipher.random_iv
+      ciphertext = cipher.update(@element.to_s) + cipher.final
+
+      REXML::Element.new("xenc:CipherData").tap do |cd|
+        cv = Base64.strict_encode64(iv + ciphertext)
+        cd.add_element("xenc:CipherValue").text = cv
+      end
+    end
+  end
+end

data/lib/lyrebird/id.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Lyrebird
+  module ID
+    def self.generate
+      "_#{SecureRandom.uuid}"
+    end
+  end
+end

data/lib/lyrebird/namespaces.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Lyrebird
+  SAML_ASSERTION_NS = "urn:oasis:names:tc:SAML:2.0:assertion"
+  SAML_PROTOCOL_NS = "urn:oasis:names:tc:SAML:2.0:protocol"
+  XMLDSIG_NS = "http://www.w3.org/2000/09/xmldsig#"
+  ENVELOPED_SIG = "http://www.w3.org/2000/09/xmldsig#enveloped-signature"
+  EXC_C14N = "http://www.w3.org/2001/10/xml-exc-c14n#"
+  SHA256_DIGEST = "http://www.w3.org/2001/04/xmlenc#sha256"
+  RSA_SHA256 = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
+  CM_BEARER = "urn:oasis:names:tc:SAML:2.0:cm:bearer"
+  ATTR_NAME_FORMAT = "urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"
+  STATUS_SUCCESS = "urn:oasis:names:tc:SAML:2.0:status:Success"
+  XMLENC_NS = "http://www.w3.org/2001/04/xmlenc#"
+  AES256_CBC = "http://www.w3.org/2001/04/xmlenc#aes256-cbc"
+  RSA_OAEP = "http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p"
+end

data/lib/lyrebird/response.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Lyrebird
+  class Response
+    def self.build(**kwargs)
+      config = OpenStruct.new(kwargs)
+
+      config.define_singleton_method(:attributes) do |&block|
+        self.attributes = OpenStruct.new.tap(&block).to_h
+      end
+
+      yield config if block_given?
+      new(**config.to_h)
+    end
+
+    def initialize(
+      issuer: DEFAULTS.issuer,
+      destination: DEFAULTS.recipient,
+      in_response_to: DEFAULTS.in_response_to,
+      sign_with: nil,
+      encrypt_with: nil,
+      **assertion_options
+    )
+      @issuer = issuer
+      @destination = destination
+      @in_response_to = in_response_to
+      @sign_with = sign_with
+      @encrypt_with = encrypt_with
+
+      @assertion = Assertion.new(
+        issuer: issuer,
+        in_response_to: in_response_to,
+        **assertion_options
+      )
+    end
+
+    def mimic
+      Base64.strict_encode64(document.to_s)
+    end
+
+    def document
+      REXML::Document.new.tap do |d|
+        d.add_element(root)
+      end
+    end
+
+    private
+
+    def root
+      REXML::Element.new("samlp:Response").tap do |r|
+        r.add_namespace("samlp", SAML_PROTOCOL_NS)
+        r.add_namespace("saml", SAML_ASSERTION_NS)
+        r.add_attribute("ID", ID.generate)
+        r.add_attribute("Version", "2.0")
+        r.add_attribute("IssueInstant", Time.now.utc.iso8601)
+        r.add_attribute("Destination", @destination) if @destination
+        r.add_attribute("InResponseTo", @in_response_to) if @in_response_to
+        r.add_element("saml:Issuer").text = @issuer
+        r.add_element(status)
+        r.add_element(assertion_element)
+        Signature.new(r, @sign_with).sign! if @sign_with
+      end
+    end
+
+    def assertion_element
+      element = @assertion.document.root
+      Signature.new(element, @sign_with).sign! if @sign_with
+      return element unless @encrypt_with
+      Encryption.new(element, @encrypt_with).encrypt
+    end
+
+    def status
+      REXML::Element.new("samlp:Status").tap do |s|
+        sc = s.add_element("samlp:StatusCode")
+        sc.add_attribute("Value", STATUS_SUCCESS)
+      end
+    end
+  end
+end