F5 Logo MyF5
Search
  1. MyF5 Home
  2. Knowledge Centers
  3. BIG-IP APM
  4. BIG-IP Access Policy Manager: Authentication and Single Sign-On
  5. OAuth Authorization Server
Manual Chapter : OAuth Authorization Server

Applies To:

Show Versions Show Versions

BIG-IP APM

  • 13.0.1, 13.0.0
Manual Chapter
Table of Contents | << Previous Chapter | Next Chapter >>

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.

About OAuth token types

As an OAuth authorization server, Access Policy Manager® (APM®) supports bearer access tokens, and refresh 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.

Overview: Configuring APM as an OAuth 2.0 authorization server

You can configure a BIG-IP® system with Access Policy Manager® (APM®) to act as an OAuth authorization server. OAuth client applications and resource servers can register to have APM authorize requests.

Task summary

Specifying OAuth scopes of access for client apps

When Access Policy Manager® (APM®) acts as an OAuth authorization server, you must configure scopes of access. (A scope specifies a string, and optionally, a value, that represents a resource.)
  1. On the Main tab, click Access > Federation > OAuth Authorization Server > Scope .
    The Scope screen opens.
  2. Click Create.
  3. In the Name field, type a name for the object.
  4. In the Scope Name field, type a name for the scope.
  5. In the Scope Value field, type a value for the scope.
  6. In the Customization Settings for English area, in the Caption field, type a caption.
  7. In the Detailed Description field, type a description of the access that the client application needs.
    If you choose to display an Authorization screen, APM displays the contents of this field on it; or, if this field is blank, APM displays the contents of the Caption field.
    Here are some examples: Access your profile or Update your tasks, projects, and workspace.
  8. Click Finished.

Registering a client application for OAuth services

For a client application to obtain OAuth tokens and OAuth authorization codes from the BIG-IP® system, you must register it with Access Policy Manager® (APM®).
  1. On the Main tab, click Access > Federation > OAuth Authorization Server > Client Application .
    The Client Application screen opens.
  2. Click Create.
  3. In the Name field, type a name for the object.
  4. In the Application Name field, type the application name.
  5. In the Customization Settings for English area in the Caption field, type a caption.
    APM displays this caption as the name of the application on an Authorization screen if you choose to display one.
  6. In the Security Settings area, for Authentication Type, select one of the options:
    • None - This is typically used in conjunction with the Implicit grant type, which does not use a secret or a certificate. For grant types other than Implicit, the other options provide better security.
    • Secret - This is the default setting. If this is selected, APM generates this secret for the client and you can request that APM regenerate the secret.
    • Certificate - Uses the client certificate. If this is selected, the Client Certificate Distinguished Name field displays.
  7. If the Client Certificate Distinguished Name field displays, leave it blank or type a name.
    If you leave it blank, APM accepts any valid client certificate. If you specify a name, APM accepts only the specific valid client certificate with the specified Distinguished Name.
    This is a sample Distinguished Name for the client certificate: emailAddress=w.smith@f5.com,CN=OAuth AS Project Client2 Cert,OU=Product Development,O=F5 Networks,ST=CA,C=US
  8. For Scope, select one or more and move them to the Selected field.
  9. From Grant Type, select one or more of the options:
    • Authorization Code - The client must authenticate with the authorization server (APM) to get a token.
    • Implicit - The client gets a token from the authorization server (APM) without authenticating to it. (Refresh tokens are not available with this grant type.)
    • Resource Owner Password Credentials - The client goes directly to the authorization server and uses the resource owner credentials to obtain a token.
  10. To apply the token management settings from an OAuth profile, perform these substeps:
    1. Retain selection of the Enabled check box in the Token Management Configuration area.
      The token management configuration settings in an OAuth profile apply to client applications assigned to that profile except when this setting is disabled.
    2. Click Finished.
  11. To manage tokens in a manner that is distinct for this client application, perform these substeps:
    1. In the Token Management Configuration area, clear the Enabled check box.
      Additional fields display.
    2. Update any of the additional fields.
    3. Click Finished.
