Manual Chapter : Using APM as a SAML IdP SSO portal

Applies To:

Show Versions Show Versions

BIG-IP APM

  • 13.0.1, 13.0.0
Manual Chapter

Overview: Configuring BIG-IP as IdP for IdP- and SP-initiated connections

This configuration supports:

  • An SSO portal on the BIG-IP® system configured as a SAML Identity Provider (IdP).
  • Service providers (SPs) with the same or different requirements for assertion type and value and attributes (provided by the IdP).
  • SP- and IdP-initiated connections.

About local IdP service

A SAML IdP service is a type of single sign-on (SSO) authentication service in Access Policy Manager® (APM®). When you use a BIG-IP® system as a SAML identity provider (IdP), a SAML IdP service provides SSO authentication for external SAML service providers (SPs). You must bind a SAML IdP service to SAML SP connectors, each of which specifies an external SP. APM responds to authentication requests from the service providers and produces assertions for them.

About SP connectors

A SAML service provider connector (an SP connector) specifies how a BIG-IP® system, configured as a SAML Identity Provider (IdP), connects with an external service provider.

What are the available ways I can configure a SAML SP connector?

You can use one or more of these methods to configure SAML service provider (SP) connectors in Access Policy Manager®.

  • From metadata - Obtain a metadata file from the vendor and import it into Access Policy Manager. The advantage to this method is that the vendor provides the majority of all required data, including certificates. You can complete the configuration by simply typing a unique name for the SP connector, a very few additional required fields, and browsing to and importing the file. Access Policy Manager then configures the SP connector.
  • From template - Use templates that Access Policy Manager provides for some vendors; for example, Google. The advantages to this method are that:
    • Most required data is included in the template
    • Additional required data is minimal. You can obtain it and certificates from the vendor
    After you select a template and type data into a few fields, Access Policy Manager configures the SP connector.
  • Custom - Obtain information from the vendor and type the settings into the Configuration utility. To use this method, you must also obtain certificates from the vendor and import them into the BIG-IP® system. Use this method when a metadata file or a template for an SP connector is not available.

Task summary

Setting up a BIG-IP® system as a SAML identity provider (IdP) system involves two major activities:

  • First, you set up connection from the BIG-IP system to the external SAML service providers (SPs)
  • Then, you set up connection from the external SAML SPs to the BIG-IP system

Task list

Flowchart: Configuration to support a SAML SSO portal

This flowchart illustrates the process for configuring a BIG-IP® system as a SAML identity provider (IdP) that provides an SSO portal.

configuration flowchart

Creating a virtual server for a BIG-IP (as SAML IdP) system

Before you start this task, configure a client SSL profile and a server SSL profile if you are going to create an SSL virtual server.
Note: Access Policy Manager® supports using a non-SSL virtual server for the BIG-IP® system configured as a SAML Identity Provider (IdP). However, we recommend using an SSL virtual server for security reasons. The following procedures include steps that are required for configuring an SSL virtual server, such as selecting client and server SSL profiles, and setting the service port to HTTPS.
Specify a host virtual server to use as the SAML IdP.
  1. On the Main tab, click Local Traffic > Virtual Servers .
    The Virtual Server List screen opens.
  2. Click the Create button.
    The New Virtual Server screen opens.
  3. In the Name field, type a unique name for the virtual server.
  4. In the Destination Address field, type the IP address for a host virtual server.
    This field accepts an address in CIDR format (IP address/prefix). However, when you type the complete IP address for a host, you do not need to type a prefix after the address.
  5. In the Service Port field, type 443 or select HTTPS from the list.
  6. For the HTTP Profile setting, verify that the default HTTP profile, http, is selected.
  7. For the SSL Profile (Client) setting, from the Available list, select the name of the Client SSL profile you previously created and move the name to the Selected list.
  8. For the SSL Profile (Server) setting, from the Available list, select the name of the Server SSL profile you previously created and move the name to the Selected list.
  9. Click Finished.
The virtual server for the BIG-IP system configured as an IdP now appears on the Virtual Server List. The virtual server destination is available for use in one or more SAML IdP service configurations.

Configuring an artifact resolution service

