Identity Headers

resource_servers[]/identity_headers

Specifies the configuration information associated with the provision of identity information to the resource server.

Encoding

Type	Description
utf8_bin	Unencoded UTF-8 data. This setting allows data to be transmitted without data loss, and the user does not need to URI-decode the data.
utf8_uri	URI encoded UTF-8 data. All white space and non-ASCII bytes are encoded %XY, where X and Y are hex values (0-F).
lcp_bin	Unencoded local code page data. Data loss can potentially occur with this mode. Use with caution.
lcp_uri	URI encoded local code page data. Any UTF-8 characters that cannot be converted to a local code page are converted to question marks (?).

Basic Authentication Modes

Mode	Description
filter	The Authorization header, if provided by the client, will be removed before the resource request is forwarded to the resource server. This is the default option if no option is specified.
supply	A new Authorization header will be created by the gateway and forwarded to the resource server. The Basic Authentication information contained in the header will consist of the name of the authenticated user, along with a static password. Use the `password` YAML configuration entry to set the static password.
ignore	The Authorization header, if provided by the client, will be forwarded to the resource server unchanged.
service	A new Authorization header will be constructed using a username and password retrieved from a configured credential service. See "services/credential" for more information about configuring a credential service. The YAML entries "service" and "resource_name" must be specified when using this mode.

Properties

Name	Type	Constraints	Description
kerberos	kerberos
encoding	string	Values: `utf8_bin`, `utf8_uri`, `lcp_bin`, `lcp_uri` Default value: `utf8_uri`	The encoding type to use for any identity headers passed to the resource server. See the Encoding table for a description of the available options.
basic_auth	basic_auth
ip_address	boolean	Values: `true` or `false` Default value: `false`	A boolean flag indicating whether or not to provide the client IP address as a HTTP header in requests forwarded to the resource server. The IP address will be added in the `iv-remote-address` HTTP header.
iv_creds	boolean	Values: `true` or `false` Default value: `false`	A boolean flag indicating whether or not to provide an ASN.1 encoded version of the credential as a HTTP header in requests forwarded to the resource server. The credential will be added in the `iv-creds` HTTP header.
attributes	Array of attributes
session_cookie	boolean	Values: `true` or `false` Default value: `false`	A boolean flag indicating whether or not to forward the reverse proxy cookie to the resource server. The name of this cookie is configured in the `server/session/cookie_name` entry.
jwt	jwt
ltpa	ltpa

resource_servers[]/identity_headers/kerberos

Specifies the information associated with Kerberos tokens. Note that the instance level services/kerberos entry must be configured before enabling Kerberos tokens for any resource server.

Properties

Name	Type	Constraints	Description
resource_spn	string		The the service principal name of the target when requesting a Kerberos token. The service principal name can be determined by executing the Microsoft utility `setspn` (that is, `setspn -L user`, where `user` is the identity of the back-end web servers account).
always_send_tokens	boolean	Values: `true` or `false` Default value: `false`	Indicates whether IAG sends a security token for every HTTP request or whether IAG waits for a 401 response before it adds the security token.
user_identity	user_identity

resource_servers[]/identity_headers/kerberos/user_identity

Configures the UPN used by the gateway when performing Kerberos constrained delegation.

Properties

Name	Type	Constraints	Description
username	string		An administrator can overwrite the UPN or sections of the UPN for Kerberos constrained delegation users with this entry. The replacement information can be either plain text or names of credential attributes that store the required information. If you specify plain text, the text is directly copied into the UPN sections. If you specify names of credential attributes by surrounding the text with braces eg. `{preferred_username}`, the replacement text is fetched from the value of the corresponding credential attribute.
realm	string		The realm to append to the client credential for Kerberos constrained delegation. The realm value must be uppercase. Any input data that is not uppercase is automatically converted to uppercase. The realm must also be added as a realm to the Kerberos configuration in the Services module.

resource_servers[]/identity_headers/basic_auth

Controls the basic authentication information, contained within the Authorization header, that is passed to the resource server.
See the Basic Authentican Modes table for a description of the available modes.
Note that some modes require additional parameters:

