Identity Headers

resource_servers[]/identity_headers

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

Encoding

TypeDescription
utf8_binUnencoded 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_uriURI encoded UTF-8 data. All white space and non-ASCII bytes are encoded %XY, where X and Y are hex values (0-F).
lcp_binUnencoded local code page data. Data loss can potentially occur with this mode. Use with caution.
lcp_uriURI 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

ModeDescription
filterThe 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.
supplyA 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.
ignoreThe Authorization header, if provided by the client, will be forwarded to the resource server unchanged.
serviceA 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

NameTypeConstraintsDescription
kerberoskerberos
encodingstringValues: 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_authbasic_auth
ip_addressbooleanValues: 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_credsbooleanValues: 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.
attributesArray of attributes
session_cookiebooleanValues: 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.
jwtjwt
ltpaltpa

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

NameTypeConstraintsDescription
resource_spnstringThe 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_tokensbooleanValues: 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_identityuser_identity

resource_servers[]/identity_headers/kerberos/user_identity

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

Properties

NameTypeConstraintsDescription
usernamestringAn 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.
realmstringThe 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

NameTypeConstraintsDescription
modestringValues: filter, ignore, supply, service

Default value: filter
The mode of handling the basic authentication headers.
passwordstringIf the mode entry is set to supply then the password must be provided here.
servicestringIf the mode entry is set to service then the credential service name must be provided here.
resource_namestringUsed 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

NameTypeConstraintsDescription
attributestringThe name of the credential attribute.
headerstringThe 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

NameTypeConstraintsDescription
certificateArray of stringPEM 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_namestringDefault value: jwtThe name of the HTTP header which will contain the generated JWT.
claimsArray 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

NameTypeConstraintsDescription
namestringThe 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.
textstringThe 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.
typestringValues: 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.
attrstringThe 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

NameTypeConstraintsDescription
keystringThe key which is used to protect the LTPA token. This key must be in the correct proprietary format for an LTPA key.
key_passwordstringThe password which is used to access the LTPA key.
versionnumberMinimum: 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}"