Single sign-on

Single sign-on (OpenID Connect)

On this page

This page applies to:

  • HAProxy Enterprise 3.2r1 and newer

HAProxy Enterprise integrates with OpenID providers, such as Microsoft Entra ID, to require users to sign in before they can access your application. The OpenID provider manages the user credentials, which means you don’t need to implement a sign-in mechanism yourself or store credentials on your own servers. The user will be directed to the OpenID provider’s sign-in page when they try to access your application. In this setup, HAProxy Enterprise relies on access tokens issued by the OpenID provider, so it’s referred to as a relying party.

The module uses the Authorization Code Flow to request an access token from the OpenID provider. It also supports refresh tokens.

Install and configure the module Jump to heading

Perform these steps on the load balancer node to install the OpenID Connect module:

  1. Install the OpenID Connect module according to your platform.

    Install the OpenID Connect module
    nix
    sudo apt-get install hapee-3.2r1-lb-oidc-sso
    nix
    sudo apt-get install hapee-3.2r1-lb-oidc-sso
    nix
    sudo yum install hapee-3.2r1-lb-oidc-sso
    nix
    sudo yum install hapee-3.2r1-lb-oidc-sso
    nix
    sudo zypper install hapee-3.2r1-lb-oidc-sso
    nix
    sudo zypper install hapee-3.2r1-lb-oidc-sso
    nix
    sudo pkg install hapee-3.2r1-lb-oidc-sso
    nix
    sudo pkg install hapee-3.2r1-lb-oidc-sso

  2. In the global section of your configuration, load the module via the module-load directive. Also, add the httpclient.resolvers.prefer ipv4 directive to force HAProxy Enterprise to connect to the OpenID provider using an IPv4 address.

    haproxy
    global
      ...
      module-load hapee-lb-oidc-sso.so
      httpclient.resolvers.prefer ipv4
    haproxy
    global
      ...
      module-load hapee-lb-oidc-sso.so
      httpclient.resolvers.prefer ipv4

  3. Add an oidc-sso section to define OpenID Connect settings. You’ll add settings depending on your OpenID provider. See Providers.

    haproxy
    oidc-sso my-oidc-settings
      # provider settings...
    haproxy
    oidc-sso my-oidc-settings
      # provider settings...

  4. Update your frontend to use the oidc-sso section.

    • Configure HTTPS, since OpenID providers typically require it for the URL they redirect back to.
    • Add an http-request oidc-sso directive that sets the name of the oidc-sso section you want to use in this frontend. To trigger authentication for only some users, such as those trying to reach a specific web application, define an if condition as shown in the example.
    • Add an http-response oidc-sso directive to set the OpenID Connect cookie that keeps the user logged in.
    haproxy
    frontend example
       bind :443 ssl crt /certs/site.pem
       http-request oidc-sso my-oidc-settings if { hdr(host) -i example.com }
       http-response oidc-sso my-oidc-settings
       ...
    haproxy
    frontend example
       bind :443 ssl crt /certs/site.pem
       http-request oidc-sso my-oidc-settings if { hdr(host) -i example.com }
       http-response oidc-sso my-oidc-settings
       ...

Providers Jump to heading

In this section, we’ll describe settings needed for various OpenID providers. Other providers should also work, and these serve as examples.

Microsoft Entra ID Jump to heading

