Manual Chapter :
Federation
Applies To:
Show Versions
BIG-IQ Centralized Management
- 7.1.0
Federation
About BIG-IQ SAML Service Provider and SAML Identity Provider Support
You may use BIG-IQ Centralized Management to set up SAML support for multiple BIG-IP devices. Many of the concepts and steps are the same as setting up SAML support in BIG-IP Access Policy Manager®.
For more information, see the
BIG-IP Access Policy Manager: Authentication and Single Sign-On
guide on the AskF5™ Knowledge Base located at support.f5.com/
.About SAML
Security Assertion Markup Language (SAML) defines a common XML framework for creating, requesting, and exchanging authentication and authorization data among entities known as Identity Providers (IdPs) and Service Providers (SPs). This exchange enables single sign-on among such entities.
- IdPis a system or administrative domain that asserts information about a subject. The information that an IdP asserts pertains to authentication, attributes, and authorization. Anassertionis a claim that an IdP makes about a subject.
- Service Provideris a system or administrative domain that relies on information provided by an IdP. Based on an assertion from an IdP, a service provider grants or denies access to protected services.
In simple terms, an IdP is a claims producer
,
and a service provider is a claims consumer. An IdP produces assertions about users, attesting to their identities. Service providers consume and validate assertions before providing access to resources.
SAML 2.0 is an OASIS open standard. The SAML core specification defines the structure and content of assertions.
SAML metadata
SAML metadata specifies how configuration information is defined and shared between two communicating entities: a SAML Identity Provider (IdP) and a SAML service provider. Service provider metadata provides information about service provider requirements, such as whether the service provider requires a signed assertion, the protocol binding support for endpoints (AssertionConsumerService) and which certificates and keys to use for signing and encryption. IdP metadata provides information about IdP requirements, such as the protocol binding support for endpoints (SingleSignOnService), and which certificate to use for signing and encryption.
You may create an external SAML connector from metadata by navigating to one of the external SAML connector landing pages and selecting
.Configure a SAML SP service
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-IQ system.
You configure information about a SAML service provider so that BIG-IQS can act as a SAML Identity Provider (IdP) for it.
Configure one SAML SP connector for each external SAML service provider for which this BIG-IP system provides SSO authentication service.
- At the top of the screen, selectConfiguration, then on the left side of the screen, click .
- Click the name of an Access group.A new screen displays the group's properties.
- ExpandFederationand click .The screen displays local SAML Service Provider (SP) services in the working configuration for the Access group.
- Select an existing SAML SP service or clickCreateto begin configuration.
- SelectGeneral Settings.
- Type the name of the SP service. Avoid using global reserved words such as all, delete, disable, enable, help, list, show, or None. You cannot change the name if you are editing an existing configuration.
- Enter aPartition. The default isCommon. You can also enter a custom path to a partition you have created. Only users with access to a partition can view the objects that the partition contains. If the object resides in theCommonpartition, all users can access it.
- In theEntity IDfield, type the FQDN of the SP virtual server.
- In theDescriptionfield, type a descriptive text of the SAML SP.
- In theRelay Statefield, the path to the resource behind BIG-IP APM.Once the IdP finishes authenticating, it sends the Relay State to the SP, which then redirects the user to the source path.
- From theSchemedrop down list, select either http or https.
- In theHostfield, the host destination.
- From theAssertion Consumer Service Bindingdrop down list, choose between the following options.
- SelectPOSTto configure the SAML SP assertion to send messages using POST binding.
- SelectArtifactto configure the SAML SP assertion to send messages using artifact binding.
- ForSign Authentication Request, after clicking the check box, the SAML service provider (this BIG-IP system) signs authentication requests.
- ForWant Signed Assertion, after clicking the check box, the SAML service provider (this BIG-IP system) requires signed assertions from the IdP.
- ForWant Encrypted Assertion, after clicking the check box, the SAML service provider (this BIG-IP system) requires encrypted assertions from the IdP.
- From theAssertion Decryption Private Keydropdown list, select the private key that the SAML SP uses to decrypt encrypted assertions from the IdP.
- From theAssertion Decryption Certificatedropdown list, select the certificate that the SAML SP uses to decrypt encrypted assertions from the IdP.
- ForForce Authentication, select this option to allow the administrator to force users to authenticate again even when they have an SSO session at the identity provider
- For Allow Name-Identifier Creation, select this option to allow the external IdP, when processing requests from this BIG-IP system as SP, to create a new identifier to represent the principal.
- From the Name-Identifier Policy Format, select the type of identifier information to use by selecting a URI reference from the Name-Identifier Policy Format list.
- In the SP Name-Identifier Qualifier field, type the assertion subject's identifier be returned in the namespace of an SP other than the requester, or in the namespace of a SAML affiliation group of SPs.
- In theProvider Namefield, type the name of the SP service provider.
- From theDefault Attribute Consuming Servicedropdown list, select an attribute consuming service as the standard service.
- ForAttribute Consuming Services, add a new attribute consuming service.
- From theComparison Methoddropdown list, Compare the authentication context to the authentication class of the user session.The default value isExact.
- From theAuthentication Context Classesdropdown list, select the URIs that specify the authentication methods in SAML authentication requests.
- From theRequest Authentication Contextdropdown list, select an authentication context that comply with an authentication, requested SAML requesters.
- ClickSave & Close.
The new SAML SP service service will be displayed in the Local SP Services list.
Configure a custom SAML IdP connector
An IdP connector specifies how a BIG-IQ system, configured as a SAML service provider (SP), connects with an external SAML identity provider (IdP). You configure a SAML IdP connector so that BIG-IQ (as a SAML service provider) can send authentication requests to this Identity Provider (IdP), relying on it to authenticate users and to provide access to resources behind BIG-IQ.
- At the top of the screen, selectConfiguration, then on the left side of the screen, click .
- Click the name of an Access group.A new screen displays the group's properties.
- ExpandFederationand click .
- Click.
- Type the name of the IdP connector. Avoid using global reserved words such as all, delete, disable, enable, help, list, show, or None. You cannot change the name if you are editing an existing configuration.
- Enter aPartition. The default isCommon. You can also enter a custom path to a partition you have created. Only users with access to a partition can view the objects that the partition contains. If the object resides in theCommonpartition, all users can access it.
- In theIdP Entity IDfield, a unique identifier for this SAML Identity Provider.Usually, this is a unique URI, representing the IdP.
- In theName Qualifierfield, the security or administrative domain of the Identity Provider.This value usually matches IdP Entity ID.
- In theDescriptionfield, type a descriptive text of the IdP connector.
- From theSingle Sign On Service URLfield, type the URL where APM redirects the user for authentication when the user initiates connection through the service provider.If the identity provider (IdP) is also a BIG-IP system (in a federation of BIG-IP systems), you can use this URL,https://IP-Address/saml/idp/profile/redirectpost/ssoand substitute the IP address or FQDN of the BIG-IP as IdP virtual server for IP-Address.
- From theSingle Sign On Service Bindinglist, select how Access Policy Manager is to send an authentication request to the SAML Identity Provider.
- ForLocation URL, type the URL of the artifact resolution service.
- ForIP Address, type the IP address of the artifact resolution service.
- ForPort, type the port number of the artifact resolution service.
- ForSign Artifact Resolution Request, select the check box to specify that artifact resolution messages from an SP are signed.
- ForServer SSL Profile, select the name of the Server SSL profile you previously created.
- Type theUsernameandPasswordof the Server SSL profile.
- ForIdentity Location, select where to find the user ID or name: in theSubjectelement of the assertion or in one of theAttributesin the attribute statement.
- ForIdentity Location Attribute, type the name of the attribute where the user ID or name can be found.
- ForAuthentication Request sent by this device to IdP, select whether the IdP expects signed authentication requests.
- ForSigning Algorithm, select the signing algorithm uses to send authentication request to IdP.
- ForIdP's Assertion Verification Certificate, select the IdP certificate that, with public key, a service provider uses to validate a signed assertion.
- ForSingle Logout Request URL, type an URL at the SAML Identity Provider (IdP) where APM can send the logout request when a service provider initiates a logout.
- ForSingle Logout Response URL, type an URL at the SAML Identity Provider (IdP) where APM can send the logout response when the IdP initiates the logout request.
- ForSingle Logout Binding, select a binding that specifies the method that Access Policy Manager uses to send logout requests and responses to the SAML Identity Provider.
- ClickSave & Close.
The IdP connector will be displayed in the External IdP Connectors List.
Automate IdP connector creation for BIG-IQ as SP
To create a BIG-IQ Identity Provider (IdP) automation configuration, you need a BIG-IQ system that is configured to function as a SAML service provider (SP) and you need to have SAML SP services defined.
When a BIG-IQ system is configured as a SAML service provider (SP), you can use SAML identity provider (IdP) automation to automatically create new SAML IdP connectors for SP services. BIG-IQ polls a file or files that you supply; the files must contain cumulative IdP metadata. After polling, BIG-IQ creates IdP connectors for any new IdPs and associates them with a specified SP service. BIG-IQ uses matching criteria that you supply to send the user to the correct IdP.
You create a connector automation configuration to automatically create SAML IdP connectors and bind them to an SP service based on cumulative IdP metadata you maintain in a file or files. You specify matching criteria in connector automation for BIG-IQ to use, in order to send a user to the correct IdP.
- At the top of the screen, selectConfiguration, then on the left side of the screen, click .
- Click the name of an Access group.A new screen displays the group's properties.
- ExpandFederationand click .
- ClickCreate.
- Type a name for the connector automation. Avoid using global reserved words such as all, delete, disable, enable, help, list, show, or None. You cannot change the name if you are editing an existing configuration.
- Enter aPartition. The default isCommon. You can also enter a custom path to a partition you have created. Only users with access to a partition can view the objects that the partition contains. If the object resides in theCommonpartition, all users can access it.
- From theSP Servicedropdown list, select the SAML SP service that binds the SAML SP connectors that this automation creates.
- ForMetadata Tag For SP Connector Name, type a value that must be contained in the metadata tag for BIG-IQ to consider it a match.
- ForMetadata Tag For SP Connector Name, type the name of a metadata tag that contains a value BIG-IQ uses to name an SP connector that it creates.
- ForFrequency, type the number of minutes after which BIG-IQ polls the SP metadata files and updates the SP connectors and bindings for the service.
- ForMetadata URLs, type an URL that begins with http or https and specifies an SP metadata file located on a remote system.
- From theDNS Resolverdropdown list, select a DNS resolver for the connector automation.
- From theSSL Profile (Server)dropdown list, select a server SSL profile for the connector automation.
- ClickSave & Close.
The new connector automation will populate in the Connector Automation list.
Create SAML authentication context classes
You create SAML authentication context classes to provide URIs to SAML service providers. These URIs specify authentication methods in SAML authentication requests and authentication statements.
- At the top of the screen, selectConfiguration, then on the left side of the screen, click .
- Click the name of an Access group.A new screen displays the group's properties.
- ExpandFederationand click .
- The screen displays SAML authentication context classes in the working configuration for the Access group. The URI reference identifies an authentication context class that describes an authentication context declaration.
- To add a new authentication context class, click theCreatebutton.
- To delete an existing authentication context class, select the check box next to the entry and click theDeletebutton.
- To configure an authentication context class, select an existing item in the list or clickCreate.
- Enter aNamefor this authentication context class configuration. Avoid using global reserved words such as all, delete, disable, enable, help, list, show, or None. You cannot change the name if you are editing an existing configuration.
- Enter aPartition. The default isCommon. You can also enter a custom path to a partition you have created. Only users with access to a partition can view the objects that the partition contains. If the object resides in theCommonpartition, all users can access it.
- UnderOrdered List of Authentication Context Classes, add a name for an authentication context class.
- ForValue, select a SAML authentication context class and select a value from the list.Each value that you select must be unique.
- ClickSave & Close.
The new SAML authentication context class will display in the authentication context list.
Create attribute consuming service
A SAML service provider (SP) endpoint can request certain attributes from a SAML IdP by including a special multi-attribute called an attribute consuming service. An attribute consuming service describes a service and a list of attributes to be used by the service. It is typically used with an AttributeConsumingService index which is used to map to an attribute consuming service. During a SAML SP configuration, the SP can specify attribute consuming service elements, where each element describes a service and a list of requested attributes, ready to use in a service. You can export this in the metadata and share it with the identity provider.
- At the top of the screen, selectConfiguration, then on the left side of the screen, click .
- Click the name of an Access group.A new screen displays the group's properties.
- ExpandFederationand click .
- The screen displays SAML attribute consuming services in the working configuration for the Access group.
- To view or edit an attribute consuming service, select it under the Name column.
- To locate an attribute consuming service, search for it by name; otherwise, look for it under the Name column.
- Selecting an policy from the list displays the Related Items section. ClickShowto display related items such as lease pools, network access, or webtops.
- To create a new attribute consuming service, click theCreatebutton.
- To delete a service, select the check box next to the profile name, and then click theDeletebutton.
- ClickCreate.
- Type a name for the attribute consuming service object. Avoid using global reserved words such as all, delete, disable, enable, help, list, show, or None. You cannot change the name if you are editing an existing configuration.
- Enter aPartition. The default isCommon. You can also enter a custom path to a partition you have created. Only users with access to a partition can view the objects that the partition contains. If the object resides in theCommonpartition, all users can access it.
- From theService Namelist, type the name of the attribute consuming service.
- From theService Descriptionlist, type a descriptive text for the attribute consuming service.
- ForNamein the SAML Attributes section, type the MCP object name for the attribute.The name must be unique.
- ForAttribute Name, type a string that represents the name of the attribute.The name must be unique.
- ForName Format, type a URI reference that classifies the attribute name.
- ForFriendly Name, type a string that provides a more readable form of the attribute name.
- ForIs required, select the check box if the service requires the corresponding SAML attribute in order to function.The default value isFalse.
- Click the+button to add another row of SAML attributes.
- ClickSave & Close.
The new SAML attribute consuming class will display in the attribute consuming services list.
Configure a SAML IdP service
A SAML IdP service is a type of single sign-on (SSO) authentication service in BIG-IQ. When you use a BIG-IQ 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. Configure a SAML Identity Provider (IdP) service for the BIG-IQ system, configured as a SAML IdP, to provide authentication service for SAML service providers (SPs).
Configure this IdP service to meet the requirements of all SAML service providers that you bind with it.
- At the top of the screen, selectConfiguration, then on the left side of the screen, click .
- Click the name of an Access group.A new screen displays the group's properties.
- ExpandFederationand click .
- ClickCreate.
- Type a name for the IdP service. Avoid using global reserved words such as all, delete, disable, enable, help, list, show, or None. You cannot change the name if you are editing an existing configuration.
- Enter aPartition. The default isCommon. You can also enter a custom path to a partition you have created. Only users with access to a partition can view the objects that the partition contains. If the object resides in theCommonpartition, all users can access it.
- In theIdP Entity IDfield, type the unique identifier of the IdP (this BIG-IP system).This is usually a URI that represents the IdP.
- ForName Qualifier, type the security or administrative domain of the IdP (this BIG-IP system).This value usually matches IdP Entity ID.
- ForDescription, type a description of the SAML IdP.
- From theLog Settinglist, select the correct log settings are selected for the access profile to ensure that events are logged as intended.
- From theSchemelist, select eitherhttporhttps.
- ForHost, type the host destination.
- ForWeb Browser SSO, select the check box to exchange information between the IdP, the SP, and the user on a web browser
- ForEnhanced Client or Proxy Profile (ECP), select the check box to specify a browser that supports ECP functionality with an HTTP proxy.You can enable SSO and this will act as an intermediary when the IdP and SP cannot communicate directly.
- From theArtifact Resolution Servicelist, select the check box to create an artifact resolution service to provide SAML artifacts in place of assertions.
- From theAssertion Subject Typelist, select where the IdP (this BIG-IP system) can find the subject to be authenticated.
- From theAssertion Subject Valuelist, select the subject value.Usually, this is a session variable.
- From theAuthentication Context Class Referencelist, select the URI reference that identifies an authentication context class.
- ForAssertion Validity, type the number in seconds for which the assertion is valid.
- ForEnable Encryption of Subject, select the check box to specify the encryption strength.
- From theSigning Keylist, select the key from the BIQ-IQ store. The default value isNone.
- From theSigning Certificatelist, select the certificate from the BIG-IQ system store.
- ForSigning Key Session Variable, type a session variable that resolves to a signing key used by the IdP to sign SAML messages.
- ForSigning Certificate Session Variable, type a session variable that resolves to a signing certificate used by the IdP to sign SAML messages.
- ClickSave & Close.
The new SAML IdP service will display in the Local IdP services list.
Configure a custom SAML SP connector
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-IQ system.
You configure information about a SAML service provider so that BIG-IQ can act as a SAML Identity Provider (IdP) for it.
Configure one SAML SP connector for each external SAML service provider for which this BIG-IQ system provides SSO authentication service.
- At the top of the screen, selectConfiguration, then on the left side of the screen, click .
- Click the name of an Access group.A new screen displays the group's properties.
- ExpandFEDERATIONand click .
- Click.
- Type the name of the SP connector. Avoid using global reserved words such as all, delete, disable, enable, help, list, show, or None. You cannot change the name if you are editing an existing configuration.
- Click the name of an Access group.A new screen displays the group's properties.
- ForRequired Signed Authentication Request, select the check box to require the user to select a signing certificate.
- ForSigning Certificate, select the certificate for verifying signed authentication requests.This is usually the service provider certificate with public key.
- ForResponse must be signed, select the check box to specify that the service provider requires signed response from the IdP.
- ForSigning Algorithm, select an RSA public-key encryption algorithm.
- ForAssertion must be signed, select the check box to specify that the service provider requires signed assertions from the IdP.
- ForAssertion must be encrypted, select the check box to specify that the service provider requires encrypted assertions from the IdP.
- ForEncryption Type, select the type of AES encryption that you want.
- ForEncryption Certificate, select the certificate to use to verify signed authentication requests.This is usually the service provider certificate with a public key.
- ForSingle Logout Request URL, type where the system should send a logout request to this service provider when the system initiates a logout request.
- ForSingle Logout Response URL, type where to send a response to the service provider to indicate that single logout is complete.
- ForSingle Logout Binding, select how the system sends a logout request to the service provider.
- ForService Provider Location, select whether the SP is located as an external, internal, or internal multi-domain provider.
- ForRelay State, type a value that the service provider uses to redirect the user after authentication.
- ForAssertion Consumer Services, specify at least one assertion consumer service.
- ClickSave & Close.
The new SAML service provider connector will be displayed in the SAML SP connector list.
Automate SP connector creation for BIG-IQ as IdP
To create a BIG-IQ Service Provider (SP) automation configuration, you need a BIG-IQ system that is configured to function as a SAML identity provider (IdP) and you need to have SAML IdP services defined.
When a BIG-IQ system is configured as a SAML identity provider (IdP), you can use SAML service provider (SP) automation to automatically create new SAML SP connectors for IdP services. BIG-IQ polls a file or files that you supply; the files must contain cumulative IdP metadata. After polling, BIG-IQ creates SP connectors for any new SPs and associates them with a specified IdP service. BIG-IQ uses matching criteria that you supply to send the user to the correct SP.
You create a connector automation configuration to automatically create SAML IdP connectors and bind them to an IdP service based on cumulative IdP metadata you maintain in a file or files. You specify matching criteria in connector automation for BIG-IQ to use, in order to send a user to the correct IdP.
- At the top of the screen, selectConfiguration, then on the left side of the screen, click .
- Click the name of an Access group.A new screen displays the group's properties.
- ExpandFederationand click .
- ClickCreate.
- Type a name for the connector automation. Avoid using global reserved words such as all, delete, disable, enable, help, list, show, or None. You cannot change the name if you are editing an existing configuration.
- Enter aPartition. The default isCommon. You can also enter a custom path to a partition you have created. Only users with access to a partition can view the objects that the partition contains. If the object resides in theCommonpartition, all users can access it.
- From theIdP Servicelist, select the SAML IdP service that binds the SAML IdP connectors that this automation creates.
- ForMetadata Tag For SP Connector Name, type the name of a metadata tag that contains a value BIG-IQ uses to name an SP connector that it creates.
- ForFrequency, type the number of minutes after which BIG-IQ polls the SP metadata files and updates the SP connectors and bindings for the service.
- ForMetadata URLs, type an URL that begins withhttporhttpsand specifies an SP metadata file located on a remote system.
- From theDNS Resolverlist, select a DNS resolver for the connector automation.
- From theSSL Profile (Server)list, select a server SSL profile for the connector automation.
- ClickSave & Close.
The new SP automation will be displayed in the Connector Automation list.
Configure 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.
F5 highly recommends that the virtual server definition include a server SSL profile.
You configure an ARS so that a BIG-IQ system that is configured as a SAML IdP can provide SAML artifacts in place of assertions. With ARS, the BIG-IQ system can receive Artifact Resolve Requests (ARRQ) from service providers, and provide Artifact Resolve Responses (ARRP) for them.
- At the top of the screen, selectConfiguration, then on the left side of the screen, click .
- Click the name of an Access group.A new screen displays the group's properties.
- ExpandFederationand click .
- Under Artifact Resolution Services (Shared) Artifact Resolution Services (Device-specific), clickCreate.The Create New SAML Artifact Resolution Service popup screen opens, showing general settings.
- In theNamefield, type a name for the artifact resolution service. Avoid using global reserved words such as all, delete, disable, enable, help, list, show, or None. You cannot change the name if you are editing an existing configuration.
- Enter aPartition. The default isCommon. You can also enter a custom path to a partition you have created. Only users with access to a partition can view the objects that the partition contains. If the object resides in theCommonpartition, all users can access it.
- In theDescriptionfield, type a new description.
- ClickService Settings.
- From theVirtual Serverlist, select the virtual server that you created previously.ARS listens on the IP address and port configured on the virtual server.
- In theArtifact Validity (Seconds)field, type the number of seconds for which the artifact remains valid. The default is 60 seconds.The system deletes the artifact if the number of seconds exceeds the artifact validity number.
- For theSend Methodsetting, select the binding to use to send the artifact, eitherPOSTorRedirect.
- In theHostfield, type the host name defined for the virtual server, for examplears.siterequest.com.
- In thePortfield, type the port number defined in the virtual server. The default is443.
- ClickSecurity Settings.
- To require that artifact resolution messages from an SP be signed, select theSign Artifact Resolution Requestcheck box.
- To use HTTP Basic authentication for artifact resolution request messages, in theUser Namefield, type a name for the artifact resolution service request and in thePasswordfield, type a password.These credentials must be present in all Artifact Resolve Requests sent to this ARS.
- ClickOK.The popup screen closes, leaving the Artifact Resolution Services list screen open.
The Artifact Resolution Service will display in the artifact resolution list.
Configure a SAML resource
You may configure a SAML resource to link to an Identity Provider or a Service Provider.
- From theConfigurationtab, create or select an Access group, select .The screen displays the token configurations for JSON web token (JWK) and lists both shared and device-specific resources.
- Type the name of the SAML resource. Avoid using global reserved words such as all, delete, disable, enable, help, list, show, or None. You cannot change the name if you are editing an existing configuration.
- Enter aPartition. The default isCommon. You can also enter a custom path to a partition you have created. Only users with access to a partition can view the objects that the partition contains. If the object resides in theCommonpartition, all users can access it.
- In theDescriptionfield, type an optional description for the SAML resource.
- ForPublish on Webtop, when selected, the SAML resource is displayed on a webtop when a user initiates connection at the SAML IdP.
- In theSSO Configurationfield, select the SAML IdP service to which the SAML SP connector for the service provider is bound.
- ForLanguage, select default language for the SAML resource. This is set on the system and cannot be changed.
- ForCaption, type the caption for the SAML resource. This customization property is required.
- ForDetailed Description, type a detailed description of the SAML resource.
- ForImage, select an icon image for the SAML resource.
- ClickSave & Close.
The SAML resource will appear in the SAML resource list.
About JSON web tokens
JSON Web Token (JWT) is an open standard (RFC
7519) that defines a compact and self-contained way for securely transmitting information in a JSON object between OAuth entities. This information can be verified and trusted because it is digitally signed. JSON tokens are not stored on an OAuth authorization server and they cannot be revoked.
The OAuth Scope Check Agent's external mode cannot have
Validation
Request
set for JWT tokens. JWT access tokens must use 'internal' mode validation.Configure JSON web keys
A key configuration specifies a cryptographic JSON web key (JWK). You can automatically create a key configuration by discovering it from an OAuth provider, or you may manually enter the information that's required to create a key configuration on the page below.
- From theConfigurationtab, create or select an Access group, select .The screen displays the token configurations for JSON web token (JWK) and lists both shared and device-specific resources.
- Select an existing key configuration or create a new one by clickingCreate.You will be directed to a page where you may configure this resource.
- Enter a uniqueNamefor this JSON web key configuration. Avoid using global reserved words such as all, delete, disable, enable, help, list, show, or None. You cannot change the name if you are editing an existing configuration.
- Enter aPartition. The default isCommon. You can also enter a custom path to a partition you have created. Only users with access to a partition can view the objects that the partition contains. If the object resides in theCommonpartition, all users can access it.
- Under theIDfield, specify a parameter to identify a specific JSON web key.
- Specify aTypeof cryptographic algorithm used to sign the JSON web key.RSAuses RSA algorithms,Elliptic Curveuses ECDSA algorithms, andOctetuses HMAC algorithms.
- To create an RSA-type JSON web key configuration using an RSA cryptographic algorithm, follow the procedure below:
- Select aSigning Algorithmfrom the drop-down menu or selectNone.
- To support an RSA, you must either select a pre-set certificate or manually provide parameters. If you select a certificate file, the parameters will be auto-generated from it.
- To select a pre-set certificate and auto-generate the associated parameters, select aCertificate Filefrom the drop-down menu.
- You may selectInclude X5Cto enable a JWKS endpoint response containing a chain of one or more PKIX certificates.
- Select aCertificate Keyfrom the drop-down menu. The certificate key is used by this JSON web key to sign the JWT.
- Specify aKey Passphraseused to encrypt the certificate key.
- Select aCertificate Chainfrom the drop-down menu. This certificate chain is used by the JSON web key to validate the certificate in theCertificate Filefield.
- Alternatively, you can manually provide parameters by selectingNoneunder theCertificate Filesdrop-down menu.
- UnderModulus, enter a modulus value for the RSA public key.
- UnderPublic Exponent, enter the encryption exponent of an RSA public key.
- UnderSHA-1 Thumbprint, enter the base64url-encoded SHA-1 thumbprint of the DER encoding of the X.509 certificate.
- UnderSHA-256 Thumbprint, enter the base64url-encoded SHA-256 thumbprint of the DER encoding of the X.509 certificate.
- To create an octet-type JSON web key configuration using an HMAC cryptographic algorithm, follow the procedure below:
- Select aSigning Algorithmfrom the drop-down menu or selectNone.
- Selectuse Client Secretto use an encrypted key generated by the client. If you enable this, no more inputs are required.
- If you wish to create your own key, disableUse Client Secret. This field is available for configuration for Access Groups running BIG-IP version 14.0 and later.
- If you would like to encode your key, select anEncoding Formatfrom the drop-down menu. This field is available for configuration for Access Groups running BIG-IP version 14.0 and later.
- Under theShared Secret, enter your own secret for this JSON web key.
- To create an elliptic curve-type JSON web key configuration using an ECDSA cryptographic algorithm, follow the procedure below:
- Select aSigning Algorithmfrom the drop-down menu.
- To support an elliptic curve, you must either select a pre-set certificate or manually provide parameters. If you select a certificate file, the parameters will be auto-generated from it.
- To select a pre-set certificate and auto-generate the associated parameters, select aCertificate Filefrom the drop-down menu.
- You may selectInclude X5Cto enable a JWKS endpoint response containing a chain of one or more PKIX certificates.
- Select aCertificate Keyfrom the drop-down menu. The certificate key is used by this JSON web key to sign the JWT.
- Specify aKey Passphraseused to encrypt the certificate key.
- Select aCertificate Chainfrom the drop-down menu. This certificate chain is used by the JSON web key to validate the certificate in theCertificate Filefield.
- Alternatively, you can manually provide parameters by selectingNoneunder theCertificate Filesdrop-down menu.
- Specify anX Coordinatefor the elliptic curve.
- Specify aY Coordinatefor the elliptic curve.
- UnderCurve, enter the value of an elliptic curve. You may enter eitherP-256orP-384.
- UnderSHA-1 Thumbprint, you can optionally enter the base64url-encoded SHA-1 thumbprint of the DER encoding of the X.509 certificate.
- UnderSHA-256 Thumbprint, enter the base64url-encoded SHA-256 thumbprint of the DER encoding of the X.509 certificate.
- SelectSave & Close.
The new JSON web key will display in the key configuration list.
Configure JSON web tokens
An access token configuration specifies a cryptographic JSON web token (JWT). A token configuration supports the BIG-IP device to consume JWTs, when configured to act as an OAuth Client / Resource Server. You can automatically create a token configuration by discovering it from an OAuth provider, or you may manually enter the information that's required to create a key configuration on the page below.
- From theConfigurationtab, create or select an Access group, select .The screen displays the token configurations for JSON web token (JWK) and lists both shared and device-specific resources.
- Select an existing token configuration or create a new one by clickingCreate.You will be directed to a page where you may configure this resource.
- Enter a uniqueNamefor this JSON web token configuration. Avoid using global reserved words such as all, delete, disable, enable, help, list, show, or None. You cannot change the name if you are editing an existing configuration.
- Enter aPartition. The default isCommon. You can also enter a custom path to a partition you have created. Only users with access to a partition can view the objects that the partition contains. If the object resides in theCommonpartition, all users can access it.
- Enter an optionalDescriptionfor this JSON web token configuration.
- UnderIssuer, specify the URL for the issuer of the JSON web token.
- If you selectUse Provider List Settings, the access token expiry time will be auto-generated from the provider list. Otherwise, you may manually set an expiry time.
- If you do not selectUse Provider List Settings, enter an integer value in theAccess Token Expires Infield. The default is zero minutes, which indicates no expiration time.
- Add anAudiencefor this token by typing a string in the field. To add another, select+and selectxto remove an audience.
- Under theSigning Algorithmfield, you may move the signing algorithms among theAvailable,Allowed, andBlockedlists. BIG-IQ specifies the list of available signing algorithms. You must specify at least one allowed signing algorithm.
- Under theKeys (JWK)field, you may move keys among theAvailable,Allowed, andBlockedlists. To manage the list of available key configurations, see theFederation>JSON Web Token>Key Configurationarea of the product.
- You may reject a valid JWT access token that contains a particular claim name paired with one of the configured claim values. In theBlacklistfield, enter aNameand aValue. You can enter multiple values per name, and can also add additional name-value pairs to blacklist.
- SelectSave&Close.
The new JSON web token will be displayed in the token configuration list.
Configure provider lists for a JSON web token
Create a new provider list to enable a single OAuth Scope agent in an access policy to validate tokens issued by multiple OAuth providers.
- From theConfigurationtab, create or select an Access group, and select .
- You will be directed to a screen that displays the provider lists for JSON web token (JWT).
- Select an existing provider list or clickCreateto navigate to a page where you may configure a provider list.
- Enter a uniqueNamefor this provider list. Avoid using global reserved words such as all, delete, disable, enable, help, list, show, or None. You cannot change the name if you are editing an existing configuration.
- Enter aPartition. The default isCommon. You can also enter a custom path to a partition you have created. Only users with access to a partition can view the objects that the partition contains. If the object resides in theCommonpartition, all users can access it.
- UnderPartition/Path, enter the partition or path to which the provider list belongs. Only users with access to a partition can view the objects (such as the provider list) that the partition contains. If the provider list resides in the Common partition, all users can access it.
- In theAccess Token Expires Infield, you may specify that length of time that you would like the token to be valid for the end-user. Please enter an integer value. The default expiration time is zero minutes, which indicates no expiration.
- In theProviderfield, select the paths to each JWT provider you would like to add to the new list. You may filter for providers using the icon on the top right.
- SelectSave&Close.
The provider list will be added to the JSON web token provider list landing page.
About OAuth Authorization Server
You may configure managed BIG-IP devices in an Access Group to act as an OAuth authorization server. OAuth client applications and resource servers can register to have APM authorize requests.
As an OAuth authorization server, Access Policy Manager (APM) supports a list of endpoints interactions with resource owners and clients on the BIG-IP system. APM supplies default URIs for each endpoint. Users can replace the default URIs. These endpoints include authorization endpoints, token issuance endpoints, token revocation endpoints, token introspection endpoints, and OpenID Connect Configuration Endpoints. See the BIG-IP APM documentation to learn more about authoriztion server support for each of these endpoint types.
About OAuth token
types
As an OAuth authorization server, BIG-IQ Centralized Management supports bearer access tokens and refresh
tokens. For utilization as bearer access tokens and refresh tokens, BIG-IQ supports opaque
tokens and JSON web tokens.
About access
tokens
As defined in the OAuth 2.0 specification (RFC 6749), an
access token
is a credential used to access protected resources. An
access token is a string that represents an authorization issued to the client. A token
represents specific scopes and durations of access granted by the resource owner. The resource
server and the authorization server enforce the scopes and durations of access.About refresh tokens
As defined in the OAuth 2.0 specification (RFC 6749), a
refresh token
is a
credential used to obtain an access token. The client uses a refresh token to get a new
access token from the authorization server when the current access token expires. If
refresh tokens are enabled in the configuration, the OAuth authorization server issues a
refresh token to the client when it issues an access token. A refresh token is a string. It represents the authorization that the resource owner grants to
the client. Unlike access tokens, a refresh token is for use with authorization servers
only, and is never sent to a resource server.
About opaque tokens
Opaque tokens
are issued in a proprietary format. Only the OAuth authorization server that issues the token can read it and validate it. The OAuth authorization server stores an opaque token for its lifetime and offers the ability to revoke the token. Use of opaque tokens forces client apps to communicate with the authorization server.The F5 Authorization server responds to introspect requests for opaque access tokens only. The OAuth Scope Check Agent's external mode cannot have
Validation
Request
set for JWT tokens. JWT access tokens must use 'internal' mode validation.Configuring APM as
an OAuth 2.0 authorization server
You can configure BIG-IQ
Centralized Management to act as an OAuth authorization server. OAuth client
applications and resource servers can register to have BIG-IQ authorize requests.
Configure OAuth scopes
When Access Policy Manager (APM) acts as an OAuth authorization server, you must configure scopes of access. Scopes are a set of identifiers used to designate access privileges, and are created to request access to an associated claim. A scope specifies a string and optionally, a value, that represents a resource. When an OAuth client application needs access to resources, scopes specify the types of resources that the client application requires.
- From theConfigurationtab, create or select an Access group, select .The screen displays the OAuth authorization server scope resources in the working configuration for the Access group.
- SelectCreateor select an existing resource to configure an OAuth scope.
- Enter a uniqueNamefor your scope configuration. Avoid using global reserved words such as all, delete, disable, enable, help, list, show, or None. You cannot change the name if you are editing an existing configuration.
- Enter aPartition. The default isCommon. You can also enter a custom path to a partition you have created. Only users with access to a partition can view the objects that the partition contains. If the object resides in theCommonpartition, all users can access it.
- UnderScope Name, enter a string to represent a resource.
- UnderScope Value, specify a session variable or other text as the value of the scope.
- Enter a descriptive text for this scope under theDescriptionfield.
- TheCaptionfield will be automatically populated with the string entered in theScope Namefield. TheCaptionfield can optionally be changed.
- UnderDetailed Description, you may optionally enter information about customized language settings.To customize text for other languages, add the languages of your choice to the list of accepted languages in the access profile. For each language, customize text in theTextarea.
- SelectSave&Close.
Your new OAuth scope will be displayed in the OAuth scope list.
Configure OAuth claim
You can configure the claims that you want to include in the JSON web tokens (JWTs). This is only required if you plan to specify claims in your JWTs. A set of OAuth claims consists of name and pair values that provides information about a user entity. You can use BIG-IQ to create a single name and pair entry to add to a set of claims.
- From theConfigurationtab, create or select an Access group, select .The screen displays a list of claims that the OAuth authorization server can make for a client application in a JSON web token.
- The screen displays a list of claims that the OAuth authorization server can make for a client application in a JSON web token.
- To delete a claim, select a resource from the list and clickDelete.
- To locate a claim, search for it by name, otherwise look for it in theNamelist.
- SelectCreateor select an existing claim to configure an OAuth claim.
- Enter a uniqueNamefor your claim configuration. Avoid using global reserved words such as all, delete, disable, enable, help, list, show, or None. You cannot change the name if you are editing an existing configuration.
- Enter aPartition. The default isCommon. You can also enter a custom path to a partition you have created. Only users with access to a partition can view the objects that the partition contains. If the object resides in theCommonpartition, all users can access it.
- In theDescriptionfield, you may optionally provide a descriptive text for the claim.
- ForClaim Type, select eitherString,Number,Boolean, or create a custom type. This field is available for configuration for Access Groups running BIG-IP version 14.1 and later.
- UnderClaim Name, specify a name for this claim. It must be a string that does not contain spaces and that does not match a registered claim name (such asiss, aud, exp, sub, iat, jti, exp, and nbf).
- UnderClaim Value, enter the value for the claim.Once you have finished, you should have a name and value pair such as"zoneinfo": "America/Los_Angeles".
- SelectSave&Close.
Your new OAuth claim will be displayed in the Claims list.
Register a client application for OAuth services
For a client application to obtain OAuth tokens and OAuth authorization codes from BIG-IQ Centralized Management, you must register it with Access.
- At the top of the screen, selectConfiguration, then on the left side of the screen, click .
- Click the name of an Access group.A new screen displays the group's properties.
- ExpandFederationand click .
- The screen displays the OAuth authorization server client applications resources in the working configuration for the Access group.
- To locate an application, search for it by name.
- To download a CSV file of one or more client applications, select the check box next to each client application, and then clickDownload Client Applications(s).
- To create a new client application, click theCreatebutton. Objects that you created are copied for other BIG-IP devices in the access group. Open and update these copies individually.
- To delete a client application, select the check box next to the application and click theDeletebutton. Deleting a client application also deletes any copies in the access group.
- ClickCreate.The New Client Application screen opens.
- Type the name of the client application configuration. You cannot change the name if you are editing an existing configuration. Avoid using global reserved words such as all, delete, disable, enable, help, list, show, or None. You cannot change the name if you are editing an existing configuration.
- Enter aPartition. The default isCommon. You can also enter a custom path to a partition you have created. Only users with access to a partition can view the objects that the partition contains. If the object resides in theCommonpartition, all users can access it.
- ForDevice, select the BIG-IP device attached to this application.
- ForApplication Name, type the name of the client application.
- ForWebsite URL, type the URL for the home page of the client application.
- ForWebsite Logo URL, type the URL that refers to the logo for the client application.
- ForContact, type contact information.
- In the Customization Settings for English area, forCaption,type the application name to display when prompting the user for authorization. (Defaults to text entered in theApplication Namefield.)
- ForDetailed Description, type the description of the application to display when prompting the user for authorization.
- ForSecret(if displayed), to regenerate the secret clickRegenerate.
- ForGrant Type, select one or more of the following options:
- Authorization Code / Hybrid- The client must authenticate with the OAuth authorization server to get a token.
- Implicit- The client gets a token from the OAuth authorization server without authenticating to it. (Refresh tokens are not available with this grant type.)
- Resource Owner Password Credentials- The client goes directly to the OAuth authorization server and uses the resource owner credentials to obtain a token.
- ForSupport OpenID Connect, selectEnabledto enable OpenID Connect support. Client applications retreive an ID token and an access token.
- ForAuthentication Type, select one of the following options:
- None- This is typically used in conjunction with the implicit grant type which does not use a secret or a certificate.
- Secret- The OAuth authorization server (BIG-IQ) auto-generates a random alphanumerical string, which is cryptographically strong.
- Certificate- The OAuth authorization server requires a client certificate in OAuth requests. The certificate must be verifiable using the trusted CA chain, that is configured in the client SSL profile and attached to the virtual server that acts as the OAuth authorization server.
- ForClient Certificate Distinguished Name(if displayed) if you specify a certificate distinguished name, then only a valid client certificate with the specified certificate distinguished name will be accepted.
- ForScope, move values between theSelectedlist, which specifies scopes that are applicable to the client application and theAvailablelist, which specifies other scopes that are defined on the BIG-IP system.
- ForRedirect URIs(if displayed), specify a list of fully qualified URIs to which the OAuth authorization server can redirect the resource owner’s user agent after authorization is obtained. A redirect URI is used with theAuthorization CodeandImplicitgrant types.
- In the Token Management Configuration area, for theUse Profile Token Management Settingscheck box:
- Select to take token management settings from the OAuth profile that is attached to the virtual server. (Additional token management settings are hidden when you select the check box.)
- Clear to configure token management settings to meet the particular requirements of this client application. (Additional token management settings display when you select the check box.)
- IfUse Profile Token Management Settingsis disabled, you can update the following fields.
- ForAuthorization Code Lifetime, type a number.This specifies the number of minutes an authorization code is considered valid.
- ForAccess Token Lifetime, type a number.This specifies the number of minutes an access token is considered valid.
- ForReuse Access Token, select or clear theEnabledcheck box. If cleared, the server generates a new access token. If selected, the server extends the expiry time of the access token associated with the refresh token.For an access token to be reused, theEnabledcheck box must be selected forGenerate Refresh Token.
- ForGenerate Refresh Token, select or clear theEnabledcheck box. If selected, the OAuth authorization server generates a refresh token in addition to the access token for authorization code and resource owner credential grants.
- ForRefresh Token Lifetime(if displayed), type a number.This specifies the number of minutes that a refresh token is considered valid after it is generated.
- ForReuse Refresh Token(if displayed), select or clear theEnabledcheck box. When cleared and a new access token is obtained, the OAuth authorization server also generates a new refresh token value.
- ForRefresh Token Usage Limit(if displayed), type a number.This specifies the number of times an access token can be obtained using the refresh token.
- ForJWT Access Token Lifetime(if displayed), type a number. This field is available for configuration for Access Groups running BIG-IP version 13.1 and later.This specifies the number of minutes a JWT access token is considered valid. In specifying this lifetime, consider that JWT access tokens cannot be revoked.
- ForJWT Generate Refresh Token, selectEnabledso the OAuth authorization server generates a refresh token in addition to the access token for authorization code and resource owner credential grants. This field is available for configuration for Access Groups running BIG-IP version 13.1 and later.
- ForJWT Refresh Token Lifetime, type a number.This specifies the number of minutes a refresh token is considered valid. In specifying this lifetime, consider that JWT refresh tokens cannot be revoked. This field is available for configuration for Access Groups running BIG-IP version 13.1 and later.
- ForID Token Lifetime, type the number of minutes an ID token is considered valid.
- ForAudience, add the audience claim for which the JWT access token is intended. This is a list of values. Each value in this list can be a string, URI, or session variable. This field is available for configuration for Access Groups running BIG-IP version 13.1 and later.
- ForJWT Claims, in theAvailablelist, specify the list of claims that are part of the JWT access token. This field is available for configuration for Access Groups running BIG-IP version 13.1 and later.
- ForID Token Claims, select the list of claims that are part of the ID token.
- ForUserInfo Claims, select the list of claims that are part of the user info.
- ClickSave & Close.
Access generates a client ID for the application. If the
Authentication Type
is set to Secret
, Access generates a secret. The application displays on the Client Application screen.Register a resource server for OAuth services
For Access in BIG-IQ Centralized Management as an OAuth authorization server to accept token introspection requests from a resource server for token validation, you must register the resource server with Access.
- At the top of the screen, selectConfiguration, then on the left side of the screen, click .
- Click the name of an Access group.A new screen displays the group's properties.
- ExpandFederationand click .
- ClickCreateor select an existing server to begin configuration.The New Resource Server screen opens.
- Enter a uniqueNamefor this resource server. Avoid using global reserved words such as all, delete, disable, enable, help, list, show, or None. You cannot change the name if you are editing an existing configuration.
- Enter aPartition. The default isCommon. You can also enter a custom path to a partition you have created. Only users with access to a partition can view the objects that the partition contains. If the object resides in theCommonpartition, all users can access it.
- FromDevice, select the associated BIG-IP device.
- ForAuthentication Type, select one of these:
- None- This option requires no authentication when the resource server sends a token introspect request to the OAuth authorization server to get the token validated.
- Secret- For this option, Access generates this secret and you can request that Access regenerate the secret.
- Certificate- This is the default setting. If this is selected,Resource Server Certificate Distinguished Namefield displays.
- ForSecret(if displayed), to regenerate the secret, clickRegenerate.
- IfResource Server Certificate Distinguished Namedisplays, leave it blank or type a name.If you leave it blank, Access accepts any valid client certificate. If you specify a name, Access 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
- ForDescription, type any descriptive text for the resource server.
- ClickSave & Close.
The new resource server displays on the list.
Configure an OAuth profile
You may 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.
- At the top of the screen, selectConfiguration, then on the left side of the screen, click .
- Click the name of an Access group.A new screen displays the group's properties.
- ExpandFederationand click .
- This screen displays the OAuth authorization server resource OAuth profile in the working configuration for the Access group.
- To view the properties of the profile, click its name in the table.
- To locate a profile, search for it by name, otherwise look for it in the Name list.
- To create a new profile, click the Create button.
- To delete a profile select the check box next to the configuration and click the Delete button. You can delete more than one profile by selecting the check box next to multiple profiles.
- ClickCreateor select an existing profile.
- In theNamefield, type a name for the object.
- Enter aPartition. The default isCommon. You can also enter a custom path to a partition you have created. Only users with access to a partition can view the objects that the partition contains. If the object resides in theCommonpartition, all users can access it.
- ForDevice, select the BIG-IP device attached to this application.
- ForApplication Name, type the name of the client application.
- ForWebsite URL, type the URL for the home page of the client application.
- ForWebsite Logo URL, type the URL that refers to the logo for the client application.
- ForContact, type contact information.
- In the Customization Settings for English area, forCaptiontype the application name to display when prompting the user for authorization. (Defaults to text entered in theApplication Namefield.)
- ForDetailed Description, type the description of the application to display when prompting the user for authorization.
- In the Security Settings area, forAuthentication Typeselect one:
- NoneThis is typically used in conjunction with the implicit grant type which does not use a secret or a certificate.
- SecretThe OAuth authorization server (APM) auto-generates a random alphanumerical string, which is cryptographically strong. If you select this option, theSecretfield displays.
- CertificateThe OAuth authorization server a requires a client certificate in OAuth requests. If you select this option, theClient Certificate Distinguished Namefield displays.
- ForClient Certificate Distinguished Name(if displayed) if you specify a certificate distinguished name, then only a valid client certificate with the specified certificate distinguished name will be accepted.
- ForSecret(if displayed), to regenerate the secret clickRegenerate.
- ForScope, move values between theSelectedlist, which specifies scopes that are applicable to the client application and theAvailablelist, which specifies other scopes that are defined on the BIG-IP system.
- ForGrant Type, select one or more:
- Authorization Codewith this type, the client must authenticate with the OAuth authorization server to get a token.
- Implicitwith this type, the client gets a token from the OAuth authorization server without authenticating to it. (Refresh tokens are not available with this grant type.)
- Resource Owner Password Credentialswith this type, the client goes directly to the OAuth authorization server and uses the resource owner credentials to obtain a token.
- ForRedirect URIs(if displayed), specify a list of fully qualified URIs to which the OAuth authorization server can redirect the resource owner’s user agent after authorization is obtained. A redirect URI is used with theAuthorization CodeandImplicitgrant types.
- In the Token Management Configuration area, for theUse Profile Token Management Settingscheck box:
- Select to take token management settings from the OAuth profile that is attached to the virtual server. (Additional token management settings are hidden when you select the check box.)
- Clear to configure token management settings to meet the particular requirements of this client application. (Additional token management settings display when you select the check box.)
- IfUse Profile Token Management Settingsis disabled, you can update these fields:
- ForAuthorization Code Lifetime, type a number.This specifies the number of minutes an authorization code is considered valid.
- ForAccess Token Lifetime, type a number.This specifies the number of minutes an access token is considered valid.
- ForReuse Access Token, select or clear theEnabledcheck box. If cleared, the server generates a new access token. If selected, the server extends the expiry time of the access token associated with the refresh token.For an access token to be reused, theEnabledcheck box must be selected forGenerate Refresh Token.
- ForGenerate Refresh Token, select or clear theEnabledcheck box. If selected, the OAuth authorization server generates a refresh token in addition to the access token for authorization code and resource owner credential grants.
- ForRefresh Token Lifetime, type a number.This specifies the number of minutes that a refresh token is considered valid after it is generated.
- ForReuse Refresh Tokenselect or clear theEnabledcheck box. When cleared and a new access token is obtained, the OAuth authorization server also generates a new refresh token value.
- ForRefresh Token Usage Limit, type a number.This specifies the number of times an access token can be obtained using the refresh token.
- ForJWT Access Token Lifetime, type a number.This specifies the number of minutes a JWT access token is considered valid. In specifying this lifetime, consider that JWT access tokens cannot be revoked.
- ForJWT Generate Refresh Token, selectEnabledso the OAuth authorization server generates a refresh token in addition to the access token for authorization code and resource owner credential grants.
- ForJWT Refresh Token Lifetime, type a number.This specifies the number of minutes a refresh token is considered valid. In specifying this lifetime, consider that JWT refresh tokens cannot be revoked.
- ForAudience, add the audience claim for which the JWT access token is intended. This is a list of values. Each value in this list can be a string, URI, or session variable.
- ForClaim, specify the list of claims that are part of the JWT access token.
- To save your changes, click theSave & Closebutton at the bottom of the screen.
The new OAuth profile will be displayed in the OAuth profile list.
Configure database instance
You may use BIG-IQ to create or edit an OAuth authorization server resource database instances in the working configuration for the Access group.
- At the top of the screen, selectConfiguration, then on the left side of the screen, click .
- Navigate to.
- SelectCreateor click on an existing database instance to configure a resource.
- Type a name for this database. You cannot change the name if you are editing an existing configuration.
- Enter aPartition. The default isCommon. You can also enter a custom path to a partition you have created. Only users with access to a partition can view the objects that the partition contains. If the object resides in theCommonpartition, all users can access it.
- Type an optionalDescription.
- Set the purge schedule. Select theFrequencyand set theSchedule Attime.Purging removes revoked, expired access tokens, refresh tokens, auth code and associated entries from the particular database instance. Purging makes space available to store new data.
- If you are editing or viewing an existing database instance, thePurge Statusshows when the last successful purge occurred.
- If you are editing or viewing an existing database instance, you can clickPurge Nowto purge the database.
- ClickSave & Closeto save your changes.
The new database instance will display in the OAuth database instance list.
About OAuth client and resource server
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
Configure OAuth server object
Follow the procedure below to add or edit an OAuth server object.
- At the top of the screen, selectConfiguration, then on the left side of the screen, click .
- Create or select an Access Group and navigate to.
- SelectCreate.
- Specify a name for the OAuth Server object.
- Set the partition and path, if required.
- Select theModefrom the list.The BIG-IP system can be configured to act as an OAuth client, an OAuth resource server, or both.
- Select theTypeof OAuth Server from the list.A number of types of OAuth server are provided.
- Select anOAuth Providerfrom the list.
- Select theDNS Resolverfrom the list.
- Move any iRules that you want to apply to the traffic between the BIG-IP system and the OAuth provider to theSelectedlist.
- In theToken Validation Intervalbox, specify the number of minutes that the token is valid in a per-request policy subroutine. If you configure a per-request policy subroutine, the subroutine repeats at this interval, or at the token expiry that the provider specifies, whichever is shorter.
- If you selected theModeClient or Client + Resource Server, configure the Client settings.
- In theClient IDbox, specify the client ID that was obtained by registering the application with an external OAuth provider.
- In theClient Secretbox, specify a client secret that might be obtained by registering the application with an external OAuth provider.
- From theClient ServerSSL Profile Namelist, select the name of the server SSL profile for the client to use.
- If you selected theModeResource Server or Client + Resource Server, configure the resource Server settings.
- In theResource Server IDbox, specify the resource server ID that was obtained by registering the application with an external OAuth provider.
- In the Resource Server Secret box, specify a resource server secret that might be obtained by registering the application with an external OAuth provider.
- From the Resource Server's ServerSSL Profile Name list, select the name of the server SSL profile for the resource server to use.
- ClickSave & Close.
The new or edited object will be displayed in the OAuth Server list.
Configure an OAuth provider
From BIG-IQ, you may create or edit an OAuth provider. The settings you configure for an OAuth provider enable APM to obtain opaque tokens or JSON web tokens (JWTs) from an OAuth authorization server that supports them. When an OAuth provider supports discovery from a well-known endpoint, APM can discover JWTs and JSON web key (JWK) configurations from the provider. Without discovery, you can still create token and key configurations manually.
- At the top of the screen, selectConfiguration, then on the left side of the screen, click .
- Create or select an Access group and navigate to.
- SelectCreateor select an existing OAuth provider to edit.
- Type aNamefor this configuration. You cannot change the name if you are editing an exising configuration.
- Type the partition and path information for the OAuth provider.
- From theDevicelist, select a BIG-IP device associated with this OAuth provider.
- Select theTypeof OAuth provider. Some configuration items may not apply, depending on the type you select.
- Select whether to ignore enforcement for an expired authorization server certificate (Ignore Expired Certificate Validation).When you enable this setting, the OAuth authorization server must include an X5C (X.509 Certificate Chain) parameter in its JSON web key (JWK) endpoint response to support this.
- ForTrusted Certificate Authorities, specify the trusted CA bundle for the authorization server. Access Policy Manager uses this CA bundle if you use auto-discovery. This displays whenUse Auto JWTis enabled.
- EnableAllow Self-Signed JWK Config Certificateto allow APM to create a JWK with a self-signed certificate if one is discovered on the provider. This displays whenUse Auto JWTis enabled.
- EnableUse Auto JWTto allow auto-discovery of JSON web token and key configurations from the provider. When enabled, additional fields display. When disabled, theToken Configuration (JWT)field displays.
- In theToken Configurationbox, select a token configuration. This displays whenUse Auto JWTis disabled. Tokens are configured in the menu.
- InAuthentication URItype the URI to use to request authentication from the provider to get an authorization code. The OAuth Client agent uses this endpoint.This URI cannot contain the # character. If discovery returns a URI that contains a fragment, remove the fragment before you save the provider.
- InToken URItype the URI to use to retrieve an access token from the provider. The OAuth Client agent uses this endpoint.This URI cannot contain the # character. If discovery returns a URI that contains a fragment, remove the fragment before you save the provider.
- InToken Validation Scope URISpecifies the URI to use to request that the provider validate a scope. The OAuth Scope agent uses this endpoint to retrieve a list of scopes associated with an opaque access token. The OAuth Client uses this endpoint to validate an opaque access token. Note:This URI cannot contain the # character. If discovery returns a URI that contains a fragment, remove the fragment before you save the provider.
- Select whether toSupport Introspection.Token introspection allows a protected resource to query the authorization server to determine the set of metadata associated with the token.
- InUserinfo Request URIspecify the URI to use to request identity information about a subject. The OAuth Scope agent uses this endpoint.This URI cannot contain the # character. If discovery returns a URI that contains a fragment, remove the fragment before you save the provider.
- If you are using Auto JWT, type theOpenID URIin the box, and set theFrequencywith which the discovery task runs in hour to day intervals.In the OpenID URI box, type a well-known endpoint for auto-discovery of JSON web token (JWT) information. This endpoint must include the phrase/.well-known/openid-configuration. For example,https://f5.com/f5-oauth2/v1/.well-known/openid-configuration.
- To perform discovery, fill in this field, verify the settings forTrusted Certificate AuthoritiesandAllow Self-Signed JWK Config Certificate, and then clickSave. After you save, clickDiscover.The additional endpoints on this screen are populated and theSigning AlgorithmandKey (JWK)fields appear, and are populated. Discovered token and key configurations are stored on the BIG-IP system. This endpoint is also used by the OAuth Client agent if you enable OpenID Connect in the agent.
- ClickSave & Close.
The new OAuth provider will be displayed in the Provider list.
Configure OAuth request
From BIG-IQ, you may create or edit an OAuth request. Configure requests to meet the requirements of your OAuth providers. An OAuth request supports requests for scope permission, scope data, authorization redirect, and tokens. It specifies the HTTP method, parameters, and headers to use for the specific type of request.
- At the top of the screen, selectConfiguration, then on the left side of the screen, click .
- Create or select an Access group, and navigate to.
- SelectCreateor click on an existing OAuth request.
- Type a name for this request. You cannot change the name if you are editing an existing request.
- Type the partition and path information for the OAuth request.
- Type an optional description.
- Select whether to useGETorPOSTfor theHTTP method.
- Specify the request type.
- auth-redirect-request- redirects a user to an Authorization Server. Use it when the OAuth Client agent is configured to use the authorization code grant type.
- openid-userinfo-request- gets user identity information.
- token-request- accesses an authorization server to obtain an access token or to exchange an authorization code for an access token.
- token-refresh-request- refreshes an expired access token.
- validation-scopes-request- used by the OAuth Client agent to get a list of scopes associated with an existing token. The same type of request is used to get scope data for the associated scopes.
- scope-data-request- is to obtain additional information from an authorization server.
- If you specified a scope-data-request, type theURI.
- Add or remove Request Parameters by clicking the plus (+) or X.
- From the list, select theParameter Type.
- access-token- The value for this parameter type is taken from the session variablesession.oauth.client.OAuthServerName.access_token.
- client-id- The value for this parameter type is the Client Id value specified in the OAuth Server object.
- client-secret- The value for this parameter type is the Secret specified in the OAuth Server object.
- resource-server-id- The value for this parameter type is the Resource Server Id specified in the OAuth Server object.
- resource-server-secret- The value for this parameter type is the Secret specified in the OAuth Server object.
- grant-type- The value for this parameter type is the Grant Type specified in the OAuth Client agent.
- scope- The value for this parameter type is the Scope specified in the OAuth Client agent.
- redirect-uri- The value for this parameter type is the Redirection URI specified in the OAuth Client agent.
- custom- Specify a name and a value for a custom parameter.
- response-type- Specify a response type value ofcode,token,id_token, or a combination.
- nonce- Specifies a response type value of a nonce, a unique random string that uniquely identifes the signed request.
- Add or remove Request Headers by clicking the plus (+) or X.
- For each header, in theHeader Namebox type a name.
- In theHeader Valuebox type a header value.
- ClickSave & Close.
About PingAccess profiles and agent properties
BIG-IQ Centralized Management provides support for PingAccess authorization and application and API protection. From BIG-IQ, you can view and manage PingAccess profiles and PingAccess agent properties that have been configured on your managed BIG-IP device.
- To verify or to change the properties of these resources, do so on the BIG-IP system that is linked to the Access group; if you make changes on the BIG-IP system, reimport the device to the BIG-IQ system.