APM generates a client ID for the application. If the Authentication Type is set to Secret, APM generates a secret. The application displays on the Client Application screen.

Registering a resource server for OAuth services

For Access Policy Manager® (APM®) as an OAuth authorization server to accept token introspection requests from a resource server for token validation, you must register the resource server with APM.
  1. On the Main tab, click Access > Federation > OAuth Authorization Server > Resource Server .
    The Resource Server screen displays.
  2. Click Create.
  3. In the Name field, type a name for the object.
  4. For Authentication Type, select one of these:
    • None - This option requires no authentication when the resource server sends a token introspect request to the OAuth authorization server to get the token validated.
    • Secret - For this option, APM generates this secret and you can request that APM regenerate the secret.
    • Certificate - This is the default setting. If this is selected, Resource Server Certificate Distinguished Name field displays.
  5. If Resource Server Certificate Distinguished Name displays, leave it blank or type a name.
    If you leave it blank, APM accepts any valid client certificate. If you specify a name, APM accepts only the specific valid client certificate with the specified Distinguished Name.
    This is a sample Distinguished Name for the client certificate: emailAddress=w.smith@f5.com,CN=OAuth AS Project Client2 Cert,OU=Product Development,O=F5 Networks,ST=CA,C=US
  6. Click Finished.
The new resource server displays on the list.

Managing storage for access tokens

You create database instances to store the access tokens that Access Policy Manager® (APM®) grants and then stores for the tokens' lifetimes.
Note: APM provides one default database instance, oauthdb. Additional instances enable you to group tokens.
  1. On the Main tab, click Access > Federation > OAuth Authorization Server > Database Instance .
    The Database Instance screen opens.
  2. Click Create.
  3. In the Name field, type a name for the object.
  4. In the Purge Schedule Settings area, select a frequency from the Frequency list and specify a time in the Schedule At field.
    Schedule the database purge for a time when the BIG-IP® system is least used to prevent any possible performance issues.
    Purging removes expired access tokens, refresh tokens, authorization codes, and associated entries from the instance. For the purpose of purging, an access token is considered expired when it passes the date when it expires; (expiry is based on the Access Token Lifetime setting).
    Note: Expired access tokens are not removed when the Reuse Access Token setting is enabled (in the corresponding OAuth profile) and a refresh token has been issued and the refresh token is not expired.
    Revoked access tokens are purged after they expire.
  5. To save this database instance, click Finished.
Database instances are available for selection in an OAuth profile.

Creating an OAuth profile

You configure an OAuth profile to specify the client applications, resource servers, token management configuration, and authorization server endpoints that apply to the traffic that goes through a particular virtual server.
Note: Client applications can override the token management configuration.
  1. On the Main tab, click Access > Federation > OAuth Authorization Server > OAuth Profile .
    The OAuth Profile screen opens.
  2. Click Create.
  3. In the Name field, type a name for the object.
  4. For Client Application, select from the available clients and move them to the Selected list.
  5. For Resource Server, select from the available servers and move them to the Selected list.
  6. From the Database Instance list, you can retain the default, oauthdb, or select another database instance.
  7. To change any of the default values in the Token Management Configuration area, select the Custom check box and then make changes.
  8. To change any of the default URLs in the Authorization Server Endpoints area, select the Custom check box and then type other URL paths in the fields.
    For example, you can change the value for Authorization Endpoint from /f5-oauth2/v1/authorize to /my_company_oauth/v2/auth.
    The OAuth authorization server ensures that the request path in the URL is the same as that configured here before serving the request.
  9. Click Finished.

Creating an access profile for F5 as an OAuth authorization server

