Security Provider - WS-Federation¶
The WS-Federation security provider enables Single Sign-On (SSO) authentication with supported WS-Federation Identity Providers (IdPs), including Microsoft Azure Active Directory (AD) and Active Directory Federation Services (AD FS). Additional information regarding WS-Federation is available in the following documents:
Configuration¶
Tokens¶
- Audience: Audience restriction. Although the standard requires a syntactically valid URI, Vinyl will accept non-URI values to integrate with nonconforming implementations. Defaults to the Entity ID.
- Recipient: Ws-Federation reply URL (Wreply). Defaults to the current URL. See Wreply Endpoint below.
- Entity ID: WS-Federation security realm URI (Wtrealm). In Microsoft Azure, this is referred to as the App ID. In AD FS, this is referred to as the Identifier. Required.
Caution
In earlier versions of Vinyl, Entity ID defaulted to the application-root URL (e.g. https://example.com/Vinyl/). Entity ID is now required.
Endpoints¶
| Type | Description |
|---|---|
| Metadata Endpoint | WS-Federation metadata URL, e.g. https://fs.example.com/FederationMetadata/2007-06/FederationMetadata.xml. Required. |
Properties¶
The WS-Federation security provider defines the following parameters:
| Parameter | Default | Description |
|---|---|---|
| IgnoreTlsErrors | False | Indicates whether Vinyl should ignore TLS errors when connecting to the WS-Federation metadata URL. This should only be used for development and testing. |
| ClockSkew | 5 | Maximum number of minutes to allow for out-of-sync server clocks when validating the SAML assertion. |
| LogPII | False | Indicates that personally identifiable information (PII) should be logged. This setting takes effect on startup. |
Claims¶
WS-Federation is fundamentally a claims-based authentication protocol. The WS-Federation security provider recognizes the following claims:
| 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.microsoft.com/ws/2008/06/identity/claims/groupsid | Group | Security group membership. |
| http://schemas.microsoft.com/ws/2008/06/identity/claims/groups | 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. |
Integration¶
Wreply Endpoint¶
The WS-Federation security provider exposes a single endpoint which listens for HTTP requests bearing a security token. The address takes the following form:
https://example.com/Vinyl/signin-WSFederation
The URL is composed of the following parts:
| Component | Description |
|---|---|
| https://example.com/Vinyl/ | Absolute URL to the Vinyl application-root directory. |
| WSFederation | URL-encoded, Ws-Federation security provider name. The value is case-sensitive. |
Known Issues and Limitations¶
The Vinyl WS-Federation security provider has the following limitations:
- Only a single audience restriction may be validated.
- The Logout protocol is not supported.