SAML

Package saml contains an implementation of the SAML / SAML 2.0 standard in golang.

SAML is a standard for identity federation, i.e. either allowing a third party to authenticate your users or allowing third parties to rely on us to authenticate their users.

Introduction

In SAML parlance an Identity Provider (IdP) is a service that knows how to authenticate users. A Service Provider (SP) is a service that delegates authentication to an IDP. If you are building a service where users log in with someone else's credentials, then you are a Service Provider. This package supports implementing both service providers and identity providers.

The core package contains the implementation of SAML. The package samlsp provides helper middleware suitable for use in Service Provider applications. The package samlidp provides a rudimentary IDP service that is useful for testing or as a starting point for other integrations.

Support

The SAML standard is huge and complex with many dark corners and strange, unused features. This package implements the most commonly used subset of these features required to provide a single sign on experience. The package supports at least the subset of SAML known as interoperable SAML.

Support Matrix

Symbol	Meaning
✅	Full: supported
⚠️	Partial: supported with limitations, see the notes below
❌	None: not supported
N/A	Not applicable to this role

Profiles

Feature	IdP	SP
Web Browser SSO (SP-initiated)	✅	✅
Web Browser SSO (IdP-initiated/unsolicited)	✅	✅
Single Logout	❌	⚠️
Artifact Resolution	❌	✅
Enhanced Client or Proxy (ECP)	❌	❌
Holder-of-Key Web Browser SSO	❌	❌
Name Identifier Management	❌	❌
Name Identifier Mapping	❌	❌
Assertion Query/Request and Attribute Query	❌	❌
Identity Provider Discovery	❌	❌
SP Request Initiation	N/A	❌

Bindings

Feature	IdP	SP
HTTP Redirect (AuthnRequest)	✅	✅
HTTP POST (AuthnRequest)	✅	✅
HTTP POST (Response)	✅	✅
HTTP Artifact (Response)	❌	✅
SOAP	❌	⚠️
HTTP POST "SimpleSign"	❌	❌
Reverse SOAP (PAOS)	❌	❌

Protocol

Feature	IdP	SP
AssertionConsumerServiceURL / Index selection	✅	N/A
RelayState	✅	✅
NameIDPolicy	⚠️	✅
ForceAuthn / IsPassive	⚠️	✅
RequestedAuthnContext	⚠️	✅
Scoping (proxying)	❌	❌
Error status responses	❌	✅
Multiple assertions in a single Response	N/A	⚠️
Replay detection	❌	⚠️

Signing and Encryption

Feature	IdP	SP
Sign Response and Assertion	✅	N/A
Verify signed Response and Assertion	N/A	✅
Sign AuthnRequest	N/A	✅
Verify signed AuthnRequest	❌	N/A
RSA and ECDSA signatures (SHA-1/256/384/512)	✅	✅
Encrypt Assertion	⚠️	N/A
Decrypt EncryptedAssertion	N/A	⚠️
EncryptedID and EncryptedAttribute	❌	❌

Metadata

Feature	IdP	SP
Publish own metadata	✅	✅
Consume EntityDescriptor	✅	✅
Consume EntitiesDescriptor	N/A	⚠️
Sign published metadata	❌	❌
Verify metadata signatures	❌	❌

Identity Provider Limitations

• Single Logout: there is no SLO endpoint. Setting IdentityProvider.LogoutURL only advertises an HTTP Redirect SingleLogoutService in the metadata; LogoutRequest and LogoutResponse messages are neither handled nor sent.
• Artifact Resolution, HTTP Artifact and SOAP: responses are only ever delivered via HTTP POST, and there is no ArtifactResolutionService.
• Verify signed AuthnRequest: request signatures are ignored. Metadata never sets WantAuthnRequestsSigned, and a request is rejected outright if it does.
• NameIDPolicy: the requested format is ignored. The NameID format comes from Session.NameIDFormat and defaults to transient, and the metadata only advertises transient.
• ForceAuthn / IsPassive: not enforced by the library. The parsed request is passed to SessionProvider.GetSession, so enforcing them is left to the implementation.
• RequestedAuthnContext: ignored by DefaultAssertionMaker, which always asserts PasswordProtectedTransport. A custom AssertionMaker can set a different context.
• Error status responses: failures produce an HTTP error rather than a SAML Response carrying a non-success status.
• Replay detection: AuthnRequest IDs are not checked for reuse.
• Encrypt Assertion: encryption always uses AES-128-CBC with RSA-OAEP-MGF1P (SHA-1), regardless of the EncryptionMethod the SP advertises, and cannot be configured.
• Signature defaults: SignatureMethod defaults to RSA-SHA1; set it explicitly to use a stronger algorithm.

Service Provider Limitations