Before you configure the artifact resolution service (ARS), you need to have configured a virtual server. That virtual server can be the same as the one used for the SAML Identity Provider (IdP), or you can create an additional virtual server.
Note: F5® highly recommends that the virtual server definition include a server SSL profile.
You configure an ARS so that a BIG-IP® system that is configured as a SAML IdP can provide SAML artifacts in place of assertions. With ARS, the BIG-IP system can receive Artifact Resolve Requests (ARRQ) from service providers, and provide Artifact Resolve Responses (ARRP) for them.
  1. On the Main tab, click Access > Federation > SAML Identity Provider > Artifact Resolution Services .
  2. Click Create.
    The Create New SAML Artifact Resolution Service popup screen opens, showing general settings.
  3. In the Name field, type a name for the artifact resolution service.
  4. In the Description field, type a new description.
  5. Click Service Settings.
  6. From the Virtual Server list, select the virtual server that you created previously.
    ARS listens on the IP address and port configured on the virtual server.
  7. In the Artifact Validity (Seconds) field, type the number of seconds for which the artifact remains valid. The default is 60 seconds.
    The BIG-IP® system deletes the artifact if the number of seconds exceeds the artifact validity number.
  8. For the Send Method setting, select the binding to use to send the artifact, either POST or Redirect.
  9. In the Host field, type the host name defined for the virtual server, for example ars.siterequest.com.
  10. In the Port field, type the port number defined in the virtual server. The default is 443.
  11. Click Security Settings.
  12. To require that artifact resolution messages from an SP be signed, select the Sign Artifact Resolution Request check box.
  13. To use HTTP Basic authentication for artifact resolution request messages, in the User Name field, type a name for the artifact resolution service request and in the Password field, type a password.
    These credentials must be present in all Artifact Resolve Requests sent to this ARS.
  14. Click OK.
    The popup screen closes, leaving the Artifact Resolution Services list screen open.
The Artifact Resolution Service is ready for use.

Configuring SAML SP connectors

Before you can configure a SAML service provider, you must first obtain an SSL certificate from the SAML service provider (SP) and import it into the certificate store on the BIG-IP® system.
You configure information about a SAML service provider so that Access Policy Manager® (APM®) can act as a SAML Identity Provider (IdP) for it.
Note: Configure one SAML SP connector for each external SAML service provider for which this BIG-IP system provides SSO authentication service.
  1. On the Main tab, click Access > Federation > SAML Identity Provider > External SP Connectors .
    A list of SAML SP connectors displays.
  2. Click Create.
    The Create New SAML SP Connector screen opens.
  3. In the Service Provider Name field, type a unique name for the SAML SP connector.
  4. In the SP Entity ID field, type a unique identifier for the service provider.
    This is usually a unique URI that represents the service provider. You should obtain this value from the service provider.
  5. From the left pane, select Endpoint Settings.
    The appropriate settings are displayed.
  6. Optional: In the Relay State field, type a value.
    The relay state can be an absolute path, such as /hr/index.html; it can be a URL, such as https://www.abc.com/index.html; or, it can be anything that the service provider understands. The information passed in relay state could be used by the service provider according to business logic. For example, some service providers use relay state to maintain a session state, while others use it to perform an action, such as redirecting the user to the page passed in relay state. APM sends the relay state value back to the service provider as part of the assertion response in the RelayState parameter.

    When the RelayState parameter is already part of the authentication request to the BIG-IP system, APM returns the value that was sent in the request. Otherwise, APM uses the value from this configuration.

  7. In the Assertion Consumer Services area, specify at least one assertion consumer service.
    A service provider can use multiple bindings to receive an assertion from the Identity Provider. The service provider can specify a different assertion consumer service (ACS) URL for each binding, and provide a unique ACS URL index for the binding.

    To support SAML artifacts, make sure that at least one ACS specifies the artifact binding.

    1. Click Add.
      A new row displays in the table.
    2. In the Index field, type the index number, zero (0) or greater.
    3. If this is the default service, select the Default check box.
      You must specify one of the services as the default.
    4. In the Location URL field, type the URL where the IdP can send an assertion to this service provider.
      APM supports HTTP-Artifact binding, POAS (HTTP reverse SOAP) binding, and HTTP-POST binding to this service.
    5. From the Binding list, select Artifact, PAOS, or POST.
    6. Click Update.
  8. From the left pane, select Security Settings.
    1. If the SP should sign the authentication or the artifact resolution requests that it sends to the SAML IdP (this BIG-IP system), select the Require Signed Authentication Request check box, select a private key from the Message Signing Private Key list, and select a certificate from the Message Signing Certificate list.
      This device (BIG-IP system as IdP) uses the certificate to verify the signature of the request from the SP.
    2. To require that the SAML IdP sign the assertion before sending it to the SP, select the Assertion must be signed check box, and select an algorithm from the Signing Algorithm list.
      Assertion must be signed is selected by default. Clearing this check box is not recommended.
    3. To require that the SAML IdP sign the response before sending it to the SP, select the Response must be signed check box.
      Note: The algorithm specified in the Signing Algorithm list applies to a signed assertion and a signed response.
    4. To require that the SAML IdP encrypt the assertion before sending it to the SP, select the Assertion must be encrypted check box, select a type from the Encryption Type list, and select a certificate from the Encryption Certificate list.
      APM supports AES128, AES192, and AES256 encryption types.
  9. From the left pane, select SLO Service Settings.
    SLO stands for Single Logout.
    1. Optional: In the Single Logout Request URL field, type a URL specifying where APM should send a logout request to this service provider when the BIG-IP system initiates a logout request.
    2. In the Single Logout Response URL field, type a URL to which the SP should send a logout response for the BIG-IP system to indicate that single logout is complete.
    Note: APM supports HTTP-POST binding for the SLO service. For SLO to work, all entities (SPs and IdPs), must support SLO.
  10. Click OK.
    The popup screen closes.
