kataras/iris · error

auth: configuration: %s access token is missing from the con

Error message

auth: configuration: %s access token is missing from the configuration

What it means

The auth Configuration validator (auth/configuration.go:82-84) requires the JWT key set loaded from c.Keys to contain a key whose ID is KIDAccess ("IRIS_AUTH_ACCESS"). That key signs/verifies access tokens. When Configuration.New -> validate runs and no key with that KID exists, construction of the auth feature is aborted with this error. The refresh key (IRIS_AUTH_REFRESH) is intentionally optional, but the access key is mandatory.

Source

Thrown at auth/configuration.go:83

func (c *Configuration) validate() (jwt.Keys, error) {
	if len(c.Headers) == 0 {
		return nil, fmt.Errorf("auth: configuration: headers slice is empty")
	}

	if c.Cookie.Name != "" {
		if c.Cookie.Hash == "" || c.Cookie.Block == "" {
			return nil, fmt.Errorf("auth: configuration: cookie block and cookie hash are required for security reasons when cookie is used")
		}
	}

	keys, err := c.Keys.Load()
	if err != nil {
		return nil, fmt.Errorf("auth: configuration: %w", err)
	}

	if _, ok := keys[KIDAccess]; !ok {
		return nil, fmt.Errorf("auth: configuration: %s access token is missing from the configuration", KIDAccess)
	}

	// Let's keep refresh optional.
	// if _, ok := keys[KIDRefresh]; !ok {
	// 	return nil, fmt.Errorf("auth: configuration: %s refresh token is missing from the configuration", KIDRefresh)
	// }
	return keys, nil
}

// BindRandom binds the "c" configuration to random values for keys and cookie security.
// Keys will not be persisted between restarts,
// a more persistent storage should be considered for production applications,
// see BindFile method and LoadConfiguration/MustLoadConfiguration package-level functions.
func (c *Configuration) BindRandom() error {
	accessPublic, accessPrivate, err := jwt.GenerateEdDSA()
	if err != nil {
		return err
	}

View on GitHub (pinned to 7bedaf55a0)

Solutions

1. Add a keys entry with ID equal to auth.KIDAccess ("IRIS_AUTH_ACCESS"), e.g. an EdDSA key with public/private PEM values and a MaxAge.
2. Easiest: call cfg.BindRandom() (or use MustGenerateConfiguration / auth.MustLoadConfiguration) to populate both access and refresh keys automatically.
3. If loading keys from file, verify the keys section ID fields exactly match "IRIS_AUTH_ACCESS" and that c.Keys.Load() succeeds (check the wrapped error above this one).
4. In tests, generate keys with kataras/jwt (jwt.GenerateEdDSA) and assign them to the Keys field before calling auth.New.

Example fix

// before
cfg := auth.Configuration{
    Headers: []string{"Authorization"},
}
_, err := auth.New(cfg) // error: IRIS_AUTH_ACCESS access token is missing

// after
cfg := auth.Configuration{
    Headers: []string{"Authorization"},
}
if err := cfg.BindRandom(); err != nil {
    panic(err)
}
_, err := auth.New(cfg)

func hasAccessKey(cfg auth.Configuration) bool {
    for _, k := range cfg.Keys {
        if k.ID == auth.KIDAccess && k.Public != "" && k.Private != "" {
            return true
        }
    }
    return false
}
// call before auth.New: if !hasAccessKey(cfg) { cfg.BindRandom() }

func validAuthConfig(cfg auth.Configuration) bool {
    keys, err := cfg.Keys.Load()
    if err != nil {
        return false
    }
    _, ok := keys[auth.KIDAccess]
    return ok
}

auth, err := auth.New(cfg)
if err != nil {
    if strings.Contains(err.Error(), auth.KIDAccess) {
        // regenerate keys or fix the keys section before retrying
        if berr := cfg.BindRandom(); berr != nil {
            log.Fatalf("cannot generate auth keys: %v", berr)
        }
        auth, err = auth.New(cfg)
    }
    if err != nil {
        log.Fatalf("auth configuration invalid: %v", err)
    }
}

When it happens

Trigger: Calling auth.New(cfg) (directly or via iris auth configuration loading) where cfg.Keys is empty, or contains keys with IDs other than "IRIS_AUTH_ACCESS", or a KeysConfiguration whose entries fail to load/parse so keys[KIDAccess] is absent after c.Keys.Load().

Common situations: Hand-writing the auth YAML/JSON config and omitting the Keys section entirely; using a custom key ID in the keys list instead of the required IRIS_AUTH_ACCESS constant; copying an example config that only defines IRIS_AUTH_REFRESH; building Configuration programmatically and forgetting to call BindRandom before New.

Related errors

• refresh max age should be bigger than access token's one[%d
• auth: signin: no provider
• access: %w
• auth: refresh: disabled
• %w: example: %s

AI-assisted analysis of kataras/iris@7bedaf55a0 (2026-08-30). Data as JSON: /api/errors/7a2991455d219c3b. Report an issue: GitHub.