### Start Local Development Server with Bun

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/README.md

Starts a local development server for live previewing changes. Requires bun to be installed.

```bash
$ bun start
```

--------------------------------

### Install ajson CLI

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/vendor/github.com/spyzhov/ajson/README.md

Install the ajson command-line interface tool using go get.

```shell
go get github.com/spyzhov/ajson/cmd/ajson@v0.9.6
```

--------------------------------

### Install uuid Package

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/vendor/github.com/google/uuid/README.md

Installs the uuid package using the go get command.

```sh
go get github.com/google/uuid
```

--------------------------------

### Install Dependencies with Bun

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/README.md

Installs project dependencies using the bun package manager. Ensure bun is installed first.

```bash
$ bun install
```

--------------------------------

### Install Dependencies and Playwright Browsers

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/e2e/README.md

Installs project dependencies using Bun and installs the necessary Playwright browser binaries.

```bash
bun install
bunx playwright install
```

--------------------------------

### Run Traefik with Keycloak

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/README.md

Starts the Traefik plugin with a pre-configured Keycloak instance for local development. Wait for services to initialize before accessing.

```bash
task run:keycloak
```

--------------------------------

### Environment Variable Configuration Example

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/getting-started/middleware-configuration.md

Demonstrates how to use environment variables for configuration properties. Supports single environment variables enclosed in ${}. Does not support templating within the variable.

```yaml
Provider:
  Url: "${MY_PROVIDER_URL}"
  ClientSecret: "${MY_CLIENT_SECRET}"
```

--------------------------------

### List Available Tasks

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/README.md

Lists all available tasks for local development and testing using the Taskfile. Ensure Taskfile CLI and Docker are installed.

```bash
task --list
```

--------------------------------

### Get Kanidm Client Configuration

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/identity-providers/kanidm.md

Retrieve the current configuration for a Kanidm OAuth2 client to verify its settings. The example shows the output for a client named 'traefik-oauth2'.

```yaml
 class: account
 class: memberof
 class: oauth2_resource_server
 class: oauth2_resource_server_basic
 class: object
 directmemberof: idm_all_accounts@example.com
 displayname: Traefik OAuth
 es256_private_key_der: private_binary
 memberof: idm_all_accounts@example.com
 name: traefik-oauth2
 oauth2_allow_insecure_client_disable_pkce: true
 oauth2_rs_basic_secret: hidden
 oauth2_rs_origin: https://login.example.com/oidc/callback
 oauth2_rs_origin_landing: https://login.example.com/
 oauth2_rs_scope_map: idm_all_persons@example.com: {"email", "groups", "openid", "profile"}
 oauth2_rs_token_key: hidden
 oauth2_strict_redirect_uri: true
 spn: traefik-oauth2@example.com
 uuid: f1f4e707-832e-4beb-ba12-9410b883dddf
```

--------------------------------

### Install Golang JWT Package

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/vendor/github.com/golang-jwt/jwt/v5/README.md

Use this command to add the jwt-go package as a dependency in your Go program.

```shell
go get -u github.com/golang-jwt/jwt/v5
```

--------------------------------

### Full Local Development Example with Multiple Services

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/getting-started/callback-uri.md

A comprehensive configuration for local development, setting up multiple services, authentication router, and using environment variables for provider details. It configures the callback URI and session cookie domain for a local development environment.

```yaml
http:
  services:
    whoami:
      loadBalancer:
        servers:
          - url: http://whoami:80

  middlewares:
    oidc-auth:
      plugin:
        traefik-oidc-auth:
          LogLevel: DEBUG
          Provider:
            Url: "${PROVIDER_URL}"
            ClientId: "${CLIENT_ID}"
            ClientSecret: "${CLIENT_SECRET}"
            UsePkce: false
          Scopes: ["openid", "profile", "email"]
          CallbackUri: "https://auth.127.0.0.1.sslip.io/oidc/callback"
          SessionCookie:
            Domain: ".127.0.0.1.sslip.io"

  routers:
    service1:
      entryPoints: ["websecure"]
      tls: {}
      rule: "Host(`service1.127.0.0.1.sslip.io`)"
      service: whoami
      middlewares: ["oidc-auth@file"]
    service2:
      entryPoints: ["websecure"]
      tls: {}
      rule: "Host(`service2.127.0.0.1.sslip.io`)"
      service: whoami
      middlewares: ["oidc-auth@file"]
    auth:
      entryPoints: ["websecure"]
      tls: {}
      rule: "Host(`auth.127.0.0.1.sslip.io`)"
      service: noop@internal
      middlewares: ["oidc-auth@file"]
```

