- PF27 headers connect OAuth requests with token, client, and resource-server context.
- JWT headers identify the signing key and algorithm used to protect token integrity.
- Access token management controls token type, lifetime, claims, and signing behavior.
- Persistent grants retain authorization data beyond the short lifetime of an access token.
- Testing workflow uses a configured client, Postman, or an OAuth playground application.
PF27 Headers: What They Control
PF27 headers are best understood as the request and token metadata surrounding an OAuth deployment in PingFederate. They do not replace the OAuth grant, client registration, access token manager, or attribute contract. Instead, they help each component identify how a request should be interpreted and how a token should be validated.
In a typical setup, PingFederate acts as the authorization server. An OAuth client requests authorization or a token, while a resource server later validates the resulting access token. The headers and claims involved in that exchange must be consistent with the selected grant, signing configuration, and client expectations.
| Area | Main responsibility | Configuration focus |
|---|---|---|
| OAuth request | Carries client and grant context | Client ID, redirect URI, scope, response type |
| Authorization response | Returns an authorization result | Code, state, redirect handling |
| Access token | Proves delegated authorization | Token type, lifetime, claims, issuer |
| JWT header | Describes token protection | Algorithm and key ID |
| Resource request | Presents access token to an API | Authorization scheme and bearer token |
Request Context
OAuth requests identify the client, requested grant, redirect destination, and requested scope. Validate these values before testing token issuance.
JWT Protection
A signed JWT normally carries an algorithm identifier and key reference in its protected header. The receiving service uses these values to locate the verification key.
Token Mapping
Access token mapping transfers values such as username, email, first name, last name, or groups into the token contract.
Treat headers, claims, and contract attributes as separate layers. A correctly signed JWT can still fail authorization if its mapped subject, audience, scope, or user attributes do not match the resource server’s expectations.
Core OAuth Objects Behind the Headers
The most reliable PF27 headers workflow starts with the underlying OAuth objects. Persistent grant storage, policy contract grant mapping, access token management, and access token mapping each perform a different job. Configuring them in the right order reduces confusing validation errors.
A persistent grant stores authorization-related information for a longer period than a short-lived access token. Its lifetime may be controlled by inactivity, maximum lifetime, expiration, revocation, or cleanup rules. PingFederate can use a database or directory server for long-term storage, while an internal HSQLDB option is more suitable for testing than production workloads.
| OAuth object | What it stores or controls | Why it matters |
|---|---|---|
| Persistent grant | Long-lived authorization data | Supports later token requests and grant continuity |
| Persistent grant contract | User and authorization attributes | Defines values retained with the grant |
| Policy contract grant mapping | Maps authentication results to grant data | Connects the authenticated user to OAuth authorization |
| Access token manager | Issues and validates access tokens | Defines token type, lifetime, and signing behavior |
| Access token mapping | Fulfills the token attribute contract | Places identity values into the token |
Persistent Grant Storage
Persistent grant storage should be selected according to the environment. A built-in database may be useful during a local proof of concept, but production deployments generally require a durable database or directory service with operational backup, access control, and maintenance procedures.
The grant lifetime should also be planned carefully. An idle timeout can remove grants after inactivity, while a maximum lifetime places an upper boundary on how long the grant remains valid. Revocation and cleanup behavior should be tested before a client is moved beyond development.
Policy Contract Grant Mapping
Policy contract grant mapping connects the authentication policy contract to the persistent grant contract. The mapping may include a user key such as a username or email address. It can also carry values needed later by access token mapping.
| Mapping value | Typical purpose | Review question |
|---|---|---|
| Username | Stable user identifier | Is the value unique in the directory? |
| User-facing or audit identity | Is the value consistently populated? | |
| First name | Profile claim | Is it required by the client or API? |
| Last name | Profile claim | Does the directory attribute use the expected name? |
| Groups | Authorization or entitlement data | Are group values filtered and scoped correctly? |
Do not treat a local test database as a production storage plan. Confirm grant retention, cleanup, replication, backup, and revocation behavior before using persistent grants in a live environment.
Access Token Manager and JWT Header Setup
The access token manager is the central configuration point for token issuance and validation. A JWT-based manager defines how the token is signed, how long it remains valid, and which claims or attributes are included. The JWT protected header commonly identifies the signing algorithm through alg and the signing key through kid.
A typical setup uses an X.509 certificate for RSA- or elliptic-curve-based signing. The active signing certificate must be available to the token manager, and the corresponding public key must be discoverable by services that validate the token.
| JWT or token setting | Function | Practical review |
|---|---|---|
| Token type | Determines the token format | Confirm the client and API support JWTs |
| Signing certificate | Signs the token | Check validity, trust, and rotation planning |
| Key ID | Identifies the active signing key | Ensure the verifier can select the matching public key |
| JWS algorithm | Protects token integrity | Use an algorithm supported by every participant |
| Token lifetime | Sets access token validity | Keep it aligned with application risk |
| Issuer claim | Identifies the token issuer | Match the value expected by the resource server |
| JWKS endpoint | Publishes verification keys | Use a unique, reachable endpoint path |
Recommended Configuration Sequence
Create the Access Token Manager
Open the OAuth access token management area and create a named instance. Select the token type required by the integration, such as a JSON Web Token, then record the instance name for later mapping.
Add the Signing Certificate
Add or select the certificate used to sign tokens. Assign the active signing certificate or key ID and confirm that its public key can be distributed to token validators.
Set the Token Lifetime
Choose a token lifetime appropriate for the client and API. A short lifetime can limit exposure, while refresh or grant behavior should handle continued authorization where supported.
Define JWT Claims
Configure issuer information and extend the attribute contract with values such as username, email, groups, or subject. Include only the claims needed by the integration.
Save and Replicate
Save the access token manager and replicate the configuration across the cluster when a clustered PingFederate environment is used. Test issuance and validation afterward.
The kid value deserves special attention during certificate rotation. A resource server may receive a new token before its key cache has refreshed. Publishing a stable JWKS endpoint and planning overlap between old and new keys can reduce avoidable validation failures.
Before troubleshooting application code, inspect the decoded JWT header and confirm the alg and kid values. Then verify that the referenced public key is available through the expected key set configuration.
Access Token Mapping and Request Testing
After the access token manager is created, access token mapping fulfills its attribute contract. Select the relevant authentication policy contract and map its values into the token manager. This is where directory attributes or authentication results become usable token claims.
A practical mapping might include a username as the subject, an email address for identity, and groups for authorization decisions. The exact attribute names depend on the configured policy contract and directory schema, so the mapping should be verified rather than assumed.
| Token attribute | Suggested source | Validation goal |
|---|---|---|
| Subject | Authentication policy contract | Identifies the authorized resource owner |
| Username | Authentication policy contract | Matches the application’s user key |
| Directory or policy contract | Provides a consistent identity value | |
| First name | Directory or policy contract | Supports profile-aware applications |
| Last name | Directory or policy contract | Supports display or audit needs |
| Groups | Directory or policy contract | Supports controlled authorization logic |
Header Validation Checklist
Before Testing:
- Confirm the client ID, redirect URI, and selected OAuth grant
- Verify the access token manager uses the intended signing certificate
- Check that JWT alg and kid values match the published verification key
- Confirm subject, username, email, and group mappings are populated
- Test token expiration, revocation, and persistent grant behavior
When testing with Postman or an OAuth playground, begin with one grant and one client. Authorization code and authorization code with PKCE flows require careful redirect and verifier handling. Client credentials testing is more direct because it represents an application identity rather than an end user. Resource owner password credentials and implicit flows should only be tested when they are explicitly supported by the deployment’s security requirements.
| Test stage | What to send or inspect | Expected result |
|---|---|---|
| Client registration | Client ID, secret, redirect URI | Client is recognized |
| Authorization request | Response type, scope, state | Authorization proceeds correctly |
| Token request | Grant type, code, verifier, or secret | Token endpoint issues a token |
| JWT inspection | Header, claims, expiration | Values match configured contracts |
| API request | Bearer access token | Resource server accepts or clearly rejects it |
| Expiration test | Expired token or revoked grant | Access is denied with a useful error |
Change one variable at a time. If a token request fails, first confirm the client and grant parameters. If issuance succeeds but the API rejects the token, inspect the JWT header, issuer, subject, audience, expiration, and signing key separately.
Troubleshooting PF27 Headers
Most OAuth header failures fall into a small number of categories: the request does not match the registered client, the token manager cannot sign or validate the token, the mapping contract is incomplete, or the resource server cannot locate the correct verification key.
Use the symptom table below to narrow the issue before changing multiple configuration values.
| Symptom | Likely cause | First check |
|---|---|---|
| Client authentication fails | Wrong client ID, secret, or method | Compare the registered client with the request |
| Redirect error | Redirect URI mismatch | Check exact scheme, host, path, and port |
| Token is issued but API rejects it | Claim or signature mismatch | Inspect issuer, subject, audience, expiration, and key |
| JWT signature cannot be verified | Wrong kid or unavailable public key | Check the JWKS endpoint and certificate |
| User claims are empty | Incomplete attribute mapping | Review policy and access token mappings |
| Grant disappears unexpectedly | Idle timeout, maximum lifetime, or cleanup | Review persistent grant settings |
| Cluster nodes behave differently | Configuration was not replicated | Compare and replicate cluster settings |
Keep a written record of the expected values for each environment. At minimum, document the issuer, token endpoint, authorization endpoint, JWKS location, signing algorithm, active key ID, token lifetime, client identifier, redirect URI, and required claims.
Authoritative references reviewed on 2026-11-08:
Decode tokens only in a controlled environment and avoid placing real secrets or production tokens in public tools. A decoded token is not proof of validity; signature, issuer, audience, expiration, and authorization checks still matter.
PF27 Headers FAQ
Q: What are PF27 headers used for?
PF27 headers describe important OAuth and JWT context, including signing algorithm and key identification. They work alongside client settings, access token management, attribute mapping, and resource-server validation.
Q: Which JWT header values should I inspect first?
Start with alg and kid. The alg value identifies the signing method, while kid identifies the signing key. Then inspect the token claims and confirm that the matching public key is available to the validator.
Q: Why can a correctly signed token still fail at the API?
A valid signature only proves that the token was signed by a trusted key. The API may still reject an incorrect issuer, audience, subject, scope, expiration value, missing claim, or unauthorized group.
Q: Is persistent grant storage the same as access token storage?
No. A persistent grant retains authorization-related data and can outlive an access token. The access token manager issues and validates tokens, while grant storage supports continuity, revocation, and related authorization behavior.
Never approve an OAuth integration solely because a token was issued. Confirm the token contract, signature verification, expiration behavior, grant lifecycle, and resource-server authorization decisions together.