A token is only as useful as the facts inside it. Customization is how you make those facts fit your business.

Out of the box, Okta puts a few standard facts into tokens: who the person is, who issued the token, who it is meant for, and when it expires. That is enough to prove someone signed in. It is rarely enough to tell an application what the person is allowed to do. A finance application may need to know the person’s department. A support portal may need to know the person’s team and region. An internal API may need to know which roles the person holds. Customization is how those business facts reach the application.

Four jobs good claims do

• They save lookups: the application reads the department straight from the token instead of calling a directory every time.
• They enable decisions: an API can allow or refuse a request based on a role claim without asking anyone.
• They personalize the experience: a portal can greet the person by preferred name and show the right language.
• They carry context: a claim can tell an application which region, tenant, or customer the person belongs to.

The cost of getting it wrong

If claims are missing, applications fall back to guessing or to slow extra lookups. If claims are wrong, people get access they should not have, or lose access they need. If claims are too numerous, tokens grow so large that browsers, gateways, or servers reject them. If claims carry sensitive data, a token copied from a log file or a browser history becomes a data breach. Each of these problems is common, and each is avoidable with a little planning.

The cost of too much customization

The opposite problem is just as real. A team that adds a new claim for every small request ends up with dozens of claims nobody understands, with names that conflict, values that overlap, and rules nobody dares to change. A short, well-named, well-documented set of claims is worth far more than a long pile of special cases.

A small set of words appears again and again in this topic. Learn them once and the rest reads easily.

Many of these words sound technical, but each one has a simple meaning. Read the table slowly. You can return to it whenever a later chapter uses a term you have forgotten.

What a token looks like to a person

Most tokens in modern sign-in systems are made of three parts joined together: a header describing how the token was signed, a body containing the claims, and a signature proving nobody changed the body. The body is readable by anyone who holds the token, because it is encoded rather than encrypted. This detail is so important that it appears again in the security chapter: never place a secret in a claim.

Standard claims and custom claims

Some claims are standard and appear in nearly every token: who issued it, who it is for, who the subject is, when it was issued, and when it expires. Others are common but optional, such as a person’s name or email. Custom claims are the ones you define yourself for your own business needs, such as a cost center, a customer tenant, or a list of application roles. Customization is mostly about custom claims, though it also includes controlling which standard claims are present.