--------------------------------

### Import Golang JWT Package

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/vendor/github.com/golang-jwt/jwt/v5/README.md

Import the jwt-go library into your Go code to start using its functionalities.

```go
import "github.com/golang-jwt/jwt/v5"
```

--------------------------------

### Authorized Token Example

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/getting-started/authorization.md

An example of a JWT token that would be considered authorized by the 'admin' or 'media' roles assertion.

```json
{
  "exp": 1749314471,
  "iat": 1749314411,
  "auth_time": 1749314411,
  "jti": "onrtac:3b5c0b13-8471-4e98-a329-226d6c1d0b78",
  "iss": "http://127-0-0-1.sslip.io:8000/realms/master",
  "aud": [
    "master-realm",
    "account"
  ],
  "sub": "c0d6f5c3-d05f-474d-bf06-f590b0a397ad",
  "typ": "Bearer",
  "azp": "traefik",
  "sid": "758810d0-6be1-43a3-8c2b-7ae69e5eba00",
  "acr": "1",
  "scope": "openid email profile",
  "email_verified": false,
  "preferred_username": "admin",
  // highlight-next-line
  "roles": ["admin"]
}
```

--------------------------------

### JSONPath bracket notation example

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/vendor/github.com/spyzhov/ajson/README.md

Demonstrates the bracket notation for accessing nested JSON properties, which is more general.

```jsonpath
$['store']['book'][0]['title']
```

--------------------------------

### Update Import Path and Install JWT Go v4

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/vendor/github.com/golang-jwt/jwt/v5/MIGRATION_GUIDE.md

Update your project to use the new import path for JWT Go v4 and install the package. This is a common step for migrating to newer versions.

```bash
go get github.com/golang-jwt/jwt/v4
go mod tidy
```

--------------------------------

### Logout Link Example

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/getting-started/how-it-works.md

Use this HTML snippet to create a logout link. The link navigates to the configured logout route to initiate the logout flow.

```html
<a href="/logout">Logout</a>
```

--------------------------------

### JSONPath dot notation example

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/vendor/github.com/spyzhov/ajson/README.md

Illustrates the dot notation for accessing nested JSON properties.

```jsonpath
$.store.book[0].title
```

--------------------------------

### Run Traefik with External IdP

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/README.md

Starts the Traefik plugin using the configuration from the .env file for an external identity provider. Access the service via http://localhost:9080.

```bash
task run:external
```

--------------------------------

### JSON Structure Example

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/getting-started/authorization.md

This is a sample JSON structure used for demonstrating complex assertions. It does not represent an actual JWT.

```json
{
  "store": {
    "bicycle": {
      "color": "red",
      "price": 19.95
    },
    "book": [
      {
        "author": "Herman Melville",
        "category": "fiction",
        "isbn": "0-553-21311-3",
        "price": 8.99,
        "title": "Moby Dick"
      },
      {
        "author": "J. R. R. Tolkien",
        "category": "fiction",
        "isbn": "0-395-19395-8",
        "price": 22.99,
        "title": "The Lord of the Rings"
      }
    ]
  }
}
```

--------------------------------

### Unauthorized Token Example

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/getting-started/authorization.md

An example of a JWT token that would be considered unauthorized because its 'roles' claim does not match the required 'admin' or 'media' values.

