IBM Security Identity and Access: Developer PortalSearchSite map
Home / IBM Application Gateway / References / Yaml / Identity Headers

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.

Identity Headers

Description

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 Auth

Type 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

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

Name Type Constraints Description
iv_creds boolean Values: true,false
Default: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.
ltpa LTPA Object
encoding string Values: utf8_bin,utf8_uri,lcp_bin,lcp_uri
Default: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.
kerberos KERBEROS Object
jwt JWT Object
basic_auth BASIC_AUTH Object
session_cookie boolean Values: true,false
Default: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.
attributes array[ATTRIBUTES Object]
ip_address boolean Values: true,false
Default: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.

LTPA Object

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

Name Type Constraints Description
version number Minimum:1
Maximum:2
Default:1		 The version of the LTPA token to create. Valid versions are 1 or 2, with a default of 1.
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.

KERBEROS Object

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.

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,false
Default: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 Object

USER_IDENTITY Object

User Identity description.

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.

JWT Object

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

Name Type Constraints Description
claims array[CLAIMS Object]
hdr_name string Default:jwt The name of the HTTP header which will contain the generated JWT.
certificate array[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).

CLAIMS Object

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.

Name Type Constraints Description
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: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.
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.
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.

BASIC_AUTH Object

Controls the basic authentication information, contained within the Authorization header, that is passed to the resource server. See the Basic Auth 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
Name Type Constraints Description
password string If the mode entry is set to 'supply' then the password must be provided here.
mode string Values: filter,ignore,supply,service
Default:filter		 The mode of handling the basic authentication headers.
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.

ATTRIBUTES Object

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

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.

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.cer"
                       - "@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/web.test.ibm.com@IBM.COM
                   always_send_tokens: true
                   user_identity: 
                       username: "{preferred_username}"