Applies To:

Show Versions Show Versions

Manual Chapter: Using APM as an OAuth 2.0 Authorization Server
Manual Chapter
Table of Contents   |   << Previous Chapter   |   Next Chapter >>

Using APM as an OAuth 2.0 Authorization Server

Overview: Configuring APM as an OAuth 2.0 authorization server

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

Task summary

Registering a client application for OAuth services

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

Registering a resource server for OAuth services

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

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.)
  1. On the Main tab, click Access > Federation > OAuth Authorization Server > Scope .
    The Scope screen opens.
  2. Click Create.
  3. In the Name field, type a name for the object.
  4. In the Scope Name field, type a name for the scope.
  5. In the Scope Value field, type a value for the scope.
  6. In the Customization Settings for English area, in the Caption field, type a caption.
  7. In the Detailed Description field, type a description of the access that the client application needs.
    If you choose to display an Authorization screen, APM displays the contents of this field on it; or, if this field is blank, APM displays the contents of the Caption field.
    Here are some examples: Access your profile or Update your tasks, projects, and workspace.
  8. Click Finished.

Configuring JWT claims

You can configure the claims that you want to include in the JSON web tokens (JWTs). (A claim specifies a string, and optionally, a value, that represents a resource.) This is only required if you plan to specify claims in your JWTs.
  1. On the Main tab, select Access > Federation > OAuth Authorization Server > Claim .
  2. Click Create.
  3. In Name, type a name for the configuration.
  4. From Claim Type, select the type of claim: String, Number, Boolean, or Custom.
  5. In Claim Name, type a name for the claim.
  6. In Claim Value, type a value for the claim depending on its type.
    Claim Type Value can be
    String ASCII characters or session variable
    Number Valid number or session variable
    Boolean true, false, or session variable
    Custom Any other format not covered by the other options or session variable
  7. Click Save.
    The newly created claim displays on the list.
You associate claims with tokens an OAuth bearer SSO configuration.

Configuring JSON web keys (JWKs)

A JSON web key configuration specifies a cryptographic JSON web key (JWK). You configure JWKs for the system to use to sign the JSON web tokens that it issues. For example, you use JWK key configurations when setting up OAuth bearer single sign-on.
  1. On the Main tab, select Access > Federation > JSON Web Token > Key Configuration .
    The Key Configuration screen opens.
  2. Click Create.
  3. In the Name field, type a name.
  4. In ID, type the ID.
  5. For Type, select RSA, Octet, or Elliptic Curve.
    Additional parameters display for the type that you select.
  6. For Signing Algorithm, select any one.
  7. For the Octet type, you only need to configure one additional setting:
    1. In Shared Secret, type the secret.
      Important: To maximize the security of the algorithm, use enough characters so that the resulting key size matches the block size for the signing algorithm: for HS256, 32 characters; for HS384, 48 characters; for HS512, 64 characters.
    2. Click Save.
      The newly created JWK displays on the list.
  8. For the RSA or Elliptic Curve key types, configure the settings in the Certificates areas:
    1. For Certificate File, select a certificate.
      Important: 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.
    2. For Certificate Key, select one.
      Important: Do not use 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.
    3. For Key Passphrase, type a passphrase.
    4. For Certificate Chain, select one.
      If this field is filled in, values for the parameters are auto-generated.
  9. Click Save.
    The newly created JWK configuration displays in 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.
Note: APM provides one default database instance, oauthdb. Additional instances enable you to group tokens.
  1. On the Main tab, click Access > Federation > OAuth Authorization Server > Database Instance .
    The Database Instance screen opens.
  2. Click Create.
  3. In the Name field, type a name for the object.
  4. In the Purge Schedule Settings area, select a frequency from the Frequency list and specify a time in the Schedule At field.
    Schedule the database purge for a time when the BIG-IP system is least used to prevent any possible performance issues.
    Purging removes expired access tokens, refresh tokens, authorization codes, and associated entries from the instance. For the purpose of purging, an access token is considered expired when it passes the date when it expires; (expiry is based on the Access Token Lifetime setting).
    Note: Expired access tokens are not removed when the Reuse Access Token setting is enabled (in the corresponding OAuth profile) and a refresh token has been issued and the refresh token is not expired.
    Revoked access tokens are purged after they expire.
  5. To save this database instance, click Finished.
Database instances are available for selection in an OAuth profile.

Creating an OAuth profile