```json
{
  "exp": 1749314471,
  "iat": 1749314411,
  "auth_time": 1749314411,
  "jti": "onrtac:3b5c0b13-8471-4e98-a329-226d6c1d0b78",
  "iss": "http://127-0-0-1.sslip.io:8000/realms/master",
  "aud": [
    "master-realm",
    "account"
  ],
  "sub": "c0d6f5c3-d05f-474d-bf06-f590b0a397ad",
  "typ": "Bearer",
  "azp": "traefik",
  "sid": "758810d0-6be1-43a3-8c2b-7ae69e5eba00",
  "acr": "1",
  "scope": "openid email profile",
  "email_verified": false,
  "preferred_username": "admin",
  // highlight-next-line
  "roles": ["user"]
}
```

--------------------------------

### Add Custom Not-Equals Operation

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/vendor/github.com/spyzhov/ajson/README.md

Demonstrates how to add a custom operation to the script engine. This example adds a not-equals operator (`<>`) that returns a boolean node.

```go
	AddOperation("<>", 3, false, func(left *ajson.Node, right *ajson.Node) (node *ajson.Node, err error) {
		result, err := left.Eq(right)
		if err != nil {
			return nil, err
		}
		return BoolNode("neq", !result), nil
	})
```

--------------------------------

### JSONPath filter expression example

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/vendor/github.com/spyzhov/ajson/README.md

Selects book titles where the price is less than 10 using a filter expression.

```jsonpath
$.store.book[?(@.price < 10)].title
```

--------------------------------

### Docker Labels for Role-Based Authorization

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/getting-started/authorization.md

This configuration uses Docker labels to achieve the same role-based authorization as the YAML example, allowing access for 'admin' or 'media' roles.

```docker
traefik.http.middlewares.oidc-auth.traefik-oidc-auth.authorization.assertClaims[0].name=roles"
traefik.http.middlewares.oidc-auth.traefik-oidc-auth.authorization.assertClaims[0].anyOf=admin,media"
```

--------------------------------

### Traefik Middleware Configuration with Kanidm (Absolute URL, No PKCE, Forward Auth Headers)

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/identity-providers/kanidm.md

Configure Traefik middleware for Kanidm authentication using an absolute callback URL, disabling PKCE, and forwarding custom headers with user claims. This setup also includes router configuration.

```yaml
http:
  middlewares:
    oidc-auth:
      plugin:
        traefik-oidc-auth:
          LogLevel: DEBUG
          CallbackUri: "https://login.example.com/oidc/callback"
          SessionCookie:
            Domain: ".example.com"
          Provider:
            Url: "https://idm.example.com/oauth2/openid/<client_id>"
            ClientId: "<client_id>"
            ClientSecret: "<client_secret>"
            UsePkce: false
          Scopes: ["openid", "profile", "email", "groups"]
          Headers:
            - Name: "Remote-User"
              Value: "{{`{{ .claims.preferred_username }}`}}"
            - Name: "Remote-Email"
              Value: "{{`{{ .claims.email }}`}}"
            - Name: "Remote-Groups"
              Value: "{{`{{ .claims.groups }}`}}"
            - Name: "Remote-Name"
              Value: "{{`{{ .claims.name }}`}}"

  routers:
    auth:
      rule: "Host(`login.example.com)"
      service: noop@internal
      middlewares: ["oidc-auth@file"]
```

--------------------------------

### Set Absolute Callback URI and Session Cookie Domain

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/getting-started/callback-uri.md

Use an absolute URL for `CallbackUri` when protecting multiple hostnames. This example also demonstrates setting a shared session cookie domain for subdomains.

```yaml
middlewares:
  oidc-auth:
    plugin:
      traefik-oidc-auth:
        CallbackUri: "https://login.example.com/oidc/callback"
        SessionCookie:
          Domain: ".example.com"
        Provider:
          Url: "https://ident.example.com/"
          ClientId: "<YourClientId>"
          ClientSecret: "<YourClientSecret>"
        Scopes: ["openid", "profile", "email"]
```

--------------------------------

### Using 'avg' Function with JSON Array

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/vendor/github.com/spyzhov/ajson/README.md

Calculates the average of numeric values in a JSON array using the 'avg' function. This example shows how to unmarshal JSON, evaluate an expression, and print the numeric result.

```go
package main

