crewjam/saml

To implement a Service Provider (SP) that delegates authentication to an Identity Provider (IDP), use the samlsp package.

Prerequisites

1. X.509 Key Pair: You must have a self-signed X.509 key pair for the SP. You can generate one using OpenSSL:

   openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"

2. IDP Metadata: You need the metadata URL of the Identity Provider to fetch its configuration at startup.

Implementation Steps

1. Load your X.509 certificate and private key.
2. Use samlsp.FetchMetadata to retrieve the IDP's metadata.
3. Initialize samlsp.New with samlsp.Options containing your URL, Key, Certificate, and IDPMetadata.
4. Use samlSP.RequireAccount(handler) to wrap protected endpoints. This ensures the user is authenticated before accessing the handler.
5. Register the samlSP instance itself at the /saml/ path to handle SAML-specific protocol requests (like ACS and metadata).

Accessing User Attributes

You can retrieve user attributes (like displayName) from the request context using samlsp.AttributeFromContext(r.Context(), "attribute_name").

// ... imports

func hello(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintf(w, "Hello, %s!", samlsp.AttributeFromContext(r.Context(), "displayName"))
}

func main() {
	keyPair, err := tls.LoadX509KeyPair("myservice.cert", "myservice.key")
	if err != nil {
		panic(err)
	}
	keyPair.Leaf, err = x509.ParseCertificate(keyPair.Certificate[0])
	if err != nil {
		panic(err)
	}

	idpMetadataURL, err := url.Parse("https://samltest.id/saml/idp")
	if err != nil {
		panic(err)
	}
	idpMetadata, err := samlsp.FetchMetadata(context.Background(), http.DefaultClient, *idpMetadataURL)
	if err != nil {
		panic(err)
	}

	rootURL, err := url.Parse("http://localhost:8000")
	if err != nil {
		panic(err)
	}

	samlSP, _ := samlsp.New(samlsp.Options{
		URL:            *rootURL,
		Key:            keyPair.PrivateKey.(*rsa.PrivateKey),
		Certificate:    keyPair.Leaf,
		IDPMetadata: idpMetadata,
	})

	app := http.HandlerFunc(hello)
	http.Handle("/hello", samlSP.RequireAccount(app))
	http.Handle("/saml/", samlSP)
	http.ListenAndServe(":8000", nil)
}

The IdpAuthnRequest struct manages the state of a single SAML authentication request during the IDP lifecycle.

Lifecycle Steps:

1. Creation: NewIdpAuthnRequest(idp, r) parses the incoming GET or POST request, decodes the SAMLRequest (handling Base64 and decompression), and extracts the RelayState.
2. Validation: req.Validate() verifies the XML structure, checks the Destination attribute, ensures the request hasn't expired, and verifies the issuer against the ServiceProviderProvider.
3. Assertion Construction: req.MakeAssertion(session) (or via an AssertionMaker) populates the req.Assertion field with user data.
4. Encryption/Signing: req.MakeAssertionEl() signs the assertion and, if the SP's metadata contains an encryption certificate, encrypts the assertion.
5. Response Generation: req.MakeResponse() wraps the assertion in a SAML Response element and signs the response.
6. Transmission: req.WriteResponse(w) or req.PostBinding() prepares the final HTML form (using the HTTP-POST binding) to automatically submit the response to the SP's ACS endpoint.

These types represent SAML endpoints used for protocol bindings.

Endpoint

Used for services like SingleLogoutService or ManageNameIDService. It includes:

• Binding: The SAML binding URN.
• Location: The URI of the endpoint.
• ResponseLocation: (Optional) The location where responses should be sent.

Validation: During unmarshaling, the Location and ResponseLocation are validated to ensure they use http or https schemes for known SAML bindings.

IndexedEndpoint

Used for services like AssertionConsumerService or ArtifactResolutionService. It includes:

• Index: An integer index.
• IsDefault: (Optional) Whether this is the default endpoint.
• Binding, Location, ResponseLocation: Same as Endpoint.

type Endpoint struct {
	Binding          string `xml:"Binding,attr"`
	Location         string `xml:"Location,attr"`
	ResponseLocation string `xml:"ResponseLocation,attr,omitempty"`
}

type IndexedEndpoint struct {
	Binding          string  `xml:"Binding,attr"`
	Location         string  `xml:"Location,attr"`
	ResponseLocation *string `xml:"ResponseLocation,attr,omitempty"`
	Index            int     `xml:"index,attr"`
	IsDefault        *bool   `xml:"isDefault,attr"`
}

The ServiceProvider struct is the central component for implementing a SAML Service Provider. It manages identity provider (IdP) metadata, local keys for signing/encryption, and endpoint URLs.

Key configuration fields include:

• EntityID: The unique identifier for your SP.
• Key: A crypto.Signer (typically *rsa.PrivateKey or *ecdsa.PrivateKey) used to sign requests.
• Certificate: The public part of your Key.
• IDPMetadata: An *EntityDescriptor containing the IdP's configuration.
• AcsURL: The Assertion Consumer Service endpoint where the IdP sends responses.
• SloURL: The Single Logout endpoint.
• SignatureMethod: The algorithm used for signing (e.g., dsig.RSASHA256SignatureMethod).
• AuthnNameIDFormat: The preferred NameIDFormat for authentication requests.

sp := &saml.ServiceProvider{
    EntityID: "https://example.com/saml/metadata",
    Key: myPrivateKey,
    Certificate: myCertificate,
    MetadataURL: myMetadataURL,
    AcsURL: myAcsURL,
    SloURL: mySloURL,
    IDPMetadata: idpMetadata,
    SignatureMethod: dsig.RSASHA256SignatureMethod,
}

When processing an IdpAuthnRequest, a signing context is used to sign the response. The signing process uses the Identity Provider's (IDP) certificate chain and private key.

Key behaviors:

• Certificate Chain: The context is built using req.IDP.Certificate.Raw followed by any provided req.IDP.Intermediates.
• Signer Selection: If req.IDP.Signer is explicitly provided, it is used to create the dsig.SigningContext. Otherwise, the context is created using req.IDP.Key and the certificate chain via a dsig.TLSCertKeyStore.
• Signature Method: If req.IDP.SignatureMethod is empty, it defaults to dsig.RSASHA1SignatureMethod.
• Canonicalization: The signing context is configured to use dsig.MakeC14N10ExclusiveCanonicalizerWithPrefixList for XML canonicalization.

// Note: signingContext is an internal method of IdpAuthnRequest used to prepare the dsig.SigningContext
// based on the IDP configuration (Certificate, Intermediates, Signer, Key, and SignatureMethod).