From 6adb07e940853200e55221659cb5a61ba2bcb783 Mon Sep 17 00:00:00 2001
From: Jim <jlambert@hashicorp.com>
Date: Mon, 25 Sep 2023 21:14:46 -0700
Subject: [PATCH] docs (saml): add a pkg level readme and a godoc link (#111)

---
 README.md      |  2 ++
 saml/README.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 49 insertions(+)
 create mode 100644 saml/README.md

diff --git a/README.md b/README.md
index b2b3486..b2577e4 100644
--- a/README.md
+++ b/README.md
@@ -222,6 +222,8 @@ if result.Success {
 
 ### [`saml package`](./saml)
 
+[![Go Reference](https://pkg.go.dev/badge/github.com/hashicorp/cap/saml.svg)](https://pkg.go.dev/github.com/hashicorp/cap/saml)
+
 A package for writing clients that integrate with SAML Providers.
 
 The SAML library orients mainly on the implementation profile for
diff --git a/saml/README.md b/saml/README.md
new file mode 100644
index 0000000..6ff4c29
--- /dev/null
+++ b/saml/README.md
@@ -0,0 +1,47 @@
+
+# [`saml package`](./saml)
+
+[![Go Reference](https://pkg.go.dev/badge/github.com/hashicorp/cap/saml.svg)](https://pkg.go.dev/github.com/hashicorp/cap/saml)
+
+A package for writing clients that integrate with SAML Providers.
+
+The SAML library orients mainly on the implementation profile for
+[federation interoperability](https://kantarainitiative.github.io/SAMLprofiles/fedinterop.html)
+(also known as interoperable SAML), a set of software conformance requirements
+intended to facilitate interoperability within the context of full mesh identity
+federations. It supports the Web Browser SSO profile with HTTP-Post and
+HTTP-Redirect as supported service bindings. The default SAML settings follow
+the requirements of the interoperable SAML
+[deployment profile](https://kantarainitiative.github.io/SAMLprofiles/saml2int.html#_service_provider_requirements).
+
+## Example usage
+
+```go
+    // Create a new saml config providing the necessary provider information:
+    cfg, err := saml.NewConfig(<entityID>, <acs>, <metadata>, options...)
+	// handle error
+
+    // Use the config to create the service provider:
+    sp, err := saml.NewServiceProvider(cfg)
+    // handle error
+
+    // With the service provider you can create saml authentication requests:
+
+    // Generate a saml auth request with HTTP Post-Binding
+    template, err := sp.AuthRequestPost("relay state", options...)
+    // handle error
+
+    // Generate a saml auth request with HTTP Request-Binding
+    redirectURL, err := sp.AuthRequestRedirect("relay state", options...)
+    // handle error
+
+    // Parsing a SAML response:
+    r.ParseForm()
+    samlResp := r.PostForm.Get("SAMLResponse")
+
+    response, err := sp.ParseResponse(samlResp, "Response ID", options...)
+    // handle error
+```
+
+You can find the full demo code in the [`saml/demo`](./saml/demo/main.go)
+package.