import (
	"fmt"
	
	"github.com/spyzhov/ajson"
)

func main() {
	json := []byte(`{"prices": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]}`)
	root, err := ajson.Unmarshal(json)
	if err != nil {
		panic(err)
	}
	result, err := ajson.Eval(root, `avg($.prices)`)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Avg price: %0.1f", result.MustNumeric())
	// Output:
	// Avg price: 5.5
}

```

--------------------------------

### YAML Assertion: Expect array to contain a set of values (Failing Example)

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/getting-started/authorization.md

This assertion checks if the 'store.book[*].price' array contains all specified values. It fails because the value '1' is not present in the array.

```yaml
Name: store.book[*].price
AllOf: [ 22.99, 8.99, 1 ]
```

--------------------------------

### Build Static Website with Bun

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/README.md

Generates the static content for the website into the 'build' directory. This output can be hosted anywhere.

```bash
$ bun run build
```

--------------------------------

### Advanced Header Configuration with Helper Functions

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/getting-started/middleware-configuration.md

Demonstrates using Go-template helper functions like `withPrefix` and `mapToJsonArray` for advanced header value construction, suitable for both YAML and CRD configurations.

```yaml
Headers:
  - Name: "Authorization"
    Value: "Bearer {{ .accessToken }}"
  - Name: "Impersonate-User"
    Value: "prefix:{{ .claims.preferred_username }}"
  - Name: "Impersonate-Group"
    Values: '{{ .claims.groups | withPrefix "prefix:" | mapToJsonArray }}'
```

--------------------------------

### Evaluate JSON from a local file

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/vendor/github.com/spyzhov/ajson/README.md

Process a local JSON file named 'example.json' using ajson with the root path selector.

```shell
ajson "$" example.json
```

--------------------------------

### Configure External Identity Provider

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/README.md

Create a .env file in the 'workspaces/external-idp' directory to configure the plugin with your own identity provider. This requires PROVIDER_URL, CLIENT_ID, and CLIENT_SECRET.

```dotenv
PROVIDER_URL=...
CLIENT_ID=...
CLIENT_SECRET=...
VALIDATE_AUDIENCE=true
```

--------------------------------

### Create Kanidm OAuth2 Client

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/identity-providers/kanidm.md

Use the `kanidm client` tool to create a new OAuth2 client. This command requires the client ID, display name, and landing page URL.

```shell
kanidm system oauth2 create <client_id> <displayname> <landing page url>
```

--------------------------------

### ZITADEL Middleware Configuration (With PKCE)

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/identity-providers/zitadel.md

Configure the traefik-oidc-auth middleware for ZITADEL when using the PKCE authentication flow. Ensure the Provider URL, ClientId, and Scopes are correctly set.

```yaml
http:
  middlewares:
    oidc-auth:
      plugin:
        traefik-oidc-auth:
          Provider:
            Url: "https://your-instance.zitadel.cloud"
            ClientId: "<YourClientId>"
            UsePkce: true
          Scopes: ["openid", "profile", "email"]
```

--------------------------------

### ZITADEL Middleware Configuration (Without PKCE)

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/identity-providers/zitadel.md

Configure the traefik-oidc-auth middleware for ZITADEL when not using the PKCE authentication flow. This requires a ClientSecret in addition to the Provider URL, ClientId, and Scopes.

```yaml
http:
  middlewares:
    oidc-auth:
      plugin:
        traefik-oidc-auth:
          Provider:
            Url: "https://your-instance.zitadel.cloud"
            ClientId: "<YourClientId>"
            ClientSecret: "<YourClientSecret>"
          Scopes: ["openid", "profile", "email"]
```

--------------------------------

### Configure BypassAuthenticationRule in Traefik

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/getting-started/bypass-authentication-rule.md

This example demonstrates how to set the BypassAuthenticationRule in the traefik-oidc-auth middleware configuration. It bypasses authentication for requests matching '/public' path or specific IP headers.

```yaml
http:
  middlewares:
    oidc-auth:
      plugin:
        traefik-oidc-auth:
          Provider:
            Url: "${PROVIDER_URL}"
            ClientId: "${CLIENT_ID}"
            ClientSecret: "${CLIENT_SECRET}"
          BypassAuthenticationRule: "PathPrefix(`/public`) || HeaderRegexp(`X-Real-Ip`, `^172\.18\.`)"