You configure an OAuth profile to specify the client applications, resource servers, token types, and authorization server endpoints that apply to the traffic that goes through a particular virtual server.
  1. On the Main tab, click Access > Federation > OAuth Authorization Server > OAuth Profile .
    The OAuth Profile screen opens.
  2. Click Create.
  3. In the Name field, type a name for the object.
  4. For Client Application, select from the available clients and move them to the Selected list.
  5. For Resource Server, select from the available servers and move them to the Selected list.
  6. Click Finished.
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.
  1. On the Main tab, click Access > Federation > OAuth Authorization Server > OAuth Profile .
    The OAuth Profile screen opens.
  2. Click the name of the OAuth profile you want to edit.
  3. In the Token Management Configuration area, select the Custom check box.
    Settings become available.
  4. To update support for opaque tokens, locate the Support Opaque Token check 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.
  5. To update support for JSON web tokens, locate the Support JWT Token check 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.
  6. Click Update.
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.
  1. On the Main tab, click Access > Federation > OAuth Authorization Server > OAuth Profile .
    The OAuth Profile screen opens.
  2. Click the name of the OAuth profile you want to edit.
  3. In the Token Management Configuration area, select the Custom check box.
    Settings become available.
  4. From the Database Instance list, you can retain the default, oauthdb, or select another database instance.
  5. To update endpoints:
    1. In the Authorization Server Endpoints area, select the Custom check box.
      Settings become available.
    2. Change values in any of these fields: Authorization Endpoint, Token Issuance Endpoint, Token Revocation Endpoint, and Token Introspection Endpoint.
  6. Click Update.

Configuring support for JWTs in an OAuth profile

Before you start, configure an OAuth profile, configure JSON web keys (JWK), and configure claims.
Note: You can configure JWKs in the Access > Federation > JSON Web Token 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.
  1. On the Main tab, click Access > Federation > OAuth Authorization Server > OAuth Profile .
    The OAuth Profile screen opens.
  2. Click the name of the OAuth profile you want to edit.
  3. In the Token Management Configuration area, select the Custom check box.
    Settings become available.
  4. If the Support JWT Tokens check box is cleared, select it.
    Additional settings display.
  5. In Issuer, type the URL for the issuer.
    For example, type https://big-ip-server.com where big-ip-server is the name of your server.
  6. In Subject, retain the default value, %{session.assigned.uuid}, or type a subject for the JWT.
    The session variable session.assigned.uuid contains the UUID that APM assigns to the session after the access policy completes.
  7. For Primary Key, select a JWK from the list.
    Important: 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.
  8. To specify Rotation Keys, select one or more JWKs and move them to the Selected list.
  9. To specify audience claims, in the Audience field, type a string and click Add. Repeat this step as needed.
  10. To specify claims, for Claims move claims to the Selected list.
  11. In JWT Refresh Token Encryption Secret, type a string.
    Important: If the JWT Generate Refresh Token setting is enabled, after you set this secret do not change it. Changing the secret automatically invalidates all the issued refresh tokens.
    Note: 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.
  12. To update endpoints, in the Authorization Server Endpoints area select the Custom check box.
    Settings become available.
  13. To update the OpenID Connect discovery endpoint, in OpenID Connect Configuration Endpoint type the URI where clients can find the OpenID Connect provider configuration document.
  14. To update the JSON Web Key Set endpoint, in JWKS Endpoint, type the URI where clients can locate the public signing keys for the APM OAuth authorization server.
  15. Click Update.
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.
  1. On the Main tab, click Access > Profiles / Policies .
    The Access Profiles (Per-Session Policies) screen opens.
  2. Click Create.
    The New Profile screen opens.
  3. In the Name field, type a name for the access profile.
    Note: A access profile name must be unique among all access profile and any per-request policy names.
  4. From the Profile Type list, select All or LTM-APM.
  5. Scroll down to the Configurations area.
  6. From the OAuth Profile list, select the OAuth profile you configured earlier.
  7. In the Language Settings area, add and remove accepted languages, and set the default language.
    A browser uses the highest priority accepted language. If no browser language matches the accepted languages list, the browser uses the default language.
    Important: If you want to translate text into other languages (as you can in Access Policy Customization), make sure to select the languages that you want to display here.
  8. Click Finished.
The access profile displays in the Access Profiles List. Default-log-setting is assigned to the access profile.
When you create a virtual server to process traffic from OAuth version 2.0 clients and resource servers, assign this access profile to it.

Sample policy: Logon, authenticate, and authorize

Access policy for APM as an OAuth authorization server

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

About 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 when Prompt for Authorization is set to Enabled:
  • Authorize Message Specifies the initial wording for the prompt.
  • Scope Message Specifies the wording that precedes the list of scopes that are specified in the Scope / Claim Assign area of this screen.
  • Allow Message Provides the label for the button that allows access.
  • Deny Message Provides the label for the button that denies access.

Configuring an access policy for F5 as an OAuth authorization server

