Security Provider - SAML Identity Provider¶

SAML Single Sign-On (SSO) authentication is defined in the following documents:

• Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0
• SAML Version 2.0 Errata 05

In a SSO scenario, there are three roles:

• Principal - The user accessing a restricted service.
• Service Provider (SP) - Provides access to restricted services.
• Identity Provider (IdP) - Authenticates users.

Vinyl can be configured as either the SP or IdP using the appropriate security provider. This document covers the SAML IdP security provider. The SAML IdP security provider authenticates users on behalf of a third-party SP. Typically, the third-party is another instance of Vinyl.

For the SP role, see the SAML security provider.

Flows¶

The SAML Single Sign-On (SSO) specification defines several flows. The SAML IdP security provider supports the following SAML SSO flows:

• Service Provider (SP) initiated
• Identity Provider (IdP) initiated

Service Provider (SP) Initiated¶

In the Service Provider (SP) initiated flow, a user navigates to a third-party service and attempts to access a restricted resource. The third-party service redirects the user to Vinyl via the SAML Redirect binding (HTTP GET). If the user has not already authenticated, Vinyl redirects the user to the login form.

Once the user has authenticated, Vinyl redirects the user back to the third-party service using the SAML Post binding (HTTP POST). The third-party service validates the SAML Response, maps the name identifier to a local user account, and grants the rights associated with that user account.

In the SP Initialted flow, the third-party service typically records the URL that the user attempted to access before performing the redirect. Once the SAML SSO process is complete, the SP redirects the user to that URL. This enables deep links.

Identity Provider (IdP) Initiated¶

In the Identity Provider (IdP) initiated flow, a user follows a link to the Single Sign-On Service. If the user has not already authenticated, Vinyl redirects the user to the login form.

Once the user has authenticated, Vinyl redirects the user back to the third-party service using the SAML Post binding (HTTP POST). As with the SP Initiated flow, the third-party service validates the SAML Response, maps the name identifier to a local user account, and grants the rights associated with that user account.

Since the IdP flow is not initiated by the third-party SP, the user is typically redirected to a default page once the SAML SSO process is complete. However, some SPs will allow the IdP to redirect the user to an arbitrary location by passing a URL in the RelayState parameter.

Configuration¶

Tokens¶

• Issuer: SAML assertion issuer.
• Audience: SAML assertion audience restriction. The value must be a syntactically valid URI.
• Recipient: SAML assertion recipient. The value must be a syntactically valid URI. Defaults to the Assertion Consumer Service.
• Entity ID: SAML entity identifier. The value must be a syntactically valid URI. Defaults to the Issuer.
• Subject: SAML NameId. Defaults to the current user name.

Endpoints¶

Certificates¶

As noted above, Vinyl requires a base64-encoded, PKCS#12 signing certificate with private key. The process for generating a certificate is outside the scope of this document. However, for illustrative purposes, the following commands demonstrate how to generate a compatible certificate using the OpenSSL command-line utility.

The following command generates a private key (key.pem) and self-signed certificate (cert.pem):

$ openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -nodes -days 1095 -subj "/CN=localhost/O=Vinyl"

The following command generates a PKCS#12 archive (cert.pfx) containing the private key and certificate:

$ openssl pkcs12 -export -in cert.pem -inkey key.pem -out cert.pfx

You will be prompted to provide a password. Vinyl will need to know this password to decrypt the private key.

Finally, the following command base64-encodes the PKCS#12 archive:

$ openssl base64 -in cert.pfx -out cert.txt -A

Copy and paste the contents of cert.txt into Vinyl.

Properties¶

The SAML IdP security provider defines the following additional parameters:

Claims¶

The SAML IdP security provider maps user properties to claims. The claims are embedded in the SAML assertion as attributes. The attribute name corresponds to the claim identifier.

For example, if the Name property has been mapped to the claim identifier http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name, the SAML assertion would contain the following attribute:

<Attribute AttributeName="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name">
  <AttributeValue>Arthur.Dent</AttributeValue>
</Attribute>

The Group property can be used to pass security group membership. By default, SAML assertions do not include groups. You must explicitly register the groups that should be included.

To include group membership, create a security provider group and map it to a Vinyl group. If the user is a member of the Vinyl group, the security provider group will be added to the assertion. The security provider group's identifier is used. If the identifier is null, the name is used.

Integration¶

The SAML IdP security provider exposes the following endpoints:

• Single Sign-On Service
• Metadata Endpoint

Single Sign-On Service¶

The Single Sign-On Service receives SAML request messages (AuthNRequest). The Single Sign-On Service URL will take the following form:

https://example.com/Vinyl/signin-SAMLIDP

The URL is composed of the following parts:

Metadata Endpoint¶

The Metadata Endpoint publishes a metadata document (Metadata). The Metadata Endpoint URL will take the following form:

https://example.com/Vinyl/metadata-SAMLIDP

The URL is composed of the following parts:

Known Issues and Limitations¶

The Vinyl SAML IdP security provider has the following limitations:

• Only a single audience restriction may be supplied.
• SAML responses may not be encrypted.
• SAML responses may not be signed.
• SAML assertions are always signed.
• The Artifact resolution protocol is not supported.
• The Logout protocol is not supported.