Use API Access Management, Okta's implementation of the OAuth 2.0 standard, to secure your APIs. API Access Management is integrated with Okta's implementation of OpenID Connect for authentication. OpenID Connect is also available separately. Similarly, Okta provides a client management API for onboarding, monitoring, and deprovisioning client apps.
For the steps on how to add Okta authentication to your API endpoints, see the Protect your APIs guide.
When do you use API Access Management and when do you use OpenID Connect?
In general, use OpenID Connect to sign users in to apps, and use API Access Management to secure your APIs: create one or more Custom Authorization Servers, define scopes and claims, and create policies and rules to determine who can access your API resources.
You can also specify authorization servers in your OpenID Connect API calls. Every OpenID resource is also available in a version that lets you specify an authorization server that you created in Okta. See OAuth 2.0 and OpenID Connect for details.
Centralizing the management of your APIs makes it easier for others to consume your API resources. Using Okta's OAuth-as-a-Service feature, API Access Management, provides many benefits:
Note: In some places we have implemented stricter requirements or behaviors for additional security.
The following is a high-level look at the basic components of API Access Management. We use the same terms as the OpenID Connect and OAuth 2.0 spec. For complete explanations, read those specs.
The two biggest security benefits of OAuth are using tokens instead of passing credentials and restricting the scope of tokens. Both of these measures go a long way toward mitigating the impact of a security compromise.
Okta helps you manage ID Tokens (OpenID Connect) and Access Tokens (OAuth 2.0).
The JWT specification we use with the OAuth Framework lets you include custom claims in ID and Access Tokens. You can design tokens to disclose the information you want to share depending on the client and the scope of the tokens. For example, a shopping site might have one set of claims for customers while they browse, but another claim for administrator functions like changing their personal information.
Custom claims also help you by reducing the number of lookup calls required to retrieve user information from the identity provider (IdP). This benefit depends, of course, on the level of security your apps require.
API Access Management, or OAuth as a Service, extends Okta's security policies, Universal Directory, and user provisioning into APIs, while providing well-defined OAuth interfaces for developers. Further, while many of our customers use dedicated API gateways such as Apigee or Mulesoft, API Access Management can be used equally well with or without a gateway.
This document represents our recommendations for proper usage based on the OAuth 2.0 specifications, our design decisions, security best practices, and successful customer deployments. Your requirements and constraints may be different, so not every recommendation fits every situation. However, most recommendations fit most scenarios.
All interactions and redirects between the user, the application, and Okta must be secured via HTTPS (SSL/TLS) to ensure credentials and tokens are protected at all times. This is non-negotiable.
An API Product is a group of API endpoints offered together to satisfy a particular set of related use cases. For example, a bank may have a Home Loan API Product and a Personal Line of Credit API Product, both of which use some of the same underlying APIs.
Okta API Products refers to all of the resources and tools that Okta makes available.
Okta provides the API Access Management administrator role to manage authorization servers. A user with this role can perform the following tasks:
Assign one authorization server per API Product. Doing so allows teams to maintain separate authorization policies and token expiration times while eliminating scope name collisions. Authorization servers often reflect use cases at the orchestration layer, not individual endpoints. For example, a banking institution may use one authorization server with a short-lived access token for money transfers but a separate authorization server with a long-lived access token for read-only transaction sync to QuickBooks.
Make the authorization server audience (the
aud claim) specific to the API to reduce the risk of inappropriate access token reuse. A single global audience is rarely acceptable. For example, instead of using
api.company.com for the audience, a better approach is specifying
Define scopes within authorization servers that are granular and specific to the permissions required. A generic administrator scope is rarely appropriate. Java-style namespacing such as
com.okta.product1.admin or Google's URL-based style such as
https://company.com/scopes/product1.admin are common and scalable approaches.
Assign an authorization server policy to specific OAuth 2.0 clients. Use the All Clients option only if no other solution is possible.
Authorization policies and rules are treated as a case or switch statement. Therefore, when a matching rule is found, it is applied and the result is immediately returned. No further rules are executed.
If a request generates unexpected scopes, it is because of an overly broad rule within the authorization server.
An OAuth 2.0 client can be assigned to any number of authorization servers. Doing so provides for a variety of tokens to be generated, each with separate authorization policies, token expiration times, and scopes. The audience claim (
aud) and client ID claim (
cid) identify which token maps to which API Product.
OAuth clients and authorization servers can be assigned on a many-to-many basis. This allows a developer to use a single OAuth client to retrieve access tokens from different authorization servers depending on the use case. The only difference is the endpoints accessed and the scopes requested.
Configure the access token lifetime to reflect the security requirements of the use case. For example, an access token for a banking API may include a
transactions:read scope with a multi-hour lifetime. By contrast, the lifetime of an access token for transferring funds should be only a matter of minutes.
Access tokens should be used exclusively via an HTTP Authorization header instead of encoded into a payload or URL which may be logged or cached.
When a gateway retrieves the JWKS (public keys) to validate a token, it should cache the result until a new or unknown key is referenced in a token.
If the gateway is performing endpoint or HTTP verb-level authorization using scopes, the scopes must be defined and granted in the Okta Authorization Server or Custom Authorization Server before being used in the gateway.
Note: If a user requests scopes from the authorization server that haven't been configured, an error is returned.
Access tokens and refresh tokens are sensitive and should be protected as such. They should never be stored in client-side or frontend code.
A client (application) should never inspect the contents of an access token. For example, do not customize the client's UI based on scopes in the access token.
Access tokens should be used exclusively via an HTTP Authorization header instead of encoded into a payload or URL that may be logged or cached.
Avoid using the resource owner password grant type (
password) except in legacy application or transitional scenarios. The authorization code, implicit, or hybrid grant types are recommended for most scenarios.
For mobile applications, using the authorization code grant type with PKCE is the best practice. The implicit or hybrid grant type is the next best option.
When an application retrieves the JWKS (public keys) to validate a token, it should cache the result until a new or unknown key is referenced in a token.
Never use an access token granted from the Okta Organization Authorization Server for authorization within your applications. These tokens are intended for use with Okta and can't be validated within your application. Instead, use tokens granted from a Custom Authorization Server. Read more about the various types of authorization servers in the OAuth 2.0 and Okta documentation.
aud) and client ID claim (
cid) match the expected audience and client ID.
exp). Do this for validation that is either local or via the introspection endpoint.