Home / IBM Application Gateway / References / Yaml / Oauth

OAuth Introspection

Description

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

The following table(s) describe the configuration properties for this component:

Name	Type	Constraints	Description
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.
name	string		The name which is used to identify and describe this endpoint.
restricted	boolean	Values: true,false Default: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.
ssl	SSL Object
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
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>
client_id	string		The client identity which is used to authenticate to the introspection endpoint.
token_type_hint	string	Default:access_token	A hint about the type of the token submitted for introspection.
multi_valued_scope	boolean	Values: true,false Default: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.
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.
attributes	array[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.
auth_method	string	Values: client_secret_post,client_secret_basic Default: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'
mapped_identity	string	Default:{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

SSL Object

SSL settings for the OAuth introspection connection.

Name	Type	Constraints	Description
certificate	array[string]		If required, any signer certificates required for the reverse proxy to trust the OAuth provider can be specified here in PEM format.

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: post
           proxy: https://www.testproxy.com:443
           token_type_hint: "access_token"
           ssl:
             certificate: 
                 - "@www-test-com-ca.cer"
           mapped_identity: "{sub}"
           attributes:
             - "+scope"
             - "+client_id"
             - "+iat"
             - "+exp"
           multi_valued_scope: true