• Single Logout: LogoutRequest messages can be created and sent (HTTP Redirect or HTTP POST) and LogoutResponse messages can be validated, however:
  • Incoming LogoutRequest messages (IdP-initiated logout) cannot be parsed or validated.
  • samlsp.Middleware does not serve the SLO endpoint.
  • HTTP Redirect messages are signed with an embedded XML signature rather than the SigAlg and Signature query parameters the binding requires, and received HTTP Redirect messages are validated the same way.
• SOAP: only used as a client to send ArtifactResolve.
• Multiple assertions in a single Response: only the first valid assertion is returned.
• Replay detection: SP-initiated responses must match a tracked request ID, but assertion IDs are not remembered, so an unsolicited response accepted with AllowIDPInitiated can be replayed until it expires.
• Decrypt EncryptedAssertion: supported algorithms are AES-128/192/256-CBC, AES-128-GCM and 3DES for content and RSA-OAEP-MGF1P for key transport. AES-192/256-GCM and XML Encryption 1.1 RSA-OAEP are not supported by default. RSA PKCS#1 v1.5 key transport is disabled by default and can be enabled with xmlenc.RegisterDecrypter(xmlenc.PKCS1v15()).
• Consume EntitiesDescriptor: samlsp.ParseMetadata uses the first entity that has an IDPSSODescriptor; there is no way to select a different entity.

RelayState

The RelayState parameter allows you to pass user state information across the authentication flow. The most common use for this is to allow a user to request a deep link into your site, be redirected through the SAML login flow, and upon successful completion, be directed to the originally requested link, rather than the root.

Unfortunately, RelayState is less useful than it could be. Firstly, it is not authenticated, so anything you supply must be signed to avoid XSS or CSRF. Secondly, it is limited to 80 bytes in length, which precludes signing. (See section 3.6.3.1 of SAMLProfiles.)

References

The SAML specification is a collection of PDFs. Each is linked below to the original published by OASIS and to a plain text conversion kept in spec.

The core SAML V2.0 standard:

• SAMLCore defines data types (PDF, TXT).
• SAMLBindings defines the details of the HTTP requests in play (PDF, TXT).
• SAMLProfiles describes data flows (PDF, TXT).
• SAMLMetadata defines the metadata format used to describe entities (PDF, TXT).
• SAMLAuthnContext defines the authentication context classes (PDF, TXT).
• SAMLConformance includes a support matrix for various parts of the protocol (PDF, TXT).
• SAMLSecurity covers security and privacy considerations (PDF, TXT).
• SAMLGloss is the glossary of terms (PDF, TXT).
• SAML V2.0 Errata 05 amends all of the above (PDF, TXT).
• SAML V2.0 Technical Overview is a non-normative introduction (PDF, TXT).

Extensions and profiles published after SAML V2.0:

Specification	Original	Text
Metadata Interoperability Profile	PDF	TXT
Metadata Extension for Entity Attributes	PDF	TXT
Metadata Extensions for Login and Discovery User Interface	PDF	TXT
Metadata Extensions for Registration and Publication Info	PDF	TXT
Metadata Profile for Algorithm Support	PDF	TXT
Metadata Extension for SAML V2.0 and V1.x Query Requesters	PDF	TXT
HTTP POST "SimpleSign" Binding	PDF	TXT
Service Provider Request Initiation Protocol and Profile	PDF	TXT
Identity Provider Discovery Service Protocol and Profile	PDF	TXT
Asynchronous Single Logout Profile Extension	PDF	TXT
Enhanced Client or Proxy (ECP) Profile Version 2.0	PDF	TXT
Channel Binding Extensions	PDF	TXT
Holder-of-Key Assertion Profile	PDF	TXT
Holder-of-Key Web Browser SSO Profile	PDF	TXT
Condition for Delegation Restriction	PDF	TXT
Identity Assurance Profiles	PDF	TXT
Session Token Profile	PDF	TXT
Change Notify Protocol	PDF	TXT
Attribute Extensions	PDF	TXT
Attribute Predicate Profile	PDF	TXT
X.500/LDAP Attribute Profile	PDF	TXT
Attribute Sharing Profile for X.509 Authentication-Based Systems	PDF	TXT
Deployment Profiles for X.509 Subjects	PDF	TXT
Kerberos Attribute Profile	PDF	TXT
Kerberos Subject Confirmation Method	PDF	TXT
Kerberos Web Browser SSO Profile	PDF	TXT

Thanks

This is a hard fork of Ross Kinder's SAML Library under the BSD 2-Clause License for the purpose of performing self-maintenance of this critical Authelia dependency.

We however:

• Acknowledge the amazing hard work of Ross Kinder and other contributors in making such an amazing library that we can do this with.
• Plan to continue to contribute back to te original repository and related projects should Ross return.
• Have ensured the licensing is unchanged in this fork of the library.
• Do not have a formal affiliation with Ross Kinder and individuals utilizing this library should not allow their usage to be a reflection on Ross Kinder as this library is not maintained by him and intentionally diverges from the original implementation.