F5 Logo MyF5
Search
  1. MyF5 Home
  2. BIG-IP Access Policy Manager: OAuth Concepts and Configuration
  3. OAuth Authorization Server Concepts
Manual Chapter : OAuth Authorization Server Concepts

Applies To:

Show Versions Show Versions

BIG-IP APM

  • 16.0.1, 16.0.0, 15.1.1, 15.1.0
Manual Chapter

OAuth Authorization Server Concepts

OAuth grant types

As an OAuth authorization server, Access Policy Manager (APM) supports the grant types in this table.
Grant Type
Description
Authorization code
An OAuth client directs a resource owner to an authorization server. As the OAuth authorization server, APM authenticates the resource owner and directs it back to the client with an authorization code. The client then uses the authorization code to get an access token.
Implicit
A client gets a token from the authorization server directly, based on resource owner authorization and without the exchange of intermediate credentials (such as an authorization code). This grant type is optimized for clients that are implemented using a scripting language in a browser. (Refresh tokens are not available with this grant type.)
Resource owner password credentials
A client goes directly to the authorization server and uses the resource owner credentials to obtain a token.

OAuth authorization server endpoints

As an OAuth authorization server, Access Policy Manager (APM) supports the endpoints listed in this table for interactions with resource owners and clients on the BIG-IP system. APM supplies default URIs for each endpoint. Users can replace the default URIs.
Authorization Server Endpoint
Description
Authorization endpoint
As defined in the OAuth 2.0 authorization framework specification (RFC 6749), this endpoint is for use by a client to obtain authorization from the resource owner through user-agent redirection. The authorization server verifies the identity of the resource owner and interacts with the resource owner to obtain the authorization grant for the client. Defaults to
/f5-oauth2/v1/authorize
.
Token issuance endpoint
Specifies the endpoint for the client to use to obtain an access token or a refresh token, per RFC 6749. Defaults to
/f5-oauth2/v1/token
.
Token revocation endpoint
Specifies the endpoint for the client to use to revoke a previously obtained access token or refresh token, as an extension of RFC 6749. Defaults to
/f5-oauth2/v1/revoke
.
Token introspection endpoint
As defined in the OAuth 2.0 token introspection specification (RFC 7662), clients and resource servers get information about the token, such as its status (active or not active), the scopes assigned to it, issue date, expiration date, and so on. Defaults to
/f5-oauth2/v1/introspect
.
OpenID Connect Configuration Endpoint
As defined in the OpenID Connect Discovery 1.0 specification, this defines the location of the OpenID provider configuration document. Defaults to
/f5-oauth2/v1/.well-known/openid-configuration
.

About OAuth token types

As an OAuth authorization server, Access Policy Manager (APM®) supports bearer access tokens, and refresh tokens. For use as bearer access tokens and refresh tokens, APM supports opaque tokens and JSON web tokens.

About access tokens

As defined in the OAuth 2.0 specification (RFC 6749), an
access token
 is a credential used to access protected resources. An access token is a string that represents an authorization issued to the client. A token represents specific scopes and durations of access granted by the resource owner. The resource server and the authorization server enforce the scopes and durations of access.

About refresh tokens

As defined in the OAuth 2.0 specification (RFC 6749), a
refresh token
 is a credential used to obtain an access token. The client uses a refresh token to get a new access token from the authorization server when the current access token expires. If refresh tokens are enabled in the configuration, the OAuth authorization server issues a refresh token to the client when it issues an access token.
A refresh token is a string. It represents the authorization that the resource owner grants to the client. Unlike access tokens, a refresh token is for use with authorization servers only, and is never sent to a resource server.

About opaque tokens

Opaque tokens
 are issued in a proprietary format. Only the OAuth authorization server that issues the token can read it and validate it. The OAuth authorization server stores an opaque token for its lifetime and offers the ability to revoke the token. Use of opaque tokens forces client apps to communicate with the authorization server.
The F5 Authorization server responds to introspect requests for opaque access tokens only. The OAuth Scope Check Agent's external mode cannot have
Validation Request
 set for JWT tokens. JWT access tokens must use 'internal' mode validation.

About JSON web tokens

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information in a JSON object between OAuth entities. This information can be verified and trusted because it is digitally signed. JSON tokens are not stored on an OAuth authorization server and they cannot be revoked.
The OAuth Scope Check Agent's external mode cannot have
Validation Request
 set for JWT tokens. JWT access tokens must use 'internal' mode validation.

