Security Provider - SAML¶
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 an SP or IdP using the appropriate security provider. This document covers the SAML security provider, which is used for the SP role. In this role, Vinyl delegates authentication to a third-party IdP. Supported IdPs include:
For the IdP role, see the SAML Identity Provider.
Flows¶
The SAML Single Sign-On (SSO) specification defines several flows. The SAML 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 Vinyl and attempts to access a restricted page. Vinyl redirects the user to the Identity Provider (IdP) via the SAML Redirect binding (HTTP GET). Once authenticated, the IdP redirects the user back to Vinyl using the SAML Post binding (HTTP POST). Vinyl validates the SAML Response, maps the name identifier to a local Vinyl user account, and grants the rights associated with the user account.
Note that, before redirecting the user to the IdP, Vinyl records the URL of the page that the user attempted to access. Once the user has authenticated, Vinyl redirects the user back to the originally requested page. This enables deep linking.
Identity Provider (IdP) Initiated¶
In the Identity Provider (IdP) flow, a user navigates directly to the IdP. Once authenticated, the user is redirected to Vinyl via the SAML Post binding (HTTP POST). As with the SP Initiated flow, Vinyl validates the SAML Response, maps the name identifier to a local Vinyl user account, and grants the rights associated with the user account.
Typically, Vinyl will redirect the user to their home page upon successful sign-in. However, the IdP may perform a deep link by passing the URI in the SAML Response RelayState parameter. See the AllowRelayStateRedirects parameter below.
Configuration¶
Tokens¶
- Issuer: The SAML assertion issuer. Defaults to the audience.
- Audience: SAML assertion audience restriction. The value must be a syntactically valid URI.
- Recipient: The SAML assertion recipient. This value must be a syntactically valid URI. Defaults to the Assertion Consumer Service URI (e.g. https://example.com/Vinyl/signin-SAML).
Caution
For legacy reasons, Audience defaults to the application-root URL (e.g. https://example.com/Vinyl/). It is strongly recommended that you explicitly set the Audience rather than rely on the default.
Endpoints¶
| Type | Description |
|---|---|
| Metadata Endpoint | SAML Single Sign-On (SSO) service metadata endpoint. This parameter is required if the Request Redirect Endpoint or SigningCertificate parameters are undefined. |
| RelayState URI | Allowed RelayState redirect URI for a SAML Identity Provider (IdP) initiated request. See the AllowRelayStateRedirects parameter for additional information. |
| Request Redirect Endpoint | SAML Single Sign-On (SSO) authentication request endpoint for the Redirect binding. This parameter is required if the Metadata Endpoint is undefined. |
Certificates¶
| Purpose | Type | Format | Description |
|---|---|---|---|
| Signature Validation |
|
| X.509 certificate used to validate SAML Single Sign-On (SSO) response signatures. The signature validation certificate is required if the Metadata Endpoint is undefined. |
Properties¶
The SAML security provider defines the following additional parameters:
| Parameter | Default | Description |
|---|---|---|
| AllowRelayStateRedirects | False | Indicates whether a SAML Identity Provider (IdP) initiated sign-on may include a redirect URI in the RelayState parameter. The redirect URI is the location that the user will be redirected to after signing in. By default, the RelayState parameter may not contain a redirect URI. Set to True to allow redirect URIs in the RelayState parameter.To guard against open relay attacks, the URI must match the RelayState URI endpoint. |
| IgnoreTlsErrors | False | Indicates whether Vinyl should ignore HTTPS certificate errors when making back-channel requests to retrieve the service metadata. This setting is for setup and testing purposes only. Do not enable this setting on a running system. |
| SignatureRequirement | AssertionOrResponse | Indicates whether the SAML response, assertion or both most be signed. Options include: - AssertionOrResponse - Either the assertion or response must be signed. - Assertion - The assertion must be signed. - Response - Only the response must be signed. The assertion inherits the response signature. - AssertionAndResponse - Both the assertion and the response must be signed. |
| LogPII | False | Indicates that personally identifiable information (PII) should be logged. This setting takes effect on startup. |
Claims¶
SAML assertions contain attributes. Attributes are multi-valued key/value pairs. Vinyl treats SAML assertion attributes as claims. The attribute name maps to a claim identifier.
For example, given a SAML assertion with the following attribute:
<Attribute AttributeName="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name">
<AttributeValue>Arthur.Dent</AttributeValue>
</Attribute>
Mapping the identifier http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name to the Name property will set the user name to "Arthur.Dent" when the user account is provisioned.
The following table describes the default claim mappings:.
| Identifier | Purpose | Description |
|---|---|---|
| http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier | Name Identifier | Unique, immutable identifier used to map the third-party identity to a Vinyl user. |
| http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name | Name | User name. |
| http://schemas.xmlsoap.org/claims/Group | Group | Security group membership. |
| http://schemas.zudy.com/identity/claims/fullname | Full Name | Full name. |
| http://schemas.zudy.com/identity/claims/displayname | Display Name | Friendly name. |
| http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress | Email Address | Email address. |
| http://schemas.zudy.com/identity/claims/phonenumber | Phone Number | Phone number. |
| http://schemas.xmlsoap.org/ws/2005/05/identity/claims/thumbprint | X.509 certificate thumbprint. | |
| http://schemas.xmlsoap.org/ws/2005/05/identity/claims/x500distinguishedname | X.509 certificate distinguished name. | |
| http://schemas.xmlsoap.org/ws/2005/05/identity/claims/dns | X.509 certificate DNS name. |
Integration¶
Assertion Consumer Service¶
The SAML security provider exposes a single endpoint. The endpoint receives SAML Responses. This is referred to as the Assertion Consumer Service. A Vinyl Assertion Consumer Service URL might look something like this:
https://example.com/Vinyl/signin-SAML
The URL is composed of the following parts:
| Component | Description |
|---|---|
| https://example.com/Vinyl/ | Absolute URL of the Vinyl application-root directory. |
| SAML | URL-encoded, SAML security provider name. The value is case-sensitive. |
Troubleshooting¶
Error "The AudienceRestrictionCondition was not valid because the specified Audience is not present in AudienceUris."¶
This error indicates that the audience URI does not match. Ensure that the Audience property has been explicitly set. If not set, it will default to the current URL, which may vary by user. The value is case-sensitive.
Known Issues and Limitations¶
The Vinyl SAML Single Sign-On (SSO) security provider has the following limitations:
- Only a single audience restriction may be validated.
- The Artifact resolution protocol is not supported.
- The Logout protocol is not supported.