Delegation and impersonation
Four of the protocols iya-sts speaks let one party obtain a token about somebody else:
- the OAuth 2.0 token exchange (RFC 8693), with this service’s own tokens or with RFC 7523 / RFC 7522 / SAML 1.1 assertions as its input;
- WS-Trust’s
OnBehalfOfandActAs(1.3, 1.4); - Kerberos’ two Microsoft extensions, S4U2Self and S4U2Proxy (MS-SFU), and a forwarded ticket-granting ticket;
- GNAP’s trusted client presenting a user assertion, and a resource server deriving a downstream token (RFC 9635, RFC 9767).
None of the four specifications says who may do this. RFC 8693 section 5 leaves it to “the policy of the authorization server”, and WS-Trust describes only what a requester asks for. Active Directory’s answer for Kerberos is a handful of account attributes.
iya-sts answers the question once, for all four protocols:
- the same settings on the same directory entries;
- the same two questions asked of the same XACML issuance policy;
- the same record of every act, issued or refused, on Monitoring → Delegation.
This page describes that model, how to configure it, what each protocol
accepts and issues, the claims that come out, and a worked example of every
kind of act, with curl wherever the protocol is HTTP.
Contents
- At a glance
- The four parties
- Delegation, impersonation, and acting for yourself
- Configuring who may act for whom
- How an act is decided
- Token types: what goes in and what comes out
- Claims in the issued token
- Worked examples
- Per protocol
- Refusals and troubleshooting
- Watching it
At a glance
| Protocol | Mechanism | Semantics | What the request presents | What is issued | Where the actor shows in the result |
|---|---|---|---|---|---|
| OAuth 2.0 (RFC 8693) | token exchange, exchange_semantics=delegation or an actor token |
delegation | subject_token (+ optional actor_token) of type access_token, refresh_token, id_token, jwt, saml2, saml1 or a Kerberos token |
an access token (issued_token_type …:access_token); a refresh token on request; an ID Token when openid survives; a Kerberos token when requested_token_type asks for one |
nested act claim; S4U_DELEGATION_INFO in a Kerberos token |
| OAuth 2.0 (RFC 8693) | token exchange, exchange_semantics=impersonation |
impersonation | the same | the same | nowhere (a prior act is kept) |
| WS-Trust 1.4 | <wst14:ActAs> |
delegation | a SAML 2.0 or SAML 1.1 assertion or a JWT this STS issued, or a Kerberos ticket obtained by S4U2Proxy or with a forwarded TGT, plus the requester’s own credential | SAML 2.0, SAML 1.1, JWT or a Kerberos token (wst:TokenType) |
SAML 2.0: del:Delegate in a Delegation Restriction condition; JWT: nested act; SAML 1.1: a delegates attribute; Kerberos: S4U_DELEGATION_INFO |
| WS-Trust 1.3 | <wst:OnBehalfOf> |
impersonation | the same | the same | nowhere (a prior chain is kept) |
| Kerberos (MS-SFU) | S4U2Self (PA-FOR-USER, PA-S4U-X509-USER) |
impersonation | the service’s own TGT | a service ticket to the service itself, forwardable only when allowed | nowhere |
| Kerberos (MS-SFU) | S4U2Proxy, classic or resource-based | delegation | the service’s TGT and the user’s forwardable evidence ticket | a service ticket to the back end | S4U_DELEGATION_INFO in the PAC |
| Kerberos (RFC 4120) | forwarded TGT | recorded as impersonation | a forwardable TGT | a forwarded TGT | nowhere |
| GNAP (RFC 9635) | trusted client (gnapSkipInteraction) with user.assertions |
impersonation | an id_token or saml2 assertion issued to that client |
GNAP access tokens in the client’s format | nowhere |
| GNAP (RFC 9767) | existing_access_token |
delegation | a GNAP access token issued for the deriving resource server | a derived GNAP access token, no wider than the original | act, in all five token formats |
Two more grants are recorded on Monitoring → Delegation as delegation, because a third party is asserting who the subject is: the JWT bearer grant (RFC 7523) and the SAML 2.0 bearer grant (RFC 7522). They are not decided by the policy on this page; their own pages say what they check.
The four parties
Every act names four parties. Each protocol finds them in its own message:
| Party | What it is | OAuth 2.0 token exchange | WS-Trust | Kerberos | GNAP |
|---|---|---|---|---|---|
| Subject | who the new token is about | the subject_token’s subject |
the subject of the token inside OnBehalfOf / ActAs |
the user named in S4U2Self (PA-FOR-USER or PA-S4U-X509-USER), or the client of S4U2Proxy’s evidence ticket |
the person the user assertion names, or the original token’s person |
| Actor | who is asking | the actor_token’s subject; without one, the authenticated client |
the requester (whoever authenticated the RST) | S4U2Self: the service asking for a ticket to itself; S4U2Proxy: the front end presenting the evidence ticket | the client instance, or the deriving resource server |
| S (source) | the application the subject’s token was issued for | the subject_token’s aud, else its client_id / azp; for a Kerberos ticket, the exchanging client |
the delegated assertion’s Audience; for a Kerberos ticket, the requester |
the service the evidence ticket was issued for | none for a user assertion; the deriving resource server for a derivation |
| R (target) | the application the new token is for | the one audience or resource |
the AppliesTo |
the service named in the TGS-REQ | each resource server the requested rights resolve to |
Parties are entries in the directory.
- An application is named by its identifier, client ID or registered
audience (
oauthAudience),AppliesTo(wstrustAppliesTo) or service principal name (SPN@REALM). - A person is named by their username.
Every target is resolved to the application that registered it before anything is compared. A target that no application registers is refused.
Delegation, impersonation, and acting for yourself
An act has one of three semantics:
- Delegation. The actor acts for the subject visibly.
- The issued token names the actor: RFC 8693’s
actclaim, a SAML 2.0 Delegation Restriction condition, or a SAML 1.1delegatesattribute. - Kerberos S4U2Proxy’s ticket is the front end’s request on the user’s behalf, and its PAC names every service it passed through.
actclaims nest. A token that already carried an actor keeps it under the new one (RFC 8693 section 4.1).
- The issued token names the actor: RFC 8693’s
- Impersonation. The actor obtains a token that is simply the subject’s.
- Nothing in the token names the actor. Monitoring → Delegation is the only place the act is visible.
- A prior
actis still kept. An exchange never turns a delegated token into an ordinary one.
- Self. The actor is the subject, or is S keeping the token for S.
- Nobody is acted for, and nothing beyond the protocol’s own checks is needed.
- A self exchange that names no target is for the subject token’s own audience.
The policy chooses the semantics, by this precedence:
- what the request asks for:
- RFC 8693: this service’s extension parameter
exchange_semantics=delegation|impersonation; - WS-Trust: the element (
ActAsis delegation,OnBehalfOfis impersonation); - Kerberos: the extension (S4U2Self is impersonation, S4U2Proxy is delegation);
- GNAP: the act (a user assertion is impersonation, a derivation is delegation);
- RFC 8693: this service’s extension parameter
- the actor’s default (
appDefaultDelegationSemantics); - the subject’s default (
stsDefaultDelegationSemantics); - the realm’s
delegation.defaultSemantics(delegation unless set).
A request may only ask for semantics that both the actor and the subject allow:
- the actor’s
appDelegationSemantics— empty means delegation only; - the subject’s
stsDelegationSemantics— empty means either.
Configuring who may act for whom
The common controls
These are the same for all four protocols. They live on the directory
entries, so they can be edited from the console, through /admin-api, or with
an ldapmodify. There are no per-protocol copies.
On an application entry (Directory → Applications → the application → Configuration, Every protocol):
| Attribute | Set on | Meaning | Active Directory analogue |
|---|---|---|---|
appAllowedToDelegateTo |
S | Applications S may hand a subject on to. For an impersonation, the applications the actor may reach. | msDS-AllowedToDelegateTo |
appAllowedToActOnBehalfOf |
R | Applications and people R accepts acting for others: resource-based delegation, set by the target’s owner. | msDS-AllowedToActOnBehalfOfOtherIdentity |
appDelegationSemantics |
the actor | Semantics it may use, delegation and/or impersonation. Empty means delegation only. |
TRUSTED_TO_AUTHENTICATE_FOR_DELEGATION (impersonation) |
appDefaultDelegationSemantics |
the actor | Its semantics when the request names none. | — |
appDelegationSubjectGroup |
the actor | Groups, by DN, whose members it may act for. Empty means anybody not protected. | — |
appNotDelegated |
an application as subject | Never acted for. | NOT_DELEGATED |
appMayAct |
an application as subject | The DN of one party it names as its delegate: tokens about it carry may_act naming that party, as the issuance policy assigns it. |
— |
appRequiredRole |
S or R | Roles a subject must hold for the application; a subject with none of them has no authority to be acted for there. | — |
krb5TrustedForDelegation |
a Kerberos service | Kerberos only, off by default. Unconstrained delegation: it may receive and use a user’s forwarded TGT. | TRUSTED_FOR_DELEGATION |
appAllowedProtocol |
any application | Protocols the application is used with. The controls above apply to whichever of WS-Trust, OAuth 2.0, Kerberos and GNAP it lists. | — |
The values of appAllowedToDelegateTo and appAllowedToActOnBehalfOf are
application identifiers (for a Kerberos service, SPN@REALM, such as
HTTP/backend.example.com@EXAMPLE.COM). Neither list may name the
application itself; the console and the API refuse that value
(STS-REG-0335). On the console each of the two cells carries a search over
the realm’s applications, and appDelegationSubjectGroup one over its groups
(see Finding the other application of a delegation in
Applications).
On a person’s entry (Directory → Users → the person, Who may act for them):
| Attribute | Meaning |
|---|---|
stsNotDelegated |
Never acted for, by anybody (NOT_DELEGATED). |
stsDelegationSemantics |
Semantics this person may be acted for with. Empty means either. |
stsDefaultDelegationSemantics |
Their default, after the actor’s. |
stsMayAct |
One party (the DN of a person or an application) this person names as their delegate. Their access tokens (and WS-Trust JWTs) carry RFC 8693 section 4.4’s may_act claim naming it — the issuance policy’s assign-may-act question assigns it, and a realm’s policy may name another party or none. A person sets it themselves on /portal/delegate, by typing the DN or by finding a person by part of their username (see below). |
Finding a delegate on /portal/delegate. Type at least three
characters of the person’s username (uid). The page searches when you stop
typing for three seconds, or as soon as you press Enter. It lists at most ten
people, each with their username, name and DN. If more people match, it says
so, and typing more of the name narrows the list. It finds only native
people of your own realm: never one a federation partner’s or a consumer
provider’s sign-in created (their entry carries stsProvisionedBy), and
never you, a disabled account, a service account, a group or an application.
A person who was created here and later linked a partner account is still
native. To name an application, type its DN in the box below the search. The
operation is GET /account-api/delegate/candidates?q=.
Realm settings
The four delegation.* settings are on Protocols → Delegation, the two
token-exchange settings on Protocols → OAuth 2.0 / OIDC, the two GNAP
settings on Protocols → GNAP and the two Kerberos settings on
Protocols → Kerberos. All of them are at GET /admin-api/config:
| Setting | Environment variable | Default | What it does |
|---|---|---|---|
delegation.defaultSemantics |
STS_DELEGATION_DEFAULT_SEMANTICS |
delegation |
The last word on semantics. |
delegation.protectedGroups |
STS_DELEGATION_PROTECTED_GROUPS |
(none) | Groups whose members are never acted for: Active Directory’s Protected Users. The console’s Admin Read and Admin Write rosters are always protected as well. |
delegation.actorRole |
STS_DELEGATION_ACTOR_ROLE |
DELEGATION_ACTOR |
The role a person needs before they may act for anybody. An application needs no role. The role is not created for you: make it with roles/create-role and add members with roles/add-member. |
delegation.maxRecords |
DELEGATION_MAX_RECORDS |
2000 |
How many acts Monitoring → Delegation keeps. |
oauth2.tokenExchangeAudience |
STS_OAUTH2_TOKEN_EXCHANGE_AUDIENCE |
authorization-server |
What an assertion presented to a token exchange may be addressed to (below). |
oauth2.tokenExchangeRefreshToken |
STS_OAUTH2_TOKEN_EXCHANGE_REFRESH_TOKEN |
when-requested |
never, when-requested or always: whether an exchange returns a refresh token. oauthTokenExchangeRefreshToken on the exchanging client’s entry overrides it. |
gnap.tokenDerivation |
STS_GNAP_TOKEN_DERIVATION |
true |
Whether a GNAP resource server may derive a token at all. |
gnap.maxDerivationDepth |
STS_GNAP_MAX_DERIVATION_DEPTH |
2 |
How many times a token may be derived: how many deriving resource servers its act chain may name, the original client at its foot not counted. |
krb5.s4uRoleSubject |
KRB5_S4U_ROLE_SUBJECT |
user |
Under S4U2Self and S4U2Proxy, whose roles the KDC checks against the role a service’s entry requires (appRequiredRole): user, the person the ticket is for, or service, the service that asks (Kerberos). |
krb5.crossRealmClassicDelegation |
KRB5_CROSS_REALM_CLASSIC_DELEGATION |
false |
Whether classic constrained delegation (appAllowedToDelegateTo) may cross a Kerberos trust; both realms must turn it on. Resource-based delegation crosses without it. |
All are runtime settings, per realm. This table is a copy: the live values
are on the console pages and at GET /admin-api/config, and every setting
is in Configuration.
Setting them through the API
Every control above is reachable by a machine. Get an /admin-api access
token with admin:read admin:write into $TOKEN as
Management API → Getting a token shows;
the calls below use this helper:
BASE=https://sts.example:8081 # add /realm/<id> to work in a trust realm
api() { # api <path under /admin-api> '<json body>'
curl -sk -X POST "$BASE/admin-api/$1" \
-H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
-d "$2"
}
An application’s controls — several at once with update-fields, or one
value at a time with set, add and remove:
# apigw1 may hand a subject on to esb1, may delegate or impersonate,
# delegates unless asked otherwise, and acts only for members of one group.
api applications/update-fields '{"application":"apigw1","fields":{
"appAllowedToDelegateTo":["esb1"],
"appDelegationSemantics":["delegation","impersonation"],
"appDefaultDelegationSemantics":"delegation",
"appDelegationSubjectGroup":["cn=api-users,ou=groups,dc=example,dc=com"]}}'
# Resource-based instead: the TARGET names who may act toward it.
api applications/add '{"application":"esb1",
"attribute":"appAllowedToActOnBehalfOf","value":"apigw1"}'
# An application nobody may act for.
api applications/set '{"application":"payroll-batch",
"attribute":"appNotDelegated","value":"TRUE"}'
In update-fields, a multi-valued attribute is made to hold exactly the
values given and an empty string or array clears an attribute.
A person’s controls:
api users/set-not-delegated '{"user":"carol","value":true}'
api users/set-may-act '{"user":"alice","delegate":"uid=bob,ou=users,dc=example,dc=com"}'
api users/set-may-act '{"user":"alice","delegate":""}' # clears it
api users/set-delegation-semantics '{"user":"alice",
"semantics":["delegation"],"default":"delegation"}'
The realm’s settings, and the role a person needs to act:
api config/set '{"key":"delegation.protectedGroups",
"value":"cn=executives,ou=groups,dc=example,dc=com"}'
api roles/create-role '{"role":"DELEGATION_ACTOR"}'
api roles/add-member '{"role":"DELEGATION_ACTOR","kind":"user","member":"dave"}'
Reading it back — the whole policy, paged into the configured pairs, the actors and the protected people:
curl -sk -H "Authorization: Bearer $TOKEN" "$BASE/admin-api/delegation/policy" | jq
The OpenAPI document at GET /admin-api/openapi.json describes every one of
these operations and their bodies.
With LDAP. The same attributes can be written with ldapmodify over
LDAPS, by an identity holding Admin Write in product mode
(LDAP); nothing caches them, so the
next request reads the change:
dn: uid=alice,ou=users,dc=example,dc=com
changetype: modify
replace: stsDelegationSemantics
stsDelegationSemantics: delegation
-
replace: stsMayAct
stsMayAct: uid=bob,ou=users,dc=example,dc=com
Development and product mode
Product mode refuses. Development mode asks the same questions, issues the token anyway, and writes on the act “WOULD HAVE BEEN REFUSED in product: …”, so a client under test still gets a working token and the operator sees what would break.
| Development | Product | |
|---|---|---|
| A policy refusal (OAuth, WS-Trust, GNAP) | token issued; the act records what would have refused it | refused |
may_act naming somebody else (token exchange, WS-Trust, GNAP) |
refused | refused |
An actor_token that is not the exchanging client’s own, or not addressed to it or this server |
refused (STS-OAUTH-0955, 0956) |
refused |
WS-Trust OnBehalfOf and ActAs in one request |
refused | refused |
| Kerberos delegation rules | enforced; the fixture services carry rules so every refusal and success is reachable | enforced; there are no rules until an operator writes one |
A subject_token / actor_token this realm cannot verify |
read without verifying, for its name | refused (STS-OAUTH-0555, 0556) |
| A token this realm has revoked | refused | refused (STS-OAUTH-0557) |
A jwt assertion from an undeclared issuer, or that does not verify |
read without verifying | refused |
A saml2 / saml1 assertion that does not verify |
refused | refused |
| A scope wider than the subject token’s | issued, and logged | refused (invalid_scope) |
| WS-Trust delegation with no requester credential | accepted | refused (wst:FailedAuthentication) |
| WS-Trust inner token | any assertion | a SAML assertion or JWT this STS signed, unexpired, naming a person |
| Client authentication at the token endpoint | not checked outside RFC 9700, OAuth 2.1 and FAPI mode | checked (product mode implies RFC 9700 mode) |
See What is not checked for the rest of what development mode lets through.
How an act is decided
The issuance policy refuses in this order. The first refusal that applies is the one the client hears.
may_actnames somebody else. The subject’s token carriesmay_act(RFC 8693 section 4.4) and it does not name the actor. Refused in every mode: the token itself says no.- More than one target. A token is issued for exactly one.
- The target is not registered. No application in the realm registers it.
- No target, unless the act is self.
- The subject is protected:
stsNotDelegatedorappNotDelegated, a member of adelegation.protectedGroupsgroup, or on the console roster. Then, for a Kerberos act across a trust only, the trust’s own rules: a disabled trust, a direction that does not accept the user’s realm, a realm the service does not list inkrb5S4uSelfRealm, classic delegation whilekrb5.crossRealmClassicDelegationis off, and a TGT the trust’s attributes do not let cross (Delegation across the trust). - The actor is unknown, or is a person without the role
delegation.actorRolenames. - The semantics are not allowed by the actor or the subject.
- The subject is outside the actor’s
appDelegationSubjectGroup, unless the subject’smay_actnames the actor. - The subject has no authority. It holds none of the roles the
application requires (
appRequiredRole): S for a delegation, R otherwise. - The relationship does not hold.
- Delegation: S must delegate to R (
appAllowedToDelegateToon S, orappAllowedToActOnBehalfOfon R). In addition, the actor must be S, R, or a party R accepts by name. - Impersonation: the actor must reach R: R is the actor itself, R is
on the actor’s
appAllowedToDelegateTo, or R accepts the actor.
- Delegation: S must delegate to R (
Everything else is allowed, with the semantics chosen above and R as the audience.
The KDC refuses in both modes, as it always has: in development its fixture accounts carry delegation settings (seeded onto their entries) so that every refusal and every success can be reached, and a KDC that issued a refused ticket would change what goes on the wire. The act on Monitoring → Delegation still says what refused it.
Writing your own rules
The rules are rules of the issuance policy, so a realm can add its own. A
realm’s issuance policy (Protocols → XACML, the Policies tab) is asked first;
the built-in policy answers whatever it says nothing about. To refuse more,
write a Deny on action-id exchange-token with the obligation
urn:sts:xacml:obligation:exchange (verdict refuse, refusal policy); the
client then hears its protocol’s policy refusal. The attributes a rule can
test — the four parties, both semantics, may_act, the protocol and the
mode — are listed in XACML. The may_act a person’s tokens carry
is the answer to a second question, assign-may-act, which a realm’s policy
can also answer.
Token types: what goes in and what comes out
RFC 8693 token exchange
The grant type is urn:ietf:params:oauth:grant-type:token-exchange, at
POST /oauth2/token (/realm/<id>/oauth2/token in a trust realm).
| Parameter | Required | What this service does with it |
|---|---|---|
subject_token |
yes | The token the new one is about. |
subject_token_type |
yes | One of the types below. It must be what the token is: an ID Token declared as an access token is refused (STS-OAUTH-0628). |
actor_token |
no | A token about the actor. Without it, the authenticated client is the actor. In every mode it must have been issued to the exchanging client and be addressed to that client or to this authorization server (STS-OAUTH-0955, STS-OAUTH-0956); an assertion has its own audience rule (below). |
actor_token_type |
exactly when actor_token is sent |
One of the types below, or Native SSO’s device secret. |
audience / resource |
for anything but a self exchange | The target. Both may be sent, but together they must name one target, registered on an application (oauthAudience, or its client ID). |
scope |
no | May narrow the subject token’s scope, never widen it. Omitted, the subject token’s scope is carried forward. |
requested_token_type |
no | urn:ietf:params:oauth:token-type:refresh_token asks for a refresh token beside the access token. A Kerberos token type asks for a Kerberos token for the one target, with oauth2.tokenExchangeKerberosOutput on (refused while it is off). Any other value is read as a request and answered with an access token, never refused. |
exchange_semantics |
no | This service’s extension: delegation or impersonation, sent at most once. Any other value is invalid_request (STS-OAUTH-0795). |
authorization_details |
no | RFC 9396, as for a direct grant. |
Accepted as subject_token_type and actor_token_type:
| URI | What it must be |
|---|---|
urn:ietf:params:oauth:token-type:access_token |
an access token this realm issued |
urn:ietf:params:oauth:token-type:refresh_token |
a refresh token this realm issued (it is opened and verified like any other) |
urn:ietf:params:oauth:token-type:id_token |
an ID Token this realm issued |
urn:ietf:params:oauth:token-type:jwt |
any other JWT this realm signed (a WS-Trust JWT, for one), or an RFC 7523 assertion from a declared issuer |
urn:ietf:params:oauth:token-type:saml2 |
an RFC 7522 SAML 2.0 assertion from a declared issuer, base64url-encoded |
urn:ietf:params:oauth:token-type:saml1 |
a SAML 1.1 assertion from a declared issuer, base64url-encoded |
http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#GSS_Kerberosv5_AP_REQ, and the profile’s five other ValueTypes |
a Kerberos ticket for this service’s own SPN in an AP-REQ, base64url: as the subject, obtained by Kerberos delegation (S4U2Proxy naming the client last, or a forwarded TGT); as the actor, the client’s own. oauth2.tokenExchangeKerberosInput |
urn:openid:params:token-type:device-secret |
as actor_token_type only, beside an id_token subject: OpenID Connect Native SSO, which is not a delegation (OpenID Connect flows) |
Anything else is invalid_request (STS-OAUTH-0627).
The response is a token response with issued_token_type, always
urn:ietf:params:oauth:token-type:access_token, because it describes the
token in the access_token member — even when a refresh token was asked for
and came back beside it. The refresh_token member is an ordinary refresh
token of this service, bound to the same DPoP key or client certificate as
the access token. scope names what the access token carries and is left out
when it carries nothing; an id_token comes back only when openid
survives, which it does not on a token for another resource server
(RFC 9068 section 2.2.3). token_type is DPoP when the exchange was made
with a DPoP proof and Bearer otherwise.
WS-Trust
The token inside OnBehalfOf or ActAs is one this STS issued: a SAML 2.0
or SAML 1.1 assertion, or a JWT in the wsse:BinarySecurityToken an RSTR
carries one in.
What is issued is chosen by wst:TokenType:
wst:TokenType |
Issued |
|---|---|
urn:ietf:params:oauth:token-type:jwt |
a JWT in a wsse:BinarySecurityToken with that ValueType |
http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1 or urn:oasis:names:tc:SAML:1.0:assertion |
a SAML 1.1 assertion; an ActAs names its delegates in a delegates attribute, because SAML 1.1 has no Delegation Restriction |
anything else, or none (http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0 is the usual one) |
a SAML 2.0 assertion |
See WS-Trust.
A Kerberos ticket in either protocol is the Kerberos Token Profile 1.1’s AP-REQ, for this service’s own SPN. Delegated, it must have been obtained by Kerberos delegation: by S4U2Proxy, its PAC naming the party that presents it last, or with a TGT forwarded to a party trusted for delegation. A ticket the subject made for this service and handed over is refused in every mode. Issued, it is a ticket for the target’s Kerberos service whose PAC names every party that acted. See WS-Trust and the token exchange.
Kerberos and GNAP
Kerberos issues service tickets (and, for a forwarded TGT, a ticket-granting
ticket); the evidence S4U2Proxy consumes is a forwardable service ticket. GNAP
issues tokens in the client’s or resource server’s configured format —
jwt-signed, jwt-encrypted, macaroon and the others
GNAP lists — and a derivation consumes a GNAP
access token issued for the deriving resource server.
Claims in the issued token
act: who acted
On a delegation, the access token carries RFC 8693 section 4.1’s act:
- The outermost entry is the current actor: the
actor_token’ssub, or — with no actor token — the exchanging client. - Every entry carries
iss, the issuer of the token it is in. An entry copied from the subject token keeps its owniss; one without is given this issuer only when this service issued the subject token. - A client has one form:
urn:sts:client:<client_id>in RFC 9700 mode (and so in product mode), and the bareclient_idotherwise — thesubits ownclient_credentialstoken carries. - The chain begins with the original client. On the first exchange of a
token this realm issued (one with no
act), the client it was issued to is nested beneath the actor — unless that client is the actor. Only the outermostactis the current actor; the nested ones are history. - An impersonation adds nothing, and keeps any
actthe subject token already carried.
act is a reserved claim name: a custom claim cannot set or replace it.
may_act: who may act
An access token about a person whose entry carries stsMayAct (or an
application with appMayAct) carries RFC 8693 section 4.4’s may_act,
naming the delegate: a person by their urn:uuid: subject, an application
by its client ID. When that token is later exchanged, an actor other than the
one named is refused in every mode (STS-OAUTH-0620). The comparison
accepts both forms of a client’s name. may_act is read only off a verified
subject token.
Introspection
POST /oauth2/introspect returns a token’s act, nested as in the token, and
its may_act (RFC 8693 section 7.2), in the JSON response and in the RFC 9701
JWT alike. As for every other member, an authenticated caller the token is not
for is told only that it is not active.
Custom claims
The claims a delegated token carries beyond the protocol’s own come from the
same places as any other token’s. They are evaluated for the subject, not
for the actor, and placeholders read what the token itself says — under a
token exchange, ${sub} is the subject’s.
- The realm’s sets (Protocols → OAuth 2.0 / OIDC, the Custom claims tab,
and
/admin-api/claims): typed claims and directory attributes; and the groups claim (groups.claim,groups.claimName,groups.claimValue, on Directory → Groups). An exchanged access token carries the realm’saccess_tokenset. - The application’s own rows, added to the realm’s and winning by name.
For an exchanged access token, the application is the exchanging
client (the token’s
client_id). For a WS-Trust token, it is theAppliesTo’s application: its access-token claims for a JWT, its custom SAML attributes for an assertion, and its groups-claim settings. - Kerberos puts the realm’s and the service’s
kerberos-pacclaims in the PAC (Kerberos).
# Every access token from now on: a typed claim, and a directory attribute.
api claims/add '{"set":"access_token","name":"dept","value":"engineering"}'
api claims/add-attribute-claim '{"set":"access_token","name":"cost_center",
"attribute":"costCenter"}'
# Only tokens issued to apigw1 (including the ones it exchanges for):
api applications/set-custom-claim '{"application":"apigw1","set":"access_token",
"name":"tier","value":"gold-${username}"}'
# What the realm's sets would put in a token about alice:
curl -sk -H "Authorization: Bearer $TOKEN" "$BASE/admin-api/claims?user=alice" | jq .attributeClaims
A value may use ${username}, ${sub}, ${email}, ${name},
${given_name}, ${family_name}, ${client_id}, ${audience}, ${now} and
${iso}. Custom claims are additive only: a name the protocol sets itself
(iss, sub, aud, exp, scope, client_id, act and the rest) is
refused when you configure it. The full rules are in
OAuth 2.0 and OpenID Connect and
Applications.
A JWT assertion’s own extra claims reach the token it is exchanged for only
through the JWT bearer grant, not through an exchange.
Worked examples
The examples share one cast, in the default realm unless a realm prefix is shown:
| Entry | Role |
|---|---|
webapp1 |
a public web client the person signs in to |
apigw1 |
an API gateway, audience https://apigw1.example.com, confidential |
esb1 |
a service bus, audience https://esb1.example.com, confidential |
sp1 |
a back-end service, audience https://sp1.example.com |
bob |
the person |
Responses are trimmed and tokens decoded. Variables: $BASE, $TOKEN and
api() are from Setting them through the API.
-k is there because development mode’s listener certificate comes from an
authority generated at each start (TLS).
0. Provision the cast
APIGW_SECRET=$(api applications/generate-secret '{}' | jq -r .clientSecret)
ESB_SECRET=$(api applications/generate-secret '{}' | jq -r .clientSecret)
SP_SECRET=$(api applications/generate-secret '{}' | jq -r .clientSecret)
XCH=urn:ietf:params:oauth:grant-type:token-exchange
api users/create '{"username":"bob","invent":false,"credential":"password",
"password":"'"$BOB_PASSWORD"'",
"attributes":{"cn":"Bob","sn":"B","mail":"bob@example.com"}}'
api applications/create '{"identifier":"webapp1","name":"webapp1",
"protocols":["oauth2","oidc"],"fields":{"oauthClientId":"webapp1",
"oauthTokenEndpointAuthMethod":["none"],
"oauthRedirectUri":["https://webapp1.example.com/callback"],
"oauthGrantType":["authorization_code","refresh_token"],
"oauthAllowedScope":["openid","profile","app1-scope"]}}'
api applications/create '{"identifier":"apigw1","name":"apigw1",
"protocols":["oauth2","oidc"],"fields":{"oauthClientId":"apigw1",
"oauthAudience":["https://apigw1.example.com"],
"oauthConfidential":"TRUE","oauthClientSecret":"'"$APIGW_SECRET"'",
"oauthTokenEndpointAuthMethod":["client_secret_basic"],
"oauthGrantType":["'"$XCH"'","client_credentials"],
"oauthAllowedScope":["app1-scope"],
"appAllowedToDelegateTo":["esb1"],
"appDelegationSemantics":["delegation","impersonation"],
"appDefaultDelegationSemantics":"delegation"}}'
api applications/create '{"identifier":"esb1","name":"esb1",
"protocols":["oauth2","oidc"],"fields":{"oauthClientId":"esb1",
"oauthAudience":["https://esb1.example.com"],
"oauthConfidential":"TRUE","oauthClientSecret":"'"$ESB_SECRET"'",
"oauthTokenEndpointAuthMethod":["client_secret_basic"],
"oauthGrantType":["'"$XCH"'","client_credentials"],
"oauthAllowedScope":["app1-scope"],
"appAllowedToDelegateTo":["sp1"],
"appDelegationSemantics":["delegation"],
"appDefaultDelegationSemantics":"delegation"}}'
api applications/create '{"identifier":"sp1","name":"sp1",
"protocols":["oauth2","oidc"],"fields":{"oauthClientId":"sp1",
"oauthAudience":["https://sp1.example.com"],
"oauthConfidential":"TRUE","oauthClientSecret":"'"$SP_SECRET"'",
"oauthTokenEndpointAuthMethod":["client_secret_basic"],
"oauthAllowedScope":["app1-scope"]}}'
app1-scope is declared on every tier because product mode issues only
declared scopes (Configuring OAuth 2.0 grants).
1. Get the subject token
bob signs in to webapp1 with the authorization code flow and PKCE, asking
for a token for the gateway with RFC 8707’s resource
(Configuring OAuth 2.0 grants
walks it). The code is redeemed so:
SUBJECT_TOKEN=$(curl -sk "$BASE/oauth2/token" \
-d grant_type=authorization_code -d client_id=webapp1 \
-d code="$CODE" -d code_verifier="$VERIFIER" \
--data-urlencode redirect_uri=https://webapp1.example.com/callback \
--data-urlencode resource=https://apigw1.example.com \
| jq -r .access_token)
The token is about bob, issued to webapp1, for the gateway:
{ "iss": "https://sts.example:8081", "sub": "urn:uuid:3f6c…", "username": "bob",
"aud": "https://apigw1.example.com", "client_id": "webapp1",
"scope": "app1-scope", "jti": "…", "exp": 1790000000 }
So S (its audience) is apigw1. In development mode only, the password grant
is a shorter way to a subject token
(Password).
2. RFC 8693 delegation, the client as the actor
apigw1 exchanges bob’s token for one addressed to esb1. No actor token:
the client is the actor, and its default semantics is delegation.
curl -sk -u "apigw1:$APIGW_SECRET" "$BASE/oauth2/token" \
-d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
-d subject_token="$SUBJECT_TOKEN" \
-d subject_token_type=urn:ietf:params:oauth:token-type:access_token \
--data-urlencode audience=https://esb1.example.com \
-d scope=app1-scope \
-d exchange_semantics=delegation
{ "access_token": "eyJ…", "token_type": "Bearer", "expires_in": 3600,
"scope": "app1-scope",
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token" }
The access token, in product mode (RFC 9700 mode names clients
urn:sts:client:<id>):
{ "iss": "https://sts.example:8081", "sub": "urn:uuid:3f6c…", "username": "bob",
"aud": "https://esb1.example.com", "client_id": "apigw1",
"scope": "app1-scope",
"act": { "sub": "urn:sts:client:apigw1", "iss": "https://sts.example:8081",
"act": { "sub": "urn:sts:client:webapp1",
"iss": "https://sts.example:8081" } } }
The policy allowed it because S (apigw1, the subject token’s audience)
delegates to R (esb1) and the actor is S.
3. RFC 8693 delegation with an actor token
The actor can be named by a token of its own. It must be the exchanging
client’s own token, addressed to that client or to this authorization server
— another client’s token is refused invalid_request in every mode. A
client_credentials token that asks for nothing else is addressed to the
client itself, so it is the one to send:
ACTOR_TOKEN=$(curl -sk -u "apigw1:$APIGW_SECRET" "$BASE/oauth2/token" \
-d grant_type=client_credentials | jq -r .access_token)
curl -sk -u "apigw1:$APIGW_SECRET" "$BASE/oauth2/token" \
-d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
-d subject_token="$SUBJECT_TOKEN" \
-d subject_token_type=urn:ietf:params:oauth:token-type:access_token \
-d actor_token="$ACTOR_TOKEN" \
-d actor_token_type=urn:ietf:params:oauth:token-type:access_token \
--data-urlencode audience=https://esb1.example.com -d scope=app1-scope
act.sub is the actor token’s sub. An actor token about a person —
still one issued to apigw1 — makes that person the actor; they need the
role delegation.actorRole names, and R must accept them in
appAllowedToActOnBehalfOf.
The next hop is the same call by esb1, presenting the token it was
given and asking for https://sp1.example.com. The result nests the new
actor over the old chain:
"act": { "sub": "urn:sts:client:esb1", "iss": "https://sts.example:8081",
"act": { "sub": "urn:sts:client:apigw1", "iss": "https://sts.example:8081",
"act": { "sub": "urn:sts:client:webapp1", "iss": "https://sts.example:8081" } } }
4. RFC 8693 impersonation
The same exchange asking for impersonation. apigw1 may, because
impersonation is in its appDelegationSemantics and esb1 is on its
appAllowedToDelegateTo (the actor reaches R):
curl -sk -u "apigw1:$APIGW_SECRET" "$BASE/oauth2/token" \
-d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
-d subject_token="$SUBJECT_TOKEN" \
-d subject_token_type=urn:ietf:params:oauth:token-type:access_token \
--data-urlencode audience=https://esb1.example.com -d scope=app1-scope \
-d exchange_semantics=impersonation
The token is bob’s, addressed to esb1, and carries no act (a subject
token that already had one would keep it):
{ "sub": "urn:uuid:3f6c…", "username": "bob", "aud": "https://esb1.example.com",
"client_id": "apigw1", "scope": "app1-scope" }
Only Monitoring → Delegation records that apigw1 obtained it.
5. A self exchange
The actor is S, keeping the token for itself — for example to drop a scope.
With no audience, the new token keeps the subject token’s audience, and no
delegation control is consulted:
curl -sk -u "apigw1:$APIGW_SECRET" "$BASE/oauth2/token" \
-d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
-d subject_token="$SUBJECT_TOKEN" \
-d subject_token_type=urn:ietf:params:oauth:token-type:access_token \
-d scope=app1-scope
6. Asking for a refresh token
curl -sk -u "apigw1:$APIGW_SECRET" "$BASE/oauth2/token" \
-d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
-d subject_token="$SUBJECT_TOKEN" \
-d subject_token_type=urn:ietf:params:oauth:token-type:access_token \
--data-urlencode audience=https://esb1.example.com -d scope=app1-scope \
-d requested_token_type=urn:ietf:params:oauth:token-type:refresh_token
{ "access_token": "eyJ…", "refresh_token": "eyJ…", "token_type": "Bearer",
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token", … }
The refresh token renews a token for esb1 only. Under
oauth2.tokenExchangeRefreshToken=never the exchange still succeeds, without
one.
7. A JWT assertion as the subject token
An RFC 7523 JWT from an issuer this realm declared. Declare it once, on an application entry with the issuer’s public key (JWT assertions):
api applications/create '{"identifier":"partner-idp","name":"partner-idp",
"protocols":["oauth2"],"fields":{"oauthClientId":["partner-idp"],
"oauthAssertionIssuer":["https://idp.partner.example"],
"oauthAssertionJwks":"{\"keys\":[ … the issuer'"'"'s public JWK … ]}"}}'
The assertion names a person the directory holds, is addressed to this
token endpoint (the default oauth2.tokenExchangeAudience), and has a
jti:
{ "iss": "https://idp.partner.example", "sub": "urn:uuid:3f6c…",
"aud": "https://sts.example:8081/oauth2/token",
"iat": 1790000000, "exp": 1790000120, "jti": "a1b2…" }
curl -sk -u "apigw1:$APIGW_SECRET" "$BASE/oauth2/token" \
-d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
-d subject_token="$JWT_ASSERTION" \
-d subject_token_type=urn:ietf:params:oauth:token-type:jwt \
--data-urlencode audience=https://esb1.example.com -d scope=app1-scope
The issued token is about the person the assertion names. An assertion
addressed to this server was issued for whoever presents it, so S is the
exchanging client (apigw1). The assertion is spent: presenting it again,
here or at the jwt-bearer grant, is refused.
8. A SAML 2.0 or SAML 1.1 assertion as the subject token
Declare the issuer with oauthSamlAssertionIssuer and give it a certificate
(SAML assertions). A certificate that merely chains to
the realm’s authority is not enough. Then send the signed assertion
base64url-encoded:
SAML_B64U=$(base64 -w0 < assertion.xml | tr '+/' '-_' | tr -d '=')
curl -sk -u "apigw1:$APIGW_SECRET" "$BASE/oauth2/token" \
-d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
-d subject_token="$SAML_B64U" \
-d subject_token_type=urn:ietf:params:oauth:token-type:saml2 \
--data-urlencode audience=https://esb1.example.com -d scope=app1-scope
For a SAML 1.1 assertion the type is
urn:ietf:params:oauth:token-type:saml1. A SAML 2.0 assertion declared as
saml1 (or the reverse) is refused (STS-OAUTH-0797).
9. An assertion as the actor token
Any of the three assertion types names the actor too. The person it names is
the actor, and act.sub is their subject:
curl -sk -u "apigw1:$APIGW_SECRET" "$BASE/oauth2/token" \
-d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
-d subject_token="$SUBJECT_TOKEN" \
-d subject_token_type=urn:ietf:params:oauth:token-type:access_token \
-d actor_token="$ACTOR_JWT_ASSERTION" \
-d actor_token_type=urn:ietf:params:oauth:token-type:jwt \
--data-urlencode audience=https://esb1.example.com -d scope=app1-scope
Token forwarding. With oauth2.tokenExchangeAudience set to
any-declared-relying-party, an assertion addressed to a relying party
registered here (its oauthAudience, or for SAML its
samlAssertionConsumerService as Recipient) may be exchanged by that
relying party. S is then that relying party, and the act is recorded as
FORWARDED.
api config/set '{"key":"oauth2.tokenExchangeAudience","value":"any-declared-relying-party"}'
Warning. Under
any-declared-relying-party, every relying party an assertion was issued to can exchange it for a token from this service. Turn it on only where that is the design.
10. Introspect a delegated token
The far end checks the token with the issuer. Introspection authenticates its caller in product mode:
curl -sk -u "sp1:$SP_SECRET" "$BASE/oauth2/introspect" \
--data-urlencode token="$DELEGATED_TOKEN" -d token_type_hint=access_token
{ "active": true, "sub": "urn:uuid:3f6c…", "aud": "https://sp1.example.com",
"client_id": "esb1", "scope": "app1-scope",
"act": { "sub": "urn:sts:client:esb1", "iss": "https://sts.example:8081",
"act": { … } } }
11. WS-Trust: provision the requesters
WS-Trust’s requester authenticates itself in the wsse:Security header,
checked in product mode. A middle tier can use a UsernameToken with its
application’s own client secret, a service account of
the same name, or a token this realm issued it
(Configuring WS-Trust
has all three). Here each requester gets a service account; the application
entry is what the policy reads either way.
for tier in webapp1:https://webapp1.example.com \
apigw1:https://apigw1.example.com \
esb1:https://esb1.example.com; do
id=${tier%%:*}; at=${tier#*:}
api applications/update-fields '{"application":"'"$id"'",
"protocols":["wstrust","saml2","oauth2","oidc"],
"fields":{"wstrustAppliesTo":["'"$at"'"],"samlEntityId":["'"$at"'"]}}'
done
# webapp1 acts first: it may impersonate or delegate, toward apigw1.
api applications/update-fields '{"application":"webapp1","fields":{
"appAllowedToDelegateTo":["apigw1"],
"appDelegationSemantics":["delegation","impersonation"]}}'
# Its service account, owned by a group of operators (the service-account
# policy asks for an owner by default).
api users/create '{"username":"webapp1","invent":false,"credential":"password",
"password":"'"$WEBAPP_PASSWORD"'","serviceAccount":true,
"owners":["admin-write"],
"attributes":{"cn":"webapp1","sn":"webapp1"}}'
12. WS-Trust: bob’s sign-in, the token to delegate
An Issue with bob’s own UsernameToken, AppliesTo webapp1. Its assertion is
about bob and restricted to webapp1 (S):
WSSE=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd
WST=http://docs.oasis-open.org/ws-sx/ws-trust/200512
SAML2=http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0
rst() { # rst <user> <password> <AppliesTo> [<OnBehalfOf|ActAs> <token xml>]
local inner=""
case "$4" in
OnBehalfOf) inner="<wst:OnBehalfOf>$5</wst:OnBehalfOf>" ;;
ActAs) inner="<wst14:ActAs xmlns:wst14=\"http://docs.oasis-open.org/ws-sx/ws-trust/200802\">$5</wst14:ActAs>" ;;
esac
cat <<EOF
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:wsse="$WSSE">
<s:Header><wsse:Security><wsse:UsernameToken>
<wsse:Username>$1</wsse:Username><wsse:Password>$2</wsse:Password>
</wsse:UsernameToken></wsse:Security></s:Header>
<s:Body><wst:RequestSecurityToken xmlns:wst="$WST">
<wst:RequestType>$WST/Issue</wst:RequestType>
<wst:TokenType>${TOKEN_TYPE:-$SAML2}</wst:TokenType>
<wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
<wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/08/addressing">
<wsa:Address>$3</wsa:Address></wsa:EndpointReference></wsp:AppliesTo>
$inner
</wst:RequestSecurityToken></s:Body></s:Envelope>
EOF
}
rst bob "$BOB_PASSWORD" https://webapp1.example.com \
| curl -sk "$BASE/sts" -H 'Content-Type: application/soap+xml' --data-binary @- \
> signin.xml
# The <saml:Assertion> inside <wst:RequestedSecurityToken>:
BOB_ASSERTION=$(xmllint --xpath \
'//*[local-name()="RequestedSecurityToken"]/*' signin.xml)
The endpoint is POST /sts (/realm/<id>/sts in a trust realm), SOAP 1.2
here; a SOAP 1.1 envelope with text/xml works too. Pass the assertion on
exactly as it came: it is signed.
13. WS-Trust OnBehalfOf (impersonation)
webapp1, authenticated as itself, presents bob’s assertion and asks for a token for apigw1:
rst webapp1 "$WEBAPP_PASSWORD" https://apigw1.example.com OnBehalfOf "$BOB_ASSERTION" \
| curl -sk "$BASE/sts" -H 'Content-Type: application/soap+xml' --data-binary @-
The RSTR carries a SAML 2.0 assertion about bob, audience
https://apigw1.example.com, with no Delegation Restriction:
<wst:RequestSecurityTokenResponseCollection …>
<wst:RequestSecurityTokenResponse>
<wst:TokenType>http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0</wst:TokenType>
<wst:RequestedSecurityToken>
<saml:Assertion …>
<saml:Subject><saml:NameID …>bob</saml:NameID>…</saml:Subject>
<saml:Conditions …>
<saml:AudienceRestriction><saml:Audience>https://apigw1.example.com</saml:Audience></saml:AudienceRestriction>
</saml:Conditions> …
14. WS-Trust ActAs (delegation)
The same request with ActAs:
rst webapp1 "$WEBAPP_PASSWORD" https://apigw1.example.com ActAs "$BOB_ASSERTION" \
| curl -sk "$BASE/sts" -H 'Content-Type: application/soap+xml' --data-binary @-
The assertion now names webapp1 as the party acting, in a SAML V2.0 Condition for Delegation Restriction:
<saml:Conditions …>
<saml:AudienceRestriction><saml:Audience>https://apigw1.example.com</saml:Audience></saml:AudienceRestriction>
<saml:Condition xmlns:del="urn:oasis:names:tc:SAML:2.0:conditions:delegation"
xsi:type="del:DelegationRestrictionType">
<del:Delegate DelegationInstant="2026-10-06T12:00:00Z">
<saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">…webapp1…</saml:NameID>
</del:Delegate>
</saml:Condition>
</saml:Conditions>
Each further ActAs hop adds one del:Delegate, least to most recent.
As SAML 1.1. With TOKEN_TYPE=http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1
the same parties, in the same order, are one AttributeValue each of a
signed attribute:
<saml:Attribute AttributeName="delegates" AttributeNamespace="urn:iya:sts:delegation">
<saml:AttributeValue>…webapp1…</saml:AttributeValue>
</saml:Attribute>
As a JWT. With TOKEN_TYPE=urn:ietf:params:oauth:token-type:jwt, the
token comes back in a <wsse:BinarySecurityToken
ValueType="urn:ietf:params:oauth:token-type:jwt">, with typ: at+jwt, the
chain as nested act, and client_id the requester’s application:
{ "iss": "https://sts.example:8081", "sub": "urn:uuid:3f6c…",
"aud": "https://apigw1.example.com", "client_id": "webapp1",
"act": { "sub": "urn:sts:client:webapp1", "iss": "https://sts.example:8081" } }
For the next hop, put that whole wsse:BinarySecurityToken element inside
the next request’s ActAs or OnBehalfOf. A request carrying both elements
is refused in every mode.
15. Kerberos: S4U2Self, S4U2Proxy, resource-based, forwarding
Kerberos is not HTTP, so these use the MIT Kerberos client tools (kinit,
kvno, klist; kvno’s -U, -F and -P need a recent MIT release —
check man kvno for your version). No test here runs these commands; the
suite drives the same exchanges with its own client.
Make four services and set their rules as
Configuring Kerberos → Delegation
does, in either mode. create-service answers with the service’s keytab,
base64, in keytab, and that reply is the only copy:
for host in frontend backend rbcd notrusted; do
api kerberos/principals/create-service '{"spn":"HTTP/'"$host"'.example.com"}' \
| jq -r .keytab | base64 -d > $host.keytab
done
| Service | Rules on its entry HTTP/<host>.example.com@EXAMPLE.COM |
|---|---|
HTTP/frontend.example.com |
appAllowedToDelegateTo the back end; delegation and impersonation in appDelegationSemantics |
HTTP/backend.example.com |
none: the classic back end |
HTTP/rbcd.example.com |
appAllowedToActOnBehalfOf the front end: the resource-based back end |
HTTP/notrusted.example.com |
appAllowedToDelegateTo the back end only: a front end that may not impersonate |
and protect one person with api users/set-not-delegated
'{"user":"carol","value":true}'. (In development mode the KDC also seeds
fixture services with these shapes; see Kerberos (MS-SFU).)
A krb5.conf for the KDC on TCP 88:
[libdefaults]
default_realm = EXAMPLE.COM
dns_lookup_kdc = false
dns_lookup_realm = false
udp_preference_limit = 1
[realms]
EXAMPLE.COM = { kdc = sts.example:88 }
# or over HTTPS, MS-KKDCP: kdc = https://sts.example:8081/KdcProxy
# (with http_anchors = FILE:/path/to/the-service-root.pem)
[domain_realm]
.example.com = EXAMPLE.COM
export KRB5_CONFIG=$PWD/krb5.conf KRB5CCNAME=FILE:/tmp/frontend.cc
# The front end's own TGT, from its keytab.
kinit -k -t frontend.keytab HTTP/frontend.example.com@EXAMPLE.COM
# S4U2Self — impersonation: a ticket to ITSELF for alice, with no password
# of alice's. Forwardable, because the front end allows impersonation.
kvno -U alice HTTP/frontend.example.com
klist -f # Flags include F (forwardable)
# S4U2Self by certificate (PA-S4U-X509-USER): a certificate this realm
# issued to alice, with clientAuth.
kvno -F alice-cert.pem HTTP/frontend.example.com
# S4U2Proxy, classic constrained delegation — delegation: alice's ticket to
# the back end, permitted by the front end's appAllowedToDelegateTo.
kvno -U alice -P HTTP/backend.example.com
# S4U2Proxy, resource-based: permitted by the back end's
# appAllowedToActOnBehalfOf; the request must carry PA-PAC-OPTIONS.
kvno -U alice -P HTTP/rbcd.example.com
The back end’s ticket carries S4U_DELEGATION_INFO in its PAC: the target
(HTTP/backend.example.com) and every service delegated through
(HTTP/frontend.example.com@EXAMPLE.COM).
What the refusals look like:
kvno -U carol -P HTTP/backend.example.com # protected: not forwardable,
# KDC_ERR_BADOPTION
KRB5CCNAME=FILE:/tmp/nt.cc kinit -k -t notrusted.keytab \
HTTP/notrusted.example.com@EXAMPLE.COM
KRB5CCNAME=FILE:/tmp/nt.cc kvno -U alice -P HTTP/backend.example.com
# S4U2Self ticket not forwardable: KDC_ERR_BADOPTION
A role the back end requires. Give the back end’s entry an
appRequiredRole and the KDC asks, under S4U, whether alice holds it —
krb5.s4uRoleSubject is user by default — whatever the front end holds;
a refusal is KDC_ERR_POLICY. Set the setting to service to ask about the
front end instead
(Kerberos).
A forwarded TGT (unconstrained delegation). A service with
krb5TrustedForDelegation gets ok-as-delegate on its tickets, which tells a
client it may forward its TGT there:
api applications/set '{"application":"HTTP/frontend.example.com@EXAMPLE.COM",
"attribute":"krb5TrustedForDelegation","value":"TRUE"}'
KRB5CCNAME=FILE:/tmp/alice.cc kinit -f alice@EXAMPLE.COM
KRB5CCNAME=FILE:/tmp/alice.cc kvno HTTP/frontend.example.com
KRB5CCNAME=FILE:/tmp/alice.cc klist -f # the service ticket shows O (ok-as-delegate)
A GSS-API client then forwards the TGT when it authenticates — for
example curl --negotiate -u : --delegation policy <url>, which forwards
only where ok-as-delegate is set. A protected person’s TGT is not
forwardable, and a forwarding request presenting one is refused. Every one of
these acts is on Monitoring → Delegation.
Across a trust between two realms, resource-based delegation names the
front end SPN@ITS-REALM on the back end’s appAllowedToActOnBehalfOf, and
S4U2Self for a foreign user needs that realm in the service’s
krb5S4uSelfRealm; classic delegation crosses only with
krb5.crossRealmClassicDelegation on in both realms.
Delegation across the trust
walks it.
16. GNAP: a trusted client presenting a user assertion (impersonation)
A GNAP client whose entry carries gnapSkipInteraction, with impersonation
in its appDelegationSemantics and each resource server reachable
(appAllowedToDelegateTo, or accepted by the resource server), presents an
ID Token issued to it:
POST /gnap
{
"client": { "key": { "proof": "mtls", "cert": "<base64 DER of the client certificate>" } },
"access_token": { "access": [ { "type": "https://apigw1.example.com/api",
"actions": ["read"] } ] },
"user": { "assertions": [ { "format": "id_token", "value": "<bob's ID Token>" } ] }
}
Every GNAP request is key-proofed. With the mtls proof method curl can send
it directly, over the certificate the key names:
curl -sk --cert client.pem --key client.key "$BASE/gnap" \
-H 'Content-Type: application/json' --data @grant.json
With httpsig, jwsd or jws, sign the request as RFC 9635 section 7.3
says (GNAP). The response carries a token for
bob in the client’s format, naming no actor. A saml2 assertion works the
same way ("format": "saml2"). An assertion issued to another client is
refused unknown_user (STS-GNAP-0073).
17. GNAP: a resource server deriving a token (delegation)
A resource server sends the token it was given as existing_access_token
(RFC 9767 section 4), proofed with its own key, and asks for rights at the
next resource server:
POST /gnap
{
"client": { "key": { "proof": "mtls", "cert": "<the resource server's certificate>" } },
"existing_access_token": "<the token it was presented>",
"access_token": { "access": [ { "type": "https://esb1.example.com/api",
"actions": ["read"] } ] }
}
Its appAllowedToDelegateTo must name the downstream resource server (or
that one’s appAllowedToActOnBehalfOf must name it). The derived token has no
more access than the original, and carries an act chain: the deriving
resource server outermost and the original client at the foot, each entry
{"sub": "urn:sts:client:<identifier>", "iss": "<the GNAP grant endpoint>"},
for at most gnap.maxDerivationDepth derivations. Where each token format
carries it is in
GNAP → What a derived token carries.
18. Read the register
curl -sk -H "Authorization: Bearer $TOKEN" \
"$BASE/admin-api/delegation?protocol=OAuth%202.0&outcome=refused" | jq '.acts[0]'
Filters: type (for example oauth-delegation, oauth-impersonation,
wstrust-actas, wstrust-onbehalfof, krb5-s4u2self,
krb5-s4u2proxy-classic, krb5-s4u2proxy-rbcd, krb5-forwarded,
gnap-impersonation, gnap-derivation), mode (delegation or
impersonation), outcome (issued or refused), protocol and q. Each
act names its four parties, the tokens consumed and produced, and
authorizedBy: what allowed it or, in development, what would have refused
it.
Per protocol
OAuth 2.0 token exchange (RFC 8693)
grant_type=urn:ietf:params:oauth:grant-type:token-exchange, with asubject_tokenand optionally anactor_token. In product mode each must be a token this realm signed and has not revoked, or an assertion from an issuer the realm declared (below).- An
actor_tokenis the exchanging client’s own, in every mode (#550). It must have been issued to that client, and be addressed to it or to this authorization server. A client’s ownclient_credentialstoken that asks for nothing else is addressed to the client, so it is the token to send. A client presenting another client’s token is refused withinvalid_request. Otherwise the token’sactwould name the other client, and the policy would decide with that client’s settings. exchange_semantics=delegation|impersonationis this service’s extension for asking. Any other value, or the parameter sent twice, isinvalid_requestin every mode.- Delegation puts
acton the access token naming the actor, nesting anyactthe subject token carried, or the original client on a first exchange (act). Impersonation issues a token about the subject with no newact. may_actis read off the verified subject token and compared with the actor’ssub(andiss, when the claim has one). It is issued on a person’s access tokens when their entry carriesstsMayAct.- The scope may narrow, never widen — a rule of the issuance policy too
(
exchange-widens-scope): in product, a scope outside the subject token’sscopeisinvalid_scope. A subject token with noscopeclaim (an ID Token, a WS-Trust JWT) has nothing to compare against. - A delegated permission follows the caller, not the subject token
(#549). A scope naming a delegated permission (an application’s
oauthPermissionBaseUriplus a name) is issued when the client making the exchange holds it (oauthDelegatedPermission), whether or not the subject token carried it, and is left out of the issued token when the client does not hold it — in every mode, while the rest of the request is issued. Both are rules of the issuance policy (exchange-permission-not-delegated,STS-OAUTH-0954). - No
scopeon the exchange carries the subject token’s forward. The issued token is asked for thescopesent, else the subject token’sscopeclaim, else nothing — the same rule for every kind of subject token. Either way it is then narrowed as every grant here is: to the scopes the client declares, the roles that authorize them, and — for anaudienceorresourcethat is not this service — without the OpenID Connect scopes (openid,profile, …), which belong to this service’s own UserInfo (RFC 9068 section 2.2.3). - Refusals are spoken as RFC 8693 section 2.2.2 says:
invalid_targetfor the target and the relationship,invalid_requestfor everything else the policy refuses (codes).
In development, two audiences are refused too, by RFC 9068 section 3: an access token for two resources is ambiguous.
See OAuth 2.0 and OpenID Connect and Configuring OAuth 2.0 grants.
Assertions as the subject or the actor
RFC 8693 section 3 names three assertion token types, and each is accepted as
the subject_token or the actor_token when a realm has declared its
issuer:
subject_token_type / actor_token_type |
What it is | Declared on the issuer’s application entry |
|---|---|---|
urn:ietf:params:oauth:token-type:jwt |
an RFC 7523 JWT assertion | oauthAssertionIssuer, with a key as for the JWT bearer grant |
urn:ietf:params:oauth:token-type:saml2 |
an RFC 7522 SAML 2.0 assertion | oauthSamlAssertionIssuer, with a certificate as for the SAML bearer grant |
urn:ietf:params:oauth:token-type:saml1 |
a SAML 1.1 assertion | the same as SAML 2.0 |
A jwt token this realm signed is still read as its own token. Anything else
of those types is verified exactly as the assertion grant verifies it:
- the issuer declared, or a person holding a key pair of their own — who may assert only about themselves;
- the signature against a key or certificate registered for that issuer. For SAML, a certificate that merely chains to the realm’s CA is not enough;
- the certificate’s chain and revocation;
- the expiry and the lifetime ceiling;
- one use, ever, in the same history as the grant. An assertion spent at
the
jwt-bearerorsaml2-bearergrant is refused at the exchange, and the reverse. It is spent only when tokens are issued.
The grant’s on/off switches (oauth2.jwtBearerGrant,
oauth2.saml2BearerGrant) do not apply: an exchange is not the grant.
The subject is the person the assertion names, provisioned as the grant
provisions one. An assertion naming nobody the directory holds is refused
(STS-OAUTH-0798). As the actor_token, the person it names is the actor and
act.sub is their subject. SAML 1.1 is read from its own elements: the
AssertionID, the Issuer attribute, the NameIdentifier in each statement,
the urn:oasis:names:tc:SAML:1.0:cm:bearer confirmation method, and the
<AudienceRestrictionCondition>. A SAML assertion whose version is not the
one its declared type says is refused (STS-OAUTH-0797).
The audience is oauth2.tokenExchangeAudience:
authorization-server(the default) — the grant’s rule. The assertion is addressed to this token endpoint or issuer, and a SAMLRecipientis the token endpoint. S, the application the subject’s token was issued for, is then the exchanging client: an assertion addressed to this server was issued for whoever presents it.any-declared-relying-party— also an application registered in the realm. This is token forwarding: a relying party that was handed an assertion trades it here. S is that relying party, a SAMLRecipientmay be an assertion consumer service registered on the exchanging client (samlAssertionConsumerService), and the act on/admin/delegationsays the input was FORWARDED.
An audience the rule does not accept is invalid_request (STS-OAUTH-0796).
Who may then exchange the assertion is the policy above, unchanged: S, the
actor, R and the subject’s protections, as for any subject token.
In development mode an undeclared or unverifiable jwt token is still read
without verifying, as it always was. A SAML token that does not verify is
refused in both modes: there is no unverified reading of XML to fall back on.
WS-Trust OnBehalfOf and ActAs
- The requester is the actor; the token in the element is the subject’s;
its
Audienceis S; theAppliesTois R. ActAsasks for delegation (WS-Trust 1.4 section 9.3). The issued token names the requester after any party the delegated assertion already named:- a SAML 2.0 assertion carries the
SAML V2.0 Condition for Delegation Restriction:
one
del:Delegateper party, least to most recent, as that profile orders them; - a JWT (
TokenTypeurn:ietf:params:oauth:token-type:jwt) carries the same chain as nestedactclaims, the most recent outermost, in the shape an OAuth 2.0 token exchange writes:- each entry has
iss; - an application is named
urn:sts:client:<client_id>in RFC 9700 mode and by its bare client_id otherwise; - the JWT’s
client_idis the requester’s application.
- each entry has
- a SAML 1.1 assertion has no Delegation Restriction, so it names the
same parties, in the same order, in an attribute:
<saml:Attribute AttributeName="delegates" AttributeNamespace="urn:iya:sts:delegation">, oneAttributeValueeach. It is signed with the assertion, and a relying party that does not know it ignores it.
- a SAML 2.0 assertion carries the
SAML V2.0 Condition for Delegation Restriction:
one
OnBehalfOfasks for impersonation (1.3 section 9.2). The token is the subject’s, and adds nobody to the chain; one the delegated assertion already carried is kept.- Both elements in one request are refused with
wst:InvalidRequest, in every mode. - A request with no
AppliesTois refused unless it is a self one. - A person may be the requester only with the role
delegation.actorRolenames, and only toward an R that accepts them by name. - Every policy refusal is a SOAP Fault carrying WS-Trust 1.4 section 11’s
wst:RequestFailed: thefaultcodeon SOAP 1.1, theSubcodeon SOAP 1.2. The fault’s reason says which rule refused. A refused act is on/admin/delegation; its subject is not added to/admin/users, which lists a delegated subject only once the policy has allowed the act (or, in development, recorded that it would have refused it). may_actis read off a JWT inside either element, as the token exchange reads it off a subject token: only when the JWT verifies with this realm’s own key, and compared with the requester, who is the actor. One naming somebody else is refused in every mode withwst:RequestFailed. A SAML assertion has no such claim. A JWT issued about a person who setstsMayActcarriesmay_act, as an access token does, so the next hop’s requester must be the delegate it names (STS-WSTRUST-0033).
See WS-Trust.
Kerberos (MS-SFU)
Kerberos service accounts are applications here: the entry whose identifier
is the service’s SPN@REALM. Their delegation settings are the common ones
above, not a second set kept by the KDC. In development the fixture services’
rules (HTTP/frontend to HTTP/backend, the resource-based HTTP/rbcd, the
HTTP/notrusted that may not impersonate, the trusted HTTP/web) are seeded
onto their entries the first time the KDC is asked, filling only what an entry
does not already hold, and the person sensitive carries stsNotDelegated.
Product mode has no rules until an operator writes one.
- S4U2Self (protocol transition) is impersonation:
- the service asks for a ticket to itself for a user, named by
PA-FOR-USERor by certificate withPA-S4U-X509-USER; - the actor is that service, and it is R as well;
- it is never refused for want of a policy — a ticket to yourself is not
the privilege — but it is forwardable only when the policy allows the
impersonation: the service allows it (
appDelegationSemantics, the job of Active Directory’sTRUSTED_TO_AUTHENTICATE_FOR_DELEGATION) and the user is not protected; - PA-S4U-X509-USER names the user by name, by a certificate this realm
issued to them (its TLS client or enrollment Issuing CA,
clientAuth, oneurn:sts:person:orurn:sts:sa:name, not revoked), or both, which must agree. Its checksum and the request’s nonce are checked, and the reply carries it back with a checksum of its own (key usage 27 when the client asks).
- the service asks for a ticket to itself for a user, named by
- S4U2Proxy is delegation:
- the front end presents the user’s evidence ticket and asks for a ticket to the back end;
- the actor is the front end, which is S;
- classic constrained delegation is the front end’s
appAllowedToDelegateTonaming the back end; - resource-based constrained delegation (the request carries
PA-PAC-OPTIONSwith the RBCD bit) is the back end’sappAllowedToActOnBehalfOfnaming the front end; - both need a forwardable evidence ticket ([MS-SFU] 3.2.5.2.1 and, since the CVE-2020-16996 update, 3.2.5.2.3);
- the ticket out of it is forwardable when the request asks for it, the front end’s TGT is forwardable and the user is not protected (RFC 4120 section 3.3.3);
- its PAC carries
S4U_DELEGATION_INFO([MS-PAC] 2.9): the target’s name (HTTP/backend.example.com) and every service delegated through, each with its realm (HTTP/frontend.example.com@EXAMPLE.COM), oldest first.
- The register records each mechanism by its own mode, as [MS-SFU] names them: S4U2Self is protocol transition, so impersonation, and S4U2Proxy is constrained delegation, so delegation, whatever made its evidence. A Kerberos impersonation chain — a service signs somebody in without Kerberos, uses S4U2Self, then S4U2Proxy hop after hop — therefore has ONE impersonation row and the rest delegation, where an OAuth 2.0 impersonation chain is impersonation at every hop. The difference is real: an S4U2Proxy ticket carries the chain in its PAC, and a token exchanged as an impersonation carries none.
- Protected users (
delegation.protectedGroups,stsNotDelegated) are never the subject of S4U, and their tickets are not forwardable. - The evidence ticket is not taken on trust. It is encrypted in the front end’s own key, so the front end could set its forwardable flag (CVE-2020-17049, Bronze Bit) or forge one for anybody. The KDC verifies the PAC’s ticket signature — which covers the flags — and its KDC signature with the krbtgt key, and refuses an evidence ticket with no PAC.
- Unconstrained delegation is
krb5TrustedForDelegationon the service’s entry, off unless set: its tickets carryok-as-delegate, which tells a client it may forward its TGT there. The KDC is never told where a forwarded TGT goes, so what it controls is the person: a protected person’s TGT is not forwardable, and a forwarding request presenting one is refused. - Refusals are the KDC’s own errors:
KDC_ERR_BADOPTIONfor a relationship that does not hold,KRB_AP_ERR_MODIFIEDfor evidence that does not verify,KDC_ERR_POLICYfor the rest of the policy. The error’se-textnames the attribute and its current value. - A role the service requires (
appRequiredRole) is checked under S4U too, against the person the ticket is for by default (krb5.s4uRoleSubject=user) or against the asking service (service). The same check runs on an AS request that names a service rather thankrbtgt, so it cannot be stepped round by skipping the TGS. A refusal isKDC_ERR_POLICY(Kerberos). - Across a Kerberos trust the same policy decides, with the trust’s facts
added: resource-based delegation crosses with no setting, S4U2Self for a
user of another realm needs that realm in the service’s
krb5S4uSelfRealm, classic delegation crosses only whilekrb5.crossRealmClassicDelegationis on in both realms, and a forwarded TGT crosses only where the trust’s attributes allow it and the target’skrb5ForeignTgtDelegationdoes not refuse it (Kerberos trusts, Delegation across the trust).
See Kerberos and SPNEGO, and Configuring Kerberos for the recipe.
GNAP (RFC 9635, RFC 9767)
- A trusted client presenting a user assertion is impersonation — the
S4U2Self shape. A client whose entry carries
gnapSkipInteractionand that presents a verifiedid_tokenorsaml2assertion in the grant request’suseris issued tokens for that person with nobody asked:- the actor is the client, the subject the person the assertion names;
- there is no S;
- R is each resource server the requested access rights resolve to (one
question each), or the client itself when they name none — which still
needs
impersonationin the client’sappDelegationSemantics, because the token can be presented; - a
may_actclaim in the ID Token must name the client (every mode); - the assertion must have been issued to the presenting client, in every mode. The token is the person’s and names no actor.
- Token derivation is delegation — the S4U2Proxy shape. A resource server
presenting
existing_access_token(RFC 9767 section 4):- is the actor and S; the subject is the original token’s person;
- R is each downstream resource server the requested rights resolve to, or the deriving one itself when it only narrows (self);
- the derived token carries no more access than the original, in every
mode, and names who acted in an
actchain, in all five token formats. This is the OAuth2 Token Exchange act chain, an extension to GNAP, written under the token exchange’s rules: the deriving resource server outermost, the original client at the foot, and every entry{"sub": "urn:sts:client:<identifier>", "iss": "<the GNAP grant endpoint>"}. It is capped bygnap.maxDerivationDepth, which counts derivations, not the original client’s entry.
- A client skipping interaction without an assertion acts for nobody and is asked nothing.
- Refusals are
request_denied(HTTP 403).
See GNAP.
Refusals and troubleshooting
Every refusal has an error code STS-<SUBSYSTEM>-<NNNN>. The code is
recorded, never sent: it is on the audit row, at the front of the log line
and on the act on Monitoring → Delegation, and the client hears only its
protocol’s own error. Look a code up in Error codes. In
development mode most policy refusals are not refused at all — read the act’s
WOULD HAVE BEEN REFUSED line to see what product will do.
OAuth 2.0 token exchange
| What happened | Client hears | Code |
|---|---|---|
No subject_token |
invalid_request |
STS-OAUTH-0224 |
subject_token_type missing; actor_token without actor_token_type, or the reverse |
invalid_request |
STS-OAUTH-0626 |
| A token type this service does not exchange; a device secret anywhere but as the actor beside an ID Token | invalid_request |
STS-OAUTH-0627 |
| A verified token that is not the type declared | invalid_request |
STS-OAUTH-0628 |
Product: the subject_token / actor_token does not verify |
invalid_request |
STS-OAUTH-0555 / 0556 |
| The token was revoked | invalid_request |
STS-OAUTH-0557 |
The actor_token was not issued to the exchanging client, or is about another client (every mode) |
invalid_request |
STS-OAUTH-0955 |
The actor_token is addressed neither to this authorization server nor to the exchanging client (every mode) |
invalid_request |
STS-OAUTH-0956 |
exchange_semantics neither delegation nor impersonation, or repeated |
invalid_request |
STS-OAUTH-0795 |
An assertion addressed to an audience oauth2.tokenExchangeAudience does not accept |
invalid_request |
STS-OAUTH-0796 |
| A SAML assertion of the other version than its declared type | invalid_request |
STS-OAUTH-0797 |
| An assertion naming nobody the directory holds | invalid_request |
STS-OAUTH-0798 |
may_act names somebody else (every mode) |
invalid_request |
STS-OAUTH-0620 |
More than one audience / resource |
invalid_target |
STS-OAUTH-0792 |
| A target no application registers | invalid_target |
STS-OAUTH-0793 |
| No target on a delegation or impersonation | invalid_target |
STS-OAUTH-0794 |
The relationship does not hold (neither appAllowedToDelegateTo nor appAllowedToActOnBehalfOf) |
invalid_target |
STS-OAUTH-0619 |
| The semantics are not allowed by the actor or the subject | invalid_request |
STS-OAUTH-0790 |
| The subject holds none of the application’s required roles | invalid_request |
STS-OAUTH-0791 |
A protected subject, an unknown actor, a person actor without the role, a subject outside appDelegationSubjectGroup |
invalid_request |
STS-OAUTH-0618 |
| A realm’s own policy refused, or no policy answered | invalid_request |
STS-OAUTH-0622 |
| Product: a scope wider than the subject token’s | invalid_scope |
STS-OAUTH-0621 |
A delegated permission the exchanging client does not hold is not a refusal:
it is left out of the issued token, in every mode, and recorded as
STS-OAUTH-0954.
WS-Trust
| What happened | Fault | Code |
|---|---|---|
Both OnBehalfOf and ActAs |
wst:InvalidRequest |
STS-WSTRUST-0025 |
The verified JWT inside the element carries a may_act naming somebody other than the requester (every mode) |
wst:RequestFailed |
STS-WSTRUST-0033 |
| Product: no requester credential on a delegation | wst:FailedAuthentication |
STS-WSTRUST-0009 |
| Product: the element carries no SAML assertion | wst:InvalidRequest |
STS-WSTRUST-0008 |
| Product: the inner assertion does not verify | wst:InvalidRequest |
STS-WSTRUST-0004 |
| Product: the inner JWT does not verify or is not this realm’s / has expired / names nobody | wst:InvalidRequest / wst:ExpiredData / wst:InvalidRequest |
STS-WSTRUST-0026 / 0027 / 0028 |
The requester has no entry here, or is a person without delegation.actorRole |
wst:RequestFailed |
STS-WSTRUST-0019 |
| The semantics are not allowed | wst:RequestFailed |
STS-WSTRUST-0022 |
| The subject has no authority | wst:RequestFailed |
STS-WSTRUST-0023 |
| No, several or an unregistered target | wst:RequestFailed |
STS-WSTRUST-0024 |
| A realm’s own policy refused, or no policy answered | wst:RequestFailed |
STS-WSTRUST-0020 |
| Any other policy refusal (a protected subject, the relationship) | wst:RequestFailed |
STS-WSTRUST-0018 |
In product mode an RST with no AppliesTo, or one nobody registered, is
refused before the policy is asked (wst:InvalidRequest, STS-WSTRUST-0031
/ wst:InvalidScope, STS-WSTRUST-0030); see WS-Trust.
Kerberos
| What happened | KDC error | Code |
|---|---|---|
| S4U2Self for a service other than the requester | KDC_ERR_BADOPTION |
STS-KRB-0006 |
| S4U2Self for a disabled person | KDC_ERR_CLIENT_REVOKED |
STS-KRB-0129 |
PA-S4U-X509-USER: undecodable, bad checksum, wrong nonce, unknown certificate, name/certificate mismatch |
KDC_ERR_BADOPTION, KRB_AP_ERR_MODIFIED, KDC_ERR_C_PRINCIPAL_UNKNOWN, KDC_ERR_CLIENT_NAME_MISMATCH |
STS-KRB-0170 to 0175 |
| S4U2Proxy not permitted by either attribute | KDC_ERR_BADOPTION |
STS-KRB-0010 |
Resource-based permission only, but no PA-PAC-OPTIONS RBCD bit |
KDC_ERR_BADOPTION |
STS-KRB-0011 |
| Evidence ticket not forwardable (classic / resource-based) | KDC_ERR_BADOPTION |
STS-KRB-0012 / 0199 |
| Evidence ticket’s PAC missing or its signatures do not verify | KRB_AP_ERR_MODIFIED |
STS-KRB-0176 |
| The issuance policy’s other rules (protected user, subject groups, semantics, authority) | KDC_ERR_BADOPTION or KDC_ERR_POLICY |
STS-KRB-0177 |
| A forwarding request with a non-forwardable ticket, or for a protected person | KDC_ERR_BADOPTION |
STS-KRB-0041 / 0042 |
The person the ticket is for (or, with krb5.s4uRoleSubject = service, the asking service) holds none of the roles the service requires |
KDC_ERR_POLICY |
STS-KRB-0039 |
Across a trust: the trust is disabled or does not accept the user’s realm; the service does not list the user’s realm in krb5S4uSelfRealm; a TGT the trust does not let cross |
KDC_ERR_POLICY or KDC_ERR_BADOPTION |
STS-KRB-0230 / 0231 / 0233 |
Across a trust: classic delegation while krb5.crossRealmClassicDelegation is off in the front end’s realm / in the target’s realm |
KDC_ERR_BADOPTION or KDC_ERR_POLICY |
STS-KRB-0232 / 0242 |
GNAP
| What happened | Error | Code |
|---|---|---|
| A user assertion issued to another client | unknown_user |
STS-GNAP-0073 |
| A trusted client’s impersonation refused by the policy | request_denied (403) |
STS-GNAP-0770 to 0775 |
Token derivation turned off (gnap.tokenDerivation) |
request_denied (403) |
STS-GNAP-0510 |
existing_access_token malformed / not active / not issued for this resource server |
invalid_request / invalid_request / request_denied |
STS-GNAP-0056 / 0511 / 0512 |
| The derived token asks for more access than the original (every mode) | request_denied (403) |
STS-GNAP-0513 |
| A derivation refused by the policy | request_denied (403) |
STS-GNAP-0776 to 0781 |
The act chain would exceed gnap.maxDerivationDepth |
request_denied (403) |
STS-GNAP-0782 |
Common causes
invalid_targeton an exchange that should work. Theaudienceorresourcemust be on an application’soauthAudience(or be its client ID), and the value inappAllowedToDelegateTois the target’s identifier, not its audience URI. Send one target, not anaudienceand a differentresource.- A delegation refused although S delegates to R. For a delegation the actor must also be S, R, or accepted by R. A client exchanging a token issued for somebody else is not S.
- An impersonation refused. The actor needs
impersonationinappDelegationSemantics— empty means delegation only. - Refused in every mode with
may_act. The subject’s token names one delegate. ClearstsMayAct(orappMayAct) for a chain with more than one actor. invalid_requestfor an actor token that looks right. It must be the exchanging client’s own: issued to it, and addressed to it or to this authorization server. Send the client’s ownclient_credentialstoken, or no actor token at all.- A person cannot be an actor. They need the role
delegation.actorRolenames (DELEGATION_ACTORby default), which must be created. - S4U2Proxy refused with a non-forwardable evidence ticket. The front
end lacks
impersonationinappDelegationSemantics, or the user is protected. KDC_ERR_POLICYunder S4U for a service that requires a role. By default the user must hold it, not the front end (krb5.s4uRoleSubject).- Works in development, refused in product. Read the act on Monitoring → Delegation: in development it states what product would have refused.
Watching it
- Monitoring → Delegation (
/admin/delegation) lists every act, issued or refused, from all four protocols, with the four parties, the semantics, the tokens consumed and produced, and the sentence saying what allowed or refused it. Filter by protocol, semantics, outcome or any name. In development, a refused act reads WOULD HAVE BEEN REFUSED. - The picture (
/admin/delegation/map) draws the same acts as a diagram:- a box per party and a line per relationship;
- chains across protocols join where they share an application;
- an application is one box however it was named — its identifier, an
audience it registered, its client_id, or the subject it acts under
with a
client_credentialstoken (urn:sts:client:<id>in product); - drill-downs per chain, per application and per person.
- Who may act for whom (the page’s policy section) lists the configured relationships, actors with their semantics and subject groups, and protected people and groups.
- The same three are
GET /admin-api/delegation,GET /admin-api/delegation/policyandGET /admin-api/console/delegation/map. - Protocols → Delegation (
/admin/delegation-settings) is where thedelegation.*settings are changed, beside the delegated permissions register: the APIs resource applications expose, the permissions each defines, and which clients hold them (Admin console → Delegated permissions). Monitoring → Delegation changes nothing.
Admin console → Delegation describes the page’s tables and its pictures in full.
Related
- Authorization overview: every authorization decision this service makes, and where each is documented.
- XACML 3.0 and ALFA: the issuance policy these rules are part of.
- Applications: where the application attributes are edited.
- Service accounts: the credential a WS-Trust requester authenticates with.
- Configuring OAuth 2.0 grants: the other grants, including the ones that produce subject tokens, and its token exchange recipe.
- Configuring WS-Trust: the
OnBehalfOfandActAschains, step by step. - Kerberos and SPNEGO and Configuring Kerberos: S4U, resource-based delegation and trusts.
- GNAP: the two GNAP acts.
- JWT assertions and SAML assertions: declaring an assertion issuer.
- What is not checked: the development-mode behaviour.
- Error codes: every refusal’s code, recorded on the audit row and never sent.