```

--------------------------------

### Unmarshal and Marshal JSON Data with ajson

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/vendor/github.com/spyzhov/ajson/README.md

Demonstrates how to unmarshal a JSON byte slice into an ajson object, evaluate a JSONPath expression to find the average price, append the result, and then marshal the modified object back into a JSON string. This is useful for dynamic JSON manipulation.

```go
package main

import (
	"fmt"
	"github.com/spyzhov/ajson"
)

func main() {
	json := []byte(`{"store": {"book": [
{"category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95}, 
{"category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99},
{"category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3", "price": 8.99},
{"category": "fiction", "author": "J. R. R. Tolkien", "title": "The Lord of the Rings", "isbn": "0-395-19395-8", "price": 22.99}], 
"bicycle": {"color": "red", "price": 19.95}, "tools": null}}`)
	root := ajson.Must(ajson.Unmarshal(json))
	result := ajson.Must(ajson.Eval(root, "avg($..price)"))
	err := root.AppendObject("price(avg)", result)
	if err != nil {
		panic(err)
	}
	marshalled, err := ajson.Marshal(root)
	if err != nil {
		panic(err)
	}
	fmt.Printf("%s", marshalled)
}
```

--------------------------------

### YAML Configuration for Role-Based Authorization

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/getting-started/authorization.md

This YAML configuration demonstrates how to set up an authorization rule to allow access only to users with 'admin' or 'media' roles.

```yaml
http:
  middlewares:
    oidc-auth:
      plugin:
        traefik-oidc-auth:
          Provider:
            Url: "https://your-idp.com"
            ClientId: "<YourClientId>"
            UsePkce: true
          Scopes: ["openid", "profile", "email"]
          # highlight-start
          Authorization:
            AssertClaims:
              - Name: roles
                AnyOf: ["admin", "media"]
          # highlight-end
```

--------------------------------

### Filter JSON Array for True Values

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/vendor/github.com/spyzhov/ajson/README.md

Filters a JSON array to find all elements that are strictly equal to the boolean `true`. This example uses the predefined `true` constant within a JSONPath expression.

```go
package main

import (
	"fmt"
	
	"github.com/spyzhov/ajson"
)

