Basics

With HTTP Header/ Value Access Rules you can define whether a request using an API Token for authentication should be allowed or denied based on the presence of an HTTP request header and optionally a value it has.

Example

The following curl command sends both the basic authentication header containing an API token and a header called REQ-ORIGIN with a value of 637623AhFGX.

curl --location --request GET 'https://jira.company.com/rest/api/2/myself' \
--header 'Authorization: Basic YWRtaW46dnRNZU5IbkpiZE5sWWgxcFU0NzZORE0zWHBEalltREtxVWo4amU=' \
--header 'REQ-ORIGIN: 637623AhFGX'

Imagine having created a token with a rule that only allows authentication if that header and value are present. That rule could also allow (or deny) requests if the value matches a regular expression.

An HTTP header name should not contain underscores, because these are mostly filtered by reverse proxies or similar components.
Also, the use of the X- prefix for custom headers is not officially recommended anymore.

Rule Types

Allow Rules

Rules that define whether the authentication request will be allowed or not.

• if a rule doesn't carry a value, the presence of the header is enough to allow the request
• if there is more than one rule assigned to the token, at least one of them needs to match during authentication in order to allow it
• header name checks are not case sensitive, so it doesn't matter if you setup rules with lower, mixed or uppercase header names

Example

A rule (1) that expects the value for the header REQ-ORIGIN to be a 3-digit number followed by the string XFEZ and a one-digit number again.
The rule tester (2) allows you to see which rule matches your test input. The request would be allowed then, provided that there are no deny rules that match.

Deny Rules

Rules that define whether the authentication request will be denied or not.

• if a rule doesn't carry a value, the presence of the header is enough to deny the request
• a match will deny the request, even if it would be allowed by allow-rules
• header name checks are not case sensitive, so it doesn't matter if you setup rules with lower, mixed or uppercase header names

Example

Very similar to the allow-rule example, this rule expects the value for the header REQ-ORIGIN to be a 3-digit number followed by the string XFEZ and a one-digit number again.
The rule tester allows you to see which rule matches your test input. The request would be denied then, even if other allow rules would match.

Review Rules

If you need to see which rules have been assigned to your tokens, you can use the details button in the actions column in your token table.
The same is also available in the Token Manager view if you have permission to create tokens on behalf of other users.

In the above example, a header with the name REQ-ORIGIN and value 1 is required to allow the authentication request.

Caveats

Headers With Multiple Values

You are expected to send a header in your request only once, with a single value.
Below are two examples in Curl, the first one is containing the same header with different values. 

Wrong

curl --location --request GET 'https://jira.company.com/rest/api/2/myself' \
--header 'REQ-ORIGIN: someValue' \
--header 'REQ-ORIGIN: anotherValue' \
--header 'Authorization: Bearer someApiTokenWithHeaderValueAccessRulesHere'

Right

curl --location --request GET 'https://jira.company.com/rest/api/2/myself' \
--header 'REQ-ORIGIN: anotherValue' \
--header 'Authorization: Bearer someApiTokenWithHeaderValueAccessRulesHere'

Admins can see a warning about this in the log files, which might be helpful for troubleshooting.

2022-07-25 12:22:45,063+0000 http-nio-8080-exec-16 WARN anonymous 742x490x1 - 11.26.52.129,104.110.0.12 /rest/api/2/myself [d.r.a.platform.auth.ApiTokenAuthSharedBase] Found HTTP header 'req-origin' with multiple values that is referenced in header/ value access rules. Please only send each header once to avoid errors during rule evaluation.