You create an access profile to provide the access policy configuration for a virtual server that establishes a secured session. Configure an access profile like this for traffic to Access Policy Manager® (APM®) as an OAuth authorization server.
  1. On the Main tab, click Access > Profiles / Policies .
    The Access Profiles (Per-Session Policies) screen opens.
  2. Click Create.
    The New Profile screen opens.
  3. In the Name field, type a name for the access profile.
    Note: An access profile name must be unique among all access profile and any per-request policy names.
  4. From the Profile Type list, select All or LTM-APM.
  5. Scroll down to the Configurations area.
  6. From the OAuth Profile list, select the OAuth profile you configured earlier.
  7. In the Language Settings area, add and remove accepted languages, and set the default language.
    A browser uses the highest priority accepted language. If no browser language matches the accepted languages list, the browser uses the default language.
    Important: If you want to translate text into other languages (as you can in Access Policy Customization), make sure to select the languages that you want to display here.
  8. Click Finished.
The access profile displays in the Access Profiles List. Default-log-setting is assigned to the access profile.
When you create a virtual server to process traffic from OAuth version 2.0 clients and resource servers, assign this access profile to it.

Sample policy: Logon, authenticate, and authorize

Access policy for APM as an OAuth authorization server

The Logon Page and OAuth Authorization agents are required in the access policy for Access Policy Manager® (APM®) to act as an OAuth authorization server. An authentication agent, such as AD Auth, is optional; if included in a policy, an authentication agent should be placed after the Logon Page and before the OAuth Authorization agent.

About the OAuth Authorization

When Access Policy Manager® (APM®) is configured to act as an OAuth authorization server, an OAuth Authorization agent must be present in the access policy.

The OAuth Authorization agent provides these elements and options.

Prompt for Authorization
  • Enabled - Displays the OAuth Authorization page. The page requests authorization for the client application to access a list of scopes and presents the options to allow or to deny access.
  • Disabled - Does not display the OAuth Authorization page.
Scopes

Specifies the scopes for which authorization is requested. If no scopes are specified here, the scopes configured in APM for the client application are used.

Customization
Customize the messages that display on the OAuth authorization page when Prompt for Authorization is set to Enabled:
  • Authorize Message Specifies the initial wording for the prompt.
  • Scope Message Specifies the wording that precedes the list of scopes that are specified in the Scopes Assign area of this screen.
  • Allow Message Provides the label for the button that allows access.
  • Deny Message Provides the label for the button that denies access.

Configuring an access policy for F5 as an OAuth authorization server

You configure an access policy so that, as OAuth authorization server, Access Policy Manager® (APM®) can identify and authorize client applications to access resources.
Note: The policy items in these steps are necessary to process traffic sent to F5 (APM) as an authorization server. You can add these items to a branch of an existing policy or add them to a new policy.
  1. On the Main tab, click Access > Profiles / Policies .
    The Access Profiles (Per-Session Policies) screen opens.
  2. In the Per-Session Policy column, click the Edit link for the access profile you want to configure.
    The visual policy editor opens the access policy in a separate screen.
  3. Click the (+) icon anywhere in the access policy to add a new item.
    Note: Only an applicable subset of access policy items is available for selection in the visual policy editor for any access profile type.
    A popup screen opens, listing predefined actions on tabs such as General Purpose, Authentication, and so on.
  4. On the Logon tab, select Logon Page and click the Add Item button.
    The Logon Page Agent properties screen opens.
  5. Click Save.
    The properties screen closes and the policy displays.
  6. On a policy branch, click the (+) icon to add an item to the policy.
  7. On the Authentication tab, select OAuth Authorization and click Add Item.
    Important: You must include an OAuth Authorization item in the policy for it to work.
    A Properties popup screen opens.
  8. If you do not want to prompt for authorization, in the OAuth Authorization area, from the Prompt for Authorization list, select Disabled.
  9. In the Scope Assign area, add entries to assign scopes:
    Assign scopes whether or not you plan to prompt for authorization.
    1. Click Add new entry.
      A numbered entry displays with Expression and Scopes properties.
    1. To specify a prerequisite for the scopes, click change and configure an expression.
      A prerequisite is not mandatory.
      For example, use an expression to verify that the user has passed an LDAP query for membership in a group. Or verify that the user has passed Active Directory authentication.
    2. For scopes, click Add/Delete (this opens a popup screen); select scopes and click Update (this closes the popup screen).
  10. Click Save.
    The properties screen closes and the policy displays.
  11. Add any additional access policy items you require to complete the access policy.
    Note: On the branch of the access policy with OAuth Authorization, do not also assign connectivity resources (as you can with various resource assign access policy items). Doing so causes a validation error on the Allow ending.
  12. Change the ending from Deny to Allow on any access policy branch on which you want to grant access.
  13. Click the Apply Access Policy link to apply and activate the changes to the policy.

Creating a client SSL profile for certificate inspection

You configure a client SSL profile to request an SSL certificate from an OAuth client application or an OAuth resource server at the start of the session.
Note: You must configure a client SSL profile for an OAuth client application or an OAuth resource server that registered with Access Policy Manager® (APM®) with a certificate type of authentication.
  1. On the Main tab, click Local Traffic > Profiles > SSL > Client .
    The Client SSL profile list screen opens.
  2. Click Create.
    The New Server SSL Profile screen opens.
  3. In the Name field, type a unique name for the profile.
  4. From the Parent Profile list, select clientssl.
  5. Scroll down to the Client Authentication area.
  6. Select the Custom check box for Client Authentication.
    The settings become available.
  7. From the Client Certificate list, retain the default setting ignore.
    Selecting ignore prevents traffic from OAuth client applications and OAuth resource servers from being blocked if they are configured to use a secret for authentication or to use no authentication at all. The BIG-IP® system still requests a certificate from any OAuth client application or OAuth resource server that specifies a certificate type of authentication.
  8. From the Trusted Certificate Authorities list, make a selection.
    The BIG-IP system supplies a default certificate and a ca-bundle.crt file that includes all well-known public certificate authority (CA) certificates for client-side processing.
  9. Click Finished.
To put this client SSL profile into effect, select it in a virtual server that is configured to accept HTTPS traffic.

Creating a virtual server for OAuth authorization server traffic

You create a virtual server to process traffic for Access Policy Manager® (APM®) configured as an OAuth authorization server.
  1. On the Main tab, click Local Traffic > Virtual Servers .
    The Virtual Server List screen opens.
  2. Click the Create button.
    The New Virtual Server screen opens.
  3. In the Service Port field, type 443 or select HTTPS from the list.
  4. From the HTTP Profile list, select http.
  5. For the SSL Profile (Client) setting, move the client SSL profile you created earlier to the Selected list.
  6. Scroll down to the Access Profile area.
  7. From the Access Profile list, select the access profile you created earlier.
  8. Click Finished.
The HTTPS virtual server appears in the Virtual Server List screen.

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.

Task summary

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.
Note: 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.
Note: 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.
Note: 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.
Note: 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 access tokens

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

Task summary

Revoking 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.
Note: 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 tokens from a database instance

You purge OAuth database instances of expired tokens when you want to recover disk space.
Note: 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 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 Traffic Management Shell (tmsh).
    tmsh
  3. Type this command: apm oauth list 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 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 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.
Note: 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.

Access token status

The OAuth access token report displays a status for each 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.
EXPIRED 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.
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.
The client app does not support ROPC grant The Resource Owner Password Credentials 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.
Note: 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
Note: 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.
Table of Contents | << Previous Chapter | Next Chapter >>
Contact Support Contact Support

Have a Question?

Support and Sales >

About F5

Education

F5 Sites

Support Tasks




©2023 F5 Networks, Inc. All rights reserved.


Trademarks Policies Privacy California Privacy Do Not Sell My Personal Information