Security Provider - OAuth¶

The OAuth security provider enables support for OAuth 2.0. The security provider is responsible for authorizing web service requests. The following data source types support OAuth:

REST
OData
RDBMS (limited to supported CData providers)

In addition, it is possible to configure an OAuth security provider as an external authentication provider. See below for additional information.

OAuth 2.0 Grants¶

The OAuth security provider supports the following OAuth 2.0 grants:

Authorization Code RFC 6749
Client Credentials RFC 6749
Resource Owner Password Credentials RFC 6749
SAML 2.0 Bearer Assertion RFC 7522
JWT Bearer Token RFC 7523

Authorization Code¶

The OAuth 2.0 Authorization Code grant provides delegated, user-level authorization. This grant is defined in RFC 6749.

In the Authorization Code flow, Vinyl redirects the user agent (browser) to the authorization server. Once the user has successfully signed in and approved the authorization request, the authorization server redirects the user agent back to Vinyl. The redirect includes an authorization code. Vinyl makes a back-channel request to the authorization server, exchanging the authorization code for an access token. The access token can then be used to authorize requests to web services.

In and of itself, OAuth provides authorization, not authentication. Therefore, OAuth security providers are not typically used as external authentication providers: they are used to authorize requests to a compatible data provider such as OData or REST. However, if the OAuth security provider publishes an endpoint which provides the user identity, the OAuth security provider can be used as an external authentication provider. See the User Info Endpoint for additional details.

Client Credentials¶

The OAuth 2.0 Client Credentials grant provides client-level authentication, akin to a service account. In this flow, the OAuth client credentials are exchanged for an OAuth access token. The Client Credentials grant is defined in RFC 6749.

Resource Owner Password Credentials¶

The OAuth 2.0 Resource Owner Password Credentials grant is defined in RFC 6749. However, the grant has since been deprecated.

The resource owner password credentials grant MUST NOT be used.

As originally conceived, the OAuth 2.0 Resource Owner Password Credentials grant provides user-level authorization. The user supplies his or her user name and password to a trusted client. The trusted client exchanges the credentials for an access token.

Vinyl provides partial support for the OAuth 2.0 Resource Owner Password Credentials grant. Vinyl does not prompt the user for their credential. Instead, a single credential is used to authorize all users. In this way, the grant is functionally equivalent to a service account.

SAML 2.0 Bearer Assertion¶

The OAuth 2.0 SAML 2.0 Bearer Assertion grant provides user-level, data source authentication. In this flow, SAML assertions are exchanged for OAuth access tokens. The OAuth 2.0 SAML 2.0 Bearer Assertion grant is defined in RFC 7522.

JWT Bearer Token¶

The OAuth 2.0 JWT Bearer Token grant provides user-level, data source authentication. In this flow, JSON Web Tokens (JWTs) are exchanged for OAuth access tokens. The OAuth 2.0 JWT Bearer Token grant is defined in RFC 7523.

Configuration¶

Configuration varies based on the OAuth grant. At a minimum, OAuth requires:

Client identifier (client_id) and client secret (client secret)
Token endpoint

Individual OAuth grants will require additional configuration as indicated below.

Authentication¶

The authentication properties determine the OAuth grant and authentication schemes.

Authentication Type: OAuth
OAuth Grant: Select a supported OAuth grant.
OAuth Client Authentication: Determines the OAuth 2.0 client authentication scheme RFC 6749 Section 2.3. Options include:
- None - Indicates that the client should not be authenticated. (none)
- Basic - Indicates that the Client Password scheme will be used. The credentials will be supplied using HTTP Basic authentication. (client_secret_basic)
- Post - Indicates that the Client Password scheme will be used. The credentials will be supplied as form parameters in the request body. (client_secret_post)
OAuth Resource Authentication: Determines the resource request authentication scheme. Options include:
- Bearer - Bearer authentication scheme. Default.
- Form - Append access token to form url-encoded body.
- Query - Append access token to query string.
Token Owner: Determines whether tokens are issued to individual users or to the client system. Options include:
- User - Tokens are issued to individual users.
- Client - Tokens are issued to the client system.
Token Delete On Sign Out: When enabled, Vinyl deletes the stored token when the user logs out. Default: Disabled. Version: 3.3.34523+.

Token¶

