Security Provider - API Key¶
The API Key security provider allows administrators to secure Vinyl REST APIs using "API keys". An API key is a code generated by Vinyl. The consumer passes the API key to Vinyl when making REST API requests. Because each API key is associated with an individual user, this provides both authentication and authorization.
API keys vs. user name and passwords¶
An API key is similar to a user name and password in that it's a secret shared between the client and server. API keys share several weaknesses with user name and password authentication schemes like HTTP Basic Authentication:
- API keys can be leaked.
- API key distribution can be difficult to manage.
However, API keys have advantages over user names and passwords:
- API keys have greater entropy than user name / password combinations.
- API keys can survive a password reset.
- API keys can be easily revoked.
- API keys can be rotated.
- API keys are faster. Passwords must be hashed, which is deliberately slow.
API key uses¶
Despite the weaknesses of API keys, they may still be appropriate for certain scenarios, including:
- Service-level accounts
- Application-to-application communication
- Server-to-server communication
- Read-only access
- Non-sensitive information
API key material¶
Vinyl's API keys consist of a 128 bit, cryptographically random number. The keys are base64url encoded.
The following is an example of an API key:
DLOo9sPS5slJEMHpXBFt3g
Configuration¶
Parameters¶
The API Key security provider defines the following parameters:
| Parameter | Default Value | Description |
|---|---|---|
| AllowApiKeyInQueryString | False | Indicates whether the security provider should accept API keys passed in the query string. By default, the security provider will only allow API keys to be passed in the HTTP request headers. See below for more information. |
| AllowUnsafeHttpConnections | False | Indicates whether the security provider should accept API keys submitted via an insecure, HTTP request. By default, the security provider will only allow API keys to be passed over a secure, HTTPS connection. See below for more information. |
HTTP header vs. query string¶
Typically, the client will pass the API key via a custom header. The header must be named X-API-Key. This limits risk of exposure. For instance, in contrast to query string parameters, HTTP headers are rarely logged to disk.
The following example demonstrates how to pass the API key as an HTTP header:
GET /Vinyl/rest/v1/sales/customers HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g
Some clients may not have access to the HTTP request headers. If this is the case, and no other workaround is available, security administrators may enable the AllowApiKeyInQueryString option. This will force Vinyl to accept the API key as a query string parameter. The query string parameter must be named apiKey.
The following example demonstrates how to pass the API key as a query string parameter:
GET /Vinyl/rest/v1/sales/customers?apiKey=DLOo9sPS5slJEMHpXBFt3g HTTP/1.1
HOST: example.com:443
Accept: application/json
Note that there is a potential conflict here. When querying the REST API, query string parameters typically map to resource field names. If API keys can be passed as a query string parameter, then resources cannot have a field named "apiKey".
HTTPS vs. HTTP¶
To prevent against man-in-the-middle attacks, API keys must be passed across a secure, HTTPS connection. Vinyl enforces this by ignoring API keys passed over HTTP.
However, in some environments, the HTTPS connection may be terminated prior to the web server. In this scenario, security administrators can enable the AllowUnsafeHttpConnections option to force Vinyl to accept API keys sent across insecure, HTTP connections.