APM creates a SAML SP connector. It is available to bind to a SAML IdP service.

Configuring a SAML IdP service for one SP connector

Configure a SAML Identity Provider (IdP) service for Access Policy Manager®, as a SAML IdP, to provide single sign-on authentication for one SAML service provider (SP).
Note: Configure one IdP service for each SAML service provider.
  1. On the Main tab, click Access > Federation > SAML Identity Provider .
    The Local IdP Services screen opens.
  2. Click Create.
    The Create New IdP Service popup screen displays.
  3. In the IdP Service Name field, type a unique name for the SAML IdP service.
  4. In the IdP Entity ID field, type a unique identifier for the IdP (this BIG-IP® system).
    Typically, the ID is a URI that points to the BIG-IP virtual server that is going to act as a SAML IdP. If the entity ID is not a valid URL, the Host field is required.
    For example, type https://siterequest.com/idp, where the path points to the virtual server you use for BIG-IP system as a SAML IdP.
  5. If the IdP Entity ID field does not contain a valid URI, you must provide one in the IdP Name Settings area:
    1. From the Scheme list select https or http.
    2. In the Host field, type a host name.
      For example, type siterequest.com in the Host field.
  6. If you select SAML Profiles on the left pane, the Web Browser SSO check box is selected by default.
    At least one profile must be selected.
  7. To specify that this IdP use an artifact resolution service, click Endpoint Settings on the left pane and select a service from the Artifact Resolution Service list.
  8. On the left pane, select Assertion Settings and complete the settings that display:
    1. From the Assertion Subject Type list, select the type of subject for the IdP to authenticate.
    2. From the Assertion Subject Value list, select the name of a session variable.
      This variable, %{session.logon.last.username}, is generally applicable. Some session variables are applicable depending on the type of authentication that you use for your site.
    3. In the Authentication Context Class Reference field, select a URI reference.
      The URI reference identifies an authentication context class that describes an authentication context declaration.
    4. In the Assertion Validity (in seconds) field, type the number of seconds for which the assertion is valid.
    5. To encrypt the subject, select the Enable encryption of Subject check box.
      The Encryption Strength list becomes available.
    6. From the Encryption Strength list, select a value.
      Supported values are AES128, AES192, and AES256.
  9. On the left pane, select SAML Attributes, and for each attribute that you want to include in the attribute statement, repeat these substeps.
    1. Click Add.
      A Create New SAML Attribute popup screen displays.
    2. In the Name field, type a unique name for the attribute.
      Usually, the name is a fixed string, but it can be a session variable.
    3. To add a value to the attribute, click Add, type a value in the Value(s) field, and click Update to complete the addition.
      You can use a session variable for the value.
      This example shows using a fixed string for the name and a session variable for the value. Name: user_telephonenumber and value: %{session.ad.last.attr.telephoneNumber}.
      You can repeat this step to add multiple values for an attribute.
    4. To encrypt the values, select the Encrypt check box and select a value from the Type list.
      Supported values for type are AES128, AES192, and AES256.
    5. Click OK.
      The Create New SAML Attribute popup screen closes.
  10. Click Security Settings from the left pane.
    1. From the Signing Key list, select the key from the BIG-IP system store.
      None is selected by default.
    2. From the Signing Certificate list, select the certificate from the BIG-IP system store.
      When selected, the IdP (the BIG-IP system) publishes this certificate to the service provider so the service provider can verify the assertion. None is selected by default.
  11. Click OK.
    The popup screen closes. The new IdP service appears on the list.
