For Use with Red Hat 3scale 2.2
Chapter 1. Authentication Patterns
By the time you complete this tutorial you’ll know how to set the authentication pattern on your API and the effect 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 between the standard Authentication Patterns Available.
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.
- OAuth 2.0: OAuth 2.0 client id, client secret and access token combinations.
3scale also offers commercially reasonable support for coupling issues credentials with IP address filtering or referrer domain filtering – see the extra section at the end of this tutorial.
1.3. Step 1: Select the Authentication mode for your service.
Once in your Administration Dashboard, navigate to the API tab and select the service you wish to work on (there may be only one service named API in which case select this). Click on the Integration Link.
Note that each service you operate could use a different authentication pattern, but only one pattern can be used per service.
It is not recommended you change the authentication pattern once credentials have already been registered since behavior may be unpredictable. To change authentication patterns we recommend creating a new service and migrating customers.
1.4. Step 2: Select the Auth Mode you want to use
Scroll down to the Authentication section an choose the required Authentication mode.
1.5. Step 3: Ensure your API accepts the right types of Credentials
Depending on the credential type chosen, you will likely need to accept different parameters in your API calls (key fields, IDs etc.). The names of these parameters need not be the same as those used internally at 3scale, your 3scale authentication will function correctly just as long as the correct parameter names are used in calls to the 3scale backend.
1.6. Step 4: Create an application to test credentials
In order to test 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 on the account you wish to use and click the new application button.
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 3scale list of registered applications.
1.7. Standard Authentication Patterns
3scale supports the following authentication patterns out of the box.
1.7.1. API Key
The simplest form of credentials supported is the single API model. Here each application with permissions on the API has a single (unique) long character string something like this:
API-key = 853a76f7c8d5f4a1ee8bf10a4e0d1f13
By default the name of the key parameter is
user_key. You can use this same label or choose another such as
API-key in which case you simply need to map the value over 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 such patterns are only used either in environments with low security requirements or with SSL security on API calls. The operations which can be carried out on the token and application are:
- 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.7.2. App_ID and App_Key Pair
Whereas the API Key Pattern combines the identity of the application and the secret usage token in one token, 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 are able to create up to 5 keys per application. This allow a developer to create a new key, add it to their code redeploy their application and then disable old keys – causing no application downtime as an API Key Regeneration would.
Note that statistics and rate limits are always kept at the application ID level of granularity and not per API Key. If a developer wishes to track two sets of statistics, they should create two applications rather than two keys.
It is also possible to change mode in the system and allow applications to be created without applications keys present. 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 (for example) widget type scenarios or where rate limits are applied to users rather than applications. Note that in most cases you will want your API to enforce there to be at least one application key per application present (this setting can be found on the Settings menu item under usage rules).
1.7.3. openAuth Support
openAuth is a set of specifications which enable a variety of different authentication patterns for APIs. The two major versions released so far (v1 and v2) are significantly different and version 2 includes a number of different supported authentication flows.
1.7.4. More Information
If you have authentication needs which are not covered by this how to, let us know by contacting support.
In addition, 3scale supports coupling credentials with authorized IP ranges per key or referrer domains per key to restrict where specific API credentials can be used. You can enable this additional filtering by navigating to the API Tab and accessing the Settings screen on the API.
Chapter 2. 3scale integration with Red Hat Single Sign-On using OpenID Connect
3scale can synchronize client credentials between 3scale (Application credentials) and a Red Hat Single Sign-On server using OpenID Connect (OIDC). 3scale utilizes a service called Zync to synchronize calls to the Red Hat Single Sign-On server.
- 3scale 2.2
- A Red Hat Single Sign-On version as specified on the Supported Configurations page
In order to connect 3scale and Red Hat Single Sign-On, perform the following configurations in your Red Hat Single Sign-On server and 3scale:
2.2. Configure Red Hat Single Sign-On
- Create a realm
Create a client:
- Specify a client ID
Configure client permissions, setting the following:
Access Typeto confidential
Standard Flow Enabledto OFF
Direct Access Grants Enabledto OFF
Service Accounts Enabledto ON
Set service account roles for your client
- Navigate to the service account roles tab of your client
In the client roles dropdown, select
In the available roles pane, select the
manage-clientslist item and assign the role by clicking
Note client credentials
- Take note of the client ID
Navigate to the
Credentialstab of your client and take note of the secret
2.3. Configure 3scale
Once you have created and configured a server and client in Red Hat Single Sign-On, you must configure 3scale to work with Red Hat Single Sign-On:
- Select the service on which you want to enable Red Hat Single Sign-On, navigate to the APIs → <your_service_name> → integration page
- On that page, select edit integration settings
Authenticationdeployment options, select
- Update the service
Edit Your APIcast Configuration
- navigate to the APIs → <your_service_name> → integration page
- On that page, select edit APIcast configuration
Under the Authentication Settings expandable heading, in the OpenID Connect Issuer field, enter your previously noted client credentials with the URL of your Red Hat Single Sign-On server:
- Save your configuration
2.4. Test Integration
Peform the following procedures in 3scale and verify the results in Red Hat Single Sign-On to test your integration:
|3scale Procedure||Red Hat Single Sign-On Result|
Create an application for the service where you configured the OpenID Connect Issuer. Note the Client ID and client secret generated for the application
The new client appears in the Red Hat Single Sign-On realm you are using
Change the Redirect URL on the application in 3Scale
The Redirect URL was updated
Delete the application
The client is deleted from the realm