To configure Microsoft Entra ID as your OpenID provider:

  1. Create a public key certificate and private key, which HAProxy Enterprise will use to authenticate to Microsoft Entra ID. For example, you can use the following command to create privateKey.key and publicKey.crt.

    nix
    openssl req -x509 \
      -sha256 \
      -nodes \
      -days 730 \
      -newkey rsa:2048 \
      -keyout privateKey.key \
      -out publicKey.crt
    nix
    openssl req -x509 \
      -sha256 \
      -nodes \
      -days 730 \
      -newkey rsa:2048 \
      -keyout privateKey.key \
      -out publicKey.crt

  2. Sign in to the Microsoft Azure portal.

  3. Search for and select Microsoft Entra ID. If you manage multiple tenants, choose Manage tenants, and then select the tenant with which you would like to enable SSO sign-in.

  4. Go to Manage > App registration in the left-hand menu and choose New registration.

  5. On the Register an application screen, set:

    • a name for the application for which you’re enabling single sign-on, such as Example Application.
    • supported account types to Accounts in this organizational directory only.
    • the redirect URI’s platform to Web.
    • the redirect URI to the address where your frontend is listening with the path you’d like to use as the callback, such as /callback. For example, set https://example.com/callback. When HAProxy Enterprise redirects a user to the Microsoft Entra ID sign-in page, it includes its redirect URI with the request, which must match the address you set here. Be sure to use HTTPS.

  6. Upload your public key certificate to Microsoft Entra ID.

    • From your enterprise application’s Overview screen, click Single sign-on, then Go to application.
    • Go to Manage > Certificates and secrets.
    • On the Certificates tab, upload your public key certificate, publicKey.crt.

  7. From the Overview screen, copy the Application (client) ID.

  8. From the Overview screen, select Endpoints. Copy the value of the Authority URL.

  9. From your Microsoft Entra ID tenant’s Overview page, go to the Users screen. Create users to give them access to your application.

  10. Edit your HAProxy Enterprise configuration’s oidc-sso section. Add directives for using Microsoft Entra ID as the OpenID provider. For example:

    haproxy
    oidc-sso my-oidc-settings
      issuer https://login.microsoftonline.com/abcd1234-defg-1234-abcd-efgi53456789/v2.0
      client-id 881c9113-c924-4006-b236-0f3a3e57fe3c
      jwt-alg RS256
      crt /path/to/certificate.crt
      key /path/to/privateKey.key
      redirect-uri https://example.com/callback
      logout-uri https://example.com/logout
      post-logout-redirect-uri https://example.com/logout/reply
      cookie domain example.com
      cookie-sec-1 mysecret
    haproxy
    oidc-sso my-oidc-settings
      issuer https://login.microsoftonline.com/abcd1234-defg-1234-abcd-efgi53456789/v2.0
      client-id 881c9113-c924-4006-b236-0f3a3e57fe3c
      jwt-alg RS256
      crt /path/to/certificate.crt
      key /path/to/privateKey.key
      redirect-uri https://example.com/callback
      logout-uri https://example.com/logout
      post-logout-redirect-uri https://example.com/logout/reply
      cookie domain example.com
      cookie-sec-1 mysecret
    • issuer is the Authority URL endpoint with /v2.0 appended to the end.
    • client-id is the Application (client) ID.
    • jwt-alg is the signing algorithm used to sign the JWT (JSON Web Token) that HAProxy Enterprise sends when requesting an access token. Microsoft Entra ID supports RS256, RS384, RS512, PS256, PS384, and PS512.
    • crt is the path to your public key certificate. You uploaded the certificate to Microsoft Entra ID already, so HAProxy Enterprise only sends the certificate’s thumbprint with the request so that Microsoft Entra ID knows which certificate to use when verifying the signature of the JWT.
    • key is the path to your private key. HAProxy Enterprise uses this to sign the JWT it sends to Microsoft Entra ID to authenticate itself when requesting an access token.
    • redirect-uri is your callback URI.
    • logout-uri is the URI that clients will request to intiate a logout process.
    • post-logout-redirect-uri is the URI to which Microsoft Entra ID will redirect the client after logout. This gives HAProxy Enterprise a chance to clear its cookie.
    • cookie configures properties of the HTTP cookie that keeps the client logged in. At a minimum, set its domain field, but you can also set other fields including secure, httponly, and maxlife.
    • cookie-sec-1 sets a secret with which to cipher the cookie.

  11. Restart HAProxy Enterprise.

    Restart HAProxy Enterprise
    nix
    sudo systemctl restart hapee-3.2r1-lb
    nix
    sudo systemctl restart hapee-3.2r1-lb

    Users that access your application will now be prompted to sign in with their Microsoft Entra ID credentials.

    Test in a private browser tab

    To ensure that your OpenID provider administrator account doesn’t clash with test user accounts you try to sign in with during testing, it’s best to do your testing in a private browser tab.

Okta Jump to heading