Overview: Localizing an OAuth authorization screen

The text on an OAuth authorization screen is a composite of captions and descriptions configured in a few different objects. When you set out to customize the authorization screen, you need to know where the text comes from.
An example OAuth Authorization screen
Element
Where configured
1
OAuth Authorization agent,
Authorize Message
 field.
2
Client application object,
Website URL Logo
 field. (Providing a different logo for different locales is not supported.)
3
Client application object,
Caption
 field.
4
Client application object,
Detailed Description
 field.
5
Client application object,
Caption
 field supplies the application name.
6
OAuth Authorization agent,
Scope Message
 field supplies the phrase which defaults to
request permission to do the following
.
7
OAuth scope objects,
Detailed Description
 field.
8
OAuth Authorization agent,
Allow Message
 and
Deny Message
 fields.

Localizing an OAuth client application

Before you start, you must have registered a client application in Access Policy Manager (APM). When you configure a client application, you specify a caption as you want it displayed when the English language is being used.
You use this process to specify the caption and detailed description as you want them displayed for additional languages.
APM supports a subset of languages, and, during a session, only matches the languages that are specified in the access profile that started the session.
This task covers general customization practices only. For information about advanced customization, see
BIG-IP Access Policy Manager: Customization
 on the AskF5 web site located at
support.f5.com
.
  1. On the Main tab, click
    Access
    Profiles / Policies
    Customization
    General
    .
    The Customization tool appears in General Customization view, displaying
    Form Factor: Full/Mobile Browser
     settings.
  2. In the left pane, select the Text tab.
    A navigation tree displays in the left pane.
  3. Expand the
    OAuth Client Applications
     folder.
  4. Click the name of the OAuth client application you want to customize.
    The partition precedes the client application name, for example
    /Common/myClientApp
    .
    A table displays
    Name
     (setting name) and
    Value
     (display text) in the right pane.
  5. From the
    Language
     list above the table, select a language.
  6. To supply text or to replace existing text for
    Caption
    :
    1. Click in the
      Value
       field.
      A pencil icon displays at the end of the field.
    2. Type your translated text and press Enter.
  7. To supply text or to replace existing text for
    Detailed Description
    :
    1. Click in the
      Value
       field.
      A pencil icon displays at the end of the field.
    2. Type your translated text and press Enter.
  8. Click the
    Save
     icon.
  9. To customize text for additional languages, select a language, make the changes that you require, and click
    Save
     before you select another language.

Localizing an OAuth scope

You must already have a scope configured in Access Policy Manager (APM). When you configure a scope, you specify a caption as you want it displayed when the English language is being used.
You use this process to customize the caption and detailed description as you want them displayed for additional languages.
APM supports a subset of languages, and, during a session, only matches the languages that are specified in the access profile that started the session.
This task covers general customization practices only. For information about advanced customization, see
BIG-IP Access Policy Manager: Customization
 on the on the AskF5 web site located at
support.f5.com
.
  1. On the Main tab, click
    Access
    Profiles / Policies
    Customization
    General
    .
    The Customization tool appears in General Customization view, displaying
    Form Factor: Full/Mobile Browser
     settings.
  2. In the left pane, select the Text tab.
    A navigation tree displays in the left pane.
  3. Expand the
    OAuth Scopes
     folder.
  4. Click the name of the OAuth scope that you want to localize.
    The partition where the scope resides precedes the scope name, for example
    Common/myEmailScope
    .
    A table displays
    Name
     (setting name) and
    Value
     (display text) in the right pane.
  5. From the
    Language
     list above the table, select a language.
  6. To supply text or to replace existing text for
    Caption
    :
    1. Click in the
      Value
       field.
      A pencil icon displays at the end of the field.
    2. Type your translated text and press Enter.
  7. To supply text or to replace existing text for
    Detailed Description
    :
    1. Click in the
      Value
       field.
      A pencil icon displays at the end of the field.
    2. Type your translated text and press Enter.
  8. Click the
    Save
     icon.
  9. To customize text for additional languages, select a language, make the changes that you require, and click
    Save
     before you select another language.

About customization for policy agents

