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.
IBM Security Verify OIDC
Description
The configuration entries in this section allow the reverse proxy to act as an OIDC relying party to IBM Security Verify.
Notice of Deprecation
This identity module is no longer preferred and will be removed in a future version. Use the OIDC identity module.
When using the OIDC identity module, 'discovery_endpoint' is given rather than 'hostname'. The format for an IBM Security Verify 'discovery_endpoint' is:
https://<hostname>/oidc/endpoint/default/.well-known/openid-configuration
For example, refer to the IBM Security Verify OIDC configuration below:
identity:
ci_oidc:
hostname: www.test.com
client_id: 11111111-2222-3333-4444-5a5a5a5a5a5a5a
...The equivalent OIDC configuration is:
identity:
oidc:
discovery_endpoint: https://www.test.com/oidc/endpoint/default/.well-known/openid-configuration
client_id: 11111111-2222-3333-4444-5a5a5a5a5a5a5a
...Response Type Values
| Name | Description |
|---|---|
| code | The authorization code flow will be used to retrieve both an access token and identity token. |
| id_token | The implicit flow will be used to retrieve the identity token. |
| id_token token | The implicit flow will be used to retrieve both an access token and identity token. |
Bearer Token Attrs Format
A JSON data element from the bearer token response 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 "-access_token" indicates that the access_token should not be added to the credential.
When a bearer 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.
ID Token Attrs Format
A claim from the ID token response which should be included or excluded in the credential as an extended attribute. The format of the configuration entry is:
[+|-]<claim>where:
| Element | Description |
|---|---|
| + | Indicates that this claim should be added to the credential. |
| - | Indicates that this claim should not be added to the credential. |
| <claim> | The corresponding claim name, which can also contain pattern matching characters (i.e. * ?). |
For example the value "-email" indicates that the email claim should not be added to the credential.
When an ID token is received each claim will be evaluated against each rule in sequence until a match is found. The corresponding code (+|-) will then be used to determine whether the claim will be added to the credential or not. If the claim 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 |
|---|---|---|---|
| scopes | array[string] | Values: profile,email,address,phone | Any scopes to be sent in the authentication request in addition to the 'openid' scope. |
| mapped_identity | string | Default:{sub} | A formatted string which is used to construct the credential principal name from elements of the ID 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 |
| bearer_token_attrs | array[string] | A list of JSON data elements from the bearer token response which should be included or excluded in the credential as an extended attribute. See the Bearer Token Attrs Format table for a description of the expected format. |
|
| hostname | string | The fully qualified host name of the IBM Security Verify tenant. |
|
| redirect_uri_host | string | This is the host which is used in the redirect URI registered with the OIDC OP. If no redirect URI host is configured the host header from the request will be used. The format of the redirect URI will be: http[s]://<host>/pkmsoidc. |
|
| response_type | string | Values: code,id_token,id_token token Default:code |
The required response type for authentication responses. See the Response Type Values table for a description of the available values. |
| client_id | string | The client identity registered with IBM Security Verify. |
|
| client_secret | string | The client secret registered with IBM Security Verify. |
|
| allowed_query_args | array[string] | Additional query string arguments can be provided to the authentication kick-off URL which will in turn be appended to the corresponding authentication request. This entry is used to define a list of allowed query string arguments. Any other arguments passed to the kick-off URL will be ignored. |
|
| id_token_attrs | array[string] | A list of claims from the ID token response which should be included or excluded in the credential as an extended attribute. See the ID Token Attrs Format table for a description of the expected format. |
|
| response_mode | string | Values: query,fragment,form_post | The required response mode for authentication responses. If no response mode is configured the response mode parameter will not be included in the authentication request. |
| proxy | string | Specifies the proxy, if any, which is used to reach IBM Security Verify. The proxy configuration entry should be in URL format. Eg: http[s]://<address>:<port> |
Example
identity:
ci_oidc:
hostname: www.test.com
client_id: 11111111-2222-3333-4444-5a5a5a5a5a5a5a
client_secret: 1a2b3c4d5e
mapped_identity: "{sub}"
redirect_uri_host: www.test2.com
response_type: code
response_mode: query
proxy: https://www.testproxy.com:443
scopes:
- profile
- email
allowed_query_args:
- "oidc_test=value"
bearer_token_attrs:
- "-access_token"
id_token_attrs:
- "-email"