To configure Okta as your OpenID provider:

  1. Sign in to your Okta org account or try out Okta with the Integrator Free Plan.

  2. In the Okta Admin Console, select Applications > Create App Integration.

  3. On the Create a new app integration screen, set:

    • Sign-in method to OIDC - OpenID Connect.
    • Application type to Web Application.
    • a name for your application, such as Example Application.
    • Grant Type to Authorization Code and Refresh Token.
    • Sign-in redirect URIs to the redirect URI to the address where your frontend is listening with the path you’d like to use as the callback, such as /callback. For example, set https://example.com/callback. When HAProxy Enterprise redirects a user to the Okta sign-in page, it includes its redirect URI with the request, which must match the address you set here. Be sure to use HTTPS.
    • Sign-out redirect URIs to the logout URI. For example, set https://example.local/logout.
    • Assignments to the group of users who should have access to your application. For example, you can set Allow everyone in your organization to access.

  4. Save your settings. Go to General > Client Credentials and click Edit.

    • Set Client authentication to Public key / Private key.
    • Click Add key to generate a new key pair and copy the private key in the PEM format.
    • Click Save.

  5. Copy these values for later use:

    • Your Okta issuer value, which you can get by clicking your account name in the upper right and copying the okta.com domain, such as integrator-12345678.okta.com.
    • Your client ID from General > Client Credentials.

  6. Go to Directory > People. Create users to give them access to your application.

  7. Edit your HAProxy Enterprise configuration’s oidc-sso section. Add directives for using Okta as the OpenID provider. For example:

    haproxy
    oidc-sso my-oidc-settings
      issuer https://integrator-12345678.okta.com
      client-id 0oavb6ssr6tR896k2697
      jwt-alg RS256
      key /path/to/privateKey.key
      redirect-uri https://example.local/callback
      logout-uri https://example.local/logout
      post-logout-redirect-uri https://example.local/logout/reply
      cookie domain example.local
      cookie-sec-1 mysecret
      no-referer-check
    haproxy
    oidc-sso my-oidc-settings
      issuer https://integrator-12345678.okta.com
      client-id 0oavb6ssr6tR896k2697
      jwt-alg RS256
      key /path/to/privateKey.key
      redirect-uri https://example.local/callback
      logout-uri https://example.local/logout
      post-logout-redirect-uri https://example.local/logout/reply
      cookie domain example.local
      cookie-sec-1 mysecret
      no-referer-check
    • issuer is your Okta domain URL.
    • client-id is your client ID.
    • jwt-alg is the signing algorithm used to sign the JWT that HAProxy Enterprise sends when requesting an access token. Okta supports HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512. When using an HS algorithm, you’ll configure a client secret in the Okta Admin Console. Then, you’ll set mac-secret to the client secret and won’t use key or crt.
    • key is the path to your private key. HAProxy Enterprise uses this to sign the JWT it sends to Okta to authenticate itself when requesting an access token.
    • redirect-uri is your callback URI.
    • logout-uri is the URI that clients will request to intiate a logout process.
    • post-logout-redirect-uri is the URI to which Okta will redirect the client after logout. This gives HAProxy Enterprise a chance to clear its cookie.
    • cookie configures properties of the HTTP cookie that keeps the client logged in. At a minimum, set its domain field, but you can also set other fields including secure, httponly, and maxlife.
    • cookie-sec-1 sets a secret with which to cipher the cookie.
    • no-referer-check to disable the referer validation check, since Okta often doesn’t set the header.

  8. Restart HAProxy Enterprise.

    Restart HAProxy Enterprise
    nix
    sudo systemctl restart hapee-3.2r1-lb
    nix
    sudo systemctl restart hapee-3.2r1-lb

    Users that access your application will now be prompted to sign in with their Okta credentials.

Sign out Jump to heading

To sign out of a session, make a request to the URL you set with logout-uri. This will redirect to the OpenID provider to end the session, then back to HAProxy Enterprise to clear the cookie.

Reference Jump to heading

In this section, we’ll describe options for configuring the OpenID Connect module.

Configuration directives Jump to heading

The global configuration section supports the following directives:

Directive Description
oidc-sso-dir <dir> Assigns an absolute filepath to a default directory from which to fetch SSL certificates and private keys. Then, oidc-sso directives can use a relative path with this as the base. Absolute locations in crt for SSL certificates, key for private key, and public-jwk-keys will override oidc-sso-dir. This setting is optional.

The oidc-sso configuration section supports the following directives:

