identizer 0.1.0

data/lib/identizer/saml/signer.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Identizer
+  module Saml
+    # Enveloped XML-DSig signing (exclusive C14N, RSA-SHA256, SHA-256 digest) of a
+    # SAML element. The Signature is inserted right after the element's Issuer, as
+    # the SAML schema requires. Validated against ruby-saml in the specs.
+    class Signer
+      DS = "http://www.w3.org/2000/09/xmldsig#"
+      EXC_C14N = "http://www.w3.org/2001/10/xml-exc-c14n#"
+      ENVELOPED = "http://www.w3.org/2000/09/xmldsig#enveloped-signature"
+      SHA256 = "http://www.w3.org/2001/04/xmlenc#sha256"
+      RSA_SHA256 = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
+
+      def initialize(keypair)
+        @keypair = keypair
+      end
+
+      # Signs `element` (a Nokogiri node with an "ID" attribute) in place.
+      def sign!(element)
+        reference_id = element["ID"]
+        # Digest is over the element BEFORE the signature exists (enveloped transform).
+        digest_value = base64(OpenSSL::Digest::SHA256.digest(canonicalize(element)))
+
+        signature = build_signature(element.document, reference_id, digest_value)
+        insert_signature(element, signature)
+
+        # Canonicalize SignedInfo in its FINAL document context, then sign it — the
+        # namespace context must match what the verifier sees.
+        signed_info = signature.at_xpath("./ds:SignedInfo", "ds" => DS)
+        signature_value = base64(@keypair.key.sign(OpenSSL::Digest.new("SHA256"), canonicalize(signed_info)))
+        signature.at_xpath("./ds:SignatureValue", "ds" => DS).content = signature_value
+
+        element
+      end
+
+      private
+
+      def canonicalize(node)
+        node.canonicalize(Nokogiri::XML::XML_C14N_EXCLUSIVE_1_0)
+      end
+
+      def base64(bytes)
+        Base64.strict_encode64(bytes)
+      end
+
+      def insert_signature(element, signature)
+        issuer = element.at_xpath("./*[local-name()='Issuer']")
+        issuer ? issuer.after(signature) : element.prepend_child(signature)
+      end
+
+      def build_signature(document, reference_id, digest_value)
+        node = Nokogiri::XML::Node.new("Signature", document)
+        node.default_namespace = DS
+        node.add_child(signed_info_xml(document, reference_id, digest_value))
+        node.add_child(node_with(document, "SignatureValue", ""))
+        node.add_child(key_info_xml(document))
+        node
+      end
+
+      # Built as compact single-line fragments: any inter-tag whitespace would
+      # become text nodes inside the canonicalized SignedInfo and break the digest.
+      def signed_info_xml(document, reference_id, digest_value)
+        fragment = [
+          %(<SignedInfo xmlns="#{DS}">),
+          %(<CanonicalizationMethod Algorithm="#{EXC_C14N}"/>),
+          %(<SignatureMethod Algorithm="#{RSA_SHA256}"/>),
+          %(<Reference URI="##{reference_id}"><Transforms>),
+          %(<Transform Algorithm="#{ENVELOPED}"/>),
+          %(<Transform Algorithm="#{EXC_C14N}"/></Transforms>),
+          %(<DigestMethod Algorithm="#{SHA256}"/>),
+          %(<DigestValue>#{digest_value}</DigestValue></Reference></SignedInfo>)
+        ].join
+        document.parse(fragment).first
+      end
+
+      def key_info_xml(document)
+        fragment = [
+          %(<KeyInfo xmlns="#{DS}"><X509Data>),
+          %(<X509Certificate>#{@keypair.certificate_base64}</X509Certificate>),
+          %(</X509Data></KeyInfo>)
+        ].join
+        document.parse(fragment).first
+      end
+
+      def node_with(document, name, content)
+        node = Nokogiri::XML::Node.new(name, document)
+        node.default_namespace = DS
+        node.content = content
+        node
+      end
+    end
+  end
+end

data/lib/identizer/saml.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Optional real SAML IdP support (signed assertions). Required on demand so the
+# nokogiri dependency is only loaded when SAML signing is actually used.
+require "nokogiri"
+require "securerandom"
+
+module Identizer
+  # A minimal SAML 2.0 identity provider: signed Response/Assertion building.
+  module Saml
+  end
+end
+
+require_relative "saml/keypair"
+require_relative "saml/signer"
+require_relative "saml/encryptor"
+require_relative "saml/response_builder"

data/lib/identizer/server.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "webrick"
+require "webrick/https"
+require "stringio"
+
+module Identizer
+  # Runs the Rack App standalone over HTTPS (WEBrick). This is only needed for
+  # the standalone/CLI use case — when mounting Identizer inside an existing
+  # Rack/Rails app you use App directly and never touch this.
+  class Server
+    def self.start(config = Identizer.configuration, app: nil)
+      new(config, app: app).start
+    end
+
+    def initialize(config = Identizer.configuration, app: nil)
+      @config = config
+      @app = app || App.new(config)
+    end
+
+    def start
+      $stdout.sync = true
+      server = mounted_server
+      trap("INT") { server.shutdown }
+      trap("TERM") { server.shutdown }
+      print_banner(@cert_path)
+      server.start
+    end
+
+    # Build the WEBrick server with the Rack app mounted, without starting it.
+    # Exposed so tests can boot/stop it on an ephemeral port.
+    def mounted_server
+      cert, key, @cert_path = TLS.resolve(@config)
+      server = build_server(cert, key)
+      server.mount_proc("/") { |request, response| dispatch(request, response) }
+      server
+    end
+
+    private
+
+    def build_server(cert, key)
+      WEBrick::HTTPServer.new(
+        Port: @config.port,
+        BindAddress: @config.host,
+        SSLEnable: true,
+        SSLCertificate: cert,
+        SSLPrivateKey: key,
+        Logger: WEBrick::Log.new($stderr, WEBrick::Log::WARN),
+        AccessLog: []
+      )
+    end
+
+    def dispatch(request, response)
+      status, headers, body = @app.call(rack_env(request))
+      log_request(request, status)
+      response.status = status
+      headers.each { |key, value| response[key] = value }
+      response.body = +""
+      body.each { |chunk| response.body << chunk }
+    ensure
+      body.close if body.respond_to?(:close)
+    end
+
+    # A concise request line so you can watch the SSO flow as it happens.
+    def log_request(request, status)
+      return unless @config.request_logging
+
+      puts "[identizer] #{Time.now.strftime('%H:%M:%S')} #{request.request_method} #{request.path} -> #{status}"
+    end
+
+    # Translate a WEBrick request into a minimal Rack env.
+    def rack_env(request)
+      body = request.body.to_s
+      env = {
+        "REQUEST_METHOD" => request.request_method,
+        "SCRIPT_NAME" => "",
+        "PATH_INFO" => request.path,
+        "QUERY_STRING" => request.query_string.to_s,
+        "SERVER_NAME" => (request.host || @config.url_host).to_s,
+        "SERVER_PORT" => @config.port.to_s,
+        "CONTENT_LENGTH" => body.bytesize.to_s,
+        "rack.input" => StringIO.new(body),
+        "rack.errors" => $stderr,
+        "rack.url_scheme" => "https"
+      }
+      request.header.each do |key, values|
+        env["HTTP_#{key.upcase.tr('-', '_')}"] = values.join(", ")
+      end
+      env["CONTENT_TYPE"] = request.content_type if request.content_type
+      env
+    end
+
+    def print_banner(cert_path)
+      base = @config.base_url
+      puts <<~BANNER
+        ────────────────────────────────────────────────────────────
+         🔑  Identizer is running — a local identity provider for SSO testing
+
+         Dashboard   #{base}/
+                     (manage users & settings, copy provider values)
+         Sign in     any directory user · password: "#{@config.shared_password}"
+        #{hosts_hint}
+
+         Point your app's SSO config at:
+           OIDC      issuer #{base}  (discovery at /.well-known/openid-configuration)
+           SAML      metadata #{base}/metadata · SSO #{base}/saml/sso
+           OAuth2    authorize / token / userinfo under #{base}
+           Cognito   COGNITO_ENDPOINT=#{base}
+        #{ldap_banner_line}
+         New to SSO? Open the dashboard → Docs → "Getting started".
+
+         TLS: self-signed cert at #{cert_path}
+              trust it for server-to-server calls: export SSL_CERT_FILE=#{cert_path}
+              (or use mkcert + --tls-cert/--tls-key). Press Ctrl-C to stop.
+        ────────────────────────────────────────────────────────────
+      BANNER
+    end
+
+    def hosts_hint
+      return "" if @config.url_host == "localhost"
+
+      " Custom domain → add to /etc/hosts:  127.0.0.1  #{@config.url_host}\n " \
+        "(the self-signed cert already covers it)\n"
+    end
+
+    def ldap_banner_line
+      host = @config.ldap_host || @config.host
+      lines = []
+      lines << "LDAP listener:  ldap://#{host}:#{@config.ldap_port}" if @config.ldap_port
+      lines << "LDAPS listener: ldaps://#{host}:#{@config.ldaps_port}" if @config.ldaps_port
+      lines.empty? ? "" : "#{lines.join("\n")}\n"
+    end
+  end
+end

data/lib/identizer/tls.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Identizer
+  # Resolves the TLS material the standalone server listens with. The login URLs
+  # must be https (browser popup guards reject http), so we either use a provided
+  # (e.g. mkcert-generated, locally-trusted) cert or fall back to a self-signed
+  # one written under config_dir, which the app can trust via SSL_CERT_FILE.
+  module TLS
+    module_function
+
+    # Returns [OpenSSL::X509::Certificate, OpenSSL::PKey::RSA, cert_path].
+    def resolve(config)
+      if config.tls_cert_path && config.tls_key_path
+        cert = OpenSSL::X509::Certificate.new(File.read(config.tls_cert_path))
+        key = OpenSSL::PKey::RSA.new(File.read(config.tls_key_path))
+        return [cert, key, config.tls_cert_path]
+      end
+
+      generate_self_signed(config)
+    end
+
+    def generate_self_signed(config)
+      key = OpenSSL::PKey::RSA.new(2048)
+      host = config.url_host
+      name = OpenSSL::X509::Name.parse("/CN=#{host}")
+
+      cert = OpenSSL::X509::Certificate.new
+      cert.version = 2
+      cert.serial = 1
+      cert.subject = name
+      cert.issuer = name
+      cert.public_key = key.public_key
+      cert.not_before = Time.now - 60
+      cert.not_after = Time.now + (365 * 24 * 60 * 60)
+
+      factory = OpenSSL::X509::ExtensionFactory.new
+      factory.subject_certificate = cert
+      factory.issuer_certificate = cert
+      cert.add_extension(factory.create_extension("basicConstraints", "CA:TRUE", true))
+      cert.add_extension(factory.create_extension("subjectAltName", subject_alt_names(host), false))
+      cert.sign(key, OpenSSL::Digest.new("SHA256"))
+
+      FileUtils.mkdir_p(config.config_dir)
+      cert_path = File.join(config.config_dir, "cert.pem")
+      key_path = File.join(config.config_dir, "key.pem")
+      File.write(cert_path, cert.to_pem)
+      File.write(key_path, key.to_pem)
+      File.chmod(0o600, key_path)
+
+      [cert, key, cert_path]
+    end
+
+    # Always covers localhost/127.0.0.1, plus a custom advertised host so HTTPS
+    # works when the app reaches Identizer by that name (via /etc/hosts).
+    def subject_alt_names(host)
+      names = ["DNS:localhost", "IP:127.0.0.1"]
+      names << "DNS:#{host}" unless host.nil? || host.empty? || host == "localhost"
+      names.join(",")
+    end
+  end
+end

data/lib/identizer/token_minter.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Identizer
+  # Mints id_tokens and serves the OIDC discovery + JWKS documents.
+  #
+  # Two signing modes:
+  #   :hs256 (default) — a shared symmetric key. Matches the original emulator's
+  #     "consumers don't verify" behaviour; simplest for local dev.
+  #   :rs256 — an RSA keypair (persisted under config_dir) with a published JWKS,
+  #     so real OIDC clients that DO verify signatures work out of the box.
+  class TokenMinter
+    def initialize(config)
+      @config = config
+    end
+
+    def id_token(identity, nonce: nil, audience: nil)
+      payload = payload(identity, nonce: nonce, audience: audience)
+      if @config.rs256?
+        JWT.encode(payload, rsa_key, "RS256", { kid: jwk.kid })
+      else
+        JWT.encode(payload, @config.hs256_key, "HS256")
+      end
+    end
+
+    def payload(identity, nonce: nil, audience: nil)
+      now = Time.now.to_i
+      registered = {
+        "iss" => @config.issuer,
+        # Audience is the requesting client_id when known, so OIDC clients that
+        # validate `aud == client_id` accept the token; falls back to a constant.
+        "aud" => audience.to_s.empty? ? "identizer" : audience,
+        "iat" => now,
+        "exp" => now + 3600 # id_token lifetime (intentionally separate from access_token_ttl)
+      }
+      registered["nonce"] = nonce unless nonce.to_s.empty?
+      # Registered claims always win over identity-derived ones, so a directory
+      # attribute can never forge iss/aud/exp/iat/nonce.
+      identity.to_h.merge(registered)
+    end
+
+    def jwks
+      return { "keys" => [] } unless @config.rs256?
+
+      { "keys" => [jwk.export] }
+    end
+
+    def discovery
+      base = @config.base_url
+      {
+        "issuer" => @config.issuer,
+        "authorization_endpoint" => "#{base}/v1/authorize",
+        "token_endpoint" => "#{base}/v1/token",
+        "userinfo_endpoint" => "#{base}/userinfo",
+        "jwks_uri" => "#{base}/.well-known/jwks.json",
+        "introspection_endpoint" => "#{base}/introspect",
+        "revocation_endpoint" => "#{base}/revoke",
+        "end_session_endpoint" => "#{base}/v1/logout",
+        "response_types_supported" => ["code"],
+        "grant_types_supported" => %w[authorization_code refresh_token],
+        "code_challenge_methods_supported" => %w[S256 plain],
+        "subject_types_supported" => ["public"],
+        "id_token_signing_alg_values_supported" => [@config.rs256? ? "RS256" : "HS256"],
+        "scopes_supported" => %w[openid email profile]
+      }
+    end
+
+    private
+
+    def jwk
+      @jwk ||= JWT::JWK.new(rsa_key)
+    end
+
+    def rsa_key
+      @rsa_key ||= load_or_generate_rsa_key
+    end
+
+    # Persist the signing key so the JWKS stays stable across restarts.
+    def load_or_generate_rsa_key
+      path = File.join(@config.config_dir, "signing_key.pem")
+      return OpenSSL::PKey::RSA.new(File.read(path)) if File.exist?(path)
+
+      key = OpenSSL::PKey::RSA.new(2048)
+      FileUtils.mkdir_p(@config.config_dir)
+      File.write(path, key.to_pem)
+      File.chmod(0o600, path)
+      key
+    end
+  end
+end

data/lib/identizer/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Identizer
+  VERSION = "0.1.0"
+end

data/lib/identizer/web/views/directory/index.html.erb

@@ -0,0 +1,69 @@
+<% editing = !entry.mail.to_s.empty? %>
+<h1>Directory</h1>
+<p class="lead">An LDAP-flavoured user directory. Entries are projected onto OIDC claims at login
+   (<span class="mono">givenName→given_name</span>, <span class="mono">sn→family_name</span>,
+   <span class="mono">memberOf→groups</span>). Base DN <span class="mono"><%= h(base_dn) %></span>.</p>
+
+<div class="card">
+  <table>
+    <thead>
+      <tr><th>DN</th><th>mail</th><th>cn</th><th>groups</th><th></th></tr>
+    </thead>
+    <tbody>
+      <% if entries.empty? %>
+        <tr><td colspan="5" class="muted">No entries yet — add one below.</td></tr>
+      <% end %>
+      <% entries.each do |item| %>
+        <tr>
+          <td class="mono"><%= h(item.dn) %></td>
+          <td class="mono"><%= h(item.mail) %></td>
+          <td><%= h(item["cn"]) %></td>
+          <td><% item.groups.each do |group| %><span class="tag"><%= h(group) %></span><% end %></td>
+          <td>
+            <div class="actions">
+              <a class="btn" href="<%= prefix %>/directory?edit=<%= h(item.mail) %>">Edit</a>
+              <form method="post" action="<%= prefix %>/directory/delete"
+                    onsubmit="return confirm('Delete <%= h(item.mail) %>?')">
+                <input type="hidden" name="mail" value="<%= h(item.mail) %>">
+                <button class="danger" type="submit">Delete</button>
+              </form>
+            </div>
+          </td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>
+
+<h2><%= editing ? "Edit entry" : "Add entry" %></h2>
+<form class="card" method="post" action="<%= prefix %>/directory">
+  <% if editing %><input type="hidden" name="original_mail" value="<%= h(entry.mail) %>"><% end %>
+  <div class="row">
+    <div><label>mail (login email)</label>
+      <input type="email" name="mail" required value="<%= h(editing ? entry.mail : "") %>"></div>
+    <div><label>uid</label>
+      <input type="text" name="uid" placeholder="auto from mail" value="<%= h(editing ? entry["uid"] : "") %>"></div>
+  </div>
+  <div class="row">
+    <div><label>givenName</label>
+      <input type="text" name="givenName" value="<%= h(editing ? entry["givenName"] : "") %>"></div>
+    <div><label>sn (surname)</label>
+      <input type="text" name="sn" value="<%= h(editing ? entry["sn"] : "") %>"></div>
+  </div>
+  <div class="row">
+    <div><label>cn (common name)</label>
+      <input type="text" name="cn" placeholder="auto from name" value="<%= h(editing ? entry["cn"] : "") %>"></div>
+    <div><label>ou (org unit)</label>
+      <input type="text" name="ou" placeholder="people" value="<%= h(editing ? entry["ou"] : "") %>"></div>
+  </div>
+  <label>memberOf / groups (one per line)</label>
+  <textarea name="memberOf"><%= h(editing ? entry.groups.join("\n") : "") %></textarea>
+  <label>Custom attributes (one per line, <span class="mono">name = value</span>)</label>
+  <textarea name="custom_attributes" placeholder="custom_1 = 12345&#10;department = Engineering"><%=
+    h(editing ? entry.custom_attributes.map { |name, value| "#{name} = #{Array(value).join(', ')}" }.join("\n") : "")
+  %></textarea>
+  <p>
+    <button class="primary" type="submit"><%= editing ? "Save entry" : "Add entry" %></button>
+    <% if editing %><a class="btn" href="<%= prefix %>/directory">Cancel</a><% end %>
+  </p>
+</form>

data/lib/identizer/web/views/docs/broker-app.html.erb

@@ -0,0 +1,67 @@
+<p class="muted"><a href="<%= prefix %>/docs">&larr; Docs</a></p>
+<article>
+  <h1>Cheatsheet: Cognito-brokered app</h1>
+  <p class="lead">A common pattern: your app federates external IdPs through an AWS Cognito user pool, where each
+     tenant's provider is either OIDC or SAML. Identizer stands in for Cognito (provider-save) and for the
+     upstream IdP (login). Here are the exact values to put in each provider type.</p>
+
+  <h2>0. Point the broker at Identizer</h2>
+  <pre>COGNITO_ENDPOINT=<%= h(config.base_url) %>      # provider-save: management API is stubbed</pre>
+  <p>Add a user on the <a href="<%= prefix %>/directory">Directory</a> page; the password is the shared
+     password from <a href="<%= prefix %>/settings">Settings</a>.</p>
+
+  <h2>OIDC provider</h2>
+  <table>
+    <tr><th>OIDC issuer URL</th><td class="mono"><%= h(config.base_url) %></td></tr>
+    <tr><th>Client ID</th><td class="mono">dev-client (any value)</td></tr>
+    <tr><th>Client secret</th><td class="mono">dev-secret (any value)</td></tr>
+    <tr><th>Authorize scopes</th><td class="mono">openid</td></tr>
+    <tr><th>Attribute request method</th><td class="mono">GET</td></tr>
+    <tr><th>Email / Given name / Family name attribute</th><td class="mono">email / given_name / family_name</td></tr>
+  </table>
+  <p class="muted">Endpoints are auto-discovered from <span class="mono"><%= h(config.base_url) %>/.well-known/openid-configuration</span>,
+     so the exact paths don't matter to the client.</p>
+
+  <h2>SAML provider</h2>
+  <table>
+    <tr><th>Metadata URL</th><td class="mono"><%= h(config.base_url) %>/metadata</td></tr>
+    <tr><th>SSO URL</th><td class="mono"><%= h(config.base_url) %>/saml/sso</td></tr>
+    <tr><th>NameID</th><td class="mono">emailAddress</td></tr>
+    <tr><th>Email / Given name / Family name attribute</th><td class="mono">email / given_name / family_name</td></tr>
+  </table>
+  <p class="muted">Or download the metadata from the link on <a href="<%= prefix %>/metadata?download=1">/metadata</a>
+     to test a "metadata file" upload field.</p>
+
+  <h2>SAML brokered via Auth0 (encryption flow)</h2>
+  <p>For providers that exchange the code at <span class="mono">/oauth/token</span> and read the profile from
+     <span class="mono">/userinfo</span>, set the Auth0 domain to Identizer:</p>
+  <pre>SSO_AUTH0_DOMAIN=<%= h(config.base_url.sub(%r{\Ahttps?://}, "")) %>   # bare host, no scheme</pre>
+  <p>Identizer also emulates the <strong>Auth0 Management API</strong> at that domain — the
+     <span class="mono">client_credentials</span> token grant plus <span class="mono">/api/v2/clients</span> and
+     <span class="mono">/api/v2/connections</span> (create / list / update / delete). So your app can provision
+     the application + SAML connection on provider save and tear them down on remove, exactly like real Auth0
+     (returns generated <span class="mono">client_id</span>/<span class="mono">client_secret</span> and a
+     <span class="mono">con_…</span> connection id).</p>
+
+  <h2>Matching attribute names</h2>
+  <p>The broker maps each provider's attributes onto your app's fields (e.g. <span class="mono">email</span>,
+     <span class="mono">given_name</span>, <span class="mono">family_name</span>, or custom ones). Identizer emits
+     attributes/claims named after the directory entry's attributes:</p>
+  <ul>
+    <li><span class="mono">mail → email</span>, <span class="mono">givenName → given_name</span>,
+        <span class="mono">sn → family_name</span> (set these on the Directory page).</li>
+    <li>For any extra/custom attribute name a provider would send (e.g. <span class="mono">custom_1</span>),
+        add it in the <a href="<%= prefix %>/directory">Directory</a> entry's
+        <em>Custom attributes</em> field (<span class="mono">name = value</span>) or via
+        <span class="mono">config.seed_identities</span> — Identizer passes it through under that exact name
+        in both OIDC claims and SAML attributes.</li>
+  </ul>
+
+  <pre>Identizer.configure do |c|
+  c.seed_identities = [
+    # standard + any custom attributes as plain keys; they pass straight through
+    { mail: "alice@example.com", givenName: "Alice", sn: "Doe",
+      custom_1: "12345", department: "eng" }
+  ]
+end</pre>
+</article>

data/lib/identizer/web/views/docs/cognito.html.erb

@@ -0,0 +1,22 @@
+<p class="muted"><a href="<%= prefix %>/docs">&larr; Docs</a></p>
+<article>
+  <h1>AWS Cognito broker</h1>
+  <p class="lead">Identizer emulates the two Cognito surfaces an app's SSO integration depends on, so you can
+     configure providers and log in without a real user pool.</p>
+
+  <h2>1. Management API (provider-save time)</h2>
+  <p>Point the AWS SDK at Identizer and the management calls (<span class="mono">CreateUserPoolClient</span>,
+     <span class="mono">CreateIdentityProvider</span>, …) are stubbed:</p>
+  <pre>COGNITO_ENDPOINT=<%= h(config.base_url) %></pre>
+  <p>Your "Add provider" UI now succeeds offline, returning fake client ids/secrets.</p>
+
+  <h2>2. Hosted UI (login time)</h2>
+  <pre>Login     <%= h(config.base_url) %>/login
+Token     <%= h(config.base_url) %>/oauth2/token</pre>
+  <p>Set your Cognito hosted-UI domain to <span class="mono"><%= h(config.base_url) %></span>. The token
+     endpoint returns an <span class="mono">id_token</span> for the signed-in directory entry.</p>
+
+  <h2>Trust the TLS cert</h2>
+  <p>The AWS SDK makes server-to-server calls, so it must trust Identizer's certificate. See
+     <a href="<%= prefix %>/docs/tls">TLS &amp; mkcert</a>.</p>
+</article>

data/lib/identizer/web/views/docs/getting-started.html.erb

@@ -0,0 +1,28 @@
+<p class="muted"><a href="<%= prefix %>/docs">&larr; Docs</a></p>
+<article>
+  <h1>Getting started</h1>
+  <p class="lead">Identizer is a local identity provider. Point your app's SSO/OIDC config at it
+     instead of a real tenant, sign in as a directory entry, and develop the whole flow offline.</p>
+
+  <h2>1. Run it</h2>
+  <pre>bundle exec identizer --port 9999
+# dashboard: <%= h(config.base_url) %>/</pre>
+
+  <h2>2. Add users</h2>
+  <p>A demo user (<span class="mono">demo@example.com</span>) is seeded on first run, so login works right
+     away. Add more on the <a href="<%= prefix %>/directory">Directory</a> page (at minimum a
+     <span class="mono">mail</span>). The password for every entry is the shared password from
+     <a href="<%= prefix %>/settings">Settings</a> (default <code>password</code>).</p>
+
+  <h2>3. Point your app at it</h2>
+  <p>Use the values from the <a href="<%= prefix %>/">Overview</a> cheatsheet for your protocol —
+     issuer/authorize/token URLs all live under <span class="mono"><%= h(config.base_url) %></span>.</p>
+
+  <h2>4. Sign in</h2>
+  <p>Trigger your app's login. Identizer shows a sign-in form; enter a configured email + the shared
+     password. A wrong password or unknown email exercises the provider's error path.</p>
+
+  <h2>Mounted vs standalone</h2>
+  <p>Run standalone via the CLI, or mount the Rack app inside your own stack —
+     <span class="mono">mount Identizer::App.new =&gt; "/idp"</span>. See <a href="<%= prefix %>/docs/oidc">OIDC</a>.</p>
+</article>

data/lib/identizer/web/views/docs/index.html.erb

@@ -0,0 +1,9 @@
+<h1>Docs</h1>
+<p class="lead">Bundled guides for wiring your app to Identizer.</p>
+<div class="card">
+  <ul>
+    <% pages.each do |page| %>
+      <li><a href="<%= prefix %>/docs/<%= page[:slug] %>"><%= h(page[:title]) %></a></li>
+    <% end %>
+  </ul>
+</div>

data/lib/identizer/web/views/docs/ldap.html.erb

@@ -0,0 +1,38 @@
+<p class="muted"><a href="<%= prefix %>/docs">&larr; Docs</a></p>
+<article>
+  <h1>LDAP listener</h1>
+  <p class="lead">Identizer can also expose the directory over LDAP, so apps that authenticate via
+     <span class="mono">ldap://</span> (simple bind + search) can test against it — the same users you
+     manage in the <a href="<%= prefix %>/directory">Directory</a>.</p>
+
+  <h2>Enable it</h2>
+  <pre>bundle exec identizer --port 9999 --ldap-port 1389</pre>
+  <p>The listener is off unless <span class="mono">--ldap-port</span> (or
+     <span class="mono">IDENTIZER_LDAP_PORT</span>) is set.</p>
+
+  <h2>Bind</h2>
+  <p>Simple bind with a user's DN and the shared password:</p>
+  <pre>uid=alice,ou=people,<%= h(config.ldap_base_dn) %>   /   password = the shared sign-in password</pre>
+  <p>An empty DN + empty password is accepted as an anonymous bind.</p>
+
+  <h2>Search</h2>
+  <p>Subtree search under the base DN <span class="mono"><%= h(config.ldap_base_dn) %></span>. Supported
+     filters: equality (<span class="mono">(mail=a@b.com)</span>), presence
+     (<span class="mono">(objectClass=*)</span>), substrings, and <span class="mono">&amp;</span> /
+     <span class="mono">|</span> / <span class="mono">!</span> combinations.</p>
+  <p>Entries are projected to standard attributes: <span class="mono">uid, cn, sn, givenName, mail, ou,
+     memberOf, objectClass</span>.</p>
+
+  <h2>LDAPS (TLS)</h2>
+  <pre>bundle exec identizer --port 9999 --ldaps-port 1636</pre>
+  <p>Adds an implicit-TLS listener reusing the same certificate as the HTTPS server (see
+     <a href="<%= prefix %>/docs/tls">TLS &amp; mkcert</a>). You can run plain LDAP and LDAPS together.</p>
+
+  <h2>StartTLS</h2>
+  <p>Clients that upgrade a plain LDAP connection with StartTLS are supported on the plain
+     <span class="mono">--ldap-port</span> listener — Identizer acknowledges the extended operation and upgrades
+     the socket to TLS (reusing the same certificate).</p>
+
+  <h2>Scope</h2>
+  <p>A development listener (simple bind). Not intended for production directories.</p>
+</article>