Every answer is checked against the model shown here before it is sent, and no answer carries a member its model does not list. A member shown as any JSON is one whose shape belongs to somebody else, and says whose. .{key} is a key that is data, and [] an element of a list.
A refusal
Unless an operation below says otherwise, any status it does not list answers this:
| Member | Type | Required | What it is |
|---|---|---|---|
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | ||
status |
integer | ||
why |
string |
GET /admin-api/saml-idp-initiated
getSamlIdpInitiatedApplications
The SAML applications a sign-in may be started here for, with each one’s link
Every SAML 2.0 service provider and SAML 1.1 relying party in this realm for which an identity-provider-initiated sign-in would be ALLOWED: the realm’s saml2.idpInitiatedSso / saml11.idpInitiatedSso (off by default), unless the entry’s saml2IdpInitiatedSso / saml11IdpInitiatedSso says otherwise — asked through the function GET /launch/{app} asks, so a row here is never one the link refuses with STS-LAUNCH-0005. One row per application and family; an application on in both is two rows.
launchUrl is the link a person follows (/launch/{app}?protocol=, this realm’s, on the sign-in service’s listener) and endpoint the protocol’s own unsolicited endpoint the link hands the browser to. A row whose missing is not empty is switched on and cannot work yet — it has no registered assertion consumer service, and the link answers STS-LAUNCH-0006 — and is listed so that it can be fixed.
realmSwitches says whether each realm setting is on: with both off, only an entry’s own override can put a row here.
Paged on idpInitiatedPage and per, by identifier.
Mirrors GET /admin/saml2 on the admin console.
The reply also carries protocolEndpoints: every endpoint of this family in the realm the call arrived in, as { name, methods, url } (plus route for an HTTP endpoint, transport for a socket, and registered: false for a route the router no longer has).
Scope: admin:read.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
idpInitiatedPage |
query | integer | Which page of idpInitiated to return, answered by idpInitiatedPaging. The applications, by identifier. |
|
per |
query | integer | Rows per page. Defaults to 50 and is capped at 300. On a drill-down it is SHARED by every list in the reply, which each carry a page number of their own. | |
DPoP |
header | string | RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires. |
|
cell |
query | string | The cell to answer this request, where this service runs as several. Ignored in a service that runs as one. |
200: One page of the applications, its paging and the realm’s two switches.
| Member | Type | Required | What it is |
|---|---|---|---|
idpInitiated |
list | ||
idpInitiated[].attribute |
string | ||
idpInitiated[].endpoint |
string, or null | ||
idpInitiated[].entityId |
string | ||
idpInitiated[].identifier |
string | ||
idpInitiated[].label |
string | ||
idpInitiated[].launchUrl |
string | ||
idpInitiated[].missing |
list | ||
idpInitiated[].missing[] |
string | ||
idpInitiated[].name |
string | ||
idpInitiated[].protocol |
string | ||
idpInitiatedPaging |
object | ||
idpInitiatedPaging.firstRow |
integer | ||
idpInitiatedPaging.lastRow |
integer | ||
idpInitiatedPaging.noun |
string, or null | ||
idpInitiatedPaging.page |
integer | ||
idpInitiatedPaging.pages |
integer | ||
idpInitiatedPaging.param |
string, or null | ||
idpInitiatedPaging.perPage |
integer | ||
idpInitiatedPaging.total |
integer | ||
protocolEndpoints |
list | ||
protocolEndpoints[].listening |
boolean | ||
protocolEndpoints[].methods |
list, or string | ||
protocolEndpoints[].methods[] |
string | ||
protocolEndpoints[].name |
string | ||
protocolEndpoints[].registered |
boolean | ||
protocolEndpoints[].route |
string | ||
protocolEndpoints[].transport |
string | ||
protocolEndpoints[].url |
string | ||
realmSwitches |
list | ||
realmSwitches[].attribute |
string | ||
realmSwitches[].enabled |
boolean | ||
realmSwitches[].label |
string | ||
realmSwitches[].protocol |
string | ||
realmSwitches[].setting |
string |
GET /admin-api/saml2
getSaml2ServiceProviders
Every SAML 2.0 service provider, and the endpoints each is configured from
A full SAML 2.0 identity provider: HTTP Redirect, HTTP POST and HTTP POST SimpleSign for the AuthnRequest, and HTTP POST, HTTP Redirect, HTTP POST SimpleSign or HTTP Artifact for the Response, with a SOAP artifact resolution service behind the last.
Every service provider gets its own identity provider metadata — a distinct entityID and its own endpoints — and in development a document is minted for any entityID asked for, so nothing has to be provisioned before a service provider can be pointed at this service; in product every per-service-provider path is a 404 for an entityID that is not registered. That is why metadataUrl is on every row rather than being one constant.
This resource holds nothing: every row is an entry in ou=applications, the same one GET /admin-api/applications reports.
?sp=<entityID> returns one of them, with what has been recorded about it — and answers 200 with found: false for an entityID that is not registered — whose metadata is still served and whose AuthnRequest would still be answered, in development only.
The list reply carries mdqRefused: the entityIDs a request asked the Metadata Query responder to register and product mode refused (no trust anchor, or an answer that did not verify), newest first, paged by mdqRefusedPage.
The ?sp= reply also says what checking its requests’ signatures found (lastRequestVerification), what they are verified against (signingCertificates), the certificate a request carried that nobody has confirmed (observedSigningCertificate), whether signed requests are required of it and why (signedRequestsRequired), and everything consuming its metadata registered (metadata).
Mirrors GET /admin/saml2 on the admin console.
The reply also carries protocolEndpoints: every endpoint of this family in the realm the call arrived in, as { name, methods, url } (plus route for an HTTP endpoint, transport for a socket, and registered: false for a route the router no longer has).
Scope: admin:read.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
q |
query | string | Part of a service provider’s entityID, case-insensitive, narrowing the list. | |
sp |
query | string | One service provider, by its entityID. | |
page |
query | integer | Which page of the match to return. CLAMPED rather than refused: a page past the end returns the last one, and the reply says which page it actually is. | |
per |
query | integer | Rows per page. Defaults to 50 and is capped at 300. On a drill-down it is SHARED by every list in the reply, which each carry a page number of their own. | |
mdqRefusedPage |
query | integer | Which page of mdqRefused to return, answered by mdqRefusedPaging. The Metadata Query lookups refused in product mode (#112), newest first. |
|
DPoP |
header | string | RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires. |
|
cell |
query | string | The cell to answer this request, where this service runs as several. Ignored in a service that runs as one. |
200: The service providers with the paging that found them, or one of them with its endpoints and its record.
| Member | Type | Required | What it is |
|---|---|---|---|
arsUrl |
string | ||
artifactsAwaitingResolution |
number | ||
assertionConsumerServices |
list | ||
assertionConsumerServices[] |
string | ||
authentications |
number | ||
found |
boolean | ||
identifier |
string | ||
idpEntityId |
string, or null | ||
kind |
string | ||
lastRequestSigned |
boolean | ||
lastRequestVerification |
object | ||
lastRequestVerification.binding |
string | ||
lastRequestVerification.outcome |
string | ||
lastRequestVerification.signatureMethod |
string | ||
lastRequestVerification.weak |
boolean | ||
mdqRefused |
list | ||
mdqRefused[].count |
number | ||
mdqRefused[].entityId |
string | ||
mdqRefused[].firstAt |
string, or null | ||
mdqRefused[].lastAt |
string, or null | ||
mdqRefused[].why |
string | ||
mdqRefusedPaging |
object | ||
mdqRefusedPaging.firstRow |
integer | ||
mdqRefusedPaging.lastRow |
integer | ||
mdqRefusedPaging.noun |
string, or null | ||
mdqRefusedPaging.offset |
integer | ||
mdqRefusedPaging.page |
integer | ||
mdqRefusedPaging.pages |
integer | ||
mdqRefusedPaging.param |
string, or null | ||
mdqRefusedPaging.perPage |
integer | ||
mdqRefusedPaging.total |
integer | ||
metadata |
object | ||
metadata.assertionConsumerServices |
list | ||
metadata.assertionConsumerServices[].binding |
string | ||
metadata.assertionConsumerServices[].index |
string | ||
metadata.assertionConsumerServices[].isDefault |
boolean, or null | ||
metadata.assertionConsumerServices[].location |
string | ||
metadata.authnRequestsSigned |
boolean | ||
metadata.cacheDuration |
string | ||
metadata.consumed |
boolean | ||
metadata.consumedAt |
string | ||
metadata.encryptionCertificate |
boolean | ||
metadata.expired |
boolean | ||
metadata.expiresAt |
string | ||
metadata.how |
string | ||
metadata.mdqUrl |
string | ||
metadata.nameIdFormats |
list | ||
metadata.nameIdFormats[] |
string | ||
metadata.refresh |
object | ||
metadata.refresh.failingSince |
string | ||
metadata.refresh.failures |
number | ||
metadata.refresh.lastAttemptAt |
string | ||
metadata.refresh.lastSuccessAt |
string | ||
metadata.refresh.ok |
boolean | ||
metadata.refresh.why |
string | ||
metadata.refreshable |
boolean | ||
metadata.refresherEnabled |
boolean | ||
metadata.refresherRunning |
boolean | ||
metadata.signature |
string | ||
metadata.signingCertificateConfigured |
boolean | ||
metadata.singleLogoutServices |
list | ||
metadata.singleLogoutServices[].binding |
string | ||
metadata.singleLogoutServices[].location |
string | ||
metadata.singleLogoutServices[].responseLocation |
string | ||
metadata.staleAt |
string | ||
metadata.state |
string | ||
metadata.stateWhy |
string | ||
metadata.trustAnchorProblems |
list | ||
metadata.trustAnchorProblems[] |
string | ||
metadata.trustAnchors |
number | ||
metadata.url |
string | ||
metadata.validUntil |
string | ||
metadata.wantAssertionsEncrypted |
boolean | ||
metadata.wantAssertionsSigned |
boolean | ||
metadataUrl |
string | ||
name |
string | ||
nameIdFormats |
list | ||
nameIdFormats[] |
string | ||
observedSigningCertificate |
string | ||
paging |
object | ||
paging.firstRow |
integer | ||
paging.lastRow |
integer | ||
paging.noun |
string, or null | ||
paging.offset |
integer | ||
paging.page |
integer | ||
paging.pages |
integer | ||
paging.param |
string, or null | ||
paging.perPage |
integer | ||
paging.total |
integer | ||
protocolEndpoints |
list | ||
protocolEndpoints[].listening |
boolean | ||
protocolEndpoints[].methods |
list, or string | ||
protocolEndpoints[].methods[] |
string | ||
protocolEndpoints[].name |
string | ||
protocolEndpoints[].registered |
boolean | ||
protocolEndpoints[].route |
string | ||
protocolEndpoints[].transport |
string | ||
protocolEndpoints[].url |
string | ||
requestsHeldForSignIn |
number | ||
responseBindings |
list | ||
responseBindings[] |
string | ||
serviceProviders |
list | ||
serviceProviders[].arsUrl |
string | ||
serviceProviders[].assertionConsumerServices |
list | ||
serviceProviders[].assertionConsumerServices[] |
string | ||
serviceProviders[].authentications |
number | ||
serviceProviders[].firstSeen |
string | ||
serviceProviders[].identifier |
string | ||
serviceProviders[].idpEntityId |
string, or null | ||
serviceProviders[].lastRequestSigned |
boolean | ||
serviceProviders[].lastRequestVerification |
string | ||
serviceProviders[].lastSeen |
string | ||
serviceProviders[].metadataUrl |
string | ||
serviceProviders[].name |
string, or null | ||
serviceProviders[].nameIdFormats |
list | ||
serviceProviders[].nameIdFormats[] |
string | ||
serviceProviders[].responseBindings |
list | ||
serviceProviders[].responseBindings[] |
string | ||
serviceProviders[].sessions |
number | ||
serviceProviders[].singleLogoutServices |
list | ||
serviceProviders[].singleLogoutServices[] |
string | ||
serviceProviders[].sloUrl |
string | ||
serviceProviders[].slug |
string, or null | ||
serviceProviders[].ssoUrl |
string | ||
serviceProviders[].users |
number | ||
settings |
object | ||
settings.context |
object | ||
settings.context.configFile |
string, or null | ||
settings.context.defaultsFile |
string, or null | ||
settings.context.inRealm |
boolean | ||
settings.context.persistenceMode |
string | ||
settings.context.persistsAppconfig |
boolean | ||
settings.context.persistsRealms |
boolean | ||
settings.context.realmId |
string, or null | ||
settings.editableCount |
integer | ||
settings.groups |
list | ||
settings.groups[].group |
string | ||
settings.groups[].settings |
list | ||
settings.groups[].settings[].appconfigPath |
string | ||
settings.groups[].settings[].csvValueNotes |
map | The sentence beside each value. | |
settings.groups[].settings[].csvValueNotes.{key} |
string | ||
settings.groups[].settings[].csvValues |
list | ||
settings.groups[].settings[].csvValues[] |
string | ||
settings.groups[].settings[].default |
list, or boolean, or number, or string, or null | ||
settings.groups[].settings[].default[] |
string | ||
settings.groups[].settings[].description |
string | ||
settings.groups[].settings[].editRefusal |
string | ||
settings.groups[].settings[].editable |
boolean | ||
settings.groups[].settings[].enumValues |
list | ||
settings.groups[].settings[].enumValues[] |
string | ||
settings.groups[].settings[].env |
string, or null | ||
settings.groups[].settings[].group |
string | ||
settings.groups[].settings[].key |
string | ||
settings.groups[].settings[].label |
string | ||
settings.groups[].settings[].legacyEnv |
string, or null | ||
settings.groups[].settings[].masked |
boolean | ||
settings.groups[].settings[].max |
number | ||
settings.groups[].settings[].min |
number | ||
settings.groups[].settings[].ordered |
boolean | ||
settings.groups[].settings[].overridden |
boolean | ||
settings.groups[].settings[].realmSettable |
boolean | ||
settings.groups[].settings[].restartReason |
string | ||
settings.groups[].settings[].selectAll |
map | The rules by kind: onlyWhileOn and aloneWhileOn. | |
settings.groups[].settings[].selectAll.{key} |
list | ||
settings.groups[].settings[].selectAll.{key}[].canBeOn |
object | Nested deeper than this page draws. | |
settings.groups[].settings[].selectAll.{key}[].on |
object | Nested deeper than this page draws. | |
settings.groups[].settings[].selectAll.{key}[].setting |
object | Nested deeper than this page draws. | |
settings.groups[].settings[].selectAll.{key}[].values |
object | Nested deeper than this page draws. | |
settings.groups[].settings[].source |
string | ||
settings.groups[].settings[].step |
number | ||
settings.groups[].settings[].text |
string, or null | ||
settings.groups[].settings[].type |
string | ||
settings.groups[].settings[].value |
list, or boolean, or number, or string, or null | ||
settings.groups[].settings[].value[] |
string | ||
settings.overridden |
list | ||
settings.overridden[] |
string | ||
settings.page |
string | ||
settings.setWith |
string | ||
settings.settingCount |
integer | ||
settings.sharedWith |
map | The other pages, by settings group. | |
settings.sharedWith.{key} |
list | ||
settings.sharedWith.{key}[].label |
string | ||
settings.sharedWith.{key}[].path |
string | ||
signedRequestsRequired |
object | ||
signedRequestsRequired.required |
boolean | ||
signedRequestsRequired.why |
string | ||
signingCertificate |
string | ||
signingCertificates |
list | ||
signingCertificates[] |
string | ||
singleLogoutServices |
list | ||
singleLogoutServices[] |
string | ||
sloUrl |
string | ||
slug |
string, or null | ||
ssoUrl |
string | ||
unscopedMetadata |
string |
POST /admin-api/saml2/confirm-signing-certificate
confirmSaml2SigningCertificate
Trust the certificate a signed request carried
A signed request’s ds:KeyInfo certificate that is not registered is recorded as OBSERVED (observedSigningCertificate on GET /admin-api/saml2?sp=, the attribute samlObservedSigningCertificate) and verifies NOTHING — anybody can sign a request and attach the key that verifies it. Development mode still encrypts an assertion to it when nothing else is on the entry; product does not.
This MOVES it onto samlSigningCertificate, so this service provider’s signatures are verified against it from the next request. Refused when nothing is observed, and for a certificate whose key signs nothing this service verifies. Confirm only a key you know is the service provider’s: this is the registration.
Mirrors POST /admin/saml2 on the admin console.
Scope: admin:write.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
DPoP |
header | string | RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires. |
|
cell |
query | string | The cell to answer this request, where this service runs as several. Ignored in a service that runs as one. |
Request body
| Member | Type | Required | What it is |
|---|---|---|---|
sp |
string | yes |
200: The application entry as it now stands.
| Member | Type | Required | What it is |
|---|---|---|---|
application |
object | ||
application.allowedProtocols |
list | ||
application.allowedProtocols[] |
string | ||
application.attributes |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.attributes.{key} |
list, or string, or null | ||
application.attributes.{key}[] |
string | ||
application.authentications |
number | ||
application.createdAt |
string, or null | ||
application.declaredKinds |
list | ||
application.declaredKinds[] |
string | ||
application.description |
string, or null | ||
application.dn |
string, or null | ||
application.dnLabel |
string, or null | ||
application.fields |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.fields.{key} |
list, or string, or null | ||
application.fields.{key}[] |
string | ||
application.firstSeen |
string | ||
application.identifier |
string | ||
application.kinds |
list | ||
application.kinds[] |
string | ||
application.lastSeen |
string | ||
application.modifiedAt |
string, or null | ||
application.name |
string, or null | ||
application.operational |
list | ||
application.operational[] |
string | ||
application.origin |
string, or null | ||
application.protocols |
list | ||
application.protocols[] |
string | ||
application.recordedProtocols |
list | ||
application.recordedProtocols[] |
string | ||
application.registered |
boolean | ||
application.registeredBy |
string | ||
application.returnAddressesObserved |
list | ||
application.returnAddressesObserved[].attribute |
string | ||
application.returnAddressesObserved[].held |
boolean | ||
application.returnAddressesObserved[].trusted |
boolean | ||
application.returnAddressesObserved[].value |
string | ||
application.sessions |
number | ||
application.users |
number | ||
changed |
boolean | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
application |
object | ||
application.allowedProtocols |
list | ||
application.allowedProtocols[] |
string | ||
application.attributes |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.attributes.{key} |
list, or string, or null | ||
application.attributes.{key}[] |
string | ||
application.authentications |
number | ||
application.createdAt |
string, or null | ||
application.declaredKinds |
list | ||
application.declaredKinds[] |
string | ||
application.description |
string, or null | ||
application.dn |
string, or null | ||
application.dnLabel |
string, or null | ||
application.fields |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.fields.{key} |
list, or string, or null | ||
application.fields.{key}[] |
string | ||
application.firstSeen |
string | ||
application.identifier |
string | ||
application.kinds |
list | ||
application.kinds[] |
string | ||
application.lastSeen |
string | ||
application.modifiedAt |
string, or null | ||
application.name |
string, or null | ||
application.operational |
list | ||
application.operational[] |
string | ||
application.origin |
string, or null | ||
application.protocols |
list | ||
application.protocols[] |
string | ||
application.recordedProtocols |
list | ||
application.recordedProtocols[] |
string | ||
application.registered |
boolean | ||
application.registeredBy |
string | ||
application.returnAddressesObserved |
list | ||
application.returnAddressesObserved[].attribute |
string | ||
application.returnAddressesObserved[].held |
boolean | ||
application.returnAddressesObserved[].trusted |
boolean | ||
application.returnAddressesObserved[].value |
string | ||
application.sessions |
number | ||
application.users |
number | ||
changed |
boolean | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
POST /admin-api/saml2/discard-signing-certificate
discardSaml2SigningCertificate
Discard the certificate a signed request carried
The opposite answer to confirm-signing-certificate: the observed certificate is taken off the entry. It was never trusted; a signed request carrying it again records it again. Refused when nothing is observed.
Mirrors POST /admin/saml2 on the admin console.
Scope: admin:write.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
DPoP |
header | string | RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires. |
|
cell |
query | string | The cell to answer this request, where this service runs as several. Ignored in a service that runs as one. |
Request body
| Member | Type | Required | What it is |
|---|---|---|---|
sp |
string | yes |
200: The application entry as it now stands.
| Member | Type | Required | What it is |
|---|---|---|---|
application |
object | ||
application.allowedProtocols |
list | ||
application.allowedProtocols[] |
string | ||
application.attributes |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.attributes.{key} |
list, or string, or null | ||
application.attributes.{key}[] |
string | ||
application.authentications |
number | ||
application.createdAt |
string, or null | ||
application.declaredKinds |
list | ||
application.declaredKinds[] |
string | ||
application.description |
string, or null | ||
application.dn |
string, or null | ||
application.dnLabel |
string, or null | ||
application.fields |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.fields.{key} |
list, or string, or null | ||
application.fields.{key}[] |
string | ||
application.firstSeen |
string | ||
application.identifier |
string | ||
application.kinds |
list | ||
application.kinds[] |
string | ||
application.lastSeen |
string | ||
application.modifiedAt |
string, or null | ||
application.name |
string, or null | ||
application.operational |
list | ||
application.operational[] |
string | ||
application.origin |
string, or null | ||
application.protocols |
list | ||
application.protocols[] |
string | ||
application.recordedProtocols |
list | ||
application.recordedProtocols[] |
string | ||
application.registered |
boolean | ||
application.registeredBy |
string | ||
application.returnAddressesObserved |
list | ||
application.returnAddressesObserved[].attribute |
string | ||
application.returnAddressesObserved[].held |
boolean | ||
application.returnAddressesObserved[].trusted |
boolean | ||
application.returnAddressesObserved[].value |
string | ||
application.sessions |
number | ||
application.users |
number | ||
changed |
boolean | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
application |
object | ||
application.allowedProtocols |
list | ||
application.allowedProtocols[] |
string | ||
application.attributes |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.attributes.{key} |
list, or string, or null | ||
application.attributes.{key}[] |
string | ||
application.authentications |
number | ||
application.createdAt |
string, or null | ||
application.declaredKinds |
list | ||
application.declaredKinds[] |
string | ||
application.description |
string, or null | ||
application.dn |
string, or null | ||
application.dnLabel |
string, or null | ||
application.fields |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.fields.{key} |
list, or string, or null | ||
application.fields.{key}[] |
string | ||
application.firstSeen |
string | ||
application.identifier |
string | ||
application.kinds |
list | ||
application.kinds[] |
string | ||
application.lastSeen |
string | ||
application.modifiedAt |
string, or null | ||
application.name |
string, or null | ||
application.operational |
list | ||
application.operational[] |
string | ||
application.origin |
string, or null | ||
application.protocols |
list | ||
application.protocols[] |
string | ||
application.recordedProtocols |
list | ||
application.recordedProtocols[] |
string | ||
application.registered |
boolean | ||
application.registeredBy |
string | ||
application.returnAddressesObserved |
list | ||
application.returnAddressesObserved[].attribute |
string | ||
application.returnAddressesObserved[].held |
boolean | ||
application.returnAddressesObserved[].trusted |
boolean | ||
application.returnAddressesObserved[].value |
string | ||
application.sessions |
number | ||
application.users |
number | ||
changed |
boolean | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
POST /admin-api/saml2/mdq-import
importSaml2MetadataFromMdq
Import a service provider from the MDQ responder
Asks saml2.mdqBaseUrl for <base>/entities/<percent-encoded entityID> (the Metadata Query Protocol), and — when the answer describes that entity — creates the application entry if it does not exist and consumes the document, held to the realm’s saml2.metadataTrustAnchors. Refused with no responder configured; an entry it created is removed again if the document is refused. In product mode with no trust anchor it is refused unless saml2.mdqImportWithoutAnchors is on, and then the reply carries warnings: the document was consumed with no signature check.
Mirrors POST /admin/saml2 on the admin console.
Scope: admin:write.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
DPoP |
header | string | RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires. |
|
cell |
query | string | The cell to answer this request, where this service runs as several. Ignored in a service that runs as one. |
Request body
| Member | Type | Required | What it is |
|---|---|---|---|
sp |
string | yes |
200: What was consumed (with created), or why nothing was.
| Member | Type | Required | What it is |
|---|---|---|---|
application |
string | ||
assertionConsumerServices |
list | ||
assertionConsumerServices[] |
string | ||
authnRequestsSigned |
boolean | ||
cacheDuration |
string, or null | ||
certificateUse |
string | ||
created |
boolean | ||
entityId |
string | ||
errors |
list | ||
errors[] |
string | ||
how |
string | ||
message |
string | ||
nameIdFormats |
list | ||
nameIdFormats[] |
string | ||
ok |
boolean | yes | |
signature |
string | ||
signingCertificates |
number | ||
singleLogoutServices |
list | ||
singleLogoutServices[] |
string | ||
skipped |
list | ||
skipped[] |
string | ||
url |
string | ||
validUntil |
string, or null | ||
wantAssertionsSigned |
boolean | ||
warnings |
list | ||
warnings[] |
string | ||
why |
string |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
application |
string | ||
assertionConsumerServices |
list | ||
assertionConsumerServices[] |
string | ||
authnRequestsSigned |
boolean | ||
cacheDuration |
string, or null | ||
certificateUse |
string | ||
created |
boolean | ||
entityId |
string | ||
errors |
list | ||
errors[] |
string | ||
how |
string | ||
message |
string | ||
nameIdFormats |
list | ||
nameIdFormats[] |
string | ||
ok |
boolean | yes | |
signature |
string | ||
signingCertificates |
number | ||
singleLogoutServices |
list | ||
singleLogoutServices[] |
string | ||
skipped |
list | ||
skipped[] |
string | ||
url |
string | ||
validUntil |
string, or null | ||
wantAssertionsSigned |
boolean | ||
warnings |
list | ||
warnings[] |
string | ||
why |
string |
POST /admin-api/saml2/refresh-metadata
refreshSaml2Metadata
Fetch a service provider’s metadata again, now
Fetches the document from the entry’s samlSpMetadataUrl — or, for an entry with none, from the realm’s Metadata Query responder (saml2.mdqBaseUrl) — through the federation outbound policy, and CONSUMES it exactly as upload-metadata does. The background refresher does the same once a document is past its cacheDuration. A failure changes nothing.
Mirrors POST /admin/saml2 on the admin console.
Scope: admin:write.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
DPoP |
header | string | RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires. |
|
cell |
query | string | The cell to answer this request, where this service runs as several. Ignored in a service that runs as one. |
Request body
| Member | Type | Required | What it is |
|---|---|---|---|
sp |
string | yes |
200: What was consumed, or why nothing was.
| Member | Type | Required | What it is |
|---|---|---|---|
application |
string | ||
assertionConsumerServices |
list | ||
assertionConsumerServices[] |
string | ||
authnRequestsSigned |
boolean | ||
cacheDuration |
string, or null | ||
certificateUse |
string | ||
created |
boolean | ||
entityId |
string | ||
errors |
list | ||
errors[] |
string | ||
how |
string | ||
message |
string | ||
nameIdFormats |
list | ||
nameIdFormats[] |
string | ||
ok |
boolean | yes | |
signature |
string | ||
signingCertificates |
number | ||
singleLogoutServices |
list | ||
singleLogoutServices[] |
string | ||
skipped |
list | ||
skipped[] |
string | ||
url |
string | ||
validUntil |
string, or null | ||
wantAssertionsSigned |
boolean | ||
warnings |
list | ||
warnings[] |
string | ||
why |
string |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
application |
string | ||
assertionConsumerServices |
list | ||
assertionConsumerServices[] |
string | ||
authnRequestsSigned |
boolean | ||
cacheDuration |
string, or null | ||
certificateUse |
string | ||
created |
boolean | ||
entityId |
string | ||
errors |
list | ||
errors[] |
string | ||
how |
string | ||
message |
string | ||
nameIdFormats |
list | ||
nameIdFormats[] |
string | ||
ok |
boolean | yes | |
signature |
string | ||
signingCertificates |
number | ||
singleLogoutServices |
list | ||
singleLogoutServices[] |
string | ||
skipped |
list | ||
skipped[] |
string | ||
url |
string | ||
validUntil |
string, or null | ||
wantAssertionsSigned |
boolean | ||
warnings |
list | ||
warnings[] |
string | ||
why |
string |
POST /admin-api/saml2/register
registerSaml2ServiceProvider
Register a service provider by entityID
OPTIONAL, and it changes nothing about whether a request is accepted: this identity provider accepts any entityID, and the first AuthnRequest or metadata fetch creates the entry anyway. What registering early buys is a metadata document to hand somebody before they have sent anything.
It is refused for an entityID that is already in the registry — an identifier names ONE application here whatever protocol brought it, so the answer to “it is already there” is to change what it holds rather than to create it twice.
Mirrors POST /admin/saml2 on the admin console.
Scope: admin:write.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
DPoP |
header | string | RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires. |
|
cell |
query | string | The cell to answer this request, where this service runs as several. Ignored in a service that runs as one. |
Request body
| Member | Type | Required | What it is |
|---|---|---|---|
sp |
string | yes | The service provider’s entityID. |
200: The application entry, and where its metadata is served.
| Member | Type | Required | What it is |
|---|---|---|---|
application |
object | ||
application.allowedProtocols |
list | ||
application.allowedProtocols[] |
string | ||
application.attributes |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.attributes.{key} |
list, or string, or null | ||
application.attributes.{key}[] |
string | ||
application.authentications |
number | ||
application.createdAt |
string, or null | ||
application.declaredKinds |
list | ||
application.declaredKinds[] |
string | ||
application.description |
string, or null | ||
application.dn |
string, or null | ||
application.dnLabel |
string, or null | ||
application.fields |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.fields.{key} |
list, or string, or null | ||
application.fields.{key}[] |
string | ||
application.firstSeen |
string | ||
application.identifier |
string | ||
application.kinds |
list | ||
application.kinds[] |
string | ||
application.lastSeen |
string | ||
application.modifiedAt |
string, or null | ||
application.name |
string, or null | ||
application.operational |
list | ||
application.operational[] |
string | ||
application.origin |
string, or null | ||
application.protocols |
list | ||
application.protocols[] |
string | ||
application.recordedProtocols |
list | ||
application.recordedProtocols[] |
string | ||
application.registered |
boolean | ||
application.registeredBy |
string | ||
application.returnAddressesObserved |
list | ||
application.returnAddressesObserved[].attribute |
string | ||
application.returnAddressesObserved[].held |
boolean | ||
application.returnAddressesObserved[].trusted |
boolean | ||
application.returnAddressesObserved[].value |
string | ||
application.sessions |
number | ||
application.users |
number | ||
changed |
boolean | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
application |
object | ||
application.allowedProtocols |
list | ||
application.allowedProtocols[] |
string | ||
application.attributes |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.attributes.{key} |
list, or string, or null | ||
application.attributes.{key}[] |
string | ||
application.authentications |
number | ||
application.createdAt |
string, or null | ||
application.declaredKinds |
list | ||
application.declaredKinds[] |
string | ||
application.description |
string, or null | ||
application.dn |
string, or null | ||
application.dnLabel |
string, or null | ||
application.fields |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.fields.{key} |
list, or string, or null | ||
application.fields.{key}[] |
string | ||
application.firstSeen |
string | ||
application.identifier |
string | ||
application.kinds |
list | ||
application.kinds[] |
string | ||
application.lastSeen |
string | ||
application.modifiedAt |
string, or null | ||
application.name |
string, or null | ||
application.operational |
list | ||
application.operational[] |
string | ||
application.origin |
string, or null | ||
application.protocols |
list | ||
application.protocols[] |
string | ||
application.recordedProtocols |
list | ||
application.recordedProtocols[] |
string | ||
application.registered |
boolean | ||
application.registeredBy |
string | ||
application.returnAddressesObserved |
list | ||
application.returnAddressesObserved[].attribute |
string | ||
application.returnAddressesObserved[].held |
boolean | ||
application.returnAddressesObserved[].trusted |
boolean | ||
application.returnAddressesObserved[].value |
string | ||
application.sessions |
number | ||
application.users |
number | ||
changed |
boolean | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
POST /admin-api/saml2/remove-logout-service
removeSaml2LogoutService
Take a logout return address off a service provider
The attribute holds a LIST, so values are removed by name rather than the list being replaced. Removing the last one puts the fallback back.
Mirrors POST /admin/saml2 on the admin console.
Scope: admin:write.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
DPoP |
header | string | RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires. |
|
cell |
query | string | The cell to answer this request, where this service runs as several. Ignored in a service that runs as one. |
Request body
| Member | Type | Required | What it is |
|---|---|---|---|
sp |
string | yes | |
value |
string | yes | The exact value to remove. |
200: The application entry as it now stands.
| Member | Type | Required | What it is |
|---|---|---|---|
application |
object | ||
application.allowedProtocols |
list | ||
application.allowedProtocols[] |
string | ||
application.attributes |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.attributes.{key} |
list, or string, or null | ||
application.attributes.{key}[] |
string | ||
application.authentications |
number | ||
application.createdAt |
string, or null | ||
application.declaredKinds |
list | ||
application.declaredKinds[] |
string | ||
application.description |
string, or null | ||
application.dn |
string, or null | ||
application.dnLabel |
string, or null | ||
application.fields |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.fields.{key} |
list, or string, or null | ||
application.fields.{key}[] |
string | ||
application.firstSeen |
string | ||
application.identifier |
string | ||
application.kinds |
list | ||
application.kinds[] |
string | ||
application.lastSeen |
string | ||
application.modifiedAt |
string, or null | ||
application.name |
string, or null | ||
application.operational |
list | ||
application.operational[] |
string | ||
application.origin |
string, or null | ||
application.protocols |
list | ||
application.protocols[] |
string | ||
application.recordedProtocols |
list | ||
application.recordedProtocols[] |
string | ||
application.registered |
boolean | ||
application.registeredBy |
string | ||
application.returnAddressesObserved |
list | ||
application.returnAddressesObserved[].attribute |
string | ||
application.returnAddressesObserved[].held |
boolean | ||
application.returnAddressesObserved[].trusted |
boolean | ||
application.returnAddressesObserved[].value |
string | ||
application.sessions |
number | ||
application.users |
number | ||
changed |
boolean | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
application |
object | ||
application.allowedProtocols |
list | ||
application.allowedProtocols[] |
string | ||
application.attributes |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.attributes.{key} |
list, or string, or null | ||
application.attributes.{key}[] |
string | ||
application.authentications |
number | ||
application.createdAt |
string, or null | ||
application.declaredKinds |
list | ||
application.declaredKinds[] |
string | ||
application.description |
string, or null | ||
application.dn |
string, or null | ||
application.dnLabel |
string, or null | ||
application.fields |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.fields.{key} |
list, or string, or null | ||
application.fields.{key}[] |
string | ||
application.firstSeen |
string | ||
application.identifier |
string | ||
application.kinds |
list | ||
application.kinds[] |
string | ||
application.lastSeen |
string | ||
application.modifiedAt |
string, or null | ||
application.name |
string, or null | ||
application.operational |
list | ||
application.operational[] |
string | ||
application.origin |
string, or null | ||
application.protocols |
list | ||
application.protocols[] |
string | ||
application.recordedProtocols |
list | ||
application.recordedProtocols[] |
string | ||
application.registered |
boolean | ||
application.registeredBy |
string | ||
application.returnAddressesObserved |
list | ||
application.returnAddressesObserved[].attribute |
string | ||
application.returnAddressesObserved[].held |
boolean | ||
application.returnAddressesObserved[].trusted |
boolean | ||
application.returnAddressesObserved[].value |
string | ||
application.sessions |
number | ||
application.users |
number | ||
changed |
boolean | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
POST /admin-api/saml2/remove-signing-certificate
removeSaml2SigningCertificate
Take one registered signing certificate off a service provider
By value — the base64 DER exactly as GET /admin-api/saml2?sp= lists it in signingCertificates (a PEM is accepted and normalised). Signatures made with that key stop verifying from the next request. Removing the last one leaves this service provider’s signatures recorded as no-certificate and not verified.
Mirrors POST /admin/saml2 on the admin console.
Scope: admin:write.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
DPoP |
header | string | RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires. |
|
cell |
query | string | The cell to answer this request, where this service runs as several. Ignored in a service that runs as one. |
Request body
| Member | Type | Required | What it is |
|---|---|---|---|
sp |
string | yes | |
value |
string | yes | The certificate to remove. |
200: The application entry as it now stands.
| Member | Type | Required | What it is |
|---|---|---|---|
application |
object | ||
application.allowedProtocols |
list | ||
application.allowedProtocols[] |
string | ||
application.attributes |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.attributes.{key} |
list, or string, or null | ||
application.attributes.{key}[] |
string | ||
application.authentications |
number | ||
application.createdAt |
string, or null | ||
application.declaredKinds |
list | ||
application.declaredKinds[] |
string | ||
application.description |
string, or null | ||
application.dn |
string, or null | ||
application.dnLabel |
string, or null | ||
application.fields |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.fields.{key} |
list, or string, or null | ||
application.fields.{key}[] |
string | ||
application.firstSeen |
string | ||
application.identifier |
string | ||
application.kinds |
list | ||
application.kinds[] |
string | ||
application.lastSeen |
string | ||
application.modifiedAt |
string, or null | ||
application.name |
string, or null | ||
application.operational |
list | ||
application.operational[] |
string | ||
application.origin |
string, or null | ||
application.protocols |
list | ||
application.protocols[] |
string | ||
application.recordedProtocols |
list | ||
application.recordedProtocols[] |
string | ||
application.registered |
boolean | ||
application.registeredBy |
string | ||
application.returnAddressesObserved |
list | ||
application.returnAddressesObserved[].attribute |
string | ||
application.returnAddressesObserved[].held |
boolean | ||
application.returnAddressesObserved[].trusted |
boolean | ||
application.returnAddressesObserved[].value |
string | ||
application.sessions |
number | ||
application.users |
number | ||
changed |
boolean | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
application |
object | ||
application.allowedProtocols |
list | ||
application.allowedProtocols[] |
string | ||
application.attributes |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.attributes.{key} |
list, or string, or null | ||
application.attributes.{key}[] |
string | ||
application.authentications |
number | ||
application.createdAt |
string, or null | ||
application.declaredKinds |
list | ||
application.declaredKinds[] |
string | ||
application.description |
string, or null | ||
application.dn |
string, or null | ||
application.dnLabel |
string, or null | ||
application.fields |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.fields.{key} |
list, or string, or null | ||
application.fields.{key}[] |
string | ||
application.firstSeen |
string | ||
application.identifier |
string | ||
application.kinds |
list | ||
application.kinds[] |
string | ||
application.lastSeen |
string | ||
application.modifiedAt |
string, or null | ||
application.name |
string, or null | ||
application.operational |
list | ||
application.operational[] |
string | ||
application.origin |
string, or null | ||
application.protocols |
list | ||
application.protocols[] |
string | ||
application.recordedProtocols |
list | ||
application.recordedProtocols[] |
string | ||
application.registered |
boolean | ||
application.registeredBy |
string | ||
application.returnAddressesObserved |
list | ||
application.returnAddressesObserved[].attribute |
string | ||
application.returnAddressesObserved[].held |
boolean | ||
application.returnAddressesObserved[].trusted |
boolean | ||
application.returnAddressesObserved[].value |
string | ||
application.sessions |
number | ||
application.users |
number | ||
changed |
boolean | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
POST /admin-api/saml2/set-logout-service
addSaml2LogoutService
Declare where this service provider’s LogoutResponse goes
A <samlp:LogoutRequest> CARRIES NO RETURN ADDRESS — only SP metadata does. The SingleLogoutService endpoints of the service provider’s CONSUMED metadata are used first; with none, what is declared here; then the profile falls back to saml2.defaultSingleLogoutService and then to the assertion consumer service URL that service provider last used, WHICH IS A GUESS and is logged as one. This is how to remove the guess.
It writes samlSingleLogoutService on the application entry, so an ldapmodify of the same attribute does exactly this — two doors onto one value, not two stores.
Mirrors POST /admin/saml2 on the admin console.
Scope: admin:write.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
DPoP |
header | string | RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires. |
|
cell |
query | string | The cell to answer this request, where this service runs as several. Ignored in a service that runs as one. |
Request body
| Member | Type | Required | What it is |
|---|---|---|---|
sp |
string | yes | The service provider’s entityID. |
value |
string | yes | An absolute URL. |
200: The application entry as it now stands.
| Member | Type | Required | What it is |
|---|---|---|---|
application |
object | ||
application.allowedProtocols |
list | ||
application.allowedProtocols[] |
string | ||
application.attributes |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.attributes.{key} |
list, or string, or null | ||
application.attributes.{key}[] |
string | ||
application.authentications |
number | ||
application.createdAt |
string, or null | ||
application.declaredKinds |
list | ||
application.declaredKinds[] |
string | ||
application.description |
string, or null | ||
application.dn |
string, or null | ||
application.dnLabel |
string, or null | ||
application.fields |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.fields.{key} |
list, or string, or null | ||
application.fields.{key}[] |
string | ||
application.firstSeen |
string | ||
application.identifier |
string | ||
application.kinds |
list | ||
application.kinds[] |
string | ||
application.lastSeen |
string | ||
application.modifiedAt |
string, or null | ||
application.name |
string, or null | ||
application.operational |
list | ||
application.operational[] |
string | ||
application.origin |
string, or null | ||
application.protocols |
list | ||
application.protocols[] |
string | ||
application.recordedProtocols |
list | ||
application.recordedProtocols[] |
string | ||
application.registered |
boolean | ||
application.registeredBy |
string | ||
application.returnAddressesObserved |
list | ||
application.returnAddressesObserved[].attribute |
string | ||
application.returnAddressesObserved[].held |
boolean | ||
application.returnAddressesObserved[].trusted |
boolean | ||
application.returnAddressesObserved[].value |
string | ||
application.sessions |
number | ||
application.users |
number | ||
changed |
boolean | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
application |
object | ||
application.allowedProtocols |
list | ||
application.allowedProtocols[] |
string | ||
application.attributes |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.attributes.{key} |
list, or string, or null | ||
application.attributes.{key}[] |
string | ||
application.authentications |
number | ||
application.createdAt |
string, or null | ||
application.declaredKinds |
list | ||
application.declaredKinds[] |
string | ||
application.description |
string, or null | ||
application.dn |
string, or null | ||
application.dnLabel |
string, or null | ||
application.fields |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.fields.{key} |
list, or string, or null | ||
application.fields.{key}[] |
string | ||
application.firstSeen |
string | ||
application.identifier |
string | ||
application.kinds |
list | ||
application.kinds[] |
string | ||
application.lastSeen |
string | ||
application.modifiedAt |
string, or null | ||
application.name |
string, or null | ||
application.operational |
list | ||
application.operational[] |
string | ||
application.origin |
string, or null | ||
application.protocols |
list | ||
application.protocols[] |
string | ||
application.recordedProtocols |
list | ||
application.recordedProtocols[] |
string | ||
application.registered |
boolean | ||
application.registeredBy |
string | ||
application.returnAddressesObserved |
list | ||
application.returnAddressesObserved[].attribute |
string | ||
application.returnAddressesObserved[].held |
boolean | ||
application.returnAddressesObserved[].trusted |
boolean | ||
application.returnAddressesObserved[].value |
string | ||
application.sessions |
number | ||
application.users |
number | ||
changed |
boolean | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
POST /admin-api/saml2/set-metadata-signing-certificate
setSaml2MetadataSigningCertificate
Require this service provider’s metadata to be signed with one key
Writes samlSpMetadataSigningCertificate. With it set, consuming a metadata document — a refresh or an upload — REFUSES one that is unsigned or whose signature does not verify against this certificate, and changes nothing. Without it a signed document is consumed and recorded as signed-not-verified: the trust act is then the administrator’s choice of URL or document. Base64 DER or PEM, any key an XML signature is verified with here; empty clears it. The realm’s saml2.metadataTrustAnchors are accepted as well.
Mirrors POST /admin/saml2 on the admin console.
Scope: admin:write.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
DPoP |
header | string | RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires. |
|
cell |
query | string | The cell to answer this request, where this service runs as several. Ignored in a service that runs as one. |
Request body
| Member | Type | Required | What it is |
|---|---|---|---|
sp |
string | yes | |
value |
string | Base64 DER or PEM; empty clears it. |
200: The application entry as it now stands.
| Member | Type | Required | What it is |
|---|---|---|---|
application |
object | ||
application.allowedProtocols |
list | ||
application.allowedProtocols[] |
string | ||
application.attributes |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.attributes.{key} |
list, or string, or null | ||
application.attributes.{key}[] |
string | ||
application.authentications |
number | ||
application.createdAt |
string, or null | ||
application.declaredKinds |
list | ||
application.declaredKinds[] |
string | ||
application.description |
string, or null | ||
application.dn |
string, or null | ||
application.dnLabel |
string, or null | ||
application.fields |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.fields.{key} |
list, or string, or null | ||
application.fields.{key}[] |
string | ||
application.firstSeen |
string | ||
application.identifier |
string | ||
application.kinds |
list | ||
application.kinds[] |
string | ||
application.lastSeen |
string | ||
application.modifiedAt |
string, or null | ||
application.name |
string, or null | ||
application.operational |
list | ||
application.operational[] |
string | ||
application.origin |
string, or null | ||
application.protocols |
list | ||
application.protocols[] |
string | ||
application.recordedProtocols |
list | ||
application.recordedProtocols[] |
string | ||
application.registered |
boolean | ||
application.registeredBy |
string | ||
application.returnAddressesObserved |
list | ||
application.returnAddressesObserved[].attribute |
string | ||
application.returnAddressesObserved[].held |
boolean | ||
application.returnAddressesObserved[].trusted |
boolean | ||
application.returnAddressesObserved[].value |
string | ||
application.sessions |
number | ||
application.users |
number | ||
changed |
boolean | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
application |
object | ||
application.allowedProtocols |
list | ||
application.allowedProtocols[] |
string | ||
application.attributes |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.attributes.{key} |
list, or string, or null | ||
application.attributes.{key}[] |
string | ||
application.authentications |
number | ||
application.createdAt |
string, or null | ||
application.declaredKinds |
list | ||
application.declaredKinds[] |
string | ||
application.description |
string, or null | ||
application.dn |
string, or null | ||
application.dnLabel |
string, or null | ||
application.fields |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.fields.{key} |
list, or string, or null | ||
application.fields.{key}[] |
string | ||
application.firstSeen |
string | ||
application.identifier |
string | ||
application.kinds |
list | ||
application.kinds[] |
string | ||
application.lastSeen |
string | ||
application.modifiedAt |
string, or null | ||
application.name |
string, or null | ||
application.operational |
list | ||
application.operational[] |
string | ||
application.origin |
string, or null | ||
application.protocols |
list | ||
application.protocols[] |
string | ||
application.recordedProtocols |
list | ||
application.recordedProtocols[] |
string | ||
application.registered |
boolean | ||
application.registeredBy |
string | ||
application.returnAddressesObserved |
list | ||
application.returnAddressesObserved[].attribute |
string | ||
application.returnAddressesObserved[].held |
boolean | ||
application.returnAddressesObserved[].trusted |
boolean | ||
application.returnAddressesObserved[].value |
string | ||
application.sessions |
number | ||
application.users |
number | ||
changed |
boolean | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
POST /admin-api/saml2/set-signing-certificate
setSaml2SigningCertificate
Replace the certificates this service provider’s signatures are verified against
THE TRUST ANCHOR FOR THIS SERVICE PROVIDER’S SIGNATURES (2026-09-17). A signed AuthnRequest, LogoutRequest or LogoutResponse from it is VERIFIED against samlSigningCertificate in every mode, and refused when it verifies against none — never against the certificate the request carries. The attribute is a LIST (a metadata rollover publishes two keys); this REPLACES it with the one certificate given, and an empty value clears it. Consuming the service provider’s metadata writes the same list.
Base64 DER or PEM — the armour and whitespace are stripped, because what the attribute holds is what a ds:X509Certificate carries. A value that is not a certificate whose key makes an XML signature this service verifies (RSA, EC, EdDSA, DSA, ML-DSA, SLH-DSA) is refused and nothing changes: an unusable certificate would make every signature from this service provider fail. Public key material, worth nothing to whoever reads the directory.
Mirrors POST /admin/saml2 on the admin console.
Scope: admin:write.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
DPoP |
header | string | RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires. |
|
cell |
query | string | The cell to answer this request, where this service runs as several. Ignored in a service that runs as one. |
Request body
| Member | Type | Required | What it is |
|---|---|---|---|
sp |
string | yes | |
value |
string | Base64 DER or PEM; empty clears the list. |
200: The application entry as it now stands.
| Member | Type | Required | What it is |
|---|---|---|---|
application |
object | ||
application.allowedProtocols |
list | ||
application.allowedProtocols[] |
string | ||
application.attributes |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.attributes.{key} |
list, or string, or null | ||
application.attributes.{key}[] |
string | ||
application.authentications |
number | ||
application.createdAt |
string, or null | ||
application.declaredKinds |
list | ||
application.declaredKinds[] |
string | ||
application.description |
string, or null | ||
application.dn |
string, or null | ||
application.dnLabel |
string, or null | ||
application.fields |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.fields.{key} |
list, or string, or null | ||
application.fields.{key}[] |
string | ||
application.firstSeen |
string | ||
application.identifier |
string | ||
application.kinds |
list | ||
application.kinds[] |
string | ||
application.lastSeen |
string | ||
application.modifiedAt |
string, or null | ||
application.name |
string, or null | ||
application.operational |
list | ||
application.operational[] |
string | ||
application.origin |
string, or null | ||
application.protocols |
list | ||
application.protocols[] |
string | ||
application.recordedProtocols |
list | ||
application.recordedProtocols[] |
string | ||
application.registered |
boolean | ||
application.registeredBy |
string | ||
application.returnAddressesObserved |
list | ||
application.returnAddressesObserved[].attribute |
string | ||
application.returnAddressesObserved[].held |
boolean | ||
application.returnAddressesObserved[].trusted |
boolean | ||
application.returnAddressesObserved[].value |
string | ||
application.sessions |
number | ||
application.users |
number | ||
changed |
boolean | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
application |
object | ||
application.allowedProtocols |
list | ||
application.allowedProtocols[] |
string | ||
application.attributes |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.attributes.{key} |
list, or string, or null | ||
application.attributes.{key}[] |
string | ||
application.authentications |
number | ||
application.createdAt |
string, or null | ||
application.declaredKinds |
list | ||
application.declaredKinds[] |
string | ||
application.description |
string, or null | ||
application.dn |
string, or null | ||
application.dnLabel |
string, or null | ||
application.fields |
map | Attribute names, which are data in a schemaless directory, and values. | |
application.fields.{key} |
list, or string, or null | ||
application.fields.{key}[] |
string | ||
application.firstSeen |
string | ||
application.identifier |
string | ||
application.kinds |
list | ||
application.kinds[] |
string | ||
application.lastSeen |
string | ||
application.modifiedAt |
string, or null | ||
application.name |
string, or null | ||
application.operational |
list | ||
application.operational[] |
string | ||
application.origin |
string, or null | ||
application.protocols |
list | ||
application.protocols[] |
string | ||
application.recordedProtocols |
list | ||
application.recordedProtocols[] |
string | ||
application.registered |
boolean | ||
application.registeredBy |
string | ||
application.returnAddressesObserved |
list | ||
application.returnAddressesObserved[].attribute |
string | ||
application.returnAddressesObserved[].held |
boolean | ||
application.returnAddressesObserved[].trusted |
boolean | ||
application.returnAddressesObserved[].value |
string | ||
application.sessions |
number | ||
application.users |
number | ||
changed |
boolean | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
POST /admin-api/saml2/upload-metadata
uploadSaml2Metadata
Consume a service provider’s metadata document
The same CONSUMPTION POST /admin-api/applications/refresh-metadata performs on a fetched document, for a document given here — a service provider whose metadata this service cannot reach. It REGISTERS what the <md:SPSSODescriptor> says: every AssertionConsumerService (binding, location, index, isDefault) as a return address — an AuthnRequest is then answered only at one of them, by index, by URL or by default, in every mode — every SingleLogoutService, every signing certificate (use="signing" or no use) as what its requests are verified against, the encryption certificate, its NameIDFormats (a NameIDPolicy naming another is then InvalidNameIDPolicy), and AuthnRequestsSigned and WantAssertionsSigned. The EFFECTIVE validUntil (earliest in the chain) is enforced — past it every request from the service provider is refused — and past the cacheDuration a document with a URL is fetched again in the background. An EntitiesDescriptor is read for this entity. The protocol URI is selected from the application declaration: SAML 1.1 is selected only for an entry declared for saml11 and not saml2; SAML 2.0 remains the choice for SAML 2.0, dual-protocol and undeclared entries unless family explicitly selects one declared SAML family. This operation can therefore consume SAML 1.1-only metadata as well.
REFUSED, changing nothing, for: a document that is not an EntityDescriptor (or an aggregate holding exactly one for this entity) with the selected SPSSODescriptor; an entityID that is not this service provider’s; a validUntil already passed; an encryption certificate this service cannot encrypt to; a signature that does not verify against samlSpMetadataSigningCertificate or a realm trust anchor when any is set (or no signature then); and a document over saml2.spMetadataMaxBytes. A signing certificate no XML signature method uses is skipped and named in skipped.
Mirrors POST /admin/saml2 on the admin console.
Scope: admin:write.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
DPoP |
header | string | RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires. |
|
cell |
query | string | The cell to answer this request, where this service runs as several. Ignored in a service that runs as one. |
Request body
| Member | Type | Required | What it is |
|---|---|---|---|
| (the answer) | any JSON |
200: What was consumed: signature, the endpoint locations, how many signing certificates were registered, and skipped.
| Member | Type | Required | What it is |
|---|---|---|---|
application |
string | ||
assertionConsumerServices |
list | ||
assertionConsumerServices[] |
string | ||
authnRequestsSigned |
boolean | ||
cacheDuration |
string, or null | ||
certificateUse |
string | ||
created |
boolean | ||
entityId |
string | ||
errors |
list | ||
errors[] |
string | ||
how |
string | ||
message |
string | ||
nameIdFormats |
list | ||
nameIdFormats[] |
string | ||
ok |
boolean | yes | |
signature |
string | ||
signingCertificates |
number | ||
singleLogoutServices |
list | ||
singleLogoutServices[] |
string | ||
skipped |
list | ||
skipped[] |
string | ||
url |
string | ||
validUntil |
string, or null | ||
wantAssertionsSigned |
boolean | ||
warnings |
list | ||
warnings[] |
string | ||
why |
string |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
application |
string | ||
assertionConsumerServices |
list | ||
assertionConsumerServices[] |
string | ||
authnRequestsSigned |
boolean | ||
cacheDuration |
string, or null | ||
certificateUse |
string | ||
created |
boolean | ||
entityId |
string | ||
errors |
list | ||
errors[] |
string | ||
how |
string | ||
message |
string | ||
nameIdFormats |
list | ||
nameIdFormats[] |
string | ||
ok |
boolean | yes | |
signature |
string | ||
signingCertificates |
number | ||
singleLogoutServices |
list | ||
singleLogoutServices[] |
string | ||
skipped |
list | ||
skipped[] |
string | ||
url |
string | ||
validUntil |
string, or null | ||
wantAssertionsSigned |
boolean | ||
warnings |
list | ||
warnings[] |
string | ||
why |
string |