You configure an access policy so that, as OAuth authorization server, Access Policy Manager (APM) can identify and authorize client applications to access resources.
Note: The policy items in these steps are necessary to process traffic sent to F5 (APM) as an authorization server. You can add these items to a branch of an existing policy or add them to a new policy.
  1. On the Main tab, click Access > Profiles / Policies .
    The Access Profiles (Per-Session Policies) screen opens.
  2. In the Per-Session Policy column, click the Edit link for the access profile you want to configure.
    The visual policy editor opens the access policy in a separate screen.
  3. Click the (+) icon anywhere in the access policy to add a new item.
    Note: Only an applicable subset of access policy items is available for selection in the visual policy editor for any access profile type.
    A popup screen opens, listing predefined actions on tabs such as General Purpose, Authentication, and so on.
  4. On the Logon tab, select Logon Page and click the Add Item button.
    The Logon Page Agent properties screen opens.
  5. Click Save.
    The properties screen closes and the policy displays.
  6. On a policy branch, click the (+) icon to add an item to the policy.
  7. On the Authentication tab, select OAuth Authorization and click Add Item.
    Important: You must include an OAuth Authorization item in the policy for it to work.
    A Properties popup screen opens.
  8. If you do not want to prompt for authorization, in the OAuth Authorization area, from the Prompt for Authorization list, select Disabled.
  9. In the Subject field, type the subject.
    This is the subject of a JSON web token (JWT).
  10. In the Audience area, for each audience that you want to support for JWT:
    1. Click Add new entry.
      A numbered entry displays.
    2. Type an audience name in the new field.
  11. 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.
    1. Click Add new entry.
      A numbered entry displays with Expression and Claim and Scope properties.
    2. To specify a prerequisite for the scopes and claims, click change and configure an expression.
      A prerequisite is not mandatory.
      For example, use an expression to verify that the user has passed an LDAP query for membership in a group. Or verify that the user has passed Active Directory authentication.
    3. To add claims and scopes, click Add/Delete; (this opens a popup screen with Scope and Claim tabs); on one or both tabs, select entries and click Update (this closes the popup screen).
  12. Click Save.
    The properties screen closes and the policy displays.
  13. Add any additional access policy items you require to complete the access policy.
    Note: On the branch of the access policy with OAuth Authorization, do not also assign connectivity resources (as you can with various resource assign access policy items). Doing so causes a validation error on the Allow ending.
  14. Change the ending from Deny to Allow on any access policy branch on which you want to grant access.
  15. Click the Apply Access Policy link 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.
  1. On the Main tab, click Local Traffic > Profiles > SSL > Client .
    The Client SSL profile list screen opens.
  2. Click Create.
    The New Server SSL Profile screen opens.
  3. In the Name field, type a unique name for the profile.
  4. From the Parent Profile list, select clientssl.
    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.
  5. From the Configuration list, select Advanced.
  6. If you have VMware View clients on Mac OS X, disable TLS 1.2 in the Options List area:
    1. In the Available Options list, select No TLS 1.2.
    2. Click Enable.
  7. If you change the values for the Cache Size or the Cache Timeout setting, 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.
  8. Scroll down to Handshake Timeout and select the Custom check box.
    Additional settings become available.
  9. To limit the timeout to a number of seconds, select Specify from the list, and type the required number in the seconds field.
    In the list, the value Indefinite specifies that the system continue trying to establish a connection for an unlimited time. If you select Indefinite, the seconds field is no longer available.
  10. Scroll down to the Client Authentication area.
  11. Next to Client Authentication, select the Custom check box.
    The settings become available.
  12. From the Client Certificate list, select request.
    Do not select require.
  13. From the Trusted Certificate Authorities and Advertised Certificate Authorities, select the certificates you imported previously.
  14. Click Finished.

Creating a virtual server for OAuth authorization server traffic

You create a virtual server to process traffic for Access Policy Manager (APM) configured as an OAuth authorization server.
  1. On the Main tab, click Local Traffic > Virtual Servers .
    The Virtual Server List screen opens.
  2. Click Create.
    The New Virtual Server screen opens.
  3. For the Destination Address/Mask setting, confirm that the Host button is selected, and type the IP address in CIDR format.
    The supported format is address/prefix, where the prefix length is in bits. For example, an IPv4 address/prefix is 10.0.0.1 or 10.0.0.0/24, and an IPv6 address/prefix is ffe1::0020/64 or 2001:ed8:77b5:2:10:10:100:42/64. When you use an IPv4 address without specifying a prefix, the BIG-IP system automatically uses a /32 prefix.
    Note: The IP address you type must be available and not in the loopback network.
  4. In the Service Port field, type 443 or select HTTPS from the list.
  5. From the HTTP Profile list, select http.
  6. For the SSL Profile (Client) setting, move the client SSL profile you created earlier to the Selected list.
  7. Scroll down to the Access Profile area.
  8. From the Access Profile list, select the access profile you created earlier.
  9. Click Finished.
The HTTPS virtual server appears in the Virtual Server List screen.
Table of Contents   |   << Previous Chapter   |   Next Chapter >>

Was this resource helpful in solving your issue?




NOTE: Please do not provide personal information.

Additional Comments (optional)