The following grants generate tokens which are exchanged for OAuth access tokens:

SAML 2.0 Bearer Assertion
JWT Bearer Token

SAML 2.0 Bearer Assertion¶

Issuer: The SAML assertion issuer.
Audience: The SAML assertion audience restriction. Though the SAML specification indicates that the audience is a URI, many implementations do not honor this. Consequently, Vinyl does not require the audience to be a URI.
Recipient: The SAML assertion recipient URI (e.g. http://example.com/service).

JWT Bearer Token¶

Issuer: JWT issuer claim (https://tools.ietf.org/html/rfc7523#section-3). Defaults to the client identifier (client_id).
Subject: JWT subject claim (https://tools.ietf.org/html/rfc7523#section-3).
- If the Token Owner is User, defaults to the current user's identity.
- If the Token Owner is Client, the Subject is required.
Audience: JWT audience claim (https://tools.ietf.org/html/rfc7523#section-3). Defaults to the Token Endpoint.

Endpoints¶

Type	Grants	Description
Authorization Endpoint	Authorization Code	OAuth 2.0 authorization endpoint URL. RFC 6749
Token Endpoint	All	OAuth 2.0 token endpoint URL. RFC 6749
User Info Endpoint	Authorization Code	Endpoint that supplies the user identity. Required when treating OAuth as an external authentication provider. Not part of the OAuth standard. The endpoint must return a JSON response which includes the user identity.

Credentials¶

Type	Grants	Description
Client	All	OAuth 2.0 client identifier (`client_id`) and secret (`client_secret`). RFC 6749
Resource Owner	Resource Owner Password Credentials	OAuth 2.0 resource owner user name (`username`) and password (`password`). RFC 6749

Certificates¶

Type	Grants	Description
Signing	SAML 2.0 Bearer Assertion JWT Bearer Token	The SAML 2.0 Bearer Assertion grant requires an X.509 certificate with private key in a password-protected PKCS#12 (.pfx) container. The JWT Bearer Token grant requires a PEM-encoded, PKCS#1 RSA private key (`RSA PRIVATE KEY`).

Properties¶

The OAuth security provider supports the following additional parameters:

Parameter	Default	Example
BearerSchemeIdentifier	`Bearer`		`Authorization` scheme when using the Bearer resource authentication.
ExpiresIn		`3600`	Access token expiry in seconds. Can be used if the token endpoint does not provide an expiry and the the resource server does not return a `401 Unauthorized` response when the access token has expired.
IgnoreTlsErrors	`False`		Indicates whether Vinyl should ignore TLS errors when making back-channel requests to the token endpoint. This should only be used for development and testing.
Scopes			Whitespace delimited list of OAuth 2.0 access token scopes. RFC 6749
SingleUseAccessToken	`False`		Indicates whether the access token can only be used once.
Token Endpoint Parameters			Parameters passed to the OAuth token endpoint. By default, Vinyl will generate the appropriate parameters based on the OAuth flow. Only use this setting for non-conformant or otherwise unsupported OAuth APIs. The parameters should be specified in form URL encoded format (`application/x-www-form-urlencoded`). If the parameter list begins with an ampersand (&), the parameters will be merged into the generated parameters. If a parameter has the same name as a generated parameter, the generated parameter will be overwritten. If a supplied parameter does not have a value, e.g. `&grant_type&username=user&password=password`, the generated parameter will be removed. Otherwise, the supplied parameter is appended to the generated parameters. The parameter list supports string interpolation. Expressions may reference dynamic parameters, e.g `username={{ client_id }}&password={{ client_secret }}`. This is useful when integrating with third-party APIs that do not use standard parameter names.

Authorization Code¶

The following additional properties apply to the Authorization Code grant.

Parameter	Default	Example
BackchannelAuthorization	`False`		Indicates whether an authorization code can be acquired via a backchannel (server-to-server) request. This is a non-standard extension to the Authorization Code grant.

SAML 2.0 Bearer Assertion¶

The following additional properties apply to the SAML 2.0 Bearer Assertion grant.

Parameter	Default	Example
SamlSingleSignOnProvider			Name of a Vinyl SAML security provider. This parameter only applies to the SAML 2.0 Bearer Assertion grant.

JWT Bearer Token¶

The following additional properties apply to the JWT Bearer Token grant.

Parameter	Default	Example
JwtClaimSet	`{ "scope": "{{ scope }}" }`		Authorization servers may require custom claims. For example, Google requires a scope claim matching the OAuth scope parameter. The JwtClaimSet parameter allows administrators to supply additional claims. The value takes the form of a JSON template. The following values may be substitued into the template: client_id - OAuth client_id parameter. client_secret - OAuth client_secret parameter. scope - OAuth scope parameter. sub - JWT sub claim. iss - JWT iss claim. aud - JWT aud claim.
SigningAlgorithm	`RS256`		JWT algorithm parameter as defined in RFC 7518. The only supported algorithm is `RS256`.

REST¶

The following additional properties apply when the OAuth security provider is used to authenticate REST data sources. These are ignored for OAuth endpoints and other types of data sources, including OData and RDBMS.
Request Headers must be separated by a carriage return (appear on its own line).

Parameter	Default	Example
RequestHeaders		`X-Custom-Header: Value X-Another-Header: Value`	Custom HTTP headers appended to REST endpoint requests. The headers must be formatted according to RFC 7230. Line folding is not supported.

Protocol Support¶

Refresh Tokens¶

If the access token request includes a refresh token, Vinyl will automatically attempt to use the refresh token to acquire a new access token after receiving a 401 Unauthorized response.

Authorization Code¶

Authorization Request¶

When constructing an authorization request, Vinyl will include the client identifier (client_id), client secret (client_secret) and scopes (scope). In addition, Vinyl will automatically append the following standard parameters:

redirect_uri - Vinyl constructs the redirect_uri parameter from the current URL. It takes the form https://example.com/Vinyl/signin-OAuth, where OAuth is the name of the OAuth security provider.
state - The state parameter is an encrypted, opaque payload. It includes a Cross-Site Request Forgery (CSRF) token as per RFC 6749.

Redirection Endpoint¶

As defined in RFC 6749, the Authorization Code grant exposes a Redirection Endpoint. This endpoint listens for authorization responses on the address:

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

Where https://example.com/Vinyl is the absolute URL to the Vinyl application root directory and OAuth is the URL-encoded, case-sensitive name of the security provider.

Most third-parties applications will need to be configured with the redirection endpoint prior to authorizing any requests.

Using OAuth for external authentication¶

As noted above, OAuth is an authorization protocol, not an authentication protocol. However, some vendor implementations extend the OAuth protocol to include authentication. Typically, this is done by publishing an endpoint which identifies the user. Vinyl refers to such an endpoint as the User Info Endpoint.

Vinyl can be configured to query the User Info Endpoint to retrieve the user's identity. This allows an OAuth security provider to be used for external authentication. Note, however, that the endpoint must meet the following requirements:

The endpoint must be reachable by Vinyl.
The endpoint must respond to an HTTP GET request that does not include a request body.
The endpoint must honor OAuth Basic client authentication (as described above).
The HTTP response must have a 200 status code.
The HTTP response must include a body with a Content-Type of application/json.
The JSON document must include a top-level property which identifies the user.

After acquiring the access token, Vinyl will make a client authenticated request to the User Info Endpoint. Vinyl will parse the response body as JSON, treating top-level properties as claims.

For instance, given the following sample response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "user_name": "arthur.dent",
    "name": "Arthur Dent",
    "email": "arthurdent@example.com"
}

The following claim types will be available:

user_name
name
email

In addition to specifying the User Info Endpoint, the developer must map the claim that identifies the user–in this case, the user_name claim–to the Name claim usage type.

SAML 2.0 Bearer Assertion¶

When using the SAML 2.0 Bearer Assertion flow, SAML assertions can be sourced in one of two ways:

Vinyl generates and signs the SAML assertions on demand. In which case, Vinyl acts as the IdP.
[DEPRECATED] A third-party Identity Provider (IdP) issues a SAML assertion during the SAML Single Sign-On (SSO) process. See the SAML provider type for more information.

Each source requires additional configuration.

Generate SAML assertions on-demand¶

To generate a SAML assertion on demand, configure the Token properties as described above. In addition, the SAML 2.0 Bearer Assertion grant requires a Signing certificate with a private key.

Source SAML assertions from an IdP¶

To source SAML assertions from a third-party IdP, set the SamlSingleSignOnProvider parameter.