flowchart LR
    U["Person signs in"] --> O["Okta"]
    O --> T["Token issued"]
    T --> H["Header
how it was signed"]
    T --> B["Body
the claims"]
    T --> S["Signature
proof of no tampering"]
    B --> A["Application reads claims"]
    

Figure 1 shows the journey. A person signs in, Okta builds a token, and the body of that token holds the claims. The application then reads the body. The signature lets the application confirm that Okta, and nobody else, produced it. The header simply tells the application which method and key to use for that check.

Claims are produced by authorization servers. Knowing which server you are using decides what you can customize.

Okta can act as a token issuer through authorization servers. You can think of an authorization server as a small, independent token factory with its own settings: its own list of scopes, its own claims, its own access policies, and its own signing keys. Okta provides a built-in server for the organization and, depending on your license, lets you create additional custom servers.

Organization server and custom servers

If your goal is to add business claims, you will almost always work with a custom authorization server, because the organization server restricts what you may change. Whether your license allows custom servers, and how many, is something to confirm in your own organization.

Where claim customization lives

Inside a custom authorization server you will find areas for scopes, claims, access policies, and settings. Claims are defined in the claims area. Each claim has a name, a choice of which token type it applies to, a value source, and a rule about when it is included. Access policies then decide which applications may receive tokens and under what conditions.

flowchart TD
    ORG["Okta organization"] --> OAS["Organization
authorization server"]
    ORG --> CAS["Custom
authorization server"]
    CAS --> SC["Scopes"]
    CAS --> CL["Claims"]
    CAS --> PO["Access policies
and rules"]
    CAS --> KE["Signing keys
and settings"]
    PO --> TK["Tokens issued"]
    CL --> TK
    SC --> TK
    

Figure 2 shows that a custom authorization server bundles four things together. When an application asks for a token, Okta consults the access policies to see whether the request is allowed, looks at the requested scopes, and then builds the token by adding the claims that apply. Changing any one of the four changes what comes out.

Why separate servers can help

Some teams create one custom server per family of APIs. This keeps claims and policies tidy: the payments APIs use the payments server, and the staff directory APIs use another. A change to one cannot accidentally break the other. The trade-off is more servers to manage, which later chapters discuss.

Two kinds of tokens serve two different readers. Claims must be designed with the right reader in mind.

The first thing to settle when adding a claim is which token should carry it. The two main kinds have different purposes, different audiences, and different safety rules.

ID tokens: who signed in

An ID token is meant for the application that asked the person to sign in, often called the client. Its job is to say who the person is. The application reads it, shows the person’s name, and creates a local session. ID tokens are read by the client and are not meant to be sent onward to other services.

Access tokens: what the caller may do

An access token is meant for an API, often called the resource server. The client carries it and presents it when calling the API. The API reads the claims inside to decide whether to allow the call. The client usually should not depend on reading the contents of an access token, because its format is a matter between the authorization server and the API.

Choosing where each claim belongs

A claim that helps the client display the page, such as a preferred name or language, belongs in the ID token. A claim that helps an API make a permission decision, such as a role or a tenant, belongs in the access token. Some claims belong in both. Putting everything in both is lazy and makes tokens larger than necessary.

sequenceDiagram
    participant P as Person
    participant C as Client app
    participant O as Okta
    participant A as API
    P->>C: Open the application
    C->>O: Ask for sign-in and scopes
    O-->>C: ID token and access token
    C->>C: Read ID token claims for display
    C->>A: Call with access token
    A->>A: Read access token claims to decide
    A-->>C: Response
    

Figure 3 follows one visit. The client receives two tokens. It uses the first to know who the person is and forwards the second to the API. The API never needs the ID token. This separation is why claim design starts with asking who the reader is.

Scopes are the shopping list a client brings to Okta. They influence which claims appear.

A scope is a named request that a client application makes when it asks for tokens. Some scopes ask for access to something, such as reading a customer list. Others ask for facts about the person, such as profile details or an email address. The authorization server decides whether to grant each requested scope, and that decision affects the token.

Scopes that unlock facts

In sign-in flows, certain standard scopes are tied to groups of claims. A scope for profile information brings name-related claims. A scope for email brings the email address. A scope for group membership may bring group names. If the client does not request the scope, the matching claims are usually left out. This is how a client signals what it actually needs.

Scopes you define

On a custom authorization server you can create your own scopes, such as one for reading orders and another for approving refunds. These scopes describe permissions of your API. They show up in the access token, and the API checks them before acting. A scope should describe a task in business terms, not a technical detail.

Linking claims to scopes

When you create a custom claim, you can choose whether it is always included or included only when certain scopes are requested. Tying a claim to a scope is a powerful way to respect the principle of asking only for what you need. A rarely needed claim, such as a detailed entitlement list, can ride on its own scope so that most tokens stay small.

flowchart LR
    C["Client requests
scopes"] --> D{"Server grants
each scope?"}
    D -->|"profile"| P["Name claims added"]
    D -->|"email"| E["Email claim added"]
    D -->|"custom scope"| X["Linked custom
claim added"]
    D -->|"not granted"| N["Nothing added"]
    P --> T["Token"]
    E --> T
    X --> T
    

Figure 4 shows the flow. For every scope the client requests, Okta checks whether it may be granted. Each granted scope can pull in its linked claims. A scope that is not granted adds nothing. The result is a token tailored to what the client asked for and what the policy allowed.

A claim needs a value, and the value has to come from somewhere reliable.

Every custom claim answers the question, “Where does this value come from?” Okta offers a few answers, and choosing the right one is the most important design decision for each claim.

Choosing the source

Prefer the source that is closest to the truth and easiest to explain. If the department is maintained by the human resources system and synchronized into the profile, read it from the profile. If permission depends on membership in a team, use groups. If you must combine facts or reshape them, use an expression, but keep it simple enough that a colleague can read and understand it a year from now.

Trust the source, not the sender

The values that end up in a token should come from data that people cannot freely edit themselves. If a person can change their own profile attribute, then a claim built from that attribute can be forged by the person. Always ask who can change the underlying value.

flowchart TD
    HR["HR system"] --> PR["Okta profile
attributes"]
    DIR["Directory"] --> PR
    ADM["Administrators"] --> GR["Group membership"]
    PR --> EX["Expression
or direct copy"]
    GR --> EX
    EX --> CL["Claim value"]
    CL --> TK["Token"]
    

Figure 5 shows the chain. The truth starts in a source system, passes into the Okta profile or group membership, and is then copied or shaped into a claim. A weak link anywhere along that chain weakens the claim. That is why successful teams document the origin of every claim.

Constants and environment labels

A constant claim always carries the same text. It sounds trivial, yet it is surprisingly useful. A claim labelling the environment as test or production helps support teams quickly see which kind of token they are holding. A claim naming the issuing business unit helps shared APIs route requests. Because constants never change per person, they are safe, cheap, and easy to explain.

When one source is not enough

Sometimes the truth lives in two places. The department may come from human resources while the project team comes from a group. An expression can combine them, but each part should still be traceable to its own owner. Write down both sources in the catalog, so that when a value looks wrong, the investigator knows which of the two feeds to check first.

Groups are the most common way to tell an application what a person may do. They are also the easiest way to make a token too big.

A group in Okta is a named collection of people, such as “Finance Approvers” or “Support Tier Two”. Applications love group claims because membership is simple to understand: either you are in the group or you are not. A group claim lists the names of the groups a person belongs to, and the application maps those names to permissions.

Filtering is the key skill

A typical employee belongs to dozens of groups, most of which have nothing to do with a given application. Sending all of them is wasteful and can expose internal structure. Okta lets you filter group claims so that only matching groups appear. You can choose to include groups whose names start with a certain prefix, contain a certain word, or match a pattern, or you can include only groups explicitly assigned to the application.

Naming groups so filters work

A filter is only as good as the names it matches. Teams that adopt a naming convention such as application, role, and environment in every group name can filter with a single simple rule. Teams with free-form names end up with fragile rules that break whenever someone creates a group with a slightly different spelling.

flowchart LR
    ALL["All groups
of the person"] --> F{"Filter rule"}
    F -->|"matches"| K["Kept in claim"]
    F -->|"does not match"| D["Dropped"]
    K --> T["Group claim
in token"]
    

Figure 6 shows the sieve. Everything the person belongs to goes in at the top. Only names matching the rule come out into the token. If the rule is too loose, the token swells. If the rule is too tight, people lose access that they should have.

Expressions let you compute a value instead of copying one. They are powerful and easy to overuse.

Okta includes a small formula language, often called Expression Language, for building values. In a claim, an expression can read fields from the person’s profile, test a condition, combine pieces of text, check group membership, or choose between two outcomes. You write the formula once, and Okta evaluates it for each token issued.

What expressions are good at

• Combining fields: joining a first name and last name into a display name.
• Choosing a value: using one attribute when it is present and a fallback when it is empty.
• Mapping: turning an internal department code into a friendly label.
• Testing membership: producing a simple yes or no claim depending on whether the person belongs to a group.
• Shaping lists: building a list of role names from group names by removing a common prefix.

Keep expressions short

A good expression fits in your head. If it needs three nested conditions and a dozen fields, the real problem lies upstream: the data should be cleaned or prepared in the profile so the claim can be a plain copy. Complex expressions are hard to test, hard to review, and easy to break during an unrelated change.

Where mistakes hide

Missing values are the most common surprise. If a profile attribute is empty, an expression that expects text may produce an error or an empty claim. Every expression should say what happens when a value is absent. Spelling differences in attribute names, extra spaces, and upper versus lower case also cause quiet failures.

flowchart TD
    IN["Inputs
profile, groups, request"] --> EV["Expression
evaluated at token time"]
    EV --> Q{"Value present?"}
    Q -->|"yes"| V["Claim value"]
    Q -->|"no"| FB["Fallback value
or claim omitted"]
    V --> TK["Token"]
    FB --> TK
    

Figure 7 shows the life of an expression. Inputs come in, the formula runs when the token is built, and the outcome is either a value or a planned fallback. Planning the fallback is what separates dependable claims from fragile ones.

Every custom claim carries a rule about when it is added. The choice affects token size and privacy.

When you define a claim, you decide whether it appears in every token of its type or only when specific conditions hold. This is one of the simplest and most effective ways to keep tokens lean.

Why not just include everything?

It is tempting to include every claim in every token so that no application ever complains. This creates three problems. Tokens grow larger and slower. Sensitive facts spread to applications that do not need them. And every application becomes quietly dependent on claims it was never promised, making later cleanup painful.

Why not hide too much?

The other extreme is hiding everything behind special scopes. Clients then have to know a long list of magic words to get a working token, and mistakes lead to confusing failures. A good balance is to include a few essentials always and keep the rest behind clearly named scopes.

flowchart TD
    R["Token request"] --> A["Always-on claims
added"]
    R --> S{"Scope requested?"}
    S -->|"yes"| SC["Scope-linked claims added"]
    S -->|"no"| SK["Skipped"]
    A --> T["Final token"]
    SC --> T
    SK --> T
    

Figure 8 shows the assembly. Essentials are added every time. Optional claims are added only when the matching scope is part of the request. The result is a token that grows only when it has a reason to.

A claim value can be a word, a number, a yes or no, or a list. Applications care about the shape.

The value inside a claim has a type. Applications that read claims make assumptions about that type. A role claim might be expected to be a list, while a department claim is expected to be plain text. If the shape changes, the application can fail in confusing ways.

The single-item list trap

A frequent bug appears when a list claim contains exactly one item. Some systems then deliver it as a plain value rather than a list, and the application breaks because it expected a list. When your claim is meant to be a list, test the cases of none, one, and many.

Keep types stable

Treat a claim like a promise. Once applications rely on a claim being a list of role names, changing it to a single text value or adding spaces to the names breaks them. If you must change a shape, publish a new claim name, let applications migrate, and retire the old claim later.

flowchart LR
    V["Claim value"] --> T{"Shape"}
    T --> TX["Text"]
    T --> NU["Number"]
    T --> BO["Yes or No"]
    T --> LI["List"]
    LI --> L0["None"]
    LI --> L1["One"]
    LI --> LN["Many"]
    

Figure 9 reminds us that a list is really three situations in disguise. An application that handles only the many case will stumble the day a person has just one role or none at all.

Claims are only as good as the profile data behind them. Clean attributes make claims simple.

Most custom claims draw on the person’s profile, the set of attributes Okta stores for each user. Some attributes are built in, such as name and email. Others you can add yourself, such as cost center, employee type, or customer tenant. Because tokens read these values directly, the quality of profile data decides the quality of the claims.

Where profile values come from

• Imported from a source: human resources systems or directories feed values into the profile on a schedule.
• Mapped from an application: an attribute mapping copies or transforms a value from a connected source.
• Entered by administrators: typed in manually for exceptional cases.
• Edited by the person: some attributes may be self-service. Be very careful using these for access decisions.

Make attributes claim-ready

Before an attribute is used in a claim, clean it. Decide on one spelling and format for each value, remove stray spaces, and agree on how to represent empty values. A department stored sometimes as “Finance” and sometimes as “FIN” will cause trouble in every downstream rule. Fixing it once in the profile is far cheaper than patching every claim expression.

Custom attributes need owners

Every custom profile attribute should have a named owner who decides what values are valid and who maintains the source. Without an owner, attributes drift: values go stale, new formats creep in, and claims built on them slowly become wrong.

flowchart LR
    SRC["Source systems"] --> MAP["Attribute mappings"]
    MAP --> PRO["Okta profile"]
    PRO --> CLM["Claims"]
    CLM --> TOK["Tokens"]
    OWN["Attribute owner"] -.-> SRC
    OWN -.-> MAP
    

Figure 10 shows why owners matter. The dotted lines indicate responsibility: someone must watch the sources and the mappings, because the claim at the end simply repeats whatever arrives.

A token is a photograph taken at one moment. Its claims can be out of date by the time it expires.

When Okta builds a token, it reads the person’s profile and groups at that moment and freezes the result into the token. If the person changes teams a minute later, tokens already issued still show the old team until they expire. This is not a bug. It is a natural property of tokens, and it makes lifetime a design decision.

Short versus long lifetimes

Refresh and re-evaluation

Many applications hold a longer-lived refresh credential that quietly obtains new access tokens. When a new token is minted, claims are evaluated again, so changes take effect. How refreshed tokens treat claims depends on your configuration and release, so confirm the behavior in the documentation and by testing.

Matching lifetime to risk

Low-risk reads, such as viewing a public directory, can tolerate longer lifetimes. High-risk actions, such as approving payments, deserve shorter ones, or an extra check at the moment of the action. Policies can set different lifetimes for different applications, so the choice need not be one size for all.

sequenceDiagram
    participant P as Person
    participant O as Okta
    participant A as API
    P->>O: Sign in
    O-->>P: Token with claims at 09:00
    Note over O: Role changes at 09:10
    P->>A: Call at 09:20 with old token
    A->>A: Sees old role
    P->>O: Refresh at 10:00
    O-->>P: New token with new role
    

Figure 11 tells the story. The token carries the role from 09:00. The role changes at 09:10, but the API still sees the old role until the next token is issued. This delay is the price of tokens that work without calling home on every request.

Designing for revocation

Sometimes a person must lose access immediately, for example when they leave the company or when an account is believed to be compromised. Tokens that are already issued do not vanish by themselves. Okta provides ways to end sessions and revoke tokens, and receivers can also check with the authorization server for sensitive actions. Plan for this before an emergency: know how long the longest token lives, know which operations are sensitive enough to deserve an extra check, and rehearse the steps with your security team.

Seeing the whole machine at once makes every later decision easier.

Token claim customization involves several cooperating parts. Understanding who does what helps you find the right place to make a change and the right place to look when something goes wrong.

flowchart LR
    CL["Client application"] -->|"request with scopes"| AS["Authorization server"]
    AS --> PO["Access policy
and rule"]
    PO --> CM["Claim builder"]
    PR["Profile and
groups"] --> CM
    CM --> SG["Signer"]
    SG -->|"token"| CL
    CL -->|"token"| RS["Resource server"]
    RS -->|"fetch public keys"| AS
    AS --> LG["System log"]
    

Figure 12 traces the path. The client asks, the policy approves, the claim builder gathers values from profile and groups, and the signer seals the token. The client hands it to the resource server, which checks the signature using public keys published by the authorization server. Everything noteworthy lands in the system log.

Public keys and trust

The signer uses a private key that never leaves Okta. The matching public key is published so that anyone can verify signatures. Resource servers fetch these public keys and cache them. When keys rotate, the published set changes, so resource servers must be able to refresh their cache.

Before any claim is built, a policy decides whether a token may be issued at all.

Inside a custom authorization server, access policies decide which clients may obtain tokens and under what conditions. A policy is attached to one or more clients. Inside the policy sit rules that look at the situation, such as the kind of request, the person’s group membership, and the scopes requested, and then decide what to issue.

What a rule can decide

• Whether to issue: a rule can allow or refuse the request.
• Which scopes to grant: a rule can limit the scopes a client may receive.
• How long tokens last: a rule can set access and refresh lifetimes.
• Which people it applies to: a rule can target certain groups.

Order matters

Policies and rules are checked in priority order, and the first match wins. A broad rule placed above a narrow one will swallow requests meant for the narrow one. When a token looks wrong, an unexpected rule match is among the first suspects.

flowchart TD
    REQ["Token request"] --> P1{"Policy matches
this client?"}
    P1 -->|"no"| DENY["Refused"]
    P1 -->|"yes"| R1{"First rule
matches?"}
    R1 -->|"yes"| ISS["Issue with this rule's
scopes and lifetime"]
    R1 -->|"no"| R2{"Next rule
matches?"}
    R2 -->|"yes"| ISS
    R2 -->|"no"| DENY
    

Figure 13 shows the walk. If no policy fits the client, the request fails. If a policy fits, its rules are tried in order. The first match issues the token with its own settings. If nothing matches, the request is refused. Many confusing failures turn out to be simple missing matches.

Older and newer sign-in styles describe the same idea with different words and different places to configure it.

Not every application uses tokens of the kind described so far. Many older enterprise applications use a sign-in style that sends an assertion, a signed message of facts, to the application. The individual facts inside are called attributes rather than claims. The goal is the same: carry business facts to the application. The place you configure them differs.

Same discipline, different screens

Both styles benefit from the same habits: send only what is needed, filter groups, document sources, and keep names stable. If you already know how to design claims, you know most of what you need to design attributes. Only the screens and the naming vary.

flowchart LR
    PR["Profile and groups"] --> A["Authorization server
claims"]
    PR --> B["Application sign-on
attribute statements"]
    A --> T["Token to modern app or API"]
    B --> S["Assertion to established app"]
    

Figure 14 reminds us that one source of truth can feed both paths. A department stored once in the profile can appear as a claim for an API and as an attribute for an older application. Keeping one source avoids contradictions between the two.

Tokens travel through browsers, gateways, and servers. Each of them has a limit on how much they will carry.

A token is usually sent as part of a web request. Browsers, proxies, and servers set limits on how large a request header may be. When a token grows too large, requests fail in puzzling ways: a gateway returns an error, a browser drops a cookie, or an application refuses the request without a clear reason. Group claims are the usual cause, because a person in many groups can generate a long list.

Signs a token is too big

• Sign-in works for some people but fails for long-tenured employees who belong to many groups.
• Gateways report oversized header errors only for certain users.
• Problems appear right after a new group-related claim goes live.

Ways to keep tokens small

flowchart TD
    BIG["Token too large"] --> Q1{"Many group names?"}
    Q1 -->|"yes"| F["Filter or convert to roles"]
    Q1 -->|"no"| Q2{"Long claim values?"}
    Q2 -->|"yes"| SH["Shorten or move behind scope"]
    Q2 -->|"no"| LU["Fetch details by lookup"]
    

Figure 15 gives a short routine. Start with groups because they are the usual culprit. If that is not the cause, look at long values. If the data is simply large, it probably belongs in a lookup rather than in the token.

Good names prevent collisions and confusion across dozens of applications.

A claim name is a public promise to every application that reads it. Poor names cause clashes with standard claims, confusion between teams, and trouble when claims need to change.

Avoid clashing with standard names

Standard claims already use common words like name, email, and groups. Reusing these for a different meaning leads to surprises, especially with libraries that expect the standard meaning. Pick distinct names for your own business claims.

Use a consistent pattern

• Short and lowercase: consistent style helps readers and avoids spelling errors.
• Descriptive: a name should hint at the meaning, such as costcenter or tenantid.
• Prefixed when shared widely: a company prefix reduces the chance of collision with other systems.
• Versioned when shape changes: add a version marker only when you must change a shape, never preemptively.

Keep a claim catalog

Maintain a simple catalog listing each claim, its meaning, its source, its owner, which tokens carry it, and which applications use it. The catalog is the single best defence against drift. It also makes cleanup safe, because you can see who depends on a claim before retiring it.

A claim is only useful if the receiver checks the token properly and uses the claim wisely.

Customizing claims is one half of the work. The other half is the application or API reading them correctly. A careless receiver can turn a well-designed token into a security hole.

What a receiver must always check

Handling missing or surprising claims

A good receiver assumes any claim may be missing, empty, or of an unexpected shape, and fails safely. If a role claim is absent, the API should deny rather than guess. Defaulting to broad access when a claim is missing is a classic and dangerous mistake.

sequenceDiagram
    participant C as Client
    participant A as API
    participant O as Okta keys endpoint
    C->>A: Request with access token
    A->>O: Fetch public keys if not cached
    O-->>A: Public keys
    A->>A: Verify signature, issuer, audience, expiry
    A->>A: Read role and scope claims
    A-->>C: Allow or deny
    

Figure 16 shows the order of work. Verification comes first. Only a verified token earns the right to have its claims read. Skipping any of the checks lets forged or misdirected tokens through.

Using libraries wisely

Most application teams use a ready-made library to verify tokens rather than writing the checks themselves. This is wise, because verification has many small details that are easy to get wrong. Still, a library only does what it is configured to do. Teams must set the expected issuer and audience correctly, allow for a small difference between clocks, and make sure the library refreshes public keys. Reviewing the library settings is as important as designing the claims.

Mapping claims to permissions

An API usually keeps its own table connecting claims to actions: the approver role may approve, the viewer role may only read. Keep this table small and clear. If every new claim value demands a code change in many places, the design is too tangled. Aim for one simple place in each application where claims turn into permissions, and make that place easy to test.

Three small stories show the design thinking from start to finish. No code is needed to follow them.

Example 1: A department claim for a staff portal

A staff portal wants to greet people and show department news. The team checks that the department is maintained by the human resources feed and cleaned to a short list of standard names. They add a claim named department to the ID token only, copying the profile value directly. They do not add it to access tokens because no API needs it. They test with a person who has an empty department and confirm the portal shows a neutral message instead of failing.

Example 2: A roles claim for an orders API

An orders API needs to know whether a caller may view, edit, or approve orders. The team names groups with a prefix for the orders application, such as orders followed by the role. They create a claim named roles in the access token. The claim lists only groups matching the orders prefix, with the prefix removed so the API sees short role names. They test people with none, one, and many roles, and confirm the API denies callers with no roles.

Example 3: A tenant claim for a customer-facing app

A software provider serves several business customers from one application. Each user has a tenant identifier stored in a controlled profile attribute that only administrators can change. The team adds a tenant claim to the access token, always included, and instructs the API to filter every database query by that tenant. They confirm no self-service screen lets users edit the attribute. A forged tenant would let one customer read another’s data, so the source of this claim is guarded carefully.

flowchart TD
    N["Business need"] --> W["Who reads it?"]
    W --> T["Which token?"]
    T --> S["What source?"]
    S --> C["Define the claim"]
    C --> X["Test edge cases"]
    X --> D["Document in catalog"]
    D --> R["Release"]
    

Figure 17 shows the path every example followed. Start from the need, identify the reader, choose the token, pick a trustworthy source, define the claim, test unusual cases, record it, and release. Skipping any step leads to the problems described in earlier chapters.

A token is a bearer item. Whoever holds it can use it, so every claim is a small disclosure risk.

Tokens are readable

Remember that the body of a token is encoded, not secret. Anyone who gets a copy, from a browser history, a log file, a support screenshot, or a network trace, can read the claims. Never place passwords, secrets, government numbers, or highly sensitive personal details in claims.

Principles to follow

Privilege escalation through claims

If an attacker can change something that feeds a claim, they can change what the API believes about them. Typical weak points are self-editable profile fields, group membership that helpdesk staff can change without review, and imported values from sources that are not well protected. Treat anyone who can change claim inputs as holding some of the power of the claim itself.

Audience and confused deputies

A token meant for one API should not be accepted by another. Always set a clear audience for each authorization server or API and make receivers check it. Otherwise a token obtained for a low-risk service might be replayed against a high-risk service.

flowchart TD
    A["Attacker goal:
higher access"] --> P1["Edit own profile
attribute"]
    A --> P2["Join a privileged group"]
    A --> P3["Replay token to
wrong API"]
    P1 --> C1["Control: admin-only attribute"]
    P2 --> C2["Control: approval and review"]
    P3 --> C3["Control: audience check"]
    

Figure 18 pairs three simple attack ideas with their controls. None of the controls is exotic. Together they close most of the easy routes to abusing claims.

You cannot fix what you cannot see. Okta records activity that helps you understand what tokens are doing.

Okta’s system log records events such as token requests that were granted or refused, policy matches, and changes made by administrators. Reading these records helps you answer questions like why a token was refused, who changed a claim, and when a problem began. How long events are kept and which events are recorded depend on your license and release, so confirm in the documentation.

What to watch

• Refusals: a rise in denied token requests often points to a policy or scope mistake.
• Administrative changes: who edited a claim, a policy, or a scope, and when.
• Key events: signing key creation and rotation.
• Unusual patterns: a client suddenly requesting many tokens or powerful scopes.
• Downstream errors: API reports of missing claims or oversized headers.

Useful measures

flowchart LR
    ACT["Token activity"] --> LOG["System log"]
    ADM["Admin changes"] --> LOG
    LOG --> ALR["Alerts"]
    LOG --> DSH["Dashboard"]
    ALR --> TM["On-call team"]
    DSH --> OWN["Claim owners"]
    

Figure 19 shows two audiences for the same events. Alerts reach responders quickly when something breaks. Dashboards help owners see slow trends such as growing token sizes or rising numbers of changes.

Never release a claim you have not looked at. Okta provides a way to preview tokens before real users depend on them.

Okta’s authorization server area includes a token preview facility. You choose a client, a person, a grant type, and the scopes, and the preview shows the token that would be issued. It is the quickest way to confirm that a claim appears, has the right shape, and respects your rules. Exact options vary by release, so look at your own console.

A test checklist

flowchart LR
    DR["Draft claim"] --> PV["Preview in console"]
    PV --> ED{"Edge cases pass?"}
    ED -->|"no"| DR
    ED -->|"yes"| TS["Test application"]
    TS --> PR["Production release"]
    

Figure 20 shows a loop. If edge cases fail, return to the draft. Only after the preview and a test application agree should the change reach production. Preview shows what Okta would issue, but only the real application proves the application understands it.

Testing across environments

Many organizations keep a separate Okta environment for testing. Build and preview claims there first, using people whose profiles resemble real ones. When the claim works, repeat the same steps in production in a quiet period, and preview again with a few real accounts. Differences between environments, such as missing groups or different attribute values, are among the most common reasons a tested change misbehaves after release. Keep notes of each test so you can repeat it after future changes.

Claims live for years. Someone must own them, change them carefully, and retire them when no longer needed.

Who does what

A simple change process

Requests for new claims should include the reader, the token type, the source, the sensitivity, and the expected benefit. The platform team reviews, builds in a test environment, previews, and releases with a note in the catalog. Retiring a claim follows the reverse path: announce, wait, remove, and update the catalog.

flowchart LR
    RQ["Request"] --> RV["Review"]
    RV --> BD["Build in test"]
    BD --> PV["Preview and test"]
    PV --> RL["Release"]
    RL --> CT["Update catalog"]
    CT --> RE["Periodic review"]
    RE --> RT["Retire if unused"]
    

Figure 21 shows a complete lifecycle. The periodic review is the step teams forget. Without it, unused claims pile up and nobody remembers why they exist.

Customization is powerful, and like every power it comes with costs.

Key trade-offs

• Convenience versus size: more claims save lookups but make tokens heavier.
• Freshness versus speed: short lifetimes keep claims fresh but cost more round trips.
• Central versus per-application: shared claims reduce duplication but create coupling.
• Flexibility versus clarity: clever expressions give power but reduce readability.

Teams that run claims well tend to reuse a handful of simple patterns.

flowchart LR
    TK["Thin token
subject, roles, tenant"] --> API["API"]
    API --> LK["Entitlement lookup
service"]
    LK --> DT["Detailed permissions"]
    DT --> API
    

Figure 22 illustrates the thin token pattern. The token proves who the caller is and carries a few stable facts. When the API needs more detail, it asks a lookup service. This keeps the token compact and the detailed data current.

These habits look convenient at first and cause pain later.

This chapter gathers the habits that separate calm claim programs from chaotic ones.

Best practices

Common mistakes

A short pre-release routine

Before any claim change goes live, run through a quick routine. Check the catalog entry is complete. Confirm the source is trustworthy and has an owner. Preview at least four kinds of people: a typical one, one with empty values, one with many groups, and one with none. Confirm the token size is comfortably within limits. Tell the application teams. Keep a note of how to undo the change. This routine takes less than an hour and prevents most of the painful surprises described in this guide.

A short yearly review

Once a year, walk through the whole list of claims with application owners. Ask whether each claim is still read, whether its meaning is still right, whether its source is still reliable, and whether it still needs to be as sensitive as it is. Retire what is unused, shorten what has grown, and update the catalog. Small regular tidying beats occasional large rescues.

Three fictional companies show how these ideas play out in practice.

flowchart LR
    P["Problem noticed"] --> I["Inspect token in preview"]
    I --> S["Find claim source"]
    S --> F["Fix data or rule"]
    F --> T["Retest edge cases"]
    T --> C["Update catalog"]
    

Figure 23 shows what the scenarios had in common. Each team looked at the actual token, found the true source, fixed the cause, retested, and recorded the lesson so it was not lost.

Quick answers to the questions beginners ask most often.

A token is a badge. Claims are what is printed on it. Your job is to print the right things, from the right sources, for the right readers.

We began with the idea that applications need facts to make decisions, and that claims carry those facts. We saw how authorization servers, scopes, policies, and signing keys work together, how ID tokens and access tokens serve different readers, and how values can come from profile attributes, groups, expressions, or constants. We explored group filtering, value shapes, lifetimes, size limits, naming, and how receivers must verify tokens before trusting them.

The craft lies in a few steady habits: start from the reader, trust only reliable sources, keep tokens small, test edge cases with preview, document every claim in a catalog, and review and retire claims regularly. Treat claims as promises, protect them as disclosures, and confirm Okta-specific details in your own console and the official documentation.