If an access or per-request policy agent supports customization, customization settings are available in agent properties from within the visual policy editor. The same customization settings are also available for the agent in the
Access
Profiles / Policies
Customization
area of the BIG-IP system. For more information, see
BIG-IP Access Policy Manager (APM®) Customization
 on the AskF5™ web site located at
support.f5.com
.

Overview: Managing opaque access tokens

Access Policy Manager (APM®) stores access tokens in on-disk databases for their lifetimes.

Task summary

Revoking opaque access tokens

To perform this task, you must be logged into the BIG-IP system in one of these user roles: manager, administrator, or resource administrator.
Based on your observations, you might want to revoke one or more access tokens.
If the BIG-IP system is part of a high availability pair, you should revoke an access token from the active device. If you revoke an access token from the standby device, the access token retains its ACTIVE status on the active device.
  1. On the Main tab, click
    Access
    Overview
    OAuth Reports
    Tokens
    .
    The OAuth Tokens screen opens. By default, the
    /Common/oauthdb/
    default database instance is selected. The display initially places the most recently issued access tokens at the top of the table.
  2. Locate the access tokens that you want to delete using any or all of these methods:
    1. From the
      DB Instance
       list, select the database instance where the client app or the resource server stores tokens.
      If you have few database instances, you might search them in turn for the access tokens that you want to revoke.
      The OAuth profiles that are associated with client apps and resource servers specify which database instance to use.
    2. In the
      Search
       field, type all or part of a user name or client application name and press Enter.
      Any results that match display.
    3. Sort the tokens by clicking a table heading, such as
      Client App
       or
      Access Token Issued
      .
  3. Select the access tokens that you want to revoke.
  4. Click
    Revoke
    .
    A popup screen displays a confirmation message.
  5. On the popup screen, click
    Revoke
    .

Purging opaque tokens from a database instance

You purge OAuth database instances of expired tokens when you want to recover disk space.
Schedule a database purge at a time when the BIG-IP system is least-used, to prevent any possible performance issues.
  1. On the Main tab, click
    Access
    Federation
    OAuth Authorization Server
    Database Instance
    .
    The Database Instance screen opens.
  2. In the
    Name
     field, click the name of a database instance.
    A Properties screen opens.
  3. To purge the database immediately, below the Purge Schedule Settings area, click
    Purge Now
    .
  4. To specify a schedule for regular database purging, perform these steps:
    1. Select a frequency from the
      Frequency
       list.
    2. Specify a time in the
      Schedule At
       field.
    1. Click
      Update
      .

Obtaining a list of OAuth IDs for purged access tokens

If you want to see a list of OAuth IDs that identify the opaque access tokens that have been purged, you can do so from the command line on the BIG-IP system.
  1. Log on to the command line of the BIG-IP system.
  2. Open the TMOS Shell (
    tmsh
    ).
    tmsh
  3. Type this command:
    show apm oauth purged-entries
    .
    A list of OAuth IDs displays with the dates and times on which access tokens were purged.

    oauth_id                                                purged_time
---------------------------------------------------------------------------
07c64b01e360f43ff4e2b561107de9f4aa5ca14e54b5e72e        2016-09-29 02:00:01

About OAuth statistics collection

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.

Charting OAuth server performance

To perform this task, you must be logged into the BIG-IP system in one of these user roles: manager, administrator, or resource administrator.
You chart server performance when you want to see the rate of requests that the OAuth authorization server, Access Policy Manager (APM) , processes over a period of time.
  1. On the Main tab, click
    Access
    Overview
    OAuth Reports
    Server
    .
    The Overview chart summarizes OAuth authorization server activity. Additional charts provide statistics by grant type.
    The x-axis for a chart specifies time. The y-axis specifies the rate: requests per second.
    The screen displays OAuth server performance charts with data from the last hour.
  2. To display the rate of requests for the interval represented by a point in a chart, place your cursor at the point in the chart.
    The legend updates to display the rates.
  3. To get the number of requests for a point in the chart, multiply the rate by the number of seconds in the interval.
    The interval between two consecutive points on a chart depends on the selected
    Time
    .
  4. To generate charts for another time period, select one from the
    Time
     list.

OAuth performance chart intervals

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)

Charting OAuth opaque token usage

