How to configure OAuth provider settings for a third-party OAuth token
provider.
About this task
When the
Token validation requirement property is
200 OK +
active:true, validation requirements are
strictly checked against response scopes in the response body. When the OAuth security requirement
defines scopes that are not a subset of response scopes, the request is denied unless advanced scope
checks are enabled.
- When the scope value in the OAuth security requirement is
scope1
and the
response scope value is scope1 scope2
, validation passes the check.
- When the scope value in the OAuth security requirement is
scope1 scope2
and the
response scope value is scope1
, validation fails the check. In this situation, you
can modify the configuration in either of the following ways to pass the validation check.
- Delete the scope value from the OAuth security requirement. To manage the scope value, use the
Allowed scopes property for an OAuth security requirement. For more
information, see Configuring an OAuth security requirement.
- Enable advanced scope validation. To enable advanced scope validation, use the Enable
advanced scope validation property.
Procedure
- In the search field, enter oauth.
- From the search results, click OAuth provider
settings.
- Click Add.
Define the general settings.
- Define the basic properties - Name, administrative state, and
comments.
- From the Provider type list, select
Third-party.
- In the Allowed scopes field, specify the scopes that
the access token is valid to access.
These scopes are a superset of defined scopes for
the OAuth security requirement and the OAuth security definition. To specify multiple scopes, use a
space between each scope. The order of scopes does not matter.
- From the Supported grant types list, select the
supported methods to grant authorization.
- From the Supported client types list, select the
client types that can obtain access tokens.
Define settings for the third-party provider.
- In the Authorization endpoint field,
specify the URL to the authorization endpoint.
- In the Token endpoint field, specify the
URL to the token endpoint.
- In the Introspection endpoint field,
specify the URL to the introspection endpoint. The value can include one or more runtime context
variables in the
$(variable)
format.
- From the TLS client profile list, select the
name of the TLS client profile to secure connections to the introspection endpoint.
- From the Introspection endpoint
security list, select how to secure connections to the introspection
endpoint.
- When Basic authentication header is set to
secure connections to the introspection endpoint. When both defined, authentication uses the header
method.
- Username and password
- Specify the username and password alias for basic authentication.
- Header
- Specify the header name to send the encoded or nonencoded authentication string such as
x-introspect-basic-authorization-header
.
- In the Custom header pattern field,
specify the name pattern of the headers to use for sending additional information.
- From the Token validation
requirement list, select the requirement to indicate when a token is valid.
- 200 OK
- Connect successfully to the third-party endpoint.
- 200 OK + active:true
- Connect successfully to the third-party endpoint and the access token is valid.
- From the Cache type list, select the cache
type to control whether and how to cache positive responses. When the cache type is TTL, specify the
duration in seconds to keep responses in the cache in the Time to live field,
The default value is 900.
- Set the Retain Authorization
header property to determine whether to retain the
Authorization
header
for a bearer token. The default behavior is to remove this header.
- Enable the Enable debug headers property to enable
debugging.
- Optional: To enable and define advanced scope validation,
click the Advanced scope tab.
- Enable the Enable advanced scope validation to enable advanced
scope validation.
- Set the Use URL for API security definition property to control
whether to use the URL from the API security OAuth or from the OAuth provider
settings.
- In the Advanced scope URL field, specify the URL to send scope
information for validation. This external endpoint is where the specified scope is verified. The
value can include one or more runtime context variables in the
$(variable)
format.
- From the TLS profile to access metadata URL list, select the
TLS client profile to secure connections to the advanced scope endpoint.
- Enable the Enable advanced scope endpoint security property to
enable security on the advanced scope endpoint.
- When security is enabled, select how to secure connections to the advanced scope
endpoint from the Advanced scope endpoint security list.
- When Basic authentication header is set to secure connections
to the advanced scope endpoint. When both defined, authentication uses the header method.
- Username and password
- Specify the username and password alias for basic authentication.
- Header
- Specify the header name to send the encoded or nonencoded authentication string such as
x-basic-authorization-header
.
- In the Request headers field, specify the custom headers to
send with the advanced scope validation request. Use a regular expression match to include headers
from the initial request.
- In the Request context variables field, specify the custom
context variables to save headers from the advanced scope validation request. Use a regular
expression to include headers from the advanced scope endpoint response.
- Click Apply to save changes to the running
configuration.
- Click Save to save changes to the persisted
configuration.
What to do next
- To apply the OAuth provider settings to protect an API or operation, create an API security
OAuth definition from the OAuth provider settings configuration.
- To apply the OAuth provider settings for OAuth processing, create an OAuth assembly action that
references the OAuth provider settings configuration.