func main() {
	json := []byte(`{"foo": [true, null, false, 1, "bar", true, 1e3], "bar": [true, "baz", false]}`)
	result, _ := ajson.JSONPath(json, `$..[?(@ == true)]`)
	fmt.Printf("Count of `true` values: %d", len(result))
```

--------------------------------

### Run Playwright Tests in Interactive UI Mode

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/e2e/README.md

Launches the Playwright interactive UI for running tests.

```bash
bunx playwright test --ui
```

--------------------------------

### Filter JSON Objects by Email Regex

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/vendor/github.com/spyzhov/ajson/README.md

Filters a JSON array of objects to find those where the 'mail' field matches a specific email regex pattern. This example utilizes the regex matching operator (`=~`).

```go
package main

import (
	"fmt"
	
	"github.com/spyzhov/ajson"
)

func main() {
	json := []byte(`[{"name":"Foo","mail":"foo@example.com"},{"name":"bar","mail":"bar@example.org"}]`)
	result, err := ajson.JSONPath(json, `$.[?(@.mail =~ '.+@example\.com')]`)
	if err != nil {
		panic(err)
	}
	fmt.Printf("JSON: %s", result[0].Source())
	// Output:
	// JSON: {"name":"Foo","mail":"foo@example.com"}
```

--------------------------------

### Example Decoded JWT Token

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/getting-started/authorization.md

This JSON object represents a decoded JWT token, showcasing various claims like expiration time, issuer, audience, subject, roles, and user information. It's useful for understanding the data available for authorization.

```json
{
  "exp": 1749314471,
  "iat": 1749314411,
  "auth_time": 1749314411,
  "jti": "onrtac:3b5c0b13-8471-4e98-a329-226d6c1d0b78",
  "iss": "http://127-0-0-1.sslip.io:8000/realms/master",
  "aud": [
    "master-realm",
    "account"
  ],
  "sub": "c0d6f5c3-d05f-474d-bf06-f590b0a397ad",
  "typ": "Bearer",
  "azp": "traefik",
  "sid": "758810d0-6be1-43a3-8c2b-7ae69e5eba00",
  "acr": "1",
  "realm_access": {
    "roles": [
      "create-realm",
      "default-roles-master",
      "offline_access",
      "admin",
      "uma_authorization"
    ]
  },
  "resource_access": {
    "master-realm": {
      "roles": [
        "view-realm",
        "view-identity-providers",
        "query-groups"
      ]
    },
    "account": {
      "roles": [
        "manage-account",
        "manage-account-links",
        "view-profile"
      ]
    }
  },
  "scope": "openid email profile",
  "email_verified": false,
  "preferred_username": "admin"
}
```

--------------------------------

### Traefik Middleware Configuration with Kanidm (Relative URL, PKCE)

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/identity-providers/kanidm.md

Configure Traefik middleware to use Kanidm for authentication with a relative URL and PKCE enabled. This is the recommended secure approach.

```yaml
http:
  middlewares:
    oidc-auth:
      plugin:
        traefik-oidc-auth:
          Provider:
            Url: "https://idm.example.com/oauth2/openid/<client_id>"
            ClientId: "<client_id>"
            UsePkce: true
          Scopes: ["openid", "profile"]
```

--------------------------------

### Unmarshal, JSONPath, and Modify JSON Data

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/vendor/github.com/spyzhov/ajson/README.md

Demonstrates how to unmarshal JSON, find elements using JSONPath, modify numeric values, append new key-value pairs, and marshal the modified JSON back. This is useful for dynamic JSON manipulation when the structure is not strictly defined.

```go
package main

import (
	"fmt"
	"github.com/spyzhov/ajson"
)

func main() {
	json := []byte(`...`)

	root, _ := ajson.Unmarshal(json)
	nodes, _ := root.JSONPath("$..price")
	for _, node := range nodes {
		node.SetNumeric(node.MustNumeric() * 1.25)
		node.Parent().AppendObject("currency", ajson.StringNode("", "EUR"))
	}
	result, _ := ajson.Marshal(root)

	fmt.Printf("%s", result)
}
```

--------------------------------

### Custom Claims with Application-Specific Validation

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/vendor/github.com/golang-jwt/jwt/v5/MIGRATION_GUIDE.md

Demonstrates how to extend custom claims with application-specific validation logic using the new ClaimsValidator interface. Errors from this method are appended to standard validation.

```go
// MyCustomClaims includes all registered claims, plus Foo.
type MyCustomClaims struct {
	Foo string `json:"foo"`
	jwt.RegisteredClaims
}

// Validate can be used to execute additional application-specific claims
// validation.
func (m MyCustomClaims) Validate() error {
	if m.Foo != "bar" {
		return errors.New("must be foobar")
	}

	return nil
}
```

--------------------------------

### Run Playwright Tests with Headed Browser

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/e2e/README.md

Runs Playwright tests with the browser window visible.

```bash
bunx playwright test --headed
```

--------------------------------

### Traefik Middleware Configuration with Kanidm (Relative URL, No PKCE)

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/identity-providers/kanidm.md

Configure Traefik middleware to use Kanidm for authentication with a relative URL, disabling PKCE. This requires the client secret to be provided.

```yaml
http:
  middlewares:
    oidc-auth:
      plugin:
        traefik-oidc-auth:
          Provider:
            Url: "https://idm.example.com/oauth2/openid/<client_id>"
            ClientId: "<client_id>"
            ClientSecret: "<client_secret>"
          Scopes: ["openid", "profile"]
```

--------------------------------

### Unmarshal JSON Data and Calculate Average Price in Go

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/vendor/github.com/spyzhov/ajson/README.md

Demonstrates how to unmarshal JSON data into an ajson object and iterate through its elements to calculate the average price of items. This is useful for processing heterogeneous JSON structures.

```go
package main

import (
	"fmt"
	"github.com/spyzhov/ajson"
)

func main() {
	data := []byte(`{"store": {"book": [
{"category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95}, 
{"category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99}, 
{"category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3", "price": 8.99}, 
{"category": "fiction", "author": "J. R. R. Tolkien", "title": "The Lord of the Rings", "isbn": "0-395-19395-8", "price": 22.99}], 
"bicycle": {"color": "red", "price": 19.95}, "tools": null}}`)

	root, err := ajson.Unmarshal(data)
	if err != nil {
		panic(err)
	}

	store := root.MustKey("store").MustObject()

	var prices float64
	size := 0
	for _, objects := range store {
		if objects.IsArray() && objects.Size() > 0 {
			size += objects.Size()
			for _, object := range objects.MustArray() {
				prices += object.MustKey("price").MustNumeric()
			}
		} else if objects.IsObject() && objects.HasKey("price") {
			size++
			prices += objects.MustKey("price").MustNumeric()
		}
	}

	if size > 0 {
		fmt.Println("AVG price:", prices/float64(size))
	} else {
		fmt.Println("AVG price:", 0)
	}
}
```

--------------------------------

### Combined Router Rule for Secure Path and Callback

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/config-samples/secured-sub-route.md

This alternative router rule combines the '/secure' path and the OIDC callback path into a single rule using an OR condition. This can simplify the configuration when both paths require similar handling.

```yaml
rule: "HostRegexp(`.+`) && (PathPrefix(`/secure`) || PathPrefix(`/oidc/callback`))"
```

--------------------------------

### Enable Traefik OIDC Auth Plugin

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/getting-started/index.md

Enable the plugin in your traefik static configuration. Ensure you specify the correct module name and version.

```yaml
experimental:
  plugins:
    traefik-oidc-auth:
      moduleName: "github.com/sevensolutions/traefik-oidc-auth"
      version: "v0.20.1"
```

--------------------------------

### Creating a Validator Instance

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/vendor/github.com/golang-jwt/jwt/v5/MIGRATION_GUIDE.md

Users can now create a Validator independently using jwt.NewValidator to perform validation. This replaces direct calls to the old Valid function on claims.

```go
var v = jwt.NewValidator(jwt.WithLeeway(5*time.Second))
v.Validate(myClaims)
```

--------------------------------

### Configure OIDC Auth Middleware (Kubernetes)

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/getting-started/index.md

Configure OIDC authentication using Kubernetes resources, including a Secret for sensitive values and a Middleware CRD. The IngressRoute then applies this middleware.

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: oidc-secret
  namespace: traefik
type: Opaque
stringData:
  pluginSecret: "MLFs4TT99kOOq8h3UAVRtYoCTDYXiRcZ"
  providerClientSecret: "<YourClientSecret>"
---
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc
  namespace: traefik
spec:
  plugin:
    traefik-oidc-auth: # same key as in the static configuration
      Secret: "urn:k8s:secret:oidc-secret:pluginSecret"
      Provider:
        ClientId: "abcd-12345"
        ClientSecret: "urn:k8s:secret:oidc-secret:providerClientSecret"
---
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: whoami
  namespace: traefik
spec:
  routes:
    - kind: Rule
      match: Host(`whoami.mycluster.com`)
      middlewares:
        - name: oidc
      services:
        - kind: Service
          name: whoami
          port: 80
```

--------------------------------

### Pipe JSON to ajson for processing

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/vendor/github.com/spyzhov/ajson/README.md

Use curl to fetch JSON data and pipe it to ajson for extracting coordinate information.

```shell
curl -s "https://randomuser.me/api/?results=10" | ajson "$..coordinates"
```

--------------------------------

### Configure Pocket ID Middleware

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/identity-providers/pocket-id.md

Basic configuration for Traefik's OIDC auth middleware using Pocket ID. Ensure the Client ID and Client Secret are correctly set.

```yaml
http:
  middlewares:
    oidc-auth:
      plugin:
        traefik-oidc-auth:
          Provider:
            Url: "https://pocket-id.mydomain.com/"
            ClientId: "<YourClientId>"
            ClientSecret: "<YourClientSecret>"
          Scopes: ["openid", "profile", "email"]  # "groups" also supported
```

--------------------------------

### Add Custom Function to ajson

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/vendor/github.com/spyzhov/ajson/README.md

Demonstrates how to add a new custom function named 'trim' to the ajson package. This function removes leading and trailing whitespace from a string node.

```go
AddFunction("trim", func(node *ajson.Node) (result *Node, err error) {
		if node.IsString() {
			return StringNode("trim", strings.TrimSpace(node.MustString())), nil
		}
		return
	})

```

--------------------------------

### Configure OIDC Auth Middleware (YAML)

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/getting-started/index.md

Configure the OIDC authentication middleware using a YAML file. It is highly recommended to change the default encryption secret.

```yaml
http:
  services:
    whoami:
      loadBalancer:
        servers:
          - url: http://whoami:80

  middlewares:
    oidc-auth:
      plugin:
        traefik-oidc-auth:
          Secret: "MLFs4TT99kOOq8h3UAVRtYoCTDYXiRcZ" # Please change this secret for your setup
          Provider:
            Url: "https://<YourIdentityProviderUrl>"
            ClientId: "<YourClientId>"
            ClientSecret: "<YourClientSecret>"
            #UsePkce: true # Or use PKCE if your Provider supports this
          Scopes: ["openid", "profile", "email"]

  routers:
    whoami:
      entryPoints: ["web"]
      rule: "HostRegexp(`.+`)"
      service: whoami
      middlewares: ["oidc-auth"]
```

--------------------------------

### Evaluate mathematical expression on piped input

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/vendor/github.com/spyzhov/ajson/README.md

Pipe a number to ajson and evaluate a mathematical expression involving pi and the input value.

```shell
echo "3" | ajson "2 * pi * $"
```

--------------------------------

### Export Keycloak Master Realm Configuration

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/e2e/README.md

Exports the current master realm configuration from a running Keycloak instance to a JSON file.

```bash
docker compose exec -it keycloak /opt/keycloak/bin/kc.sh export --file /opt/keycloak/data/import/master-realm.json --realm master
```

--------------------------------

### Evaluate JSON from URL with JSONPath

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/vendor/github.com/spyzhov/ajson/README.md

Fetch JSON data from a URL and evaluate it using a JSONPath expression to calculate the average of registered ages.

```shell
ajson "avg($..registered.age)" "https://randomuser.me/api/?results=5000"
```

--------------------------------

### Run All Playwright Tests

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/e2e/README.md

Executes all defined Playwright end-to-end tests.

```bash
bunx playwright test
```

--------------------------------

### YAML Header Configuration with Escaped Go-Templates

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/website/docs/getting-started/middleware-configuration.md

Use this configuration when defining headers in Traefik's YAML configuration files. Go-templates must be escaped using backticks and outer curly braces.

```yaml
Headers:
  - Name: "Authorization"
    Value: "{{`Bearer {{ .accessToken }}`}}"
  - Name: "X-Oidc-Username"
    Value: "{{`{{ .claims.preferred_username }}`}}"
```

--------------------------------

### Add Custom Constant to Script Engine

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/vendor/github.com/spyzhov/ajson/README.md

Demonstrates how to add a new constant to the script engine using the `AddConstant` function. This is useful for defining custom values that can be used within JSONPath expressions.

```go
AddConstant("c", NumericNode("speed of light in vacuum", 299_792_458))
```

--------------------------------

### Process Docker logs with multiline JSON and filtering

Source: https://github.com/sevensolutions/traefik-oidc-auth/blob/main/vendor/github.com/spyzhov/ajson/README.md

Filter Docker logs for 'ERROR' messages with severity using multiline input and quiet mode.

```shell
docker logs image-name -f | ajson -qm 'root($[?(@=="ERROR" && key(@)=="severity")])'
```