OAuth

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:

Element	Description
+	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

Name	Type	Constraints	Description
name	string		The name which is used to identify and describe this endpoint.
restricted	boolean	Values: `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_endpoint	string		The 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_id	string		The client identity which is used to authenticate to the introspection endpoint.
client_secret	string		The 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_hdr	string		The 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_method	string	Values: `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_hint	string	Default value: `access_token`	A hint about the type of the token submitted for introspection.
ssl	ssl
mapped_identity	string	Default 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
proxy	string		Specifies 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>`
attributes	Array of string		A 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_scope	boolean	Values: `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.
headers	Array of headers

identity/oauth[]/ssl

SSL settings for the OAuth introspection connection.

Properties

Name	Type	Constraints	Description
certificate	Array of string		If 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

Name	Type	Constraints	Description
source	string	Values: `text`, `header`, `credential`	The source that the HTTP header value should be taken from.
value	string		For 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.
name	string		The 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