identity/oauth[]

The configuration entries in this section allow the reverse proxy to accept an OAuth bearer token and use the configured OAuth introspection endpoints to validate the token and create an authenticated session.
IBM Security Verify, IBM Security Verify Access and IBM Security Access Manager 9.0.7.0+ provide supported OAuth introspection endpoints.
Multiple introspection endpoints may be different so that different providers can be enabled for different resource servers.

Attributes Format

A JSON data element from the introspection response token which should be included or excluded in the credential as an extended attribute.
The format of the configuration entry is:

[+|-]<json-data>

where:

ElementDescription
+Indicates that this JSON data should be added to the credential.
-Indicates that this JSON data should not be added to the credential.
<json-data>The corresponding JSON data name, which can also contain pattern matching characters (i.e. * ?).

For example the value "-exp" indicates that the expiry time of the token should not be added to the credential.

When an introspection response token is received each JSON data element will be evaluated against each rule in sequence until a match is found.
The corresponding code (+|-) will then be used to determine whether the JSON data will be added to the credential or not.
If the JSON data name does not match a configured rule it will by default be added to the credential.

Properties

NameTypeConstraintsDescription
namestringThe name which is used to identify and describe this endpoint.
restrictedbooleanValues: true or false

Default value: false
A boolean flag which indicates whether this endpoint is restricted to certain resource servers or not. If the endpoint is restricted only those resource servers which specifically mention this endpoint, using the identity/oauth element within the resource server definition, will be allowed to use this endpoint.
introspection_endpointstringThe fully qualified introspection endpoint for the OAuth provider.

For IBM Security Verify, this URL is usually in the format:

https://<verify-hostname>/v1.0/endpoint/default/introspect

For IBM Security Verify Access, this URL is usually in the format:

https://<verify-access-hostname>/<junction>/sps/oauth/oauth20/introspect
client_idstringThe client identity which is used to authenticate to the introspection endpoint.
client_secretstringThe client secret which is used to authenticate to the introspection endpoint. If a client_id field is not configured the secret will be treated as a bearer token, otherwise it will be used in a basic authentication header.
client_id_hdrstringThe name of the HTTP header which contains the client identifier which is used to authenticate to the introspection endpoint. This configuration entry is mutually exclusive with the client_id configuration entry. If the client_id configuration entry is provided this configuration entry will be ignored.
auth_methodstringValues: client_secret_post, client_secret_basic

Default value: client_secret_post
Introspection can be authenticated with BA or Forms. Specify the value client_secret_post to post the client credentials or client_secret_basic to provide the credentials via the Authorization header. If not provided will default to client_secret_post
token_type_hintstringDefault value: access_tokenA hint about the type of the token submitted for introspection.
sslssl
mapped_identitystringDefault value: {sub}A formatted string which is used to construct the credential principal name from elements of the introspection response token. Claims can be added to the identity string, surrounded by {}, for example:
{iss}/{sub} - would construct a principal name like the following:
https://server.example.com/248289761001
proxystringSpecifies the proxy, if any, which is used to reach the OAuth provider. The proxy configuration entry should be in URL format. Eg: http[s]://<address>:<port>
attributesArray of stringA list of JSON data elements from the introspection response token which should be included in or excluded from the credential as an extended attribute. See the Attributes Format table for a description of the expected format.
multi_valued_scopebooleanValues: true or false

Default value: true
By default the OAuth scope attribute is provided as a single space separated string. By enabling this configuration option the scope attribute will instead be converted to a multi-value attribute.
headersArray of headers

identity/oauth[]/ssl

SSL settings for the OAuth introspection connection.

Properties

NameTypeConstraintsDescription
certificateArray of stringIf required, any signer certificates required for the reverse proxy to trust the OAuth provider can be specified here in PEM format.

identity/oauth[]/headers[]

Additional HTTP headers which can be included in the introspection request.

Properties

NameTypeConstraintsDescription
sourcestringValues: text, header, credentialThe source that the HTTP header value should be taken from.
valuestringFor the header or credential type, the name of the HTTP header or credential attribute the value will be taken from.
For the text type, this is the string literal which will be used as the value.
namestringThe name of the HTTP header which will be included in the introspection request.

Example

identity:
  oauth:
    - name: verify_introspection
      restricted: false
      introspection_endpoint: https://ibm-app-gw.verify.ibm.com/v1.0/endpoint/default/introspect
      client_id: 11111111-2222-3333-4444-5a5a5a5a5a5a5a
      client_secret: 1a2b3c4d5e
      auth_method: client_secret_post
      proxy: https://www.testproxy.com:443
      token_type_hint: "access_token"
      ssl:
        certificate:
          - "@www-test-com-ca.pem"
      mapped_identity: "{sub}"
      attributes:
        - "+scope"
        - "+client_id"
        - "+iat"
        - "+exp"
      multi_valued_scope: true
      headers:
        - source: header
          value:  host
          name:   X-Forwarded-For
        - source: credential
          value:  AZN_CRED_NETWORK_ADDRESS_STR
          name:   origin
        - source: text
          value:  green
          name:   X-Deployment-Status