Security provider - OAuth¶

The OAuth security provider integrates with third-party applications using the OAuth 2.0 Authorization Code Grant Flow as documented in the OAuth 2.0 standard: https://tools.ietf.org/html/rfc6749

In this flow, Vinyl redirects the user agent to the authorization server. Once the user has successfully signed into the authorization server and approved the authorization request, the user agent is redirected 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 UserInfoEndpoint for additional details.

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.

Configuring OAuth¶

Vinyl supports the OAuth 2.0 Authorization Framework (https://tools.ietf.org/html/rfc6749). Specifically, Vinyl's OAuth security provider can work in conjunction with the HTTP and OData security providers to authorize access to REST and OData resources using Authorization Code flow (https://tools.ietf.org/html/rfc6749#section-1.3.1). In this flow, Vinyl assumes the role of "client", delegating authentication to an OAuth authorization server.

Authentication vs. authorization¶

Unlike most other security providers, the OAuth security provider is an authorization provider. OAuth, by itself, does not identify a user. Instead, the OAuth sign-in process produces a token that can be used to access resources on a user's behalf. Consequently, OAuth cannot typically be used to authenticate users. Instead, it's used to extend an authenticated user's authorization.

In practical terms, this means that an OAuth security provider cannot be presented as a sign-in option on the login form (i.e. Show On Login Form). Instead, users will be prompted to sign-in with the OAuth security provider when they attempt to access a resource (REST or OData) that requires an OAuth authorization. In this scenario, Vinyl will issue a "challenge". The web client will intercept the challenge and redirect the browser to the login form. However, if the Redirect On Challenge is enabled, the web client will bypass the login form, redirecting the user to the OAuth provider.

Note, however, that some vendors have extended the OAuth protocol to include authentication. Typically, this is accomplished by publishing a separate endpoint which identifies the user. Although not part of the OAuth standard, Vinyl supports these authentication protocols as long as the endpoint meets several requirements. See the OAuth security provider documentation for additional information.

Integrating with OAuth providers¶

Many cloud services and APIs support OAuth 2.0. The steps to setup and configure OAuth vary based on the provider. However, the fundamental procedure is the same.

1. Determine the Redirect URI.
2. Register Vinyl as a client application with the OAuth provider.
3. Create the OAuth provider within Vinyl.
4. Create a data source authentication provider (HTTP or OData) within Vinyl.
5. Create a data source server (REST or OData) that utilizes the data source authentication provider.

Determine the redirect URI¶

The OAuth authorization endpoint (https://tools.ietf.org/html/rfc6749#section-4.1.1) defines a redirect_uri parameter (https://tools.ietf.org/html/rfc6749#section-3.1.2). This is sometimes referred to as a "callback" URL. The redirect_uri is defined by Vinyl. It's an absolute URL to which users will be redirected after signing in with the OAuth provider.

A redirect_uri will look something like this:

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

This example assumes that Vinyl is hosted at the following URL:

https://example.com/Vinyl/

The remainder of the redirect_uri takes the following form:

signin-<provider-name>

Where <provider-name> is the name of the Vinyl security provider. In the example above, the provider name is Acme. Note that the name must be URL encoded as per RFC 3986 (https://tools.ietf.org/html/rfc3986).

Therefore, to determine the redirect_uri, you will need to know the following:

• The Vinyl root URL.
• The security provider name.

Register Vinyl as a client application with the OAuth provider¶

As noted above, Vinyl is an OAuth client. OAuth clients must be preregistered with the authorization server. The procedure varies by provider.

That said, the registration process will require the redirect_uri. Once the registration is complete, the OAuth provider will supply values for the following OAuth parameters:

• client_id - The client_id parameter identifies the Vinyl client.
• client_secret - The client_secret is used to authenticate access token requests.
• scope - The scope parameter is used to limit authorization. The scope parameter is optional and often unused.

In addition to the aforementioned OAuth parameters, Vinyl will require the following endpoints:

• Authorization endpoint - Vinyl will redirect user agents to the authorization endpoint. Example: http://example.com/oauth/authorize
• Token endpoint - Vinyl will make a back-channel request to the token endpoint to exchange an authorization code for an access token. Example: http://example.com/oauth/token

Typically, these endpoints are not specific to the client and can be found in the OAuth provider's documentation.

Create the OAuth provider within Vinyl¶

To create an OAuth provider, start by signing into Vinyl as an administrator.

1. Navigate to the Control Center
2. Click the Security Providers button
3. In the Data Source Authentication panel click the Create button

4. Provide the following:

   • Name: {OAuth Provider Name}

     Example: Acme

   • Type: OAuth

   • Priority: A unique integer between 10 and 100. Note that this value must be unique.

     Example: 50

   • Enabled: Check

5. Click the Save button

6. Set the following properties. In the Properties panel, click the Create button → Select the Parameter → Provide the Value → Click the Save icon.

   • AuthorizationEndpoint: The authorization endpoint URI supplied by the OAuth provider.

     Example: http://example.com/oauth/authorize

   • TokenEndpoint: The token endpoint URI supplied by the OAuth provider.

     Example: http://example.com/oauth/token

   • ClientId: The client_id parameter supplied by the OAuth provider.

   • ClientSecret: The client_secret parameter supplied by the OAuth provider.

Create a data source authentication provider (HTTP or OData) within Vinyl¶

To create a data source authentication provider, start by signing into Vinyl as an administrator.

1. Navigate to the Control Center
2. Click the Security Providers button
3. In the Data Source Authentication panel, click the Create button

4. Provide the following:

   • Name: {Data Source Provider Name}

     Example: AcmeDS

   • Type: HTTP or OData

   • Priority: A unique integer between 10 and 100. Note that this value must be unique.

     Example: 60

   • Enabled: Check

5. Click the Save button

6. Set the following properties. In the Properties panel, click the Create button → Select the Parameter → Provide the Value → Click the Save icon.

7. AuthenticationType: AuthorizationCode

8. OAuthProvider: {OAuth Provider Name}

   Example: Acme

Create a data source server (REST or OData) that utilizes the data source authentication provider.

Setting up and configuring a data source server is beyond the scope of this document. Refer to specific examples for further information.

OAuth 2.0 grants¶

Authorization code flow (delegated)¶

The OAuth 2.0 Authorization Code flow provides user-level authentication. In this flow, authorization codes are exchanged for OAuth access tokens. The OAuth 2.0 Authorization Code flow is standardized in RFC 6749.

Unlike the Anonymous and HTTP Basic authentication schemes, the Authorization Code flow must be explicitly enabled. This is done by associating a data source with an OData security provider that has an authentication type of "AuthorizationCode".

Furthermore, the OAuth authorization code flow works in conjunction with an OAuth security provider. The OAuth security provider is responsible for authorizing the user and exchanging authorization codes for access tokens.

Configuration¶

Parameters¶

The following parameters enable and configure the OAuth 2.0 Authorization Code flow:

Client credentials flow¶

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

Configuration¶

Parameters¶

The following parameters enable and configure the OAuth 2.0 Client Credentials flow:

JSON web token bearer token flow¶

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

Configuration¶

Parameters¶

The following parameters enable and configure the OAuth 2.0 JWT Bearer Token flow:

Resource owner password credentials flow¶

The Resource Owner Password Credentials flow is defined in RFC 6749. However, the flow 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 flow. Vinyl does not prompt the user for his or her credentials. Instead, a single set of credentials is used to authorize all users. In this way, it is functionally equivalent to a service account.

Configuration¶

Parameters¶

The following parameters enable and configure the OAuth 2.0 Resource Owner Password Credentials flow:

SAML 2.0 bearer assertion flow¶

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

Configuration¶

Parameters¶

The following parameters enable and configure the OAuth 2.0 SAML 2.0 Bearer Assertion flow:

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

1. A third-party Identity Provider (IdP) will issue SAML assertion during the SAML Single Sign-On (SSO) process. See the SAML provider type for more information.
2. Vinyl can generate and sign the SAML assertions on demand. In which case, Vinyl acts as the IdP.

Each source requires additional configuration.

Sourcing SAML assertions via a third-party IdP¶

Generating SAML assertions on demand¶

Configuration¶

The OAuth security provider exposes a single endpoint, listening for authorization responses on the address:

• https://example.com/Vinyl/signin-{Provider}

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

The OAuth standard defines this URI as the "Redirection Endpoint": https://tools.ietf.org/html/rfc6749#section-3.1.2

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

Parameters¶

The OAuth security provider defines the following parameters:

Protocol support¶

When constructing an authorization request, Vinyl will include the client ID (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 collection of name/value pairs. It includes a Cross-Site Request Forgery (CSRF) token as per https://tools.ietf.org/html/rfc6749#section-10.12

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 UserInfoEndpoint.

Vinyl can be configured to query the UserInfoEndpoint 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 UserInfoEndpoint. 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 UserInfoEndpoint, the developer must map the claim that identifies the user–in this case, the user_name claim–to the Name claim usage type.