Manual Chapter :
OAuth Client and Resource Server
Applies To:
Show VersionsBIG-IP APM
- 14.0.1, 14.0.0
OAuth Client and Resource Server
OAuth 2.0
authorization servers that APM supports
Access Policy Manager (APM®) supports OAuth 2.0 only. When configured as an OAuth
client and resource server, APM has been tested with these OAuth authorization servers:
- AzureAD - Azure Active Directory
- F5 - APM configured as an OAuth authorization server.
- Facebook
- Google
- Okta
- Ping Identity - PingFederate
For compatibility information, see release notes for APM on the AskF5™ web site located at
support.f5.com
. APM also supports the configuration of custom providers, that is, external
OAuth 2.0 authorization servers that F5 has not tested. Custom providers should comply with RFC
6749.
About APM support for
OpenID Connect
OpenID Connect adds an identity layer on top of OAuth 2.0. When configured
as an OAuth client / resource server, Access Policy
Manager (APM) can interact with an OpenID Connect
provider to get this data:
- UserInfo requests
- APM can make UserInfo requests to an endpoint that is specified for that purpose on an OAuth provider. APM supports UserInfo requests from the OAuth Scope and OAuth Client agents in an access policy or a per-request policy subroutine.
- ID Token
- As defined in the OpenID Connect core 1.0 spec, an ID Token contains claims by an authorization server about the authenticated user when using a client. APM obtains an ID Token from an OAuth provider when OpenID Connect is enabled in the OAuth Client agent in an access policy or a per-request policy. (The OAuth provider must support OpenID Connect.)
Grant types that APM supports as an OAuth
client
When configured as an OAuth client, Access Policy Manager (APM®) supports authorization code and resource owner password credentials grant
types.
About the OAuth client and resource server
configuration
To configure Access Policy Manager (APM®) as an
OAuth client and resource server, first you must create these objects: OAuth providers, OAuth
servers, and OAuth requests. Then, you must configure APM policies with agents that reference the
objects to get tokens, get permission for scopes, and retrieve scopes.
About OAuth providers
An OAuth provider configuration object specifies an external OAuth authorization server
type and settings to support opaque access tokens, JSON web tokens, and ID Tokens and
OpenID Connect UserInfo requests for those providers that support OpenID Connect.
About OAuth servers
An OAuth server specifies an OAuth provider and the OAuth role that Access Policy Manager (APM®) plays with that provider. It also specifies
the IDs, secrets, and SSL certificates that APM requires to communicate with the OAuth
provider.
About OAuth requests
In Access Policy Manager (APM®), the request
object enables configuration of requests to meet the requirements of your OAuth providers. The
object supports requests for scope permission, scope data, authorization redirect, tokens, and
OpenID Connect UserInfo. It specifies the HTTP method, parameters, and headers to use for the
specific type of request.
About OAuth Client
An OAuth Client agent is a policy item that requests authorization and tokens from an OAuth
server. An OAuth Client can also get scope data on a per-request basis. The OAuth Client agent
provides these configuration elements and options:
- Server
- Specifies the OAuth server to which this OAuth client directs requests.
- Grant Type
- Specifies the type of grant that the OAuth client uses.
- Authorization code - The client redirects the resource owner to the OAuth server to request an authorization code.
- Password - The client uses resource owner password credentials to request an access token from the OAuth server.
- OpenID Connect
- Specifies whether the agent uses OpenID Connect for authorization. Displays whenGrant Typeis set toAuthorization code.To function correctly when enabled, the OAuth provider (associated with the selectedServer) must be configured to support JSON web tokens.
- OpenID Connect Flow Type
- Specifies the OpenID Connect flow type to use:Authorization codeorHybrid.
- OpenID Connect Hybrid Response Type
- Specifies the response type to use for an OpenID Connect hybrid flow:code-idtoken,code-token, orcode-idtoken-token.
- Authentication Redirect Request
- Specifies an auth-redirect-request type request, which redirects a user to an OAuth server. Displays whenGrant Typeis set toAuthorization code.
- Token Request
- Specifies a token-request type of request.
- Refresh Token Request
- Specifies a token-refresh-request type of request. APM uses this request on a per-request basis.
- OpenID Connect UserInfo Request
- Specifies an openid-userinfo-request type of request. Displays whenOpenID Connectis set toEnabled.
- Redirection URI
- Specifies the URI for the OAuth server to redirect a user back to the OAuth client. Displays whenGrant Typeis set toAuthorization code.
- Scope
- Specifies one or more strings separated by spaces; for examplecontacts photo email. The strings are defined by the OAuth authorization server. Your best source of information for the strings that a particular OAuth authorization server defines could be APIs for OAuth 2.0 scopes on developer sites for OAuth providers.For theAuthorization codegrant type, an OAuth authorization server prompts the user to grant or deny access to the scopes. For thePasswordgrant type, an OAuth authorization server grants permission to the requested scopes based on the user providing resource owner password credentials.
Requests are configured in the
area of the product.About OAuth Scope
The OAuth Scope agent validates JSON web tokens (JWT) or validates scopes for opaque tokens.
The OAuth Scope item provides these elements and options:
- Token Validation Mode
- Internal- In this mode, the agent validates JSON web tokens (JWT).
- External- In this mode, the agent makes requests to an OAuth authorization server to get scopes associated with a token and to get scope data, such as a user's email address or contact list.
- JWT Provider List
- Specifies a list of OAuth providers that support JWT. The agent validates JWT from any of these providers when configured. ForInternalmode.
- Server
- Specifies an OAuth server. OAuth servers in resource server, or client and resource server modes are available for selection. ForExternalmode.
- Scopes Request
- Specifies a validation-scopes-request type request. This request type retrieves a list of scopes associated with the token. ForExternalmode.
In
External
mode, there can be multiple scope data requests in this
agent with these elements:- Scope Name
- Specifies the name of a scope for which you are requesting data. (The external OAuth provider specifies the names of the scopes that it supports.)
- Request
- Specifies a scope-data-request type request. This is optional. If the provider does not require this type of request to obtain additional information from an authorization server, you do not need to fill in this field.
Requests are configured in the
area of the product.Overview: Configuring APM as an OAuth client
and resource server
Register Access Policy Manager (APM®) as a client to
an external OAuth authorization server and get information from the external server about the
scopes that it supports. Then configure the OAuth providers, servers, and requests to use from
Access Policy Manager (APM®) policies to interact
with external OAuth authorization servers.
Task summary
Registering APM with a social media OAuth
provider
For users to access resources that
Access Policy Manager (APM) protects
through social media accounts, you must add APM as a client application to an external
server that provides OAuth authorization services.
Perform this step
whether you plan to use APM in the OAuth client role, the OAuth resource server
role, or in both the OAuth client and OAuth resource server roles.
- Create a developer account with the provider.Go to Google or Facebook developer sites or go to another OAuth provider site.
- Log in to your developer account and add APM as a client application.Part of configuring APM as a client application should be to supply the provider with a redirect URI. The OAuth server uses it to redirect users back to APM OAuth client after they complete authorization. Type a URI that includes the FQDN for the virtual server you will configure on the BIG-IP system plus/oauth/client/redirect.Here is an example redirect URI:https://siterequest.com/oauth/client/redirect.
- Copy the IDs and secrets from the configuration and keep them handy.To configure APM as an OAuth client, you need to provide a client ID and client secret when you configure an OAuth server in APM.To configure APM as an OAuth resource server, you need to provide a resource server ID and resource server secret when you configure an OAuth server in APM.Social media account providers supply only a client ID and client secret; you must use them for the client and resource server IDs and the client and resource server secrets in APM.
Registering APM with an enterprise OAuth
provider
To register Access
Policy Manager (APM) as a client application of an
enterprise provider, you must consult the enterprise provider documentation. For
example, if F5 provides OAuth authorization services on another BIG-IP system, you must register APM as a client or as a resource server on
that BIG-IP system. F5 provides the necessary instructions in
BIG-IP
Access Policy Manager: Authentication and Single
Sign-On
on the AskF5 web site located at
support.f5.com
.For users to access resources that
Access Policy Manager (APM) protects
through enterprise accounts, you must add APM as a client application to an external
server that provides OAuth authorization services.
Perform this step
whether you plan to use APM in the OAuth client role, the OAuth resource server
role, or in both the OAuth client and OAuth resource server roles.
- Add APM as a client application of the enterprise OAuth authorization server following instructions from the enterprise provider.Part of configuring APM as a client application should be to supply the provider with a redirect URI. The OAuth server uses it to redirect users back to APM OAuth client after they complete authorization. Type a URI that includes the FQDN for the virtual server you will configure on the BIG-IP system plus/oauth/client/redirect.Here is an example redirect URI:https://siterequest.com/oauth/client/redirect.
- Copy the IDs and secrets from the configuration and keep them handy.To configure APM as an OAuth client, you need to provide a client ID and client secret when you configure an OAuth server in APM.To configure APM as an OAuth resource server, you need to provide a resource server ID and resource server secret when you configure an OAuth server in APM.
Configuring OAuth providers to autodiscover JWTs and JWKs
You can automatically add JWT settings to Access Policy Manager (APM) if your OAuth provider supports OpenID Connect discovery.
- On the Main tab, click.The Provider screen opens.
- ClickCreate.
- In theNamefield, type a name for the object.
- FromType, select a type.You can configure autodiscovery for any provider type except Facebook.The fields that display and default values might change based on your choice.
- ForIgnore Expired Certificate Validation, select the check box to specify whether to ignore enforcement for an expired authorization server certificate.
- ForAllow Self-Signed JWK Config Certificate, select check box to allow APM to create a JWK with a self-signed certificate if one is discovered on the provider.
- Retain the selection of theUse Auto JWTcheck box.TheDiscovery Tasksection displays when this option is selected.
- InOpenID URI, type a string that appends.well-known/openid-configurationto the URL of the issuer and clickDiscover.Discovery updates the URIs in the remaining fields on the screen.
- In theAuthentication URIfield, type the URI to use to request authentication from the provider to get an authorization code.
- In the Token URI field, type the URI to use to retrieve an access token from the provider.
- If any of the URIs contains a fragment, remove it before you save the provider.If there's a#character in a URI, you won't be able to save the provider.
- From theFrequencylist, selectNoneor the frequency of the auto-discovery in hour-to-day intervals.
- ClickSave.
Configuring JWKs
for OAuth clients / resource servers
When Access Policy Manager (APM) is configured to
act as an OAuth client or resource server, it uses JSON web keys (JWKs) to validate the
JSON web tokens it receives. You can use APM to autodiscover JWKs from OAuth providers
that support it. Otherwise, you can configure JWKs using this procedure.
- On the Main tab, select.The Key Configuration screen opens.
- ClickCreate.
- In theNamefield, type a name.
- InID, type an ID.This parameter is used to identity a specific JSON web key.
- 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 a 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.
- To support anRSAor anElliptic Curvekey type, you must either configure settings in the Certificates area or in the Parameters area. To get the necessary parameters from a certificate, go to the Certificates area and configure these settings:
- ForCertificate File, select a certificate.When the BIG-IP system is on a chassis platform or is included in an HA pair, do not select the default certificate. F5 strongly discourages the use of the default certificate in a JWK in any configuration.TheInclude X5C,Certificate Key, andKey Passphrasesettings apply only for a JWK for use with APM as an OAuth authorization server.
- ForCertificate Chain, select one.
- ClickSave.The newly created JWK displays on the list.
- For theRSAtype, in the absence of a certificate go to the Parameters area and complete these substeps:
- ForModulus, type the modulus of the RSA public key.
- ForPublic Exponent, type the public exponent of the RSA public key.
- Supply values for theSHA-1 Thumbprint, andSHA-256 Thumbprintfields.
- ClickSave.The newly created JWK displays on the list.
- For theElliptic Curvetype, in the absence of a certificate, go to the Parameters area and complete these substeps:
- ForX Coordinate, type an X coordinate for the elliptic curve.
- ForY Coordinate, type an Y coordinate for the elliptic curve.
- ForCurve, specify an elliptic curve.For example, typeP-256.
- Supply values for theSHA-1 Thumbprint, andSHA-256 Thumbprintfields.
- ClickSave.The newly created JWK displays on the list.
Specifying token
configurations for JSON web tokens
If you're configuring Access Policy Manager (APM) as an OAuth Client or OAuth Resource
Server and your external OAuth provider supports OpenID Connect, you can autodiscover
the token configuration from the provider instead of using this procedure to configure
it. Before you use this procedure, configure JSON web key settings in APM.
You create token configurations for APM to use as
an OAuth
client/resource
server.
- On the Main tab, select.The Token Configuration screen opens.
- Open the properties for a token configuration:
- To edit an existing token configuration, click its name.
- To add a new token configuration, clickCreate, then on the screen that opens, type a name.
- InIssuerfield, type the URL of the token issuer, starting withhttps.You cannot modify the issuer if this JWT was auto-discovered.
- To use the value ofAccess Token Expires Infrom the provider list, retain the selection of theUse Provider List Settingscheck box. Otherwise, clear the check box and type the number of minutes the access token should live in theAccess Token Expires Infield.
- ForAudience, add all audiences that the provider supports. For each one, type a case-sensitive string and clickAddAudience settings apply to the access token and not to the ID token.Interpretation of audience is application-specific.
- In the Signing Algorithms area, select from theAvailablelist and populate theAllowedandBlockedlists.
- In the Keys (JWK) area, select from theAvailablelist and populate theAllowedandBlockedlists.
- In the Access Tokens area, forBlacklist, to reject a valid JWT access token that contains one of the configured claim names paired with one of the configured claim values, add names and values:
- In the Access Tokens area click (+).
- In theNamefield, type a claim name.
- In theValuesfield, type a claim value to be blacklisted for that claim and clickAdd. (Repeat this step if necessary.)
- ClickSave.The new token displays on the Token Configuration list.
Configuring OAuth
providers without autodiscovery
If you want to use JSON web tokens (JWTs) and the OAuth provider supports them, then
configure JWTs in Access Policy Manager (APM) before you start this task.
You specify the URIs on an external server where
APM gets OAuth authorization services when configured as an OAuth client and resource
server.
APM provides preconfigured providers named
AzureAD
(Azure Active Directory
from Microsoft), F5
(APM),
Facebook
, Google
, Okta
, and Ping
(PingFederate from Ping
Identity).- On the Main tab, click.The Provider screen opens.
- ClickCreate.
- In theNamefield, type a name for the object.
- From theTypefield, select a predefined type of provider, or selectCustom.Based on the type that you select, the fields that display might changeIf you select a predefined type, additional fields fill with default values where possible.
- If theUse Auto-discovered JWTsetting displays, clear the check box.TheToken Configuration (JWT)field displays and is set toNone.
- If these fields display and you want to support JWTs, configure them as follows:
- ForToken Configuration (JWT), select a configuration from the list.
- To specify that the OAuth provider ignore the certificate expiry check during token verification for a resource server, enable theIgnore Expired Certificate Validationcheck box.For this to work as intended, the OAuth authorization server must include an X5C (X.509 Certificate Chain) parameter in its JWKS endpoint response.
- In theAuthentication URIfield, type the URI on the provider where APM should redirect the user for authentication.
- In theToken URIfield, type the URI on the provider where APM can get a token.
- In theToken Validation Scope URIfield, type the URI on the provider where APM can get information about a specific token.
- If the provider supports OpenID Connect and you want to request identity information about a subject, forUserInfo Request URItype the URI at which to make the request.
- ClickFinished.The new provider displays on the Provider screen.
About OAuth client and resource server roles
for APM
A
Mode
setting in the OAuth server configuration specifies the OAuth
roles that you intend Access Policy Manager (APM®) to
play: OAuth client, OAuth resource server, or OAuth client and resource server. You can configure
OAuth servers for each or any of the modes on one BIG-IP® system.About SSL administration for OAuth clients
and resource servers
You might need to perform some SSL administration tasks to support communication between Access Policy Manager (APM®) as an OAuth client and
an OAuth resource server, and external OAuth authorization servers. OAuth server objects on
APM require a server SSL profile for an OAuth client and for an OAuth resource server.
SSL certificates are configured in the
area of the product.Server SSL profiles are configured in the
area of the product. For more information, refer to
BIG-IP® System: SSL
Administration
on the AskF5™ web site located at
support.f5.com
.Configuring OAuth
servers for APM as client and resource server
You configure the OAuth servers that process
requests from Access Policy Manager (APM).
For
APM to play the role of an OAuth client and an OAuth resource server, configure
OAuth servers with
Mode
set to Client + Resource
Server
. - On the Main tab, click.The OAuth Server screen opens.
- ClickCreate.
- In theNamefield, type a name for the object.
- From theModelist, selectClient + Resource Server.APM can use this OAuth server to request access tokens and scope details, such as an email address for the user.The Client Settings and Resource Server Settings areas display.
- From theTypelist, to get OAuth authorization services from another BIG-IP system, retain the default selectionF5; otherwise select another type.If any providers of the selected type exist, theOAuth Providerfield displays one.
- From theOAuth Providerlist, retain the default selection or select another provider.
- From theDNS Resolverlist, select a DNS resolver (or click the plus (+) icon, create a DNS resolver, and then select it).
- In theToken Validation Intervalfield, type a number.If you configure a per-request policy subroutine to validate the token, the subroutine repeats at this interval, or the expiry time of the access token, whichever is shorter.
- In the Client Settings area, fill in these fields:You should have gotten a client ID and client secret when you registered APM as a client of the OAuth authorization server.
- In theClient IDfield, type or paste the client ID.
- In theClient Secretfield, type or paste the secret.
- From theClient's ServerSSL Profile Name, select a server SSL profile.
- In the Resource Server Settings area, fill in these fields.You should have gotten an ID and secret from the OAuth authorization server when you registered APM with it.Social account providers supply only client ID and client secret. For social account providers, use the client ID and client secret for the client and the resource server IDs and secrets.
- In theResource Server IDfield, type or paste the resource server ID (for an enterprise provider).For a social provider, type or paste the client ID instead.
- In theResource Server Secretfield, type or paste the resource server secret (for an enterprise provider).For a social provider, type or paste the client secret instead.
- From theResource Server's ServerSSL Profile Name, select a server SSL profile.
- ClickFinished.The server displays on the OAuth Servers screen.
The OAuth servers that you have configured are available for selection from the OAuth
Client and OAuth Scope agents when you configure an access policy or a per-request
policy.
Configuring OAuth
servers for APM as a client
You configure the OAuth servers that process
requests from Access Policy Manager (APM).
For
APM to play the role of an OAuth client only, configure OAuth servers with
Mode
set to Client
. - On the Main tab, click.The OAuth Server screen opens.
- ClickCreate.
- In theNamefield, type a name for the object.
- From theModelist, selectClient.In this mode, APM can request access tokens from this OAuth server; APM can also refresh an existing access token when expired on a per-request basis.The Client Settings area displays.
- From theTypelist, to get OAuth authorization services from another BIG-IP system, retain the default selectionF5; otherwise select another type.If any providers of the selected type exist, theOAuth Providerfield displays one.
- From theOAuth Providerlist, retain the default selection or select another provider.
- From theDNS Resolverlist, select a DNS resolver (or click the plus (+) icon, create a DNS resolver, and then select it).
- If you have iRules to use, in theiRulessetting move them to theSelectedlist.For detailed information on iRules, see the F5 Networks DevCentral web site,devcentral.f5.com.
- In theToken Validation Intervalfield, type a number.If you configure a per-request policy subroutine to validate the token, the subroutine repeats at this interval, or the expiry time of the access token, whichever is shorter.
- In the Client Settings area, fill in these fields:You should have gotten a client ID and client secret when you registered APM as a client of the OAuth authorization server.
- In theClient IDfield, type or paste the client ID.
- In theClient Secretfield, type or paste the secret.
- From theClient's ServerSSL Profile Name, select a server SSL profile.
- ClickFinished.The server displays on the OAuth Servers screen.
The OAuth servers that you have configured are available for selection from the OAuth
Client agent when you configure an access policy or a per-request policy.
Configuring OAuth
servers for APM as a resource server
You configure the OAuth servers that process
requests from Access Policy Manager (APM).
For
APM to play the role of an OAuth resource server only, configure OAuth servers with
Mode
set to Resource Server
.
- On the Main tab, click.The OAuth Server screen opens.
- ClickCreate.
- In theNamefield, type a name for the object.
- From theModelist, selectResource Server.APM can use this OAuth server to request a list of scopes associated with the access token , request details for a particular scope, such as an email address for the user, or to make both types of requests.The Resource Server Settings area displays.
- From theTypelist, to get OAuth authorization services from another BIG-IP system, retain the default selectionF5; otherwise select another type.If any providers of the selected type exist, theOAuth Providerfield displays one.
- From theOAuth Providerlist, retain the default selection or select another provider.
- From theDNS Resolverlist, select a DNS resolver (or click the plus (+) icon, create a DNS resolver, and then select it).
- If you have iRules to use, in theiRulessetting move them to theSelectedlist.For detailed information on iRules, see the F5 Networks DevCentral web site,devcentral.f5.com.
- In theToken Validation Intervalfield, type a number.If you configure a per-request policy subroutine to validate the token, the subroutine repeats at this interval, or the expiry time of the access token, whichever is shorter.
- In the Resource Server Settings area, fill in these fields.You should have gotten an ID and secret from the OAuth authorization server when you registered APM with it.Social account providers supply only client ID and client secret. For social account providers, use the client ID and client secret for the client and the resource server IDs and secrets.
- In theResource Server IDfield, type or paste the resource server ID (for an enterprise provider).For a social provider, type or paste the client ID instead.
- In theResource Server Secretfield, type or paste the resource server secret (for an enterprise provider).For a social provider, type or paste the client secret instead.
- From theResource Server's ServerSSL Profile Name, select a server SSL profile.
- ClickFinished.The server displays on the OAuth Servers screen.
The OAuth servers that you have configured are available for selection from the OAuth
Scope agent when you configure an access policy or a per-request policy.
Configuring requests for preconfigured providers
Configure requests for token validation,
getting scopes and scope details, authorization redirect, access token, or refresh token
to meet the specifications of the provider.
- On the Main tab, click.APM supplies several preconfigured requests for these providers: AzureAD (Azure Active Directory), F5 (APM), Facebook, Google, Okta, and Ping (PingFederate from Ping Identity).
- To copy a request:You cannot delete or update preconfigured requests. However, you can copy preconfigured requests and edit the copies. You can also create new requests.
- In the Copy column of the request, click theCopylink.
- In theNew Request Namefield, type a name.
- ClickCopy.The Properties screen for the new request displays.
- For theHTTP MethodandTypesettings, retain the existing values or select new ones.
- To edit existing request parameters:
- FromRequest Parameters, select an entry and clickEdit.The entry populates theParameter TypeandParameter Namefields, and, for acustomparameter type, theParameter Valuefield.
- Edit the Request Parameters as needed.Do not configure aCODE,REFRESH_TOKEN, orSTATEparameter. APM adds these parameters automatically when needed.
- ClickAdd.The edited request parameters display in the list.
- Add or delete any request parameters as needed.
- If you need to add a request header:
- In theHeader Namefield, type a name.
- In theHeader Valuefield, type a value.
- ClickAdd.
The entry displays in theRequest Headersfield. - ClickUpdate.
If using Okta preconfigured requests, Okta
provides a refresh token only when
offline_access
is requested.
Therefore, offline_access
is used as the
scope in default requests. If you need to make the user consent prompt
visible, you must create a new request that does not specify
offline_access
as the
scope. In addition, in the Okta setup, make sure that you have the API Access
Management and User Consent features enabled. When both features are enabled,
clients see a user consent prompt when connecting to their resources. Refer to
Okta documentation for how to add user consent dialogs to the authentication
flow.Requests are available for selection in the OAuth Client and OAuth Scope agents
when you configure an access policy or a per-request policy subroutine.
Configuring
requests for custom providers
To perform this task, you need to understand the request parameters, request values,
request headers, and HTTP method that the external OAuth authorization server supports
for the type of request you plan to specify.
You configure a request for token validation,
getting scopes and scope details, authorization redirect, access token, or refresh token
that meets the specifications of the custom provider.
APM
provides preconfigured providers, AzureAD (Azure Active Directory), F5 (APM),
Facebook, Google, Okta, and Ping (PingFederate from Ping Identity), and supports
configuration of custom providers.
- On the Main tab, click.
- ClickCreate.
- In theNamefield, type a name.
- ForHTTP Method, retainPOSTor selectGET.
- From theTypelist, select a request type.
- If you selected thescope-data-requesttype, type a URI in theURIfield.
- Specify request parameters:
- FromParameter Type, select an option.If you selectcustom, theParameter Valuefield displays.
- In theParameter Namefield, type a name as specified by your provider.Do not configure aCODE,REFRESH_TOKEN, orSTATEparameter. APM adds these parameters automatically when needed.
- In theParameter Valuefield, type a value.
- ClickAdd.The entry displays in theRequest Parametersfield.
- Add request headers if needed:
- In theHeader Namefield, type a name.
- In theHeader Valuefield, type a value.
- ClickAdd.
The entry displays in theRequest Headersfield. - ClickFinished.
The request displays in the list on
the screen.
Requests are available for selection in the OAuth
Client and OAuth Scope agents when you configure a per-session policy or a per-request
policy subroutine.
Configuring UserInfo requests for OpenID Connect
To perform this task, you need to understand
the request parameters, request values, request headers, and HTTP method that the
external OAuth authorization server supports for an OpenID Connect UserInfo
request.
Access Policy Manager (APM) provides
preconfigured requests for acquiring UserInfo through OpenID Connect for the Ping
(PingFederate from Ping Identity), Okta, and Google OAuth provider types. To get
UserInfo from custom providers that support OpenID Connect, you create requests that
meet the specifications of the custom provider.
- On the Main tab, click.
- ClickCreate.
- In theNamefield, type a name.
- ForHTTP Method, retainPOSTor selectGET.
- From theTypelist, selectopenid-userinfo-request.
- Specify the options in theRequest Parameterssetting:
- FromParameter Type, select an option.If you selectcustom, theParameter Valuefield displays.
- In theParameter Namefield, type a name as specified by your provider.Do not configure aCODE,REFRESH_TOKEN, orSTATEparameter. APM adds these parameters automatically when needed.
- In theParameter Valuefield, type a value.
- ClickAdd.The entry displays in theRequest Parametersfield.
- AddRequest Headersif needed:
- In theHeader Namefield, type a name.
- In theHeader Valuefield, type a value.
- ClickAdd.
The entry displays in theRequest Headersfield. - ClickFinished.
Requests are available for selection in the OAuth
Client and OAuth Scope agents when you configure an access policy or a per-request
policy subroutine.
Configuring a
provider list
Access Policy Manager (APM) provides a number of preconfigured OAuth providers. To add
custom OAuth providers to a provider list, first configure them in the
area. You configure a provider list for use with APM
configured as an OAuth resource server. A
provider list
enables a single OAuth Scope agent in an access policy to validate tokens issued
by multiple OAuth providers. - On the Main tab, select.
- ClickCreate.
- InName, type a name for the configuration.
- InAccess Token Expires In, type the number of minutes that access token should live.
- From theProviderlist, select a provider and clickAdd. Repeat this step to add additional providers to the list.
OAuth request type reference
The table lists OAuth request types, and specifies the agents that use them and the
policies where they are used.
Request type |
Description |
Agents and policies where used |
---|---|---|
auth-redirect-request |
Redirects a user to an authorization server. |
An OAuth Client agent uses this request at the start of a session (from the
access policy) and can also use it from a per-request policy subroutine. This request
is applicable when the OAuth Client is configured with the authorization code grant.
This request can only use the GET parameter. |
token-request |
Accesses an authorization server to obtain an access token or exchange an
authorization code for an access token. |
An OAuth Client agent uses this request at the start of a session (from the
access policy) and can also use it from a per-request policy subroutine. |
token-refresh-request |
Refreshes an expired access token. |
An OAuth Client agent can make token refresh requests from a per-request policy
subroutine. |
validation-scopes-request |
Accesses an authorization server to get a list of scopes associated with an
access token and to get scope data for those scopes. |
An OAuth Scope agent uses this request at the start of a session (from the access
policy) and can also use it from a per-request policy subroutine. The
preconfigured F5ScopesRequest request is designed for use
when APM is the OAuth server. |
scope-data-request |
Accesses an authorization server to get scope data. |
An OAuth Scope agent can use this request type from an access policy and can also
use it from a per-request policy subroutine. |
openid-userinfo-request |
Accesses a well-known endpoint for OpenID Connect to get UserInfo |
An OAuth Scope and OAuth Client agent can use this request to get
information. |
Implementation result
The OAuth provider, server, and request objects are ready for use in OAuth Client and OAuth
Scope agents in access policies and per-request policy subroutines.
Overview: Configuring policies for OAuth
client and resource server
When Access Policy Manager (APM®) acts as an OAuth
client, an OAuth Client policy item can obtain an access token (and a refresh token if configured
to do so) at the start of a session through the access policy. The OAuth client can also make
OpenID Connect UserInfo requests following one of the OpenID Connect-defined flows (Authorization
code flow or hybrid flow).
Throughout the session, an OAuth Client policy item can run periodically from a per-request
policy subroutine to make OpenID Connect UserInfo requests, and, when the token expires, make an
attempt to refresh the access token (if a refresh token exists) or authenticate the user anew.
When APM acts as an OAuth resource server, an OAuth Scope policy item can be used to validate a
token and make scope data and UserInfo requests from the access policy and, periodically, from a
per-request policy subroutine.
Task summary
Sample policy: Get an access token once per
session
To obtain an access token one time only for the session, you need to configure an access
policy. The OAuth Client agent can request a token.
With this access policy, the user logs on through a BIG-IP® system. The
OAuth Client agent obtains an access token, and an OAuth Scope agent tries to retrieve the
list of scopes associated with the token from the OAuth provider. The session starts. When the
token expires, the system makes no attempt to refresh it.
Sample policies: Get
a token and validate it for each request
To obtain an access token and to validate it for each request, first you
need an access policy to obtain the token.
To periodically validate and refresh the token, you need a per-request
policy subroutine.
Sample policy: Validate tokens
per-request
When Access Policy Manager (APM®) acts as an OAuth
resource server, an OAuth Scope agent validates tokens obtained from the incoming request.
Creating an access
profile for OAuth client and resource server
You create an access profile to provide the access
policy configuration for a virtual server that establishes a secured session.
- 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, select one these options:
- LTM-APM: Select for a web access management configuration.
- SSL-VPN: Select to configure network access, portal access, or application access. (Most access policy items are available for this type.)
- ALL: Select to support LTM-APM and SSL-VPN access types.
- SWG - Explicit: Select to configure access using Secure Web Gateway explicit forward proxy.
- SWG - Transparent: Select to configure access using Secure Web Gateway transparent forward proxy.
Depending on licensing, you might not see all of these profile types.Additional settings display. - 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.
- ClickFinished.
The access profile displays in the Access Profiles
List. Default-log-setting is assigned to the access profile.
Configuring an
OAuth Client agent in an access policy
Before you start, you need an OAuth server configured in Access Policy Manager (APM)
that supports clients (
Mode
is
set to Client
or Client + Resource Server
) .You add an OAuth Client agent to an access policy
to request authorization from an OAuth server for one or more scopes. You can add more
than one OAuth Client item to an access policy, with each item requesting permission for
additional scopes.
- 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 theAuthenticationtab, selectOAuth Client.
- ClickAdd Item.The screen is not active while the visual policy editor creates the action. The screen closes and a Properties screen opens.
- In theNamefield, type a name for the policy item.This name is displayed in the action field for the policy.
- From theServerlist, select an OAuth server.Only OAuth servers configured withModeset toClientorClient + Resource Serverdisplay.
- From theGrant Typelist, select one of these options:
- Authorization code- Redirects the user to the external server to authenticate. The user is redirected back to APM with an authorization code. APM uses the authorization code to request an access token
- Password- Requests an access token from the external server by using the user's credentials (username and password). If this method is configured, the user must provide their external credentials to APM; to make this happen you must insert a logon page before the OAuth Client item in the access or the per-request policy.
If you selectAuthorization code, theRedirection URIfield displays. - To enable OpenID Connect in the agent, perform these substeps:
- ForOpenID Connect, selectEnabled.Additional fields display.
- ForOpenID Connect Flow Type, retainAuthorization codeor selectHybridand then select an entry forOpenID Connect Hybrid Response Type.
- ForOpenID Connect UserInfo Request, select a request.
- Select the requests to make to the OAuth server from the access policy.
- Authentication Redirect Request- Specifies an auth-redirect-request type request, which redirects a user to an OAuth server. Displays whenGrant Typeis set toAuthorization code.
- Token Request- Specifies a token-request type of request.
You can make a selection from theRefresh Token Requestlist, but the OAuth Client does not use this request from an access policy.Requests are configured in thearea of the product. - If theRedirection URIfield displays, retain the default value (https://%{session.server.network.name}/oauth/client/redirect) or type a URI that points back to the APM client.If you type a URI, you must retain this path/oauth/client/redirect. Only change the host name portion of the URI.The OAuth server uses the URI to send the user back to APM.
- In theScopefield, type one or more scopes separated by spaces.Each time you add another OAuth Client agent to a policy, you must include the scopes (for example,email photos) that were requested in the previous instance of the OAuth Client and append any additional scopes (for example, contacts) to the list (for example,email photos contacts).Read the OAuth provider documentation to learn the names of the scopes that they support and the URIs where you can obtain the data.
- ClickSave.The Properties screen closes. The newly added item displays in the policy.
- If you selectedPasswordfrom theGrant Typelist, you must insert a logon page agent to precede the OAuth Client agent.
- Click (+) ahead of theOAuth Clienton the policy branch.
- On the Logon Page tab, selectOAuth Logon Pageand clickAdd Item.A Properties screen displays.
- ClickSave.The properties screen closes. The policy displays.
- Complete the policy:
- Add any branch rules that you need.By default, theOAuth Clientitem has a successful branch for any valid non-error JSON response it receives. However, you can add other branch rules based on authorization server response to suit your needs.
- Change branch endings as needed; changeDenytoAllowwhere you want to provide access.
- Click theApply Access Policylink to apply and activate the changes to the policy.
Configuring OAuth
Scope for opaque tokens in an access policy
Before you start, you need an OAuth server that supports resource servers (
Mode
is set to Resource
or Client + Resource Server
) configured
in Access Policy Manager (APM).You add an
OAuth Scope
item to a policy either
to request the list of scopes associated with an opaque token or to request scope data
from the OAuth server. If the access policy already includes an
OAuth Client
item, place the
OAuth Scope
agent
somewhere after the OAuth
Client
on the policy branch.- 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 theAuthenticationtab, selectOAuth Scope.
- ClickAdd Item.The screen is not active while the visual policy editor creates the action. The screen closes and a Properties screen opens.
- In theNamefield, type a name for the policy item.This name is displayed in the action field for the policy.
- FromToken Validation Mode, retain the default setting,External.This mode allows the OAuth Scope agent to make scope requests and OpenID Connect UserInfo requests.
- From theServerlist, select an OAuth server.Only OAuth servers configured withModeset toResource ServerorClient + Resource Serverdisplay.
- To get a list of scopes associated with an access token, from theScopes Requestlist, select a request to send to the OAuth provider.The list displays validation-scopes-request types.If F5 (APM) is the OAuth provider, selectF5ScopesRequest.Requests are configured in thearea of the product.
- To add requests for scope data (for example, to request a user's email address or profile), perform these steps:
- ClickAdd new entry.A new line is added to the list of entries.
- In theScope Namefield, type the name of a scope that the OAuth provider supports.The scope must be associated with the access token. (The user must have granted permission for this scope.)For example, some OAuth providers support scopes namedemailorprofile.
- From theRequestlist, select a request.The list includes scope-data-request types. Select one that you configured to meet the requirements of the specific OAuth provider.
- To include a UserInfo request, select one from theOpenID Connect UserInfo Requestlist.
- ClickSave.The Properties screen closes. The newly added item displays in the policy.
- Complete the policy:
- Add any additional policy items you require.
- 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.
Configuring OAuth Scope for JWTs in an access policy
Before you start, you need to have configured a
JSON web token (JWT) provider list. You can configure it in the
area of the product.You can add an
OAuth Scope
item to a policy to
process JSON web tokens (JWTs) from multiple providers. If the access policy already includes an
OAuth Client
item, place the
OAuth Scope
agent
somewhere after the OAuth
Client
on the policy branch.- 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 theAuthenticationtab, selectOAuth Scope.
- ClickAdd Item.The screen is not active while the visual policy editor creates the action. The screen closes and a Properties screen opens.
- In theNamefield, type a name for the policy item.This name is displayed in the action field for the policy.
- FromToken Validation Mode, selectInternal.This mode allows the OAuth Scope agent to process JSON web tokens from multiple providers.TheJWT Provider Listfield displays.
- FromJWT Provider List, select a list.Provider lists are configured in thearea of the product.
- ClickSave.The Properties screen closes. The newly added item displays in the policy.
- Complete the policy:
- Add any additional policy items you require.
- Change the ending fromDenytoAllowon any access policy branch on which you want to grant access.
What causes a subroutine to run for an OAuth
server?
A
per-request policy
runs at each request. A per-request policy
subroutine
runs periodically at whichever of these intervals is shorter: the number
of minutes specified in the OAuth server Token Validation Interval
field on Access Policy Manager (APM®), or the
interval that the external OAuth authentication server specifies in the
expires_in
attribute of the access token it issues. Configuring an
OAuth Client agent in a subroutine
Before you start, you need an OAuth server configured in Access Policy Manager (APM)
that supports clients (
Mode
is
set to Client
or Client + Resource Server
) .You configure a per-request policy subroutine to
periodically validate an OAuth token, to obtain a new or a refresh token, to get scopes
and scope data.
- On the Main tab, click.The Per-Request Policies screen opens.
- In theNamefield, locate the policy that you want to update, then in thePer-Request Policyfield, click theEditlink.The visual policy editor opens in another tab.
- Click theAdd New Subroutinebutton.A popup screen opens.
- On theSubroutine from templatelist, retain the selectionEmpty, and clickSave.The popup screen closes. The subroutine, with the heading[+] Subroutine:, displays below the main editor.Name
- Expand the subroutine by clicking the [+] icon.The subroutine displays.
- Click the(+)icon anywhere in the subroutine to add a new item.A small set of actions are provided for building a subroutine.A popup screen displays actions on tabs, such as General Purpose and Authentication, and provides a search field.
- On theAuthenticationtab, selectOAuth Client.
- ClickAdd Item.The screen is not active while the visual policy editor creates the action. The screen closes and a Properties screen opens.
- In theNamefield, type a name for the policy item.This name is displayed in the action field for the policy.
- From theServerlist, select an OAuth server.Only OAuth servers configured withModeset toClientorClient + Resource Serverdisplay.
- From theGrant Typelist, select one of these:
- Authorization code- Redirects the user to the external server to authenticate. The user is redirected back to APM with an authorization code. APM uses the authorization code to request an access token
- Password- Requests an access token from the external server by using the user's credentials (username and password). If this method is configured, the user must provide their external credentials to APM; to make this happen, you must insert a logon page before the OAuth Client item in the access or the per-request policy.If you select the password grant type, every time the per-request policy subroutine runs, it must request credentials from the user.
- To add an OpenID Connect UserInfo request to the policy, perform these steps:
- ForOpenID Connect, selectEnabled.Additional fields display.
- ForOpenID Connect Flow Type, retainAuthorization codeor, selectHybridand then select an entry forOpenID Connect Hybrid Response Type.
- ForOpenID Connect UserInfo Request, select a request.
- Select requests for the per-request policy to make to the OAuth server.
- Authentication Redirect Request- Specifies an auth-redirect-request type request, which redirects a user to an OAuth server. Displays whenGrant Typeis set toAuthorization code.
- Token Request- Specifies a token-request type of request.
- Refresh Token Request- Specifies a token-refresh-request type of request.
Requests are configured in thearea of the product. - If theRedirection URIfield displays, retain the default value (https://%{session.server.network.name}/oauth/client/redirect) or type a URI that points back to the APM client.If you type a URI, you must retain this path/oauth/client/redirect. Only change the host name portion of the URI.The OAuth server uses the URI to send the user back to APM.
- In theScopefield, type one or more scopes separated by spaces.Each time you add another OAuth Client agent to a policy, you must include the scopes (for example,email photos) that were requested in the previous instance of the OAuth Client and append any additional scopes (for example, contacts) to the list (for example,email photos contacts).Read the OAuth provider documentation to learn the names of the scopes that they support and the URIs where you can obtain the data.
- ClickSave.The Properties screen closes. The newly added item displays in the policy.
- If you selectedPasswordfrom theGrant Typelist, you must insert a logon page agent to precede the OAuth Client agent.
- Click (+) ahead of theOAuth Clienton the policy branch.
- On the Logon Page tab, selectOAuth Logon Pageand clickAdd Item.A Properties screen displays.
- ClickSave.The properties screen closes. The policy displays.
- Complete the policy:
- Add any branch rules that you need.By default, theOAuth Clientitem has a successful branch for any valid non-error JSON response it receives. However, you can add other branch rules based on authorization server response to suit your needs.
- Change branch endings as needed; changeDenytoAllowwhere you want to provide access.
- Add the subroutine to the per-request policy:
- On a per-request policy branch, click the (+) icon.
- Select the Subroutines tab.
- Select the subroutine and clickAdd Item.The popup screen closes and the policy displays.
- To rename the subroutine or to update number of seconds that the subroutine has to complete its interactions with the OAuth server, perform these steps:
- ClickSubroutine Settings/Rename.
- To rename the subroutine, type in theNamefield.
- To update the timeout, type a number in theSubroutine Timeout (sec)field.No additional settings on this screen are applicable to the OAuth Client and OAuth Scope items.
- ClickSave.The popup screen closes. The subroutine displays in the policy.
To affect network traffic, along with an access
policy, a per-request policy must be specified on a virtual server.
Configuring OAuth Scope for opaque tokens
in a subroutine
Before you start, you need an OAuth
server that supports resource servers (
Mode
is set to
Resource
or Client + Resource Server
)
configured in Access Policy Manager (APM).To periodically get scopes and scope
data for an existing access token, you configure an OAuth Scope agent in a per-request
policy subroutine.
- On the Main tab, click.The Per-Request Policies screen opens.
- In theNamefield, locate the policy that you want to update, then in thePer-Request Policyfield, click theEditlink.The visual policy editor opens in another tab.
- Click theAdd New Subroutinebutton.A popup screen opens.
- On theSubroutine from templatelist, retain the selectionEmpty, and clickSave.The popup screen closes. The subroutine, with the heading[+] Subroutine:, displays below the main editor.Name
- Expand the subroutine by clicking the [+] icon.The subroutine displays.
- Click the(+)icon anywhere in the subroutine to add a new item.A small set of actions are provided for building a subroutine.A popup screen displays actions on tabs, such as General Purpose and Authentication, and provides a search field.
- On theAuthenticationtab, selectOAuth Scope.
- ClickAdd Item.The screen is not active while the visual policy editor creates the action. The screen closes and a Properties screen opens.
- In theNamefield, type a name for the policy item.This name is displayed in the action field for the policy.
- FromToken Validation Mode, retain the default setting,External.This mode allows the OAuth Scope agent to make scope requests and OpenID Connect UserInfo requests.
- From theServerlist, select an OAuth server.Only OAuth servers configured withModeset toResource ServerorClient + Resource Serverdisplay.
- To get a list of scopes associated with an access token, from theScopes Requestlist, select a request to send to the OAuth provider.The list displays validation-scopes-request types.If F5 (APM) is the OAuth provider, selectF5ScopesRequest.Requests are configured in thearea of the product.
- To add requests for scope data (for example, to request a user's email address or profile), perform these steps:
- ClickAdd new entry.A new line is added to the list of entries.
- In theScope Namefield, type the name of a scope that the OAuth provider supports.The scope must be associated with the access token. (The user must have granted permission for this scope.)For example, some OAuth providers support scopes namedemailorprofile.
- From theRequestlist, select a request.The list includes scope-data-request types. Select one that you configured to meet the requirements of the specific OAuth provider.
- To include a UserInfo request, select one from theOpenID Connect UserInfo Requestlist.
- ClickSave.The Properties screen closes. The newly added item displays in the policy.
- Add the subroutine to the per-request policy:
- On a per-request policy branch, click the (+) icon.
- Select the Subroutines tab.
- Select the subroutine and clickAdd Item.The popup screen closes and the policy displays.
- To rename the subroutine or to update number of seconds that the subroutine has to complete its interactions with the OAuth server, perform these steps:
- ClickSubroutine Settings/Rename.
- To rename the subroutine, type in theNamefield.
- To update the timeout, type a number in theSubroutine Timeout (sec)field.No additional settings on this screen are applicable to the OAuth Client and OAuth Scope items.
- ClickSave.The popup screen closes. The subroutine displays in the policy.
To affect network traffic, along with an access policy, a per-request policy must
be specified on a virtual server.
Configuring an
OAuth Scope agent for JWTs in a subroutine
Before you start this task, you need to have configured a JSON web token (JWT) provider
list. Provider lists are configured in the
area of the product.You can add an
OAuth Scope
item to a policy to
process JSON web tokens (JWTs) from multiple providers. - On the Main tab, click.The Per-Request Policies screen opens.
- In theNamefield, locate the policy that you want to update, then in thePer-Request Policyfield, click theEditlink.The visual policy editor opens in another tab.
- Click theAdd New Subroutinebutton.A popup screen opens.
- On theSubroutine from templatelist, retain the selectionEmpty, and clickSave.The popup screen closes. The subroutine, with the heading[+] Subroutine:, displays below the main editor.Name
- Expand the subroutine by clicking the [+] icon.The subroutine displays.
- Click the(+)icon anywhere in the subroutine to add a new item.A small set of actions are provided for building a subroutine.A popup screen displays actions on tabs, such as General Purpose and Authentication, and provides a search field.
- On theAuthenticationtab, selectOAuth Scope.
- ClickAdd Item.The screen is not active while the visual policy editor creates the action. The screen closes and a Properties screen opens.
- In theNamefield, type a name for the policy item.This name is displayed in the action field for the policy.
- FromToken Validation Mode, selectInternal.This mode allows the OAuth Scope agent to process JSON web tokens from multiple providers.
- FromJWT Provider List, select a list.Provider lists are configured in thearea of the product.
- ClickSave.The Properties screen closes. The newly added item displays in the policy.
Creating a virtual server to manage HTTPS traffic
You can create a virtual server to manage HTTPS traffic.
- On the Main tab, click.The Virtual Server List screen opens.
- ClickCreate.The New Virtual Server screen opens.
- In theNamefield, type a unique name for the virtual server.
- In theService Portfield, type443or selectHTTPSfrom the list.
- From theHTTP Profilelist, selecthttp.
- For theSSL Profile (Client)setting, from theAvailablelist, selectclientssl, and using the Move button, move the name to theSelectedlist.
- ClickFinished.
The HTTPS virtual server appears in the Virtual Server List screen.
Adding access
profile and per-request policy to the virtual server
You associate an access profile with a virtual server for use in
establishing an access session. If you have configured a per-request policy, which
is for use throughout the access session, you associate it with the virtual server
also.
- On the Main tab, click.The Virtual Server List screen opens.
- Click the name of the virtual server that manages access for the web application you are securing.
- In the Access Policy area, from theAccess Profilelist, select the access profile that you configured earlier.
- In the Access Policy area, from thePer-Request Policylist, select the policy that you configured earlier.
- ClickUpdate.
The access profile (and access policy) and the per-request policy are now associated
with the virtual server.
Overview: Customizing an OAuth Logon
Page
The default OAuth Logon Page agent displays messages that instruct the user to log in using an
authorization code or a resource owner password credentials (ROPC) grant type. It displays
option buttons from which users select the OAuth provider through whom they want to log in.
For an alternative look and
feel, an advanced customization template for the OAuth Logon Page agent is available on
DevCentral.
Customization options in the OAuth Logon Page agent enable an admin to add, update, delete, and
reorganize the OAuth providers, as well as to configure the fields and text to display.
About the OAuth Logon Page advanced
customization template
The OAuth Logon Page advanced customization template provides the code and the images necessary
to display a logon page that, by default, looks like this.
No affiliation between F5 Networks, Inc. (and its affiliated companies), and any of the above
companies, including their associated products and services, relating to the functionality
above, exists or is implied, nor is there any actual or implied recommendation or endorsement
thereof.
The template forms a starting point for additional customization to achieve a logon page with
the preferred providers, images, colors, fields, and text.
The OAuth Logon Page template is available for download from DevCentral™ at
devcentral.f5.com
. Instructions for advanced customization with the
OAuth Logon Page template are also available in BIG-IP®
Access Policy Manager: Advanced Customization Examples
on
DevCentral.Updating OAuth providers on the OAuth
Logon Page
You can add, delete, and reorder the
list of OAuth providers that display on an OAuth Logon Page.
- Open the per-session policy (or the per-request policy subroutine) that you want to update.
- Click theOAuth Logon Pageitem.A Properties screen opens.
- In row 1 of the Logon Page Agent table, click theValuesfield.Row 1 contains values for theoauthprovidertypevariable.A popup screen displays options with aValueand aTextfield for each provider.
- Add, delete, or reorder the providers, and clickFinished.The popup screen closes. The updated list of providers displays in theValuesfield in row 1.
- If you added a provider, add a branch rule for that provider:
- Click the Branch Rules tab.
- ClickAdd Branch Rule.A new entry withNameandExpressionsettings displays.
- In theNamefield, replace the default name by typing a new name.The name appears on the branch in the policy.
- Select and copy an expression from another branch rule.For example, copy the expression displayed for theF5branch rule:expr{[mcget{session.logon.last.oauthprovidertype}] == "F5"}
- For the branch rule that you added, in theExpressionsetting click thechangelink.A popup screen opens.
- Click the Advanced tab, paste the expression into the field, and replace the existing provider name (such asF5) with the new provider name.For example, the result might look like this:expr{[mcget{session.logon.last.oauthprovidertype}] == "Siterequest"}
- ClickFinished.The popup screen closes.
- ClickSave.The properties screen closes and the policy displays.
- ClickFinished.The popup screen closes.
- If you are working with a per-session policy, click theApply Access Policylink.
Overview: Configuring APM as an OAuth
resource server gateway
Some applications do not support standard HTTP redirection and cookies. For Access Policy Manager (APM®) to act as an OAuth resource server and
provide an OAuth authorization layer into an API gateway, you must configure APM with a special
access profile. This access profile also allows only a limited set of policy agents.
As a resource server gateway, APM must validate the tokens it receives. APM supports JSON web
tokens (JWT) and validates them internally on the BIG-IP® system. APM also
supports opaque tokens: to validate them, APM must interact with OAuth providers that are
external to the BIG-IP system. APM also supports requesting UserInfo at a URI on an OAuth
provider.
A single OAuth Scope agent works to validate tokens internally or externally. If you need to do
both, you need two OAuth Scope agents. You can configure them using one access profile and
policies that branch to the separate agents. Or you can configure them using two access profiles
with policies that each contain an OAuth Scope agent. Those details are up to you. In this
example, we walk through configuring one access profile and a policy that includes one OAuth
Scope agent.
This configuration supports OAuth client apps that send requests with an HTTP Authorization
header that contains an OAuth Bearer token.
Task summary
Creating an access
profile for a resource server gateway
You create an access profile to provide the access
policy configuration for a virtual server that establishes a secured session.
- 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, selectOAuth-Resource Server.TheUser Identification Methodsetting changes toOAuth Token.
- 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.
- ClickFinished.
The access profile displays in the Access Profiles
List. Default-log-setting is assigned to the access profile.
Creating APM access and per-request
policies for a resource server gateway
Before you start this task, you need
to have configured these objects in Access Policy Manager (APM):
- An OAuth server that supports resource servers only (Modeis set toResource).
- An access profile of theOAuth-Resource Servertype.
- A JSON web token provider list to process JWTs if you plan to process them with this agent.
To use Access
Policy Manager (APM) as an OAuth resource server gateway,
you need an OAuth Scope agent to validate the tokens that APM receives. You can
configure an OAuth Scope agent in an access policy, a per-request policy subroutine, or
both.
In the
policies, you must use only the subset of agents that are allowed with the
OAuth-Resource Server
access profile
type.- Open the access policy in the visual policy editor:
- On the Main tab, click.The screen displays a list of access profiles.
- Locate the correct access profile.Look in theProfile Typefield forOAuth-Resource Server.
- In thePer-Session Policyfield, click theEditlink.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.
- To review the subset of agents that are allowed for use with theOAuth-Resource Serveraccess profile type, click each tab.
- To configure the OAuth Scope agent to validate JSON web tokens internally, on the BIG-IP system, perform these substeps:You can configure an OAuth Scope agent to validate JWTs internally or to perform validation externally. With external validation, you can validate opaque tokens and get UserInfo. To perform internal validation and external validation requires configuration of more than one OAuth Scope agent.To configure external validation instead, skip these substeps.
- FromToken Validation Scope, selectInternal.
- FromJWT Provider Listtab, select a list of providers.
- ClickSave.The properties screen closes. The policy displays.
- To configure an OAuth Scope agent to validate opaque tokens or to get UserInfo or both, perform these substeps:
- FromToken Validation Scope, selectExternal.
- On theAuthenticationtab, selectOAuth Scope.
- From theServerlist, select an OAuth server that you know to be configured withModeset toResource Server.Do not select an OAuth server configured withModeset toClient + Resource Server.
- From theScopes Requestlist, select a request.Only validate-scopes-request type requests display.If F5 (APM) is the OAuth provider, selectF5ScopesRequest.
- To add scope data requests, clickAdd new entryand, in theScope Namefield, type the name of a scope that the OAuth provider supports; then, from theRequestlist, select a scope data request that was configured to meet the requirements of the OAuth provider.
- ClickSave.The properties screen closes. The policy displays.
- To save and apply any changes that you made to the access policy, clickApply Access Policy.
- To add an OAuth Scope agent to a per-request policy subroutine:
- On the Main tab, click.
- To open a per-request policy for editing, click theEditlink in thePer-Request Policyfield.If you must create a per-request policy first, provide a name for it that is unique among all access profiles and per-request policies.
- ClickAdd New Subroutine.A popup screen opens. TheSubroutine from templatefield specifiesEmpty.
- ClickSave.The popup screen closes. The heading,[+] Subroutine:, displays below the main editor.Name
- Expand the subroutine for editing by clicking the[+]icon.
- In the subroutine area, click[+].AnAdd Itempopup screen opens.
- On the Authentication tab, selectOAuth Scopeand clickAdd Item.
- To configure theOAuth Scopeagent properties, follow the instructions provided in this task previously.
- To add the subroutine to the per-request policy, in the main editor click the[+]icon.
- Click the Subroutines tab, select the subroutine, and clickAdd Item.The subroutine displays in the per-request policy.
To put the access policy into
effect, you must specify the access profile in the virtual server. If you configured a
per-request policy subroutine, you must also specify the per-request policy in that
virtual server.
Creating a virtual server to manage HTTPS traffic
You can create a virtual server to manage HTTPS traffic.
- On the Main tab, click.The Virtual Server List screen opens.
- ClickCreate.The New Virtual Server screen opens.
- In theNamefield, type a unique name for the virtual server.
- In theService Portfield, type443or selectHTTPSfrom the list.
- From theHTTP Profilelist, selecthttp.
- For theSSL Profile (Client)setting, from theAvailablelist, selectclientssl, and using the Move button, move the name to theSelectedlist.
- ClickFinished.
The HTTPS virtual server appears in the Virtual Server List screen.
Adding access
profile and per-request policy to the virtual server
You associate an access profile with a virtual server for use in
establishing an access session. If you have configured a per-request policy, which
is for use throughout the access session, you associate it with the virtual server
also.
- On the Main tab, click.The Virtual Server List screen opens.
- Click the name of the virtual server that manages access for the web application you are securing.
- In the Access Policy area, from theAccess Profilelist, select the access profile that you configured earlier.
- In the Access Policy area, from thePer-Request Policylist, select the policy that you configured earlier.
- ClickUpdate.
The access profile (and access policy) and the per-request policy are now associated
with the virtual server.
Overview: Using an OAuth token for single
sign-on
After Access Policy Manager (APM®) gets or validates
an OAuth token, the token can be used for single sign-on (SSO). Simply create an OAuth bearer SSO
configuration and select it from any configuration object where APM lets you do that; for
example, in an access profile.
APM gets or validates tokens when OAuth Client or OAuth Scope agents run in a policy.
Task summary
Creating an OAuth
bearer SSO configuration
You create an OAuth bearer SSO configuration when
you want to allow single-sign on using an OAuth token that Access Policy Manager (APM)
has gotten or validated from an external OAuth authorization server.
- On the Main tab, select.The OAuth Bearer Configurations screen opens.
- ClickCreate.The New SSO Configuration screen opens.
- In theNamefield, type a name for the SSO configuration.The maximum length of a single sign-on configuration is 225 characters, including the partition name.
- In the SSO Method Configuration area, select a server from theOAuth Serverlist.
- ClickFinished.
When you configure an APM object that supports
single sign-on, it includes an
SSO
Configuration
property. Select the SSO bearer configuration from the
object where you want to put SSO into effect.Adding OAuth bearer
SSO to an access profile
You add an OAuth bearer SSO to an access profile
if you want to allow SSO using an OAuth token from the access profile.
You
can also select an SSO configuration from objects such as an Exchange profile, a
SAML resource, or a portal access resource.
- On the Main tab, click.The Access Profiles (Per-Session Policies) screen opens.
- Click the name of the access profile that you want to edit.The properties screen opens.
- ClickSSO / Auth Domainson the menu bar.The SSO Across Authentication Domains screen opens.
- From theSSO Configurationslist, select an OAuth bearer SSO configuration.Other settings on the screen are not relevant when using an OAuth bearer SSO configuration.
- ClickUpdate.
An access profile goes into effect when it is
specified in a virtual server.
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 client and resource 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 Access Policy Manager
(APM), acting as an OAuth client or resource server or both,
processes over a period of time.
- On the Main tab, click.The x-axis for the chart specifies time. The y-axis specifies the rate: requests per second.The screen displays the Overview line graph with data from the last hour. The legend specifies the request types represented by each colored line;Errorrepresents errors that occurred for any of the requests.
- To display the rate of requests for the interval represented by a point in the 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 the chart for another period of time, 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) |
OAuth client and resource server
troubleshooting tips
You might run into problems with an OAuth client or resource server on the BIG-IP system in some instances. Follow these tips to try to resolve any
issues you might encounter.
Log message |
Possible explanations and corrective actions |
---|---|
OAuth Client: SSL profile from apmd is missing |
The server SSL profile is missing for the OAuth client or resource server that is
specified in the OAuth server configuration. Verify the OAuth server configuration on
the BIG-IP system. |
Invalid URI log |
One or more URIs are not configured properly for the OAuth provider. Verify the
OAuth provider configuration on the BIG-IP system. |
Failed to initialize OAuth agent |
This is an internal APMD error; this error should not occur. |
OAuth request is not configured for agent |
A particular request object is not configured properly. Verify request object
configuration on the BIG-IP system. |
OAuth Client: state parameters do not match |
This is an internal APMD error; this error should not occur. |
OAuth Authorization redirect is empty |
The authorization redirect request URI is invalid. Verify the OAuth Client agent
configuration in the policy and verify the configuration for the authorization
redirect request that it specifies. |
Authorization code not found |
Authorization code sent by the authorization server is not found. There could be
a problem on the OAuth client or on the external authorization server. Examine the
error logs on the external authorization server. |
OAuth Client: Unsupported grant type |
An improper grant type was used from the OAuth Client; this error should not
occur. |
OAuth Client: Unsupported parameter type |
A parameter for an OAuth request was invalid; this error should not occur. |
OAuth Response is empty from server |
The OAuth client (or resource server) received an empty response from the
authorization server. Examine the error logs on the external authorization
server. |
OAuth Scope: Failed to get scope details for scope |
The OAuth resource server failed to get scope details. Examine the error logs on
the external authorization server. |
Unsupported agent type |
This is an internal APMD error; this error should not occur. |
OAuth Error Code received |
The OAuth client received an error code. Use the error code and message to help
with troubleshooting. |
Access Token validation failed for server |
This warning means that the OAuth client agent failed to validate the token. When
this happens, the OAuth client tries to refresh or get a new token |
OAuth Client: Failed to refresh token for server |
This warning means that the OAuth client failed to refresh an access token. When
this happens, the OAuth client tries to fetch a new token. |
HTTP error 503, connect failed |
This error indicates that the OAuth client or resource server failed to connect
to the authorization server. Typically, this is caused by one or more configuration
issues. Verify that these aspects of your configuration are correct:
|
Invalid JWS token |
Configure JSON web keys (JWKs) to verify this JSON Web Token (JWT) signature; or,
request a new valid JWT |
Invalid b64url encoded header |
The authorization server must include a base64 URL-encoded JSON Object Signing
and Encryption (JOSE) header in the JWT. |
Invalid JSON |
Request a new valid JWT. |
Unsecured JWT should have alg none |
In an unsecured JWT, the authorization server must send a JOSE header with alg:
none. |
Empty header: Algorithm(alg) field mandatory |
The authorization server must send a JOSE header with the "alg" claim and
value. |
Empty payload: Issuer(iss) field mandatory |
The authorization server must send a JOSE payload with the "iss" claim and
value. |
crit must be an array of string |
If the authorization server sends the "crit" header parameter, it must be a
string array. |
crit must be a non-empty array of string |
If "crit" header parameter is specified in the JWT that the authorization server
sends, it must be a non-empty string array. |
Invalid JOSE header parameter |
The JOSE header parameter sent in the JWT was invalid. Request a new valid
JWT. |
Unsupported algorithm |
Request a JWT signed by an algorithm supported by F5 Client. |
Missing mandatory alg header parameter |
The authorization server must send a JOSE header with the "alg" claim and
value. |
No provider supporting alg none is found with issuer |
Configure the provider that matches this issuer with allowed
algorithms=none. |
Issuer Mismatch |
Configure the right issuer for this provider; or, request a JWT from the right
provider. |
Audience not found |
The JWT was not meant for this client; or, configure the right audience for the
client. |
JWT not active before nbf |
Invalid JWT received; request a new JWT. |
JWT expired |
Request another JWT, because the received JWT has expired. |
Audience is not string |
Configuration on the authorization server that sends JWT must send the audience
claim with a string value. |
Token blacklisted |
The received JWT has been blacklisted; request a new valid JWT. |
Signature verification failed |
Signature verification of the JWT did not succeed. |
Internal error during Signature verification |
Check JWK key configuration to match JWT signature |
Initialization failed |
Make sure the JWK key configuration matches the JWT algorithms |
JWT symmetric signature match failed |
Configure the correct symmetric key to verify this JWT signature. |
No JWK keys found to verify signature |
Configure the correct key to verify the received JWT signature. |