If the mode is service, the following entries must also be
provided:
- service
- resource_name
If the mode is supply, the following entry must also be
provided:
- password

Properties

Name	Type	Constraints	Description
mode	string	Values: `filter`, `ignore`, `supply`, `service` Default value: `filter`	The mode of handling the basic authentication headers.
password	string		If the mode entry is set to `supply` then the password must be provided here.
service	string		If the mode entry is set to `service` then the credential service name must be provided here.
resource_name	string		Used only when `mode` is `service`. The name of the resource which will be passed to the credential service when retrieving the username/password.

resource_servers[]/identity_headers/attributes[]

Specifies a list of attributes from the authenticated credential which will be inserted into the HTTP requests sent to the resource server.

Properties

Name	Type	Constraints	Description
attribute	string		The name of the credential attribute.
header	string		The name of the HTTP header which will contain the credential attribute. If no name is supplied the name of the credential attribute itself will be used.

resource_servers[]/identity_headers/jwt

Specifies the information associated with the generation of JSON Web tokens (JWT).

Properties

Name	Type	Constraints	Description
certificate	Array of string		PEM based personal certificate files which will be used to sign the JWT. These certificate files should include the private key, a certificate signed with the private key, and the signer certificate or signer certificate chain (if required).
hdr_name	string	Default value: `jwt`	The name of the HTTP header which will contain the generated JWT.
claims	Array of claims

resource_servers[]/identity_headers/jwt/claims[]

The claims which are to be added to the JWT. The claim can either be obtained from a literal string, or from the value of a credential attribute.

Properties

Name	Type	Constraints	Description
name	string		The name of the claim which is to be added to the JWT. If the name is not specified, and the claim value is obtained from an attribute name, the name of the claim will match the name of the attribute. Nested objects can be specified, separating the name of each object field with a . (dot). If the name of a field itself embeds a dot it should be escaped with a backslash character.
text	string		The literal text to be used as the claim value. If both a `text` value and an `attr` value is specified the `text` value will be used. If an array is supplied in the configuration the claim will be added to the JWT as a JSON array.
type	string	Values: `string`, `bool`, `int` Default value: `string`	The type of textual data which is being provided. This will control the JSON type which is used in the JWT. Please note that this field is only valid if a `text` value has been specified and will be ignored if an `attr` value is specified.
attr	string		The name of the credential attribute from which the claim value will be obtained. The `*` and `?` pattern matching characters can be used to match multiple attributes, however the pattern matching characters will be ignored if a claim `name` is specified. If both a `text` value and an `attr` value is specified the `text` value will be used.

resource_servers[]/identity_headers/ltpa

Specifies the information associated with the generation of an LTPA token.

Properties

Name	Type	Constraints	Description
key	string		The key which is used to protect the LTPA token. This key must be in the correct proprietary format for an LTPA key.
key_password	string		The password which is used to access the LTPA key.
version	number	Minimum: `1` Maximum: `2` Default value: `1`	The version of the LTPA token to create. Valid versions are 1 or 2, with a default of 1.

Example

resource_servers:
  - path: "/example"
    # ...
    identity_headers:
      encoding: utf8_uri
      basic_auth:
        mode: filter
      ip_address: true
      attributes:
        - attribute: emailAddress
          header: email_header
        - attribute: AUTHENTICATION_LEVEL
          header: auth_level
      ltpa:
        key: "@ltpa_keyfile"
        key_password: passw0rd
        version: 2
      session_cookie: true
      jwt:
        certificate:
          - "@jwt.crt"
          - "@jwt.key"
        hdr_name: jwt
        claims:
          - text: www.ibm.com
            name: iss
          - attr: AZN_CRED_PRINCIPAL_NAME
            name: sub
          - attr: AZN_*
  - path: /ibmiis
    connection_type: "tcp"
    servers:
      - host: test.ibm.com
        port: 80
    identity_headers:
      kerberos:
        resource_spn: HTTP/[email protected]
        always_send_tokens: true
        user_identity:
          username: "{preferred_username}"