Directive Description
auth-ep-uri <uri> Sets the authentication endpoint URI. This is the URI used by HAProxy Enterprise to redirect the end user to the authentication server during the Authorization Code Flow. When discovery is on, this setting will be set automatically from data fetched from the discovery-uri URI.
client-id <client-id> This setting identifies the relying party (HAProxy Enterprise) from the OpenID provider’s point of view. It’s mandatory and must be provided by the OpenID provider.
cookie domain <domain> [secure] [httponly] [maxlife <lifle>] Configure the OIDC cookies handled by HAProxy Enterprise. The cookie’s name is oidc_cookie. It isn’t configurable. All the other arguments have exactly the same role as the one for the cookie directive for proxies. This setting is mandatory with at least a domain argument provided. Default <life> value is 10 hours.
cookie-sec-1 <secret>, cookie-sec-2 <secret> Sets a weak secret to cipher the OIDC cookie. At least one secret must be defined and at most two may be defined. These settings are optional, but at least one must be defined. The current in-use secret is defined by cur-cookie-sec. Note that this isn’t the weak secrets used to cipher the OIDC cookies. A strong secret is derived from the weak one to cipher the cookie (256-bits AES keys).
cur-cookie-sec { 1 or 2 } Identify the current secret used by the relying party to generate new cookies. This doesn’t mean than cookie-sec-1 and cookie-sec-2 cannot be used at the same time to decipher already generated cookies. A value of 1 means that cookie-sec-1 is currently used to generate new cookies. This setting is optional with 1 as default value. See Cookie secret rotation.
crt <filename> This setting provides the name of the PEM file containing a public certificate to verify on the OpenID provider side the signatures generated by the relying party (HAProxy Enterprise). This certificate must be provided to the OpenID provider. This setting isn’t mandatory, but must be set for an OpenID provider like Microsoft Entra ID. This public key must match the one provided by the key setting.
discovery { on or off } Enables (on) or disables (off) the discovery of some properties from the metadata document URI, set with discovery-uri. It’s enabled by default.
discovery-uri <uri> This is the unique, OpenID provider-side setting that relates to the discovery directive. It’s the discovery URI used by HAProxy Enterprise to request from the OpenID provider its discoverable settings. This setting is optional. If not provided, the discovery URI is built from the issuer value, which is mandatory. Typically: <issuer>/.well-known/openid-configuration. This URI is named the OpenID Connect metadata document. For instance on Microsoft Entra ID, the OpenID Connect metadata document is built as follows: https://login.microsoftonline.com/<tenant>/v2.0/.well-known/openid-configuration with <tenant> being the Microsoft Entra ID directory of your application.
end-sess-ep-uri <uri> Sets the end session endpoint URI. This is the URI that HAProxy Enterprise uses to redirect the end user to the authentication server (OpenID provider) during the sign-out process. This setting is mandatory only if logout-uri is provided because logout-uri implicitly enables the logout feature. When discovery is on, this setting will be set automatically from data fetched from the discovery-uri URI.
issuer <uri> URI using the https scheme with no query or fragment components that the OpenID provider asserts as its Issuer Identifier. This mandatory setting must be provided by the OpenID provider.
jwks-uri <uri> Sets the JWK (JSON Web Key Set) URI used by HAProxy Enterprise to retrieve the OpenID provider’s public keys. They’re needed to verify the OpenID provider’s signatures. This URI may be built as follows for Microsoft Entra ID: https://login.microsoftonline.com/<tenant>/discovery/v2.0/keys with <tenant> the Microsoft Entra Directory of your application. When discovery is on, this setting will be set automatically from data fetched from the discovery-uri URI.
jwt-alg <algo> This setting define the algorithm used by the relying party (HAProxy Enterprise) to generate its signatures. This setting is mandatory. See Supported signing algorithms.
key <filename> This setting provides the PEM filename which contains a private key used to authenticate the requests to the /token endpoint during the Authorization Code Flow. Note that if the PEM filename path is relative, the search directory is the one set by oidc-sso-dir, or the current working directory if not set. One of the mac-secret or key directives must be exclusively set.
logout-uri <uri> URI which should be used by the end users to intiate a sign-out process. This parameter is optional, but highly recommended. End users should alway have the possibility to properly end their OpenID Connect SSO sessions. This option implicitly enables the sign-out feature (see also the end-sess-ep-uri and post-logout-redirerect-uri settings).
mac-secret <secret> This settings provides a secret used for HMAC signature algorithms. This must be an ASCII string. The same secret must be used on the OpenID provider side. Note that either the mac-secret or key directive must be exclusively set.
no-referer-check Disables the referer HTTP header validation check during the sign-on process.
post-logout-redirect-uri <uri> URI used by the OpenID provider to redirect the user to the relying party. This way, the relying party is able to reset the OIDC cookie session only if everything went well on the OpenID provider during the sign-out process. This setting is required if logout-uri is set.
public-jwks-keys <filename> This setting provides a filename for a file containing the OpenID provider’s public keys with JWKS as the format (JSON). It shouldn’t be used if the discovery feature is enabled or if jwks-uri is set.
redirect-uri <uri> Sets the redirection URI used by the OpenID provider to redirect the user to HAProxy Enterprise with the authorization code during the Authorization Code Flow. This setting is mandatory and must be provided to the OpenID provider.
scope <comma-separated list of scopes> Allows the relying party to use a list of additional scopes for the access tokens. By default, the relying party already uses openid and offline_access. There’s no need to provide these two default scopes. This setting is optional.
token-ep-uri <uri> Sets the token endpoint URI. This is the URI used by HAProxy Enterprise to request from the authentication server tokens during the Authorization Code Flow. When discovery is on, this setting will be set automatically from data fetched from the discovery-uri URI.