To perform this task, you must be logged into the BIG-IP system in one of these user roles: manager, administrator, or resource administrator.
You can report on the opaque access tokens that are stored on the OAuth authorization server. You might want to view access and refresh token usage for particular users, client apps, user agents, scopes, or other token data over a time period.
To conserve database space and make room for new access tokens, database instances must be purged of expired tokens on a regular basis.
  1. On the Main tab, click
    Access
    Overview
    OAuth Reports
    Tokens
    .
    The OAuth Tokens screen opens. By default, the
    /Common/oauthdb/
    default database instance is selected. The display initially places the most recently issued access tokens at the top of the table.
  2. Use the fields at the top of the screen (
    DB Instance
    ,
    Access Token Issued
    , and
    Search
    ) to select a database instance, to change the time period, or to type part of a user or client application name and search for it.
    The screen updates with data to match the filters you set.
  3. To view the scopes associated with an access token:
    1. Click the link in the
      Scopes
       column.
      A popup screen displays the list of scopes.
    2. Click
      OK
      .
  4. To view the user agents associated with an access token:
    1. Click the link in the
      User Agents
       column.
      A popup screen displays the list of scopes.
    2. Click
      OK
      .
  5. To sort the access tokens by
    Client App
    ,
    User
    ,
    User Agent
    , or any other table column, click the table column name.
  6. To page through the report, use the fields at the bottom of the screen.

Opaque access token status

The OAuth access token report displays a status for each opaque access token. This table defines each status.
Access Token Status
Description
ACTIVE
A token status is active when the token is granted and remains active until an event occurs that changes the status.
EXPIRED
Token status changes to expired only when a validation request is attempted on a token that has passed its expiration date.
REVOKED
Token status changes to revoked when a client or an administrator revokes that access token.

OAuth authorization server troubleshooting tips

You might run into problems with an OAuth authorization 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
Invalid grant type requested in OAuth mode
An OAuth profile might not be specified in the access profile. Verify that the access profile specifies an OAuth profile.
None of the configured JWK keys match the received token
The Okta default authorization server does not publish the access token signing key causing the OAuth Scope check agent to fail. To fix this, you should use a custom authorization server that will publish the access token signing key on the respective jwks_uri.
For example, if the issuer is:
https://f5test1.oktapreview.com
then the issuer is the built-in OIDC authorization server, and the access token cannot be validated locally.
If the issuer is:
https://partnerpoc.oktapreview.com/oauth2/ausce8ii5wBzd0zvQ0h7
then it is an API Access Management authorization server, and the tokens can be validated locally.
OAuth mode not set for Authorization Agent: Incoming OAuth request might not match the configured OAuth endpoints or could be failing for other reasons.
Incoming OAuth request might not match the configured OAuth endpoints.
OAuth mode not set for Authorization Agent: OAuth profile is not configured for this access profile.
OAuth profile is not specified in the access profile.
The client app does not support Auth code grant
The Authorization Code grant type is not selected in the client app configuration.
The client app does not support Implicit grant
The Implicit grant type is not selected in the client app configuration.
OAuth mode not set for Authorization Agent
An OAuth profile might not be specified in the access profile. Verify that the access profile specifies an OAuth profile.
Invalid Scope:
'name'
The client application sent a request with an invalid scope,
name
.
  • The scope might not be configured on the BIG-IP system.
  • The scope might not be assigned to the client application.
Verify and correct the configuration on the BIG-IP system:
  1. Look for the scope. If it does not exist, create it.
  2. Look at the client application. If the scope is not assigned to it, assign it.
Client ID 0fb9b2... IP 165.160.15.20 attempted to use Auth Code 03f59e... given to client ID 093eb2...
A client application tried to use an authorization code that the Authorization Server provided to another client application. Any remediation action, such as unregistering the app, is at the admin's discretion.
Client ID 093eb2... IP 165.160.15.20 attempted to use already consumed Auth Code 03f59e...
An authorization code can be used to retrieve an access token once only. This error message indicates that the Authorization server detected a client application presenting the same authorization code to retrieve an access token more than once. Any remediation action, such as notifying the app developer or unregistering the app, is at the admin's discretion.
Failed to initiate DB synchronization (ERR_DB)
The error code might help indicate what problem was seen. This error can also occur if the OAuth plugin restarted.
Request Introspect Token from ID bd3d27... IP 165.160.15.20 failed. Error Code (invalid_request) Error Description (Required parameter (resource_server_secret) is missing)
The error description field provides the detailed reason why a request failed. The reason could vary from missing a required field in the request to an out-of-memory situation in the traffic management microkernel (TMM) process, and so on. The error description should be detailed enough to help with troubleshooting.
Request Auth Code from Source ID 052ae66... IP 165.160.15.20 failed. Error Code (server_error) Error Description (Assigned scopes exceed buffer size limit.)
All assigned scopes (space separated) are returned to the client application. However, if all assigned scope names exceed 1000 bytes, this error message will be generated. To resolve the problem, you can:
  • Shorten the scope names, or
  • Reduce the number of assigned scopes, or
  • Both of the above.
