Chapter 1. Authentication Patterns
By the end of this tutorial you will know how to set the authentication pattern on your API and the effect that this has on applications communicating with your API.
Depending on your API, you may need to use different authentication patterns to issue credentials for access to your API. These can range from API keys to openAuth tokens and custom configurations. This tutorial covers how to select from the available standard Authentication Patterns.
1.1. Authentication Patterns
3scale supports the following authentication patterns out of the box:
- Standard API Keys: Single randomized strings or hashes acting as an identifier and a secret token.
- Application Identifier and Key pairs: Immutable identifier and mutable secret key strings.
- OpenID Connect
1.2. Step 1: Select the Authentication mode for your service
From the Administration Dashboard, navigate to the API tab and select the service that you want to work on (there may be only one service named API in which case select this). Click on the Integration Link.
Each service that you operate, can use a different authentication pattern, but only one pattern can be used per service.
You must not change the authentication pattern after the credentials have been registered because the behavior of the service may then become unpredictable. To change authentication patterns we recommend creating a new service and migrating customers.
1.3. Step 2: Select the Auth Mode you want to use
Scroll to the Authentication section and choose the required Authentication mode.
1.4. Step 3: Ensure your API accepts the correct types of credentials
Depending on the credential type chosen, you may need to accept different parameters in your API calls (key fields, IDs etc.). The names of these parameters may not be the same as those used internally at 3scale. The 3scale authentication will function correctly if the correct parameter names are used in calls to the 3scale backend.
1.5. Step 4: Create an application to test credentials
To ensure that the credential sets are working, you can create a new application to issue credentials to use the API. Navigate to the Accounts area of your dashboard, click the account you want to use and click new application.
Filling out the form and clicking save will create a new application with credentials to use the API. You can now use these credentials to make calls to your API and records will be checked against the 3scale list of registered applications.
1.6. Standard Authentication Patterns
3scale supports the authentication patterns detailed in the following sections.
1.6.1. API Key
The simplest form of credential supported is the single API model. Here, each application with permissions on the API has a single (unique) long character string; example:
API-key = 853a76f7c8d5f4a1ee8bf10a4e0d1f13
By default, the name of the key parameter is user_key. You can use this label or choose another, such as API-key. If choosing another label, you need to map the value before you make the authorization calls to 3scale. The string acts as both, an identifier and a secret token, for use of the API. It is recommended that you use such patterns only in environments with low security requirements or with SSL security on API calls. Following are the operations that can be carried out on the token and application:
- Application Suspend: This suspends the applications access to the API and, in effect, all calls to the API with the relevant key will be suspended.
- Application Resume: Undoes the effect of an application suspend action.
- Key Regenerate: This action generates a new random string key for the application and associates it with the application. Immediately after this action is taken, calls with the previous token will cease to be accepted.
The latter action can be triggered from the API Administration dashboard and (if permitted) from the API Developers User console.
1.6.2. App_ID and App_Key Pair
The API Key Pattern combines the identity of the application and the secret usage token in one token; however, this pattern separates the two. Each application using the API, issues an immutable initial identifier known as the Application ID (App ID). The App ID is constant and may or may not be secret. In addition, each application may have 1-n Application Keys (App_Keys). Each Key is associated directly with the App_ID and should be treated as secret.
app_id = 80a4e03 app_key = a1ee8bf10a4e0d1f13853a76f7c8d5f4
In the default setting, developers can create up to five keys per application. This allows a developer to create a new key, add it to their code, redeploy their application, and then disable old keys. This does not cause any application downtime the way an API Key Regeneration would.
Statistics and rate limits are always kept at the application ID level of granularity and not per API Key. If a developer wants to track two sets of statistics, they should create two applications rather than two keys.
It is also possible to change the mode in the system and allow applications to be created in the absence of application keys. In this case the 3scale system will authenticate access based on the App ID only (and no key checks are made). This mode is useful for widget type scenarios or where rate limits are applied to users rather than applications. In most cases you will want your API to enforce the presence of at least one application key per application present (this setting is available in the Settings menu under usage rules).
1.6.3. OpenID Connect
For information on OpenID Connect authentication, see the OpenID Connect integration section.
1.7. Referrer Filtering
3scale supports the Referrer Filtering feature that can be used to whitelist IP addresses or domain names from where an application can access the API. The API clients specify the referrer value in the Referer header. The purpose and the usage of the Referer header are described in the RFC 7231, section 5.5.2: Referer.
To enable the Referrer Filtering feature go to API > {selected API} > Settings, click the Require referrer filtering checkbox and click Update Service.
The developers with access to your API must configure allowed domain/IP referrers from the developer portal.
In the Admin Portal on the application details page for all applications that belong to this service a new Referrer Filters section displays. Here, the admin can also configure a whitelist of the allowed Referrer header values for this application.
You can set a maximum of five referrer values per application.
The value can only consist of Latin letters, numbers, and special characters *, ., and -. * can be used for wildcard values. If the value is set to *, any referrer value will be allowed, so the referrer check will be bypassed.
For the Referrer Filtering feature to work, the APIcast Referrer policy must be enabled in the service policy chain.
When the Require referrer filtering feature and the 3scale Referrer policy are enabled, the authorization works as follows:
- The applications that do not have Referrer Filters specified are authorized normally only using the provided credentials.
-
For the applications that have Referrer Filters values set, APIcast extracts the referrer value from the
Refererheader of the request and sends it asreferrerparam in the AuthRep (authorize and report) request to the Service Management API. The following table shows the AuthRep responses for different combination of the referrer filtering parameters.
referrer parameter passed? | Referrer Filters configured for the app? | Referrer parameter value | HTTP Response | Response body |
|---|---|---|---|---|
| Yes | Yes | matches referrer filter | 200 OK |
|
| Yes | No | matches referrer filter | 200 OK |
|
| Yes | Yes | does not match referrer filter | 409 Conflict |
|
| Yes | No | does not match referrer filter | 200 OK |
|
| Yes | Yes |
| 200 OK |
|
| Yes | No |
| 200 OK |
|
| No | Yes | — | 409 Conflict |
|
| No | No | — | 200 OK |
|
The calls that are not authorized by AuthRep are rejected by APIcast with an "Authorization Failed" error. You can configure the exact status code and the error message on the service Integration page.
