PingAuthorize

Troubleshooting AWS IAM authentication issues

Learn how to fix common errors when setting up AWS Identity and Access Management (IAM) authentication for ElastiCache attribute and service caches.

You can find more information about ElastiCache IAM authentication in Configuring Trust Framework attribute caching for development and Configuring Trust Framework attribute caching for production.

Errors are logged in different locations depending on when they occur and which PDP mode is in use:

  • Startup errors (incompatible config, failed connection, AccessDeniedException):

    • Embedded PDP mode: The PingAuthorize Server remains running but raises a pdp-unavailable administrative alert. The server records alert and exception details in logs/errors. The PDP becomes unavailable for policy evaluation until the issue is resolved.

    • External PDP mode: The Policy Editor fails to start and logs errors to logs/authorize-pe.log.

  • Runtime errors (IAM token generation failures during normal operation):

    • Embedded PDP mode: The PingAuthorize Server logs these errors to logs/trace (the file-based trace logger). You must enable the trace logger to record these messages.

    • External PDP mode: The Policy Editor logs these errors to logs/authorize-pe.log.

The following sections are organized by error message. Each section contains information about how to identify the problem, what the problem is, and how to solve the problem.

Failed to generate IAM auth token

Indicators

  • Embedded PDP mode: Check logs/trace.

  • External PDP mode: Check logs/authorize-pe.log.

    The message typically appears alongside a NoCredentialProviders or similar AWS SDK error.

Problem

The AWS SDK couldn’t resolve valid credentials to generate the IAM auth token.

Solution

Confirm the following, based on your environment:

  • If running on Amazon EKS, confirm that IAM roles for service accounts (IRSA) is configured correctly. The AWS SDK checks for IRSA credentials before falling back to instance profile credentials.

  • If running on Amazon EC2 (outside EKS), confirm that an IAM role or instance profile is attached to the instance or service.

  • If region auto-detection fails, set the AWS_REGION environment variable.

IAM auth is incompatible with a static password

Indicators

  • Embedded PDP mode: The PingAuthorize Server records a pdp-unavailable alert in logs/errors. The server continues running, but the cache is unavailable.

  • External PDP mode: The Policy Editor records this error in logs/authorize-pe.log and fails to start.

Problem

Both a static password and IAM authentication are configured simultaneously.

  • Embedded PDP mode: use-iam-auth is set to true on the external cache, and a password is provided.

  • External PDP mode: useIamAuth is set to true in the options.yml file’s cacheConfig and a password is provided.

Solution

Remove the password.

  • Embedded PDP mode: Clear the password property on the external attribute cache with dsconfig or the admin console.

  • External PDP mode: Remove the password field from cacheConfig.

IAM auth requires a non-blank username

Indicators

  • Embedded PDP mode: The PingAuthorize Server records a pdp-unavailable alert in logs/errors. The server continues running, but the cache is unavailable.

  • External PDP mode: The Policy Editor records this error in logs/authorize-pe.log and fails to start.

Problem

IAM authentication is enabled, but no username is provided.

  • Embedded PDP mode: use-iam-auth is set to true on the external cache, but username is missing or blank.

  • External PDP mode: useIamAuth is set to true in the options.yml file’s cacheConfig, but username is missing or blank.

Solution

Set username to the ElastiCache user ID.

  • Embedded PDP mode: Set the username property on the external attribute cache with dsconfig or the admin console.

  • External PDP mode: Set username in cacheConfig.

AccessDeniedException

Indicators

  • Embedded PDP mode: The PingAuthorize Server records a pdp-unavailable alert in logs/errors. The server continues running, but the cache is unavailable.

  • External PDP mode: The Policy Editor records this error in logs/authorize-pe.log and fails to start.

Problem

AWS denied the node discovery call because the IAM principal doesn’t have the elasticache:DescribeCacheClusters permission.

Solution

Add the missing permission to the IAM policy and restart the PDP.

Unable to connect to external Redis cache (WRONGPASS version)

Indicators

  • Embedded PDP mode: The PingAuthorize Server records a WRONGPASS message in logs/trace and a pdp-unavailable administrative alert in logs/errors. The server continues running.

  • External PDP mode: The Policy Editor fails to start and records a WRONGPASS message in logs/authorize-pe.log.

Problem

ElastiCache rejected the IAM token because either the IAM principal lacks the elasticache:Connect permission or IAM authentication isn’t enabled on the ElastiCache user.

Solution

Confirm the following, then restart the PDP:

  • The IAM policy covers both the replication group and the user Amazon Resource Names (ARNs).

  • The replication group’s user group contains the ElastiCache user, and IAM auth is enabled on that user.

Unable to connect to external Redis cache (No host addresses)

Indicators

  • Embedded PDP mode: The connection error with no host addresses is visible in logs/trace, and the PingAuthorize Server records a pdp-unavailable administrative alert in logs/errors. The server continues running.

  • External PDP mode: The Policy Editor fails to start and records the connection error in logs/authorize-pe.log.

Problem

No cluster nodes were found for the configured replication group ID.

  • Embedded PDP mode: Check the redis-replication-group-id property on the external attribute cache.

  • External PDP mode: Check the replicationGroupId value in cacheConfig.

Solution

Make sure that:

  • The replication group ID is correct for your PDP mode (see previous).

  • The IAM principal has the elasticache:DescribeCacheClusters permission in the correct AWS region.