The maximum length for one scope name is 400 characters. The maximum length for all the scope names assigned to the client app and separated by spaces is 1000 characters (1000 bytes).
Request Auth Code from Source ID 052ae6... IP 165.160.15.20 failed. Error Code (server_error) Error Description (Assigned scopes cause scope_data to exceed buffer size limit.)
Scope data (scope_data) is JSON-formatted output that contains all assigned scope names and their values. Whenever the JSON-formatted output length exceed 4000 bytes, this error is generated. To resolve the problem, you can:
  • Shorten the scope name, or
  • Shorten the scope value, or
  • Reduce the number of assigned scopes, or
  • All of the above
The maximum length for one scope name is 400 characters. The maximum length for one scope value is 3500 characters. The maximum length for all scope data (scope names, scope values, spaces, and formatting characters) is 4000 characters (4000 bytes).
Failed to register OAuth global tmstat table (ERR_MEM)
These are OAuth global TMSTAT initialization related failures. These events are unlikely. Restarting TMM could help. For more information, refer to SOL89999342: BIG-IP daemons (12.x) on the AskF5 web site located at
support.f5.com
.
Failed to create OAuth global tmstat row (ERR_MEM)
Failed to set OAuth global tmstat field name (ERR_MEM)
Failed to get OAuth global stats row during tmstat initialization (ERR_UNKNOWN)
This is an OAuth global TMSTAT initialization related failure. This is an unlikely event. Restarting TMM could help.
Request Access Token from Source ID 052ae666629882d29c0e385ce9380023e96cf9c0a5ae4857 IP 10.192.144.45 failed. Error Code (server_error) Error Description (JWT AT signing failed)
Indicates that the JSON web token (JWT) access token signature generation failed. It might fail due to an invalid JSON web key (JWK) configuration being used on the OAuth Profile.
Request Access Token from Source ID 052ae666629882d29c0e385ce9380023e96cf9c0a5ae4857 IP 10.192.144.45 failed. Error Code (server_error) Error Description (JWT AT signing failed due to expired cert)
Indicates that the certificate used by the assigned JWK on the OAuth Profile has expired. Either create a configuration with valid certificate or enable the
Ignore expired certificate validation
 check box on the OAuth Profile.
Request Access Token from Source ID 052ae666629882d29c0e385ce9380023e96cf9c0a5ae4857 IP 10.192.144.45 failed. Error Code (server_error) Error Description (Unexpected: JWT subject JSON format out of bound.)
Indicates the subject field value length is too large. Change the configuration to reduce the size of subject's value.
Request Access Token from Source ID 052ae666629882d29c0e385ce9380023e96cf9c0a5ae4857 IP 10.192.144.45 failed. Error Code (server_error) Error Description (Generate JWT Access/Refresh token size exceeds available buffer size limit.
This indicates the generated access token size is too large than the currently supported size limit of 16 K. Create a configuration using fewer claims and scopes, shorten the claim and scope values, and so on.
Request Access Token from Source ID 052ae666629882d29c0e385ce9380023e96cf9c0a5ae4857 IP 10.192.144.45 failed. Error Code (server_error) Error Description (Refresh token encryption failed)
While generating the JWT refresh token, encryption failed. This indicates a problem with the
JWT Refresh Token Encryption Secret
 configuration or an issue with crypto operations.
Contact Support Contact Support

Have a Question?

Support and Sales >

About F5

Education

F5 Sites

Support Tasks




©2023 F5, Inc. All rights reserved.


Trademarks Policies Privacy California Privacy Do Not Sell My Personal Information