Supported signing algorithms Jump to heading

You can set the following values for the jwt-alg directive, depending on which ones your OpenID provider also supports.

Algorithm Digital Signature or MAC Algorithm
HS256 HMAC using SHA-256
HS384 HMAC using SHA-384
HS512 HMAC using SHA-512
RS256 RSASSA-PKCS1-v1_5 using SHA-256
RS384 RSASSA-PKCS1-v1_5 using SHA-384
RS512 RSASSA-PKCS1-v1_5 using SHA-512
ES256 ECDSA using P-256 and SHA-256
ES384 ECDSA using P-384 and SHA-384
ES512 ECDSA using P-521 and SHA-512
PS256 RSASSA-PSS using SHA-256 and MGF1 with SHA-256
PS384 RSASSA-PSS using SHA-384 and MGF1 with SHA-384
PS512 RSASSA-PSS using SHA-512 and MGF1 with SHA-512 
Example: HMAC using SHA512
text
oidc-sso my-oidc-settings
  jwt-algo HS512
  mac-secret xxxxyyyyyyaaaaabbbb
Example: HMAC using SHA512
text
oidc-sso my-oidc-settings
  jwt-algo HS512
  mac-secret xxxxyyyyyyaaaaabbbb
Example: RSASSA-PKCS1-v1_5 using SHA-256
text
oidc-sso my-oidc-settings
  jwt-algo RS256
  key key.pem
  crt crt.pem
Example: RSASSA-PKCS1-v1_5 using SHA-256
text
oidc-sso my-oidc-settings
  jwt-algo RS256
  key key.pem
  crt crt.pem

You can use the cur-cookie-sec directive in combination with cookie-sec-1 and cookie-sec-2 to modify the secret used to cipher the OIDC cookie without having an impact on the cookies already ciphered by the previous secret. To avoid breaking cookie sessions due to cookie secret changes, ensure that at least one cookie session lifetime has elapsed between two consecutive changes. A good practice is to keep the last secret before adding a new one as follows:

First in-use secret: my_weak_sec_1

haproxy
oidc-sso ha-rp
  cookie-sec-1 my_weak_sec_1
haproxy
oidc-sso ha-rp
  cookie-sec-1 my_weak_sec_1

Next in use secret: my_weak_sec_2

haproxy
oidc-sso ha-rp
  cookie-sec-1 my_weak_sec_1
  cookie-sec-2 my_weak_sec_2
  cur-cookie-sec 2
haproxy
oidc-sso ha-rp
  cookie-sec-1 my_weak_sec_1
  cookie-sec-2 my_weak_sec_2
  cur-cookie-sec 2

Next in use secret: my_weak_sec_3

haproxy
oidc-sso ha-rp
  cookie-sec-1 my_weak_sec_3
  cookie-sec-2 my_weak_sec_2
  cur-cookie-sec 1 # may be removed
haproxy
oidc-sso ha-rp
  cookie-sec-1 my_weak_sec_3
  cookie-sec-2 my_weak_sec_2
  cur-cookie-sec 1 # may be removed

