Access Policy Manager® (APM®) supports OAuth 2.0 only. When configured as an OAuth client and resource server, APM has been tested with these OAuth authorization servers:
For compatibility information, see release notes for APM on the AskF5™ web site located at support.f5.com.
APM also supports the configuration of custom providers, that is, external OAuth 2.0 authorization servers that F5 has not tested. Custom providers should comply with RFC 6749.
OpenID Connect adds an identity layer on top of OAuth 2.0. When configured as an OAuth client / resource server, Access Policy Manager (APM) can interact with an OpenID Connect provider to get this data:
When configured as an OAuth client, Access Policy Manager® (APM®) supports authorization code and resource owner password credentials grant types.
To configure Access Policy Manager® (APM®) as an OAuth client and resource server, first you must create these objects: OAuth providers, OAuth servers, and OAuth requests. Then, you must configure APM policies with agents that reference the objects to get tokens, get permission for scopes, and retrieve scopes.
An OAuth provider configuration object specifies an external OAuth authorization server type and settings to support opaque access tokens, JSON web tokens, and ID Tokens and OpenID Connect UserInfo requests for those providers that support OpenID Connect.
An OAuth server specifies an OAuth provider and the OAuth role that Access Policy Manager® (APM®) plays with that provider. It also specifies the IDs, secrets, and SSL certificates that APM requires to communicate with the OAuth provider.
In Access Policy Manager® (APM®), the request object enables configuration of requests to meet the requirements of your OAuth providers. The object supports requests for scope permission, scope data, authorization redirect, tokens, and OpenID Connect UserInfo. It specifies the HTTP method, parameters, and headers to use for the specific type of request.
An OAuth Client agent is a policy item that requests authorization and tokens from an OAuth server. An OAuth Client can also get scope data on a per-request basis. The OAuth Client agent provides these configuration elements and options:
For the Authorization code grant type, an OAuth authorization server prompts the user to grant or deny access to the scopes. For the Password grant type, an OAuth authorization server grants permission to the requested scopes based on the user providing resource owner password credentials.
The OAuth Scope agent validates JSON web tokens (JWT) or validates scopes for opaque tokens. The OAuth Scope item provides these elements and options:
In External mode, there can be multiple scope data requests in this agent with these elements:
Register Access Policy Manager® (APM®) as a client to an external OAuth authorization server and get information from the external server about the scopes that it supports. Then configure the OAuth providers, servers, and requests to use from Access Policy Manager® (APM®) policies to interact with external OAuth authorization servers.
A Mode setting in the OAuth server configuration specifies the OAuth roles that you intend Access Policy Manager® (APM®) to play: OAuth client, OAuth resource server, or OAuth client and resource server. You can configure OAuth servers for each or any of the modes on one BIG-IP® system.
You might need to perform some SSL administration tasks to support communication between Access Policy Manager® (APM®) as an OAuth client and an OAuth resource server, and external OAuth authorization servers. OAuth server objects on APM require a server SSL profile for an OAuth client and for an OAuth resource server.
SSL certificates are configured in the
area of the product.Server SSL profiles are configured in the
area of the product.For more information, refer to BIG-IP® System: SSL Administration on the AskF5™ web site located at support.f5.com.
The table lists OAuth request types, and specifies the agents that use them and the policies where they are used.
Request type | Description | Agents and policies where used |
---|---|---|
auth-redirect-request | Redirects a user to an authorization server. | An OAuth Client agent uses this request at the start of a session (from the access policy) and can also use it from a per-request policy subroutine. This request is applicable when the OAuth Client is configured with the authorization code grant. This request can only use the GET parameter. |
token-request | Accesses an authorization server to obtain an access token or exchange an authorization code for an access token. | An OAuth Client agent uses this request at the start of a session (from the access policy) and can also use it from a per-request policy subroutine. |
token-refresh-request | Refreshes an expired access token. | An OAuth Client agent can make token refresh requests from a per-request policy subroutine. |
validation-scopes-request | Accesses an authorization server to get a list of scopes associated with an access token and to get scope data for those scopes. | An OAuth Scope agent uses this request at the start of a session (from the access policy) and can also use it from a per-request policy subroutine. The preconfigured F5ScopesRequest request is designed for use when APM is the OAuth server. |
scope-data-request | Accesses an authorization server to get scope data. | An OAuth Scope agent can use this request type from an access policy and can also use it from a per-request policy subroutine. |
openid-userinfo-request | Accesses a well-known endpoint for OpenID Connect to get UserInfo | An OAuth Scope and OAuth Client agent can use this request to get information. |
The OAuth provider, server, and request objects are ready for use in OAuth Client and OAuth Scope agents in access policies and per-request policy subroutines.
When Access Policy Manager® (APM®) acts as an OAuth client, an OAuth Client policy item can obtain an access token (and a refresh token if configured to do so) at the start of a session through the access policy. The OAuth client can also make OpenID Connect UserInfo requests following one of the OpenID Connect-defined flows (Authorization code flow or hybrid flow).
Throughout the session, an OAuth Client policy item can run periodically from a per-request policy subroutine to make OpenID Connect UserInfo requests, and, when the token expires, make an attempt to refresh the access token (if a refresh token exists) or authenticate the user anew.
When APM acts as an OAuth resource server, an OAuth Scope policy item can be used to validate a token and make scope data and UserInfo requests from the access policy and, periodically, from a per-request policy subroutine.
To obtain an access token one time only for the session, you need to configure an access policy. The OAuth Client agent can request a token.
With this access policy, the user logs on through a BIG-IP® system. The OAuth Client agent obtains an access token, and an OAuth Scope agent tries to retrieve the list of scopes associated with the token from the OAuth provider. The session starts. When the token expires, the system makes no attempt to refresh it.
To obtain an access token and to validate it for each request, first you need an access policy to obtain the token.
Access policy for APM as an OAuth client and resource server
To periodically validate and refresh the token, you need a per-request policy subroutine.
Per-request policy runs for each request but subroutine runs at an interval
When Access Policy Manager® (APM®) acts as an OAuth resource server, an OAuth Scope agent validates tokens obtained from the incoming request.
Per-request policy runs for each request, while subroutine runs only at an interval
A per-request policy runs at each request. A per-request policy subroutine runs periodically at whichever of these intervals is shorter: the number of minutes specified in the OAuth server Token Validation Interval field on Access Policy Manager® (APM®), or the interval that the external OAuth authentication server specifies in the expires_in attribute of the access token it issues.
You associate an access profile with a virtual server for use in establishing an access session. If you have configured a per-request policy, which is for use throughout the access session, you associate it with the virtual server also.
The default OAuth Logon Page agent displays messages that instruct the user to log in using an authorization code or a resource owner password credentials (ROPC) grant type. It displays option buttons from which users select the OAuth provider through whom they want to log in.
Customization options in the OAuth Logon Page agent enable an admin to add, update, delete, and reorganize the OAuth providers, as well as to configure the fields and text to display.
The OAuth Logon Page advanced customization template provides the code and the images necessary to display a logon page that, by default, looks like this.
OAuth Logon Page (advanced customization template)
The template forms a starting point for additional customization to achieve a logon page with the preferred providers, images, colors, fields, and text.
The OAuth Logon Page template is available for download from DevCentral™ at devcentral.f5.com. Instructions for advanced customization with the OAuth Logon Page template are also available in BIG-IP® Access Policy Manager®: Advanced Customization Examples on DevCentral.
Some applications do not support standard HTTP redirection and cookies. For Access Policy Manager® (APM®) to act as an OAuth resource server and provide an OAuth authorization layer into an API gateway, you must configure APM with a special access profile. This access profile also allows only a limited set of policy agents.
As a resource server gateway, APM must validate the tokens it receives. APM supports JSON web tokens (JWT) and validates them internally on the BIG-IP® system. APM also supports opaque tokens: to validate them, APM must interact with OAuth providers that are external to the BIG-IP system. APM also supports requesting UserInfo at a URI on an OAuth provider.
A single OAuth Scope agent works to validate tokens internally or externally. If you need to do both, you need two OAuth Scope agents. You can configure them using one access profile and policies that branch to the separate agents. Or you can configure them using two access profiles with policies that each contain an OAuth Scope agent. Those details are up to you. In this example, we walk through configuring one access profile and a policy that includes one OAuth Scope agent.
This configuration supports OAuth client apps that send requests with an HTTP Authorization header that contains an OAuth Bearer token.
You associate an access profile with a virtual server for use in establishing an access session. If you have configured a per-request policy, which is for use throughout the access session, you associate it with the virtual server also.
After Access Policy Manager® (APM®) gets or validates an OAuth token, the token can be used for single sign-on (SSO). Simply create an OAuth bearer SSO configuration and select it from any configuration object where APM lets you do that; for example, in an access profile.
APM gets or validates tokens when OAuth Client or OAuth Scope agents run in a policy.
Access Policy Manager® (APM®) collects OAuth performance statistics on the BIG-IP® system. After you configure and start to use APM as an OAuth server or an OAuth client and resource server, APM collects statistics without requiring any additional setup.
The interval between two consecutive points in an OAuth performance chart depends on the time period selected for the chart.
Time | Interval |
---|---|
Last hour | 30 seconds |
Last 3 hours | 1 minute (60 seconds) |
Last 12 hours | 6 minutes (360 seconds) |
Last day | 12 minutes (720 seconds) |
Last week | 1 hour (3600 seconds) |
Last 30 days | 4 hours (14400 seconds) |
Last 3 months | 12 hours (43200 seconds) |
Last 6 months | 1 day (86400 seconds) |
You might run into problems with an OAuth client or resource server on the BIG-IP system in some instances. Follow these tips to try to resolve any issues you might encounter.
Log message | Possible explanations and corrective actions |
---|---|
OAuth Client: SSL profile from apmd is missing | The server SSL profile is missing for the OAuth client or resource server that is specified in the OAuth server configuration. Verify the OAuth server configuration on the BIG-IP system. |
Invalid URI log | One or more URIs are not configured properly for the OAuth provider. Verify the OAuth provider configuration on the BIG-IP system. |
Failed to initialize OAuth agent | This is an internal APMD error; this error should not occur. |
OAuth request is not configured for agent | A particular request object is not configured properly. Verify request object configuration on the BIG-IP system. |
OAuth Client: state parameters do not match | This is an internal APMD error; this error should not occur. |
OAuth Authorization redirect is empty | The authorization redirect request URI is invalid. Verify the OAuth Client agent configuration in the policy and verify the configuration for the authorization redirect request that it specifies. |
Authorization code not found | Authorization code sent by the authorization server is not found. There could be a problem on the OAuth client or on the external authorization server. Examine the error logs on the external authorization server. |
OAuth Client: Unsupported grant type | An improper grant type was used from the OAuth Client; this error should not occur. |
OAuth Client: Unsupported parameter type | A parameter for an OAuth request was invalid; this error should not occur. |
OAuth Response is empty from server | The OAuth client (or resource server) received an empty response from the authorization server. Examine the error logs on the external authorization server. |
OAuth Scope: Failed to get scope details for scope | The OAuth resource server failed to get scope details. Examine the error logs on the external authorization server. |
Unsupported agent type | This is an internal APMD error; this error should not occur. |
OAuth Error Code received | The OAuth client received an error code. Use the error code and message to help with troubleshooting. |
Access Token validation failed for server | This warning means that the OAuth client agent failed to validate the token. When this happens, the OAuth client tries to refresh or get a new token |
OAuth Client: Failed to refresh token for server | This warning means that the OAuth client failed to refresh an access token. When this happens, the OAuth client tries to fetch a new token. |
HTTP error 503, connect failed | This error indicates that the OAuth client or resource server failed to connect
to the authorization server. Typically, this is caused by one or more configuration
issues. Verify that these aspects of your configuration are correct:
|
Invalid JWS token | Configure JSON web keys (JWKs) to verify this JSON Web Token (JWT) signature; or, request a new valid JWT |
Invalid b64url encoded header | The authorization server must include a base64 URL-encoded JSON Object Signing and Encryption (JOSE) header in the JWT. |
Invalid JSON | Request a new valid JWT. |
Unsecured JWT should have alg none | In an unsecured JWT, the authorization server must send a JOSE header with alg: none. |
Empty header: Algorithm(alg) field mandatory | The authorization server must send a JOSE header with the "alg" claim and value. |
Empty payload: Issuer(iss) field mandatory | The authorization server must send a JOSE payload with the "iss" claim and value. |
crit must be an array of string | If the authorization server sends the "crit" header parameter, it must be a string array. |
crit must be a non-empty array of string | If "crit" header parameter is specified in the JWT that the authorization server sends, it must be a non-empty string array. |
Invalid JOSE header parameter | The JOSE header parameter sent in the JWT was invalid. Request a new valid JWT. |
Unsupported algorithm | Request a JWT signed by an algorithm supported by F5 Client. |
Missing mandatory alg header parameter | The authorization server must send a JOSE header with the "alg" claim and value. |
No provider supporting alg none is found with issuer | Configure the provider that matches this issuer with allowed algorithms=none. |
Issuer Mismatch | Configure the right issuer for this provider; or, request a JWT from the right provider. |
Audience not found | The JWT was not meant for this client; or, configure the right audience for the client. |
JWT not active before nbf | Invalid JWT received; request a new JWT. |
JWT expired | Request another JWT, because the received JWT has expired. |
Audience is not string | Configuration on the authorization server that sends JWT must send the audience claim with a string value. |
Token blacklisted | The received JWT has been blacklisted; request a new valid JWT. |
Signature verification failed | Signature verification of the JWT did not succeed. |
Internal error during Signature verification | Check JWK key configuration to match JWT signature |
Initialization failed | Make sure the JWK key configuration matches the JWT algorithms |
JWT symmetric signature match failed | Configure the correct symmetric key to verify this JWT signature. |
No JWK keys found to verify signature | Configure the correct key to verify the received JWT signature. |