Access Policy Manager® (APM®) creates a SAML IdP service. It is available to bind to an SP connector.

Binding a SAML IdP service to one SP connector

Bind a SAML Identity Provider (IdP) service and a SAML service provider (SP) connector so that the BIG-IP® system can provide authentication (SAML IdP service) to the external SAML service provider.
  1. On the Main tab, click Access > Federation > SAML Identity Provider .
    The Local IdP Services screen opens.
  2. Select a SAML IdP service from the list.
    Select an IdP service that you configured for use with one particular SP connector only.
  3. Click Bind/Unbind SP Connectors.
    The screen displays a list of available SAML SP connectors.
  4. Select the one SAML SP connector that you want to pair with this IdP service.
  5. Select OK.
    The screen closes.
The SAML SP connector that you selected is bound to the SAML IdP service.

Exporting SAML IdP metadata from APM

You need to convey the SAML Identity Provider (IdP) metadata from Access Policy Manager® (APM®) to the external service provider that uses this SAML IdP service. Exporting the IdP metadata for a SAML IdP service to a file provides you with the information that you need to do this.
  1. On the Main tab, click Access > Federation > SAML Identity Provider .
    The Local IdP Services screen opens.
  2. Select a SAML IdP service from the table and click Export Metadata.
    A popup screen opens, with No selected on the Sign Metadata list.
  3. For APM to sign the metadata, perform these steps:
    1. From the Sign Metadata list, select Yes.
    2. From the Signing Key list, select a key.
      APM uses the key to sign the metadata.
    3. From the Signature Verification Certificate list, select a certificate.
      APM exports the certificate to the metadata file. The system on which you import the metadata file can use the certificate to verify the metadata signature.
  4. Select OK.
    APM downloads an XML file.
You must either import the IdP metadata XML file on the service provider system or use the information in the file to configure the SAML IdP on the service provider system.

Configuring a SAML resource and attaching a SAML IdP service

Configure a SAML resource to provide access to services on a SAML service provider when using Access Policy Manager® (APM®) as a SAML IdP.
Note: Configure one SAML resource for each SAML IdP service that you have configured.
  1. On the Main tab, click Access > Federation > SAML Resources .
    The SAML Resources list screen opens.
  2. Click the Create button.
    The SAML Resource New Resource window opens
  3. In the Name field, type a unique name for the SAML resource.
  4. Do not clear the Publish on Webtop check box unless when you want to remove this resource from the webtop.
    When Publish on Webtop is selected, the SAML resource is displayed on a webtop where a user can initiate connection to an SP by clicking the icon. If you want users to initiate connection to this resource from an external SAML service provider only and do not want to show this resource on a webtop, clear the check box.
  5. In the Configuration area from the SSO Configuration list, select the SAML IdP service that is bound to the SAML SP connector with the resources you want.
  6. In the Customization Settings for English area in the Caption field, type a caption for this SAML resource.
  7. Click Finished.
    The SAML resource is created and associated with a SAML IdP service that is bound to one external service provider.

Configuring a full webtop

A full webtop allows your users to connect and disconnect from a network access connection, portal access resources, SAML resources, app tunnels, remote desktops, and administrator-defined links.
  1. On the Main tab, click Access > Webtops > Webtop Lists .
    The Webtops screen displays.
  2. Click Create.
    The New Webtop screen opens.
  3. In the Name field, type a name for the webtop.
  4. From the Type list, select Full.
    The Configuration area displays with additional settings configured at default values.
  5. Click Finished.
The webtop is now configured, and appears in the list. You can edit the webtop further, or assign it to an access policy.
To use this webtop, it must be assigned to an access policy with an advanced resource assign action or with a webtop, links, and sections assign action. All resources assigned to the full webtop are displayed on the full webtop.

Configuring an access policy for a SAML SSO portal