Next in use secret: my_weak_sec_4

haproxy
oidc-sso ha-rp
  cookie-sec-1 my_weak_sec_3
  cookie-sec-2 my_weak_sec_4
  cur-cookie-sec 2
haproxy
oidc-sso ha-rp
  cookie-sec-1 my_weak_sec_3
  cookie-sec-2 my_weak_sec_4
  cur-cookie-sec 2

Variables Jump to heading

The OpenID Connect module makes several variables available within your configuration file. They are available during the authorization code, sign-out, and refresh token protocol flows.

Variable Description
txn.oidc.id_token The JSON-formatted ID token.
txn.oidc.access_token The JSON-formatted access token. 
Example id_token
json
{
  "aud": "123456789-c924-4006-b236-0f3a3e57fe3c",
  "iss": "https://login.microsoftonline.com/abcd1234-defg-1234-abcd-efgi53456789/v2.0",
  "iat": 1757686316,
  "nbf": 1757686316,
  "exp": 1757690216,
  "nonce": "7602cefd871b4f419c20035857084c2d",
  "rh": "1.AXEBGJktvXbUM0WkT75GakwCARORHIgkyQZAsjYPOj5X_jzoAR5xAQ.",
  "sub": "5G9zfu9P-yUvMHNKxrjutii1sqKjUvQbE0DZc0a69Lk",
  "tid": "abcd1234-defg-1234-abcd-efgi53456789",
  "uti": "C0ur6gbI306GugUJ_meBAA",
  "ver": "2.0"
}
Example id_token
json
{
  "aud": "123456789-c924-4006-b236-0f3a3e57fe3c",
  "iss": "https://login.microsoftonline.com/abcd1234-defg-1234-abcd-efgi53456789/v2.0",
  "iat": 1757686316,
  "nbf": 1757686316,
  "exp": 1757690216,
  "nonce": "7602cefd871b4f419c20035857084c2d",
  "rh": "1.AXEBGJktvXbUM0WkT75GakwCARORHIgkyQZAsjYPOj5X_jzoAR5xAQ.",
  "sub": "5G9zfu9P-yUvMHNKxrjutii1sqKjUvQbE0DZc0a69Lk",
  "tid": "abcd1234-defg-1234-abcd-efgi53456789",
  "uti": "C0ur6gbI306GugUJ_meBAA",
  "ver": "2.0"
}
Example access_token
json
{
  "aud": "00000003-0000-0000-c000-000000000000",
  "iss": "https://sts.windows.net/abcd1234-defg-1234-abcd-efgi53456789/",
  "iat": 1757686753,
  "nbf": 1757686753,
  "exp": 1757691573,
  "acct": 0,
  "acr": "1",
  "aio": "AXQAi/8ZAAAAbJKLpgJ4rPUuVWxlm6bJUxDjO2GVW4...",
  "amr": [
    "pwd"
  ],
  "app_displayname": "Example Application",
  "appid": "123456789-c924-4006-b236-0f3a3e57fe3c",
  "appidacr": "2",
  "family_name": "User",
  "given_name": "Test",
  "idtyp": "user",
  "ipaddr": "2600:382:abd3:249b:9cbc:cbed:363a:8c75",
  "name": "Test User",
  "oid": "b661d2ae-27e2-4263-bbbf-42e314f519e9",
  "platf": "3",
  "puid": "10032005172A6722",
  "rh": "1.AXEBGJktvXbUM0WkT75GakwCAQMAAAAAAAAAwAAAAAAAAADoAR5xAQ.",
  "scp": "openid profile email",
  "sid": "008b30e9-2795-383b-6f10-2c54301b0fda",
  "sub": "ISz8-WQ7LU8rB0Sp4Ml4hNqduzKTlKpTSP4oPYVJjas",
  "tenant_region_scope": "NA",
  "tid": "abcd1234-defg-1234-abcd-efgi53456789",
  "unique_name": "test@example.onmicrosoft.com",
  "upn": "test@example.onmicrosoft.com",
  "uti": "8gMSknJS0UOyFxCv_jveAA",
  "ver": "1.0",
  "wids": [
    "b79fbf4d-3ef9-4689-8143-76b194e85509"
  ],
  "xms_ftd": "06waa-lQtApkWM6At9X8F08tOPCPYw058WeThqSJCkkBdXN3ZXN0My1kc21z",
  "xms_idrel": "1 18",
  "xms_st": {
    "sub": "5G9zfu9P-yUvMHNKxrjutii1sqKjUvQbE0DZc0a69Lk"
  },
  "xms_tcdt": 1757344041
}
Example access_token
json
{
  "aud": "00000003-0000-0000-c000-000000000000",
  "iss": "https://sts.windows.net/abcd1234-defg-1234-abcd-efgi53456789/",
  "iat": 1757686753,
  "nbf": 1757686753,
  "exp": 1757691573,
  "acct": 0,
  "acr": "1",
  "aio": "AXQAi/8ZAAAAbJKLpgJ4rPUuVWxlm6bJUxDjO2GVW4...",
  "amr": [
    "pwd"
  ],
  "app_displayname": "Example Application",
  "appid": "123456789-c924-4006-b236-0f3a3e57fe3c",
  "appidacr": "2",
  "family_name": "User",
  "given_name": "Test",
  "idtyp": "user",
  "ipaddr": "2600:382:abd3:249b:9cbc:cbed:363a:8c75",
  "name": "Test User",
  "oid": "b661d2ae-27e2-4263-bbbf-42e314f519e9",
  "platf": "3",
  "puid": "10032005172A6722",
  "rh": "1.AXEBGJktvXbUM0WkT75GakwCAQMAAAAAAAAAwAAAAAAAAADoAR5xAQ.",
  "scp": "openid profile email",
  "sid": "008b30e9-2795-383b-6f10-2c54301b0fda",
  "sub": "ISz8-WQ7LU8rB0Sp4Ml4hNqduzKTlKpTSP4oPYVJjas",
  "tenant_region_scope": "NA",
  "tid": "abcd1234-defg-1234-abcd-efgi53456789",
  "unique_name": "test@example.onmicrosoft.com",
  "upn": "test@example.onmicrosoft.com",
  "uti": "8gMSknJS0UOyFxCv_jveAA",
  "ver": "1.0",
  "wids": [
    "b79fbf4d-3ef9-4689-8143-76b194e85509"
  ],
  "xms_ftd": "06waa-lQtApkWM6At9X8F08tOPCPYw058WeThqSJCkkBdXN3ZXN0My1kc21z",
  "xms_idrel": "1 18",
  "xms_st": {
    "sub": "5G9zfu9P-yUvMHNKxrjutii1sqKjUvQbE0DZc0a69Lk"
  },
  "xms_tcdt": 1757344041
}

