Skip to Content

Client Authentication

Vinyl can operate as an OpenID Connect (OIDC) authorization server. The authorization server allows client applications, including other instances of Vinyl, to authenticate users. The OIDC sign-in pocess produces an access token that allows the client application to access protected resources on the user's behalf. Protected resources include Vinyl-hosted REST and Webhook APIs, as well as Vinyl Connector data sources.

Protocol Support

The OIDC protocol is defined by the OpenID Connect Core 1.0 standard. OIDC is an identity layer built on top of the OAuth 2.0 authorization framework, which is defined by RFC-6749. Together, these standards describe:

  • Flows - A flow is a process by which the client retrieves identity and access tokens. For this reason, flows are also referred to as grants.
  • Endpoints - Each flow involves one or more HTTP requests to well-known URLs.
  • Scopes - Client applications may request one or more scopes. Scopes determines which tokens are issued (identity, refresh), what's included in those tokens (claims), and which APIs can be accessed with those tokens.
  • Claims - As described by the standard, the identity token is fundamentally a JSON Web Token (JWT). JWTs are claims-based. The requested scope determines which claims are included in the identity token.

Supported Flows

The Vinyl authorization server supports the following, base OAuth 2.0 flows:

  • Authorization Code. The Authorization Code flow allows the client to aquire an access token, which allows the client to access protected resources on the user's behalf. The Authorization Code flow is an interactive flow: a user must be present to initiate the Authorization Code flow.
  • Client Credentials. The Client Credentials flow allows the client application to acquire an access token on behalf of itself. This is a server-to-server flow, typically operating as a service account.
  • Refresh Token. The Refresh Token flow allows the client to request a new access token once the current token has expired. This is sometimes referred to as "offline access." The refresh token flow can be used in combination with either the Authorization Code or Client Credentials flows. The offline_access scope enables the Refresh Token flow (see below).

As noted above, OIDC is built on the OAuth 2.0 authorization framework. OIDC leverages OAuth 2.0 flows, using the scope parameter to opt into OIDC-specific functionality. The Vinyl authorization server supports the following OIDC flows:

  • Authorization Code. When the openid scope is specfied, the Authorization Code flow allows the client to authenticate a user by returning an additional identity token. Additional scopes determine which claims are included in the token.
  • Refresh Token. The Refresh Token flow operates the same in OIDC as it does in OAuth 2.0.

The authorization server does not support either the OIDC Implicit or Hybrid flows. The OAuth 2.0 Client Credentials flow is not an OIDC flow.

The Authorization Code flow can be used with or without the Proof Key for Code Exchange (PKCE) extension, as defined by RFC-7636.

Supported Endpoints

The Vinyl authorization server publishes the following endpoints:

Endpoint Standard Description
/connect/authorize RFC-6749 Issues an authorization code.
/connect/token RFC-6749 Issues an access token.
/connect/introspect RFC-7662 Access token introspection.
/connect/userinfo OIDC Core Identity token introspection.
/.well-known/openid-configuration OIDC Discovery OpenID Connect provider configuration.

Supported Scopes

The Vinyl authorization server supports the following scopes:

Scope Description
openid Issues an OIDC identity token.
profile Includes user profile claims in the identity token.
email Includes email address claims in the identity token.
phone Includes phone number claims in the identity token.
offline_access Issues a refresh token for use in the Refresh Token flow.
* Not available for public clients
api Authorizes access Vinyl-hosted REST, Webhook and Vinyl Connector APIs.

Supported Claims

As noted above, the identity token is a claims-based, JWT token. The client may determine which claims are included in the identity token by specifying scopes.

Scope Claims
openid sub
profile name, nickname, locale and zoneinfo
email email and email_verified
phone phone_number and phone_number_verified

For a description of each of these claims, see section 5.1 Standard Claims of the OIDC standard. Any standard claim not explicitly listed above is unsupported.

Configuration