Before you configure this access policy, configure an access profile without selecting an SSO configuration for it.
Configure an access policy so that the BIG-IP® system, as a SAML Identity Provider (IdP) can authenticate users using any non-SAML authentication type, and assign SAML resources and a webtop to the session.
Note: This access policy supports users that initiate a connection at a SAML service provider or at the SAML IdP.
  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. Make any changes that you require to the logon page properties and click Save.
    The properties screen closes and the policy displays.
  6. Add one or more authentication checks on the fallback branch after the Logon Page action.
    Select the authentication checks that are appropriate for application access at your site.
  7. On a successful branch after an authentication check, assign SAML resources and a full webtop to the session.
    1. Click plus [+] on a successful branch after an authentication check.
      The Add Item window opens.
    2. On the Assignment tab, select the Advanced Resource Assign agent, and click Add Item.
      The Resource Assignment window opens.
    3. Click Add new entry.
      An Empty entry displays.
    4. Click the Add/Delete link below the entry.
      The screen changes to display resources on multiple tabs.
    5. Select the SAML tab, then from it select the SAML resources that represent the service providers that authorized users can access.
    6. Click Update.
      The window changes to display the Properties screen, where the selected SAML resources are displayed.
    7. Click the Add/Delete link below the entry.
      The screen changes to display resources on multiple tabs.
    8. Select the Webtop tab, then select a full webtop on which to present the selected resources.
      You must assign a full webtop to the session even if you have configured all SAML resources to not publish on a webtop.
    9. Click Update.
      The window changes to display the Properties screen. The selected webtop and SAML resources are displayed.
    10. Click Save.
      The Properties window closes and the Access Policy window is displayed.
    You have configured a webtop to display resources that are available from service providers and that an authorized user can access.
  8. Optional: Add any other branches and actions that you need to complete the policy.
  9. Change the Successful rule branch from Deny to Allow, and click the Save button.
  10. Click the Apply Access Policy link to apply and activate the changes to the policy.
  11. Click the Close button to close the visual policy editor.
You have an access policy that presents a logon page, authenticates the user, and assigns SAML resources and a full webtop on which to present them to the user.

Simple access policy for access to services on SAML service providers

Example access policy for SAML IdP-initiated connection
To apply this access policy to network traffic, add the access profile to a virtual server.
Note: To ensure that logging is configured to meet your requirements, verify the log settings for the access profile.

Verifying log settings for the access profile

Confirm that the correct log settings are selected for the access profile to ensure that events are logged as you intend.
Note: Log settings are configured in the Access > Overview > Event Log > Settings area of the product. They enable and disable logging for access system and URL request filtering events. Log settings also specify log publishers that send log messages to specified destinations.
  1. On the Main tab, click Access > Profiles / Policies .
    The Access Profiles (Per-Session Policies) screen opens.
  2. Click the name of the access profile that you want to edit.
    The properties screen opens.
  3. On the menu bar, click Logs.
    The access profile log settings display.
  4. Move log settings between the Available and Selected lists.
    You can assign up to three log settings that enable access system logging to an access profile. You can assign additional log settings to an access profile provided that they enable logging for URl request logging only.
    Note: Logging is disabled when the Selected list is empty.
  5. Click Update.
An access profile is in effect when it is assigned to a virtual server.

Adding the access profile to the virtual server

  1. On the Main tab, click Local Traffic > Virtual Servers .
    The Virtual Server List screen opens.
  2. Click the name of the virtual server you want to modify.
  3. In the Access Policy area, from the Access Profile list, select the access profile that you configured earlier.
  4. Click Update to save the changes.
Your access policy is now associated with the virtual server.

Adding IdP metadata from APM to external SAML SPs

To complete the agreement between Access Policy Manager® as the SAML IdP and a SAML Service Provider (SP), you must configure IdP metadata at the service provider.
Note: Complete this step on each SAML service provider for which an SP connector is bound to the SAML IdP service in APM®.
Using the method that the vendor provides, either:
  • Import the SAML IdP metadata file that you exported from APM for the SAML IdP service that this service provider uses.
  • Or take information from the SAML IdP metadata file that you exported from APM for the SAML IdP service and add it to the service provider using the vendor's interface. Pay particular attention to the values for entityID, AssertionConsumerService, SingleSignOnService, and the certificate.
    Note: Regardless of the value of entityID in the metadata file, type an SSO URI that consists of the virtual server host and /saml/idp/profile/redirectorpost/sso. For example, if the host virtual server is https://Bigip-idp, type: https://Bigip-idp/saml/idp/profile/redirectorpost/sso