We Have Moved
The IBM Application Gateway has a new home - docs.verify.ibm.com/gateway
The documentation on this site will no longer be maintained after v21.02, please update your bookmarks.
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