Manual Chapter : Advanced Customization with the OAuth Logon Page Template

Applies To:

Show Versions Show Versions

BIG-IP APM

  • 15.0.1, 15.0.0
Manual Chapter

Advanced Customization with the OAuth Logon Page Template

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.
OAuth Logon Page (advanced customization template)
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.

Importing the OAuth Logon Page template

Import the OAuth Logon Page advanced customization template into an OAuth Logon Page agent in the visual policy editor as the first step in customizing the page with the providers you want, in the order you want, using the text, images, and colors that you want.
  1. Get the OAuth Logon Page Advanced Customization Template from DevCentral at
    https://devcentral.f5.com.
    .
    The
    cust-logon-oauth-advanced.apmom.tar.gz
    file contains the template.
  2. On the BIG-IP system, open the per-session policy or the per-request policy that you want to update:
    1. To open a per-session policy, on the Main tab select
      Access
      Profiles / Policies
      Access Profiles (Per-Session Policies)
      .
    2. To open a per-request policy, on the Main tab select
      Access
      Profiles / Policies
      Per-Request Policies
      .
    The visual policy editor displays.
  3. Start adding an item by doing the following:
    1. For a per-session policy, click (
      +
      ) on a policy branch
    2. For a per-request policy, expand a subroutine and click (
      +
      ) in the subroutine or subroutine macro.
    An Add Item popup screen displays.
  4. On the Authentication tab, select
    OAuth Logon Page
    and click
    Add Item
    .
    A Properties screen displays.
  5. In the Customization area, click the
    Import
    button.
    The
    Choose File
    and
    Import
    buttons display.
  6. Click
    Choose File
    , then locate and choose the
    cust-logon-oauth-advanced.apmom.tar.gz
    file, and click
    Open
    .
  7. Click
    Import
    .
  8. Click
    Save
    .
    The OAuth Logon Page properties screen closes.
  9. If you are configuring a per-session policy, click the
    Apply Access Policy
    link.

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.
  1. Open the per-session policy (or the per-request policy subroutine) that you want to update.
  2. Click the
    OAuth Logon Page
    item.
    A Properties screen opens.
  3. In row 1 of the Logon Page Agent table, click the
    Values
    field.
    Row 1 contains values for the
    oauthprovidertype
    variable.
    A popup screen displays options with a
    Value
    and a
    Text
    field for each provider.
  4. Add, delete, or reorder the providers, and click
    Finished
    .
    The popup screen closes. The updated list of providers displays in the
    Values
    field in row 1.
  5. If you added a provider, add a branch rule for that provider:
    1. Click the Branch Rules tab.
    2. Click
      Add Branch Rule
      .
      A new entry with
      Name
      and
      Expression
      settings displays.
    3. In the
      Name
      field, replace the default name by typing a new name.
      The name appears on the branch in the policy.
    4. Select and copy an expression from another branch rule.
      For example, copy the expression displayed for the
      F5
      branch rule:
      expr
      {[
      mcget
      {
      session.logon.last.oauthprovidertype
      }] == "
      F5
      "}
    5. For the branch rule that you added, in the
      Expression
      setting click the
      change
      link.
      A popup screen opens.
    6. Click the Advanced tab, paste the expression into the field, and replace the existing provider name (such as
      F5
      ) with the new provider name.
      For example, the result might look like this:
      expr
      {[
      mcget
      {
      session.logon.last.oauthprovidertype
      }] == "
      Siterequest
      "}
    7. Click
      Finished
      .
      The popup screen closes.
    8. Click
      Save
      .
      The properties screen closes and the policy displays.
  6. Click
    Finished
    .
    The popup screen closes.
  7. If you are working with a per-session policy, click the
    Apply Access Policy
    link.

Adding images and customizing buttons for the OAuth Logon Page

You might want to add an image for a custom OAuth provider or use an image other than the ones that are available in the advanced customization template. You might also want to customize the colors you use for an OAuth provider.
  1. On the Main tab, select
    Access
    Profiles / Policies
    Customization
    General
    .
    The Customization screen displays with the Branding tab selected.
  2. Navigate to the
    OAuth Logon Page
    folder for your per-session policy (located in the
    Access Profiles
    folder) or your per-request policy (located in the
    Per-Request Policies
    folder).
  3. Expand the
    OAuth Logon Page
    folder and, in it, click
    Advanced Customization
    .
    An Advanced Customization Images screen displays.
  4. To upload a new image:
    For best results make sure that the image is 25 x 25 px.
    1. Click
      Image Browser
      .
      An Image Browser popup screen opens.
    2. Click
      Add Image
      , find and select the image, and click
      Open
      .
      The image loads and a thumbnail opens.
    3. Close the Image Browser popup screen.
  5. Back on the Advanced Customization Images screen, in any
    Value
    field that contains
    /public/images/my/tr.gif
    (a default value), click the field, then click the icon that displays at the end of the field, then click
    Replace
    .
    A Choose an Image popup screen opens.
  6. Select the image that you uploaded previously, then click
    Change
    .
    The popup screen closes. A path and the name of the image file that you chose displays in the
    Value
    field.
  7. On your keyboard, press Enter to finalize the change; then, on your screen on the menu bar, click
    Save
    .
    In the
    Value
    field, the path and the image file name completely change. The file name changes to something like
    image
    xx
    _
    nn
    .png
    where
    xx
    is a number and
    nn
    represents a language code.
  8. Click the new value, copy it, and paste it to a text file to save it temporarily.
    You will need to paste this exact value into the code for the OAuth Logon Page in a later step.
  9. From the
    View
    list at the top right of the screen, select
    Advanced Customization
    .
    The Customization tool switches to the advanced view.
  10. In the
    OAuth Logon Page
    folder, click
    logon.inc
    .
    The code displays in the Advanced Customization Editor.
  11. Search for the phrase
    authLoginSelectCusts
    .
    The phrase displays within these lines of code:
    /* BEGIN OF ADDED CODE */ $settings = ["patchFieldId" => "oauthprovidertype", "patchFieldValue" => "ROPC"]; $authLoginSelectCusts = [ "__default__" => ["/public/images/my/tr.gif", "#e59c91", "#D92138", "#FFFFFF"], // please use low case in keys because of $authLoginSelectCusts[strtolower($o)] later in code "f5" => ["/public/images/my/flogo_mobile.png", "#ea7281", "#D92138", "#FFFFFF"], "google" => ["/public/images/customization/Common/vs-show-profile-2_act_oauth_logon_page_ag/image00_en.png", "#96C3E0", "#557CBF", "#FFFFFF"], "facebook" => ["/public/images/customization/Common/vs-show-profile-2_act_oauth_logon_page_ag/image01_en.png", "#7b94ca", "#4768b2", "#FFFFFF"], "ping" => ["/public/images/customization/Common/vs-show-profile-2_act_oauth_logon_page_ag/image02_en.png", "#EE6E81", "#EA4A62", "#FFFFFF"] ];
    The code specifies an OAuth provider name in lowercase, an image name and path, and hexadecimal color codes for the foreground, background, and text.
  12. Duplicate one of the lines of code for a provider.
    For example, your result might look like this:
    "f5" => ["/public/images/my/flogo_mobile.png", "#ea7281", "#D92138", "#FFFFFF"], "f5" => ["/public/images/my/flogo_mobile.png", "#ea7281", "#D92138", "#FFFFFF"],
  13. Update the duplicated line of code:
    1. Replace the provider name with a provider name that you specified in the properties for the OAuth Logon Page (as configured in the visual policy editor).
      Type the provider name in lowercase, regardless of the case you used in the visual policy editor when you configured the OAuth Logon Page properties.
    2. Replace the image name and path with the exact image name and path that you copied from the Advanced Customization Images screen.
    3. Replace the hexadecimal color codes with the ones you want to use.
    Your result, for example, might look like this:
    "f5" => ["/public/images/my/flogo_mobile.png", "#ea7281", "#D92138", "#FFFFFF"], "siterequest" => ["/public/images/customization/Common/vs-profile-2_act_oauth_logon_page_ag/image03_en.png", "#FFFFFF", "#000000", "#FF0000"],
  14. On the menu bar, click
    Save
    .
  15. If you want to remove the Logon button from the OAuth Logon Page screen, you can do that while you are still in the Advanced Customization view:
    1. In the
      OAuth Logon Page
      folder, click
      logon.inc
      .
    2. Search for and remove these lines of code:
      <tr id="submit_row"> <? if( $GLOBALS["label_position"] == "above" ){ ?> <td class="credentials_table_unified_cell"><input type=submit class="credentials_input_submit" value="%[logon]"></td> <? }else{ ?> <td class="credentials_table_label_cell" ></td> <td class="credentials_table_field_cell"><input type=submit class="credentials_input_submit" value="%[logon]"></td> <? } ?> </tr>
    3. On the menu bar, click
      Save
      .
  16. If you've been working on a per-session policy, click the
    Apply Access Policy
    link.