Use the var fetch method to retrieve a variable’s value. Then, use the json_query converter to extract a field from the value. For example, to set an HTTP request header named access-token-name to the name field from the access token, use this syntax:

haproxy
frontend example
  ...
  http-request set-header access-token-name %[var(txn.oidc.access_token),json_query('$.name')]
haproxy
frontend example
  ...
  http-request set-header access-token-name %[var(txn.oidc.access_token),json_query('$.name')]

Troubleshooting Jump to heading

To troubleshoot problems, enable tracing to show errors that happen during the OpenID Connect module’s processing.

  • Add configuration to start a trace of the source named oidc-sso. This saves the trace’s log to the file /tmp/oidc.traces.

    haproxy
    ring buf1
      size 10485760 # 10MB
      format timed
      backing-file /tmp/oidc.traces
    traces
      trace oidc-sso sink buf1 level developer verbosity complete start now
    haproxy
    ring buf1
      size 10485760 # 10MB
      format timed
      backing-file /tmp/oidc.traces
    traces
      trace oidc-sso sink buf1 level developer verbosity complete start now

    Learn more about traces.

Errors you could see in the log include:

  • wrong referer error. This can happen if the browser doesn’t set the Referer header, which can happen if it doesn’t trust your web application’s SSL/TLS certificate. Try adding your certificate’s CA to the browser’s list of trusted CAs. You can disable the referer check with the no-referer-check directive.

  • issuer not found or wrong error. This can happen if the issuer you’ve set in the HAProxy Enterprise configuration doesn’t match the issuer value discovered from the /.well-known/openid-configuration metadata document endpoint.

See also Jump to heading

Do you have any suggestions on how we can improve the content of this page?

Previous page Kerberos Next page SAML
© 2025 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences