Manual Chapter :
OAuth Authorization Server
Applies To:
Show Versions
BIG-IP APM
- 14.0.1, 14.0.0
OAuth Authorization Server
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.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.
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
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).
- On the Main tab, click.The Client Application screen opens.
- ClickCreate.
- In theNamefield, type a name for the object.
- In theApplication Namefield, type the application name.
- In the Customization Settings for English area in theCaptionfield, type a caption.APM displays this caption as the name of the application on an Authorization screen if you choose to display one.
- In the Security Settings area, forAuthentication 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 thanImplicit, 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, theClient Certificate Distinguished Namefield displays.
- If theClient Certificate Distinguished Namefield 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
- ForScope, select one or more and move them to theSelectedfield.
- FromGrant Type, select one or more of the options:
- Authorization Code / Hybrid- 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.
- ForRedirect URI(s)(if displayed), type a fully qualified URI, clickAdd, and repeat as needed.Redirect URI(s) form a list of URIs to which the OAuth authorization server can redirect the resource owner’s user agent after authorization is obtained for an authorization code or implicit grant type.
- ForSupport OpenID Connect, select Enabled to select OpenID Connect support.Client applications retreive an ID token and an access token.
- To apply the token management settings from an OAuth profile, perform these substeps:
- In the Token Management Configuration area, retain selection of theEnabledcheck box.The token management configuration settings in an OAuth profile apply to client applications assigned to that profile except when this setting is disabled.
- Skip to step 13.
- To manage tokens in a manner that is distinct for this client application, perform these substeps:
- In the Token Management Configuration area, clear theEnabledcheck box.Additional fields display.
- Update any of the additional fields.
- ClickFinished.
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.
- On the Main tab, click.The Resource Server screen displays.
- ClickCreate.
- In theNamefield, type a name for the object.
- ForAuthentication 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 Namefield displays.
- IfResource Server Certificate Distinguished Namedisplays, 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
- ClickFinished.
The new resource server displays on
the list.
Configuring 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.)- On the Main tab, click.The Scope screen opens.
- ClickCreate.
- In theNamefield, type a name for the object.
- In theScope Namefield, type a name for the scope.
- In theScope Valuefield, type a value for the scope.
- In the Customization Settings for English area, in theCaptionfield, type a caption.
- In theDetailed Descriptionfield, 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 theCaptionfield.Here are some examples:Access your profileorUpdate your tasks, projects, and workspace.
- ClickFinished.
Configuring JWT
claims for client apps
When Access Policy Manager (APM) acts as an OAuth
authorization server, you must configure the claims that you want APM to include in the
JSON web tokens it generates. (A
claim
specifies a
string, and optionally, a value, that represents a resource.) - On the Main tab, select.
- ClickCreate.
- InName, type a name for the configuration.
- InClaim Name, type a name for the claim.
- InClaim Value, type a value for the claim.
- ClickSave.The newly created claim displays on the list.
You associate claims with tokens when you
configure an OAuth profile or a client application.
Configuring JWKs
for OAuth authorization server
You configure JSON web keys (JWKs) for Access
Policy Manager (APM) to use to sign the JSON web tokens that it issues when APM acts as
an OAuth authorization server.
- On the Main tab, select.The Key Configuration screen opens.
- ClickCreate.
- In theNamefield, type a name.
- InID, type the ID.
- ForType, selectRSA,Octet, orElliptic Curve.Additional parameters display for the type that you select.
- ForSigning Algorithm, select any one.
- For theOctettype, you only need to configure one additional setting:
- InShared Secret, type the secret.To maximize the security of the algorithm, type enough characters so that the resulting key size matches the block size for the signing algorithm: forHS256, 32 characters; forHS384, 48 characters; forHS512, 64 characters.
- ClickSave.The newly created JWK displays on the list.
- For theRSAorElliptic Curvekey types, configure the settings in the Certificate areas:
- ForCertificate File, select a certificate.Do not select the default certificate when the BIG-IP system is on a chassis platform or is included in an HA pair. F5 strongly discourages the use of the default certificate in a JWK in any configuration.
- To include an X5C (X.509 Certificate Chain) parameter in the JWKS response from the OAuth authorization server JWKS endpoint, selectInclude X5C.
- ForCertificate Key, select one.Do not select the default key when the BIG-IP system is on a chassis platform or is included in an HA pair. F5 strongly discourages the use of the default key in a JWK in any configuration.
- ForKey Passphrase, type a passphrase.
- ForCertificate Chain, select one.
- ClickSave.The newly created JWK displays on the list.
Managing storage
for opaque tokens
You create database instances to store the opaque
tokens that Access Policy Manager (APM) grants and then stores for the tokens'
lifetimes.
APM provides one default database instance,
oauthdb
. Additional instances
enable you to group tokens.- On the Main tab, click.The Database Instance screen opens.
- ClickCreate.
- In theNamefield, type a name for the object.
- In the Purge Schedule Settings area, select a frequency from theFrequencylist and specify a time in theSchedule Atfield.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 theAccess Token Lifetimesetting).Expired access tokens are not removed when theReuse Access Tokensetting 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.
- To save this database instance, clickFinished.
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 types, and authorization server
endpoints that apply to the traffic that goes through a particular virtual
server.
- On the Main tab, click.The OAuth Profile screen opens.
- ClickCreate.
- In theNamefield, type a name for the object.
- ForClient Application, select from the available clients and move them to theSelectedlist.
- ForResource Server, select from the available servers and move them to theSelectedlist.
- ClickFinished.
You have created an OAuth profile that supports the client apps and resource servers
you selected; it supports opaque tokens and is configured to store them in the default
database instance.
You can update the types of tokens (JSON web token and opaque token) provided
through this OAuth profile and update token management settings for either type of
token.
Enabling or disabling opaque tokens and
JSON web tokens
Before you begin this task, you must
create an OAuth profile.
You configure the OAuth profile so
that the OAuth authorization server can issue opaque tokens, JSON web tokens (JWT), or
both, for the traffic that goes through a particular virtual server.
- On the Main tab, click.The OAuth Profile screen opens.
- Click the name of the OAuth profile you want to edit.
- In the Token Management Configuration area, select theCustomcheck box.Settings become available.
- To update support for opaque tokens, locate theSupport Opaque Tokencheck box; then select it to enable opaque tokens or clear it to disable them.When the check box is selected, settings for opaque tokens display, and when it is cleared the settings are hidden.
- To update support for JSON web tokens, locate theSupport JWT Tokencheck box; then select it to enable JWT tokens or clear it to disable them.When the check box is selected, settings for JWT tokens display, and when it is cleared the settings are hidden.
- ClickUpdate.
If the OAuth profile supports both opaque tokens and JWTs, for an OAuth client to
get a JWT, its request to the authorization server must include this parameter and
value:
token_content_type=jwt
.Configuring opaque token settings in an OAuth profile
Before you start, configure an OAuth profile. By default, an OAuth profile enables
opaque tokens and supplies default token management settings for them.
You might want to store opaque tokens in a
non-default database instance or change the access token lifetime.
- On the Main tab, click.The OAuth Profile screen opens.
- Click the name of the OAuth profile you want to edit.
- In the Token Management Configuration area, select theCustomcheck box.Settings become available.
- From theDatabase Instancelist, you can retain the default,oauthdb, or select another database instance.
- To update endpoints:
- In the Authorization Server Endpoints area, select theCustomcheck box.Settings become available.
- Change values in any of these fields:Authorization Endpoint,Token Issuance Endpoint,Token Revocation Endpoint, andToken Introspection Endpoint.
- ClickUpdate.
Configuring support
for JWTs in an OAuth profile
Before you start, configure an OAuth profile, configure JSON web keys (JWK), and
configure claims.
You can configure JWKs in the
area of the product.So that Access Policy Manager (APM) will generate
JSON web tokens (JWTs) for the traffic on a specific virtual server, you configure these
settings in the OAuth profile.
- On the Main tab, click.The OAuth Profile screen opens.
- Click the name of the OAuth profile you want to edit.
- In the Token Management Configuration area, select theCustomcheck box.Settings become available.
- If theSupport JWT Tokenscheck box is cleared, select it.Additional settings display.
- InIssuer, type the URL for the issuer.For example, typehttps://big-ip-server.comwherebig-ip-serveris the name of your server.
- InSubject, retain the default value,%{session.assigned.uuid}, or type a subject for the JWT.The session variablesession.assigned.uuidcontains the UUID that APM assigns to the session after the access policy completes.
- ForPrimary Key, select a JWK from the list.Key rotation is a manual process. The administrator should keep track of the certificate expiration for the primary key and assign rotation keys as needed.
- To specifyRotation Keys, select one or more JWKs and move them to theSelectedlist.
- To specify audience claims, in theAudiencefield, type a string and clickAdd. Repeat this step as needed.
- To specify claims, forClaimsmove claims to theSelectedlist.
- InJWT Refresh Token Encryption Secret, type a string.If theJWT Generate Refresh Tokensetting is enabled, after you set this secret do not change it. Changing the secret automatically invalidates all the issued refresh tokens.F5 recommends that you write the secret down and store it in a safe place in case you ever need to rebuild the OAuth profile.
- To update endpoints, in the Authorization Server Endpoints area select theCustomcheck box.Settings become available.
- To update the OpenID Connect discovery endpoint, inOpenID Connect Configuration Endpointtype the URI where clients can find the OpenID Connect provider configuration document.
- To update the JSON Web Key Set endpoint, inJWKS Endpoint, type the URI where clients can locate the public signing keys for the APM OAuth authorization server.
- ClickUpdate.
If the OAuth profile supports both opaque tokens
and JSON web tokens (JWT), for an OAuth client to get a JWT, its request to the
authorization server must include this parameter and value:
token_content_type=jwt
.About key rotation for JWTs
Access Policy Manager (APM®) does not support
automatic rotation of signing keys for JSON web tokens (JWTs). To configure signing keys, an
administrator selects a primary key in the OAuth profile for authorization server
configurations, and optionally, can specify rotation keys. To determine when to update the
primary key and when to add or to update rotation keys, an administrator might consider
factors such as when the certificates in the keys expire, and how long JWTs that use a
particular key remain valid.
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.
- On the Main tab, click.The Access Profiles (Per-Session Policies) screen opens.
- ClickCreate.The New Profile screen opens.
- In theNamefield, type a name for the access profile.A access profile name must be unique among all access profile and any per-request policy names.
- From theProfile Typelist, selectAllorLTM-APM.
- Scroll down to the Configurations area.
- From theOAuth Profilelist, select the OAuth profile you configured earlier.
- 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.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.
- ClickFinished.
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 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.
- Subject
- Type the name of a subject claim (for JSON web tokens).
- Audience
- Specifies the audiences for the claims (for JSON web tokens).
- Scope / Claim Assign
- Specifies the scopes or the claims for which authorization is requested. If no scopes or claims are specified here, the ones configured in APM for the client application are used.
- Customization
- Customize the messages that display on the OAuth authorization page whenPrompt for Authorizationis set toEnabled:
- Authorize MessageSpecifies the initial wording for the prompt.
- Scope MessageSpecifies the wording that precedes the list of scopes that are specified in the Scope / Claim Assign area of this screen.
- Allow MessageProvides the label for the button that allows access.
- Deny MessageProvides 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.
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.
- On the Main tab, click.The Access Profiles (Per-Session Policies) screen opens.
- In the Per-Session Policy column, click theEditlink for the access profile you want to configure.The visual policy editor opens the access policy in a separate screen.
- Click the(+)icon anywhere in the access policy to add a new item.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.
- On the Logon tab, selectLogon Pageand click theAdd Itembutton.The Logon Page Agent properties screen opens.
- ClickSave.The properties screen closes and the policy displays.
- On a policy branch, click the(+)icon to add an item to the policy.
- On the Authentication tab, selectOAuth Authorizationand clickAdd Item.You must include anOAuth Authorizationitem in the policy for it to work.A Properties popup screen opens.
- If you do not want to prompt for authorization, in the OAuth Authorization area, from thePrompt for Authorizationlist, selectDisabled.
- In theSubjectfield, type the subject.This is the subject of a JSON web token (JWT).
- In the Audience area, for each audience that you want to support for JWT:
- ClickAdd new entry.A numbered entry displays.
- Type an audience name in the new field.
- In the Scope / Claim Assign area, add entries to assign scopes, claims, or both:Assign these whether or not you plan to prompt for authorization.
- ClickAdd new entry.A numbered entry displays withExpressionandClaimandScopeproperties.
- To specify a prerequisite for the scopes and claims, clickchangeand 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.
- To add claims and scopes, clickAdd/Delete; (this opens a popup screen with Scope and Claim tabs); on one or both tabs, select entries and clickUpdate(this closes the popup screen).
- ClickSave.The properties screen closes and the policy displays.
- Add any additional access policy items you require to complete the access policy.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.
- Change the ending fromDenytoAllowon any access policy branch on which you want to grant access.
- Click theApply Access Policylink to apply and activate the changes to the policy.
Creating a client
SSL profile for certificate inspection
Before you start this task, import the CA certificate for VMware View Horizon server to
the BIG-IP system certificate store.
You create a custom client SSL profile to request
an SSL certificate from the client at the start of the session. This enables a Client
Cert Inspection item in an access policy to check whether a valid certificate was
presented.
- On the Main tab, click.The Client SSL profile list screen opens.
- ClickCreate.The New Server SSL Profile screen opens.
- In theNamefield, type a unique name for the profile.
- From theParent Profilelist, selectclientssl.The default settings for the profile specify a 10-second SSL handshake timeout. Some users with smart cards cannot authenticate within that time. You can increase the timeout if this is the case at your site.
- From theConfigurationlist, selectAdvanced.
- If you have VMware View clients on Mac OS X, disable TLS 1.2 in the Options List area:
- In theAvailable Optionslist, selectNo TLS 1.2.
- ClickEnable.
- If you change the values for theCache Sizeor theCache Timeoutsetting, do not specify a value of zero (0) for either setting.When these values are 0, the client must supply a PIN on each browser page refresh.
- Scroll down toHandshake Timeoutand select theCustomcheck box.Additional settings become available.
- To limit the timeout to a number of seconds, selectSpecifyfrom the list, and type the required number in thesecondsfield.In the list, the valueIndefinitespecifies that the system continue trying to establish a connection for an unlimited time. If you selectIndefinite, thesecondsfield is no longer available.
- Scroll down to the Client Authentication area.
- Next to Client Authentication, select theCustomcheck box.The settings become available.
- From theClient Certificatelist, selectrequest.Do not selectrequire.
- From theTrusted Certificate AuthoritiesandAdvertised Certificate Authorities, select the certificates you imported previously.
- ClickFinished.
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.
- On the Main tab, click.The Virtual Server List screen opens.
- ClickCreate.The New Virtual Server screen opens.
- In theService Portfield, type443or selectHTTPSfrom the list.
- From theHTTP Profilelist, selecthttp.
- For theSSL Profile (Client)setting, move the client SSL profile you created earlier to theSelectedlist.
- Scroll down to the Access Profile area.
- From theAccess Profilelist, select the access profile you created earlier.
- ClickFinished.
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. |
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
. - On the Main tab, click.The Customization tool appears in General Customization view, displayingForm Factor: Full/Mobile Browsersettings.
- In the left pane, select the Text tab.A navigation tree displays in the left pane.
- Expand theOAuth Client Applicationsfolder.
- 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 displaysName(setting name) andValue(display text) in the right pane.
- From theLanguagelist above the table, select a language.
- To supply text or to replace existing text forCaption:
- Click in theValuefield.A pencil icon displays at the end of the field.
- Type your translated text and press Enter.
- To supply text or to replace existing text forDetailed Description:
- Click in theValuefield.A pencil icon displays at the end of the field.
- Type your translated text and press Enter.
- Click theSaveicon.
- To customize text for additional languages, select a language, make the changes that you require, and clickSavebefore 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
.
- On the Main tab, click.The Customization tool appears in General Customization view, displayingForm Factor: Full/Mobile Browsersettings.
- In the left pane, select the Text tab.A navigation tree displays in the left pane.
- Expand theOAuth Scopesfolder.
- Click the name of the OAuth scope that you want to localize.The partition where the scope resides precedes the scope name, for exampleCommon/myEmailScope.A table displaysName(setting name) andValue(display text) in the right pane.
- From theLanguagelist above the table, select a language.
- To supply text or to replace existing text forCaption:
- Click in theValuefield.A pencil icon displays at the end of the field.
- Type your translated text and press Enter.
- To supply text or to replace existing text forDetailed Description:
- Click in theValuefield.A pencil icon displays at the end of the field.
- Type your translated text and press Enter.
- Click theSaveicon.
- To customize text for additional languages, select a language, make the changes that you require, and clickSavebefore 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 ® system. For more information, see
area of the BIG-IPBIG-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.
- On the Main tab, click.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.
- Locate the access tokens that you want to delete using any or all of these methods:
- From theDB Instancelist, 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.
- In theSearchfield, type all or part of a user name or client application name and press Enter.Any results that match display.
- Sort the tokens by clicking a table heading, such asClient ApporAccess Token Issued.
- Select the access tokens that you want to revoke.
- ClickRevoke.A popup screen displays a confirmation message.
- On the popup screen, clickRevoke.
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.
- On the Main tab, click.The Database Instance screen opens.
- In theNamefield, click the name of a database instance.A Properties screen opens.
- To purge the database immediately, below the Purge Schedule Settings area, clickPurge Now.
- To specify a schedule for regular database purging, perform these steps:
- Select a frequency from theFrequencylist.
- Specify a time in theSchedule Atfield.
- ClickUpdate.
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.
- Log on to the command line of the BIG-IP system.
- Open the TMOS Shell (tmsh).tmsh
- 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.
- On the Main tab, click.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.
- 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.
- 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 selectedTime.
- To generate charts for another time period, select one from theTimelist.
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.
- On the Main tab, click.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.
- Use the fields at the top of the screen (DB Instance,Access Token Issued, andSearch) 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.
- To view the scopes associated with an access token:
- Click the link in theScopescolumn.A popup screen displays the list of scopes.
- ClickOK.
- To view the user agents associated with an access token:
- Click the link in theUser Agentscolumn.A popup screen displays the list of scopes.
- ClickOK.
- To sort the access tokens byClient App,User,User Agent, or any other table column, click the table column name.
- 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. |
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 .
|
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:
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:
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. |