To make use of the authorization server, the Vinyl administrator must first:

  1. Enable the authorization server.
  2. Register a client application.
  3. Configure the client application.

Enable the Authorization Server

To enable the authorization server, start by signing into Vinyl as an administrator:

  1. Click the IDE link.
  2. Click the Security Providers button.
  3. In the User Authentication panel, locate the Authorization Server security provider and click the Details icon (Chevron).
  4. Click the Edit button.
  5. Check the Enabled option.
  6. Click the Save button.

Register a Client Application

Each client application that intends to authenticate users or access protected resources must be registered. To register a client application, start by signing into Vinyl as an administrator:

  1. Click the IDE link.
  2. Click the User Management button.
  3. Click the Clients button.
  4. Click the +Client button to regsister a new client application.

  5. Provide the following:

    • Name: A descriptive, friendly name for the client application.
    • Description: An optional description.
    • User: Select the service user account. Required for the Client Credentials flow. Otherwise, leave blank.
    • Requires PKCE: When checked, the client must use the PKCE extension. Only applies to the Authorization Code flow, and is required for public clients.

  6. Click the Save button.

Generate a Client Secret

The client application must supply its own credentials when requesting an access token. The client credentials consist of the client ID and a client secret. Client secrets can only be generated for confidential clients. The Secrets panel will be hidden for public clients.

To generate a client secret:

  1. In the Secrets panel, click the +Secret button.

  2. Provide the following:

    • Description: Optional client secret description.
    • Expires On: If the secret should expire, set the expiration date and time. Otherwise, leave this field blank.

  3. Click the Save button.

  4. Copy the Client ID and Client Secret.

WARNING: This is the only time that the secret will be visible.

Register Client Redirect URI

As noted above, the Authorization Code flow is an interative flow. During this flow, the user is redirected to the authorization endpoint. Once the user has authenticated, they are redirected back to the client application.

The client application callback URL is referred to as the "redirect URI." Each redirect URI must be registered. Client redirect URIs must adhere to following restrictions:

  • The client redirect URL must be an absolute URL.
  • The client redirect URL should use the HTTPS protocol. However, the client redirect URL may use the HTTP protocol when redirecting to localhost.
  • The client redirect URL may contain a query string.
  • The client redirect URL must not contain a fragment.

To register a client redirect URI:

  1. In the Redirects panel, click the +URL button.
  2. Provide the URL.
  3. Click the Save button.

Configure the Client Application

Any standards-compliant OIDC or OAuth 2.0 client application that supports either the Authorization Code or Client Credentials flows can utilize the Vinyl authorization server. This includes Vinyl itself: it is possible to configure a second instance of Vinyl as a client.

To configure the Vinyl client, you will need:

  • Vinyl authorization server root URL, e.g. https://example.com/Vinyl.
  • Client ID and secret (see above)

Start by signing into the client instance of Vinyl as an administrator:

  1. Click the IDE link.
  2. Click the Security Providers button.
  3. In the User Authentication panel, click the +User Authentication button.

  4. Provide the following:

    • Name: Security provider name, e.g. Vinyl.
    • Type: Vinyl / OpenID Connect
    • Show On Login Form: Check this option to display the login option on the login form.
    • User Provisioning: Check this option to enable user provisioning.

  5. Click the Save button.

  6. In the Endpoints panel, click the +Endpoint button.

  7. Provide the following:

    • Endpoint Type: OpenID Connect Issuer
    • URL. The Vinyl authorization server root URL.

  8. Click the Save button.

  9. In the Credentials panel, click the +Credential button.

  10. Provide the following:

    • Type: Client
    • User Name: The client ID (see above).
    • Password: The client secret (see above).

  11. Click the Save button.

  12. In the Provider panel, click the Edit button.
  13. Check the Enabled option.
  14. Click the Save button.

Once complete, users will be able to sign into the client Vinyl instance using the Vinyl authorization server.

Known Limitations

The Vinyl authorization server does not support the following

  • User consent.
  • OIDC Implicit or Hybrid flows