From 56246096e09728ae6e62903120d042f40195ee5d Mon Sep 17 00:00:00 2001 From: Jan Verhaeghe Date: Thu, 19 Dec 2024 14:48:18 +0100 Subject: [PATCH] Align on one realm-name placeholder Closes #36047 Signed-off-by: Jan Verhaeghe --- .../topics/enforcer-js-adapter.adoc | 4 +-- ...vice-authorization-discovery-document.adoc | 14 +++++----- ...n-obtaining-permission-authentication.adoc | 4 +-- ...ce-authorization-obtaining-permission.adoc | 6 ++--- .../service-authorization-pushing-claims.adoc | 2 +- ...rvice-authorization-uma-authz-process.adoc | 6 ++--- ...ion-uma-submiting-permission-requests.adoc | 2 +- ...ervice-protection-permission-api-papi.adoc | 14 +++++----- .../topics/service-protection-policy-api.adoc | 10 +++---- ...service-protection-resources-api-papi.adoc | 26 +++++++++---------- .../service-protection-whatis-obtain-pat.adoc | 2 +- .../service-rpt-token-introspection.adoc | 2 +- .../release_notes/topics/22_0_0.adoc | 2 +- .../clients/saml/idp-initiated-login.adoc | 4 +-- .../saml/proc-creating-saml-client.adoc | 2 +- .../saml/proc-using-an-entity-descriptor.adoc | 2 +- .../topics/identity-broker/tokens.adoc | 2 +- .../identity-brokering/account-linking.adoc | 4 +-- .../topics/identity-brokering/tokens.adoc | 2 +- .../server_development/topics/themes.adoc | 2 +- .../topics/changes/changes-23_0_0.adoc | 6 ++--- .../topics/changes/changes-24_0_0.adoc | 4 +-- .../topics/changes/changes-26_0_0.adoc | 2 +- docs/guides/securing-apps/token-exchange.adoc | 2 +- .../server/bootstrap-admin-recovery.adoc | 4 +-- docs/transient-users.md | 4 +-- 26 files changed, 67 insertions(+), 67 deletions(-) diff --git a/docs/documentation/authorization_services/topics/enforcer-js-adapter.adoc b/docs/documentation/authorization_services/topics/enforcer-js-adapter.adoc index 57f0f78feae..c131b417e72 100644 --- a/docs/documentation/authorization_services/topics/enforcer-js-adapter.adoc +++ b/docs/documentation/authorization_services/topics/enforcer-js-adapter.adoc @@ -49,8 +49,8 @@ responds with a *401* status code and a `WWW-Authenticate` header. [source,bash,subs="attributes+"] ---- HTTP/1.1 401 Unauthorized -WWW-Authenticate: UMA realm="${realm}", - as_uri="https://${host}:${port}{kc_realms_path}/${realm}", +WWW-Authenticate: UMA realm="${realm-name}", + as_uri="https://${host}:${port}{kc_realms_path}/${realm-name}", ticket="016f84e8-f9b9-11e0-bd6f-0021cc6004de" ---- diff --git a/docs/documentation/authorization_services/topics/service-authorization-discovery-document.adoc b/docs/documentation/authorization_services/topics/service-authorization-discovery-document.adoc index e8318b89125..d946b42f2cd 100644 --- a/docs/documentation/authorization_services/topics/service-authorization-discovery-document.adoc +++ b/docs/documentation/authorization_services/topics/service-authorization-discovery-document.adoc @@ -9,10 +9,10 @@ The discovery document can be obtained from: [source,bash,subs="attributes+"] ---- curl -X GET \ - http://${host}:${port}{kc_realms_path}/${realm}/.well-known/uma2-configuration + http://${host}:${port}{kc_realms_path}/${realm-name}/.well-known/uma2-configuration ---- -Where `${host}:${port}` is the hostname (or IP address) and port where {project_name} is running and `${realm}` is the name of +Where `${host}:${port}` is the hostname (or IP address) and port where {project_name} is running and `${realm-name}` is the name of a realm in {project_name}. As a result, you should get a response as follows: @@ -24,11 +24,11 @@ As a result, you should get a response as follows: // some claims are expected here // these are the main claims in the discovery document about Authorization Services endpoints location - "token_endpoint": "http://${host}:${port}{kc_realms_path}/${realm}/protocol/openid-connect/token", - "token_introspection_endpoint": "http://${host}:${port}{kc_realms_path}/${realm}/protocol/openid-connect/token/introspect", - "resource_registration_endpoint": "http://${host}:${port}{kc_realms_path}/${realm}/authz/protection/resource_set", - "permission_endpoint": "http://${host}:${port}{kc_realms_path}/${realm}/authz/protection/permission", - "policy_endpoint": "http://${host}:${port}{kc_realms_path}/${realm}/authz/protection/uma-policy" + "token_endpoint": "http://${host}:${port}{kc_realms_path}/${realm-name}/protocol/openid-connect/token", + "token_introspection_endpoint": "http://${host}:${port}{kc_realms_path}/${realm-name}/protocol/openid-connect/token/introspect", + "resource_registration_endpoint": "http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/resource_set", + "permission_endpoint": "http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/permission", + "policy_endpoint": "http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/uma-policy" } ---- diff --git a/docs/documentation/authorization_services/topics/service-authorization-obtaining-permission-authentication.adoc b/docs/documentation/authorization_services/topics/service-authorization-obtaining-permission-authentication.adoc index cd38856442c..603624e7442 100644 --- a/docs/documentation/authorization_services/topics/service-authorization-obtaining-permission-authentication.adoc +++ b/docs/documentation/authorization_services/topics/service-authorization-obtaining-permission-authentication.adoc @@ -12,7 +12,7 @@ Clients should send an access token as a Bearer credential in an HTTP Authorizat [source,bash,subs="attributes+"] ---- curl -X POST \ - http://${host}:${port}{kc_realms_path}/${realm}/protocol/openid-connect/token \ + http://${host}:${port}{kc_realms_path}/${realm-name}/protocol/openid-connect/token \ -H "Authorization: Bearer ${access_token}" \ --data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" ---- @@ -31,7 +31,7 @@ Clients can use any of the client authentication methods supported by {project_n [source,bash,subs="attributes+"] ---- curl -X POST \ - http://${host}:${port}{kc_realms_path}/${realm}/protocol/openid-connect/token \ + http://${host}:${port}{kc_realms_path}/${realm-name}/protocol/openid-connect/token \ -H "Authorization: Basic cGhvdGg6L7Jl13RmfWgtkk==pOnNlY3JldA==" \ --data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" ---- diff --git a/docs/documentation/authorization_services/topics/service-authorization-obtaining-permission.adoc b/docs/documentation/authorization_services/topics/service-authorization-obtaining-permission.adoc index daaeb411dfd..ea3a9c2f9e7 100644 --- a/docs/documentation/authorization_services/topics/service-authorization-obtaining-permission.adoc +++ b/docs/documentation/authorization_services/topics/service-authorization-obtaining-permission.adoc @@ -105,7 +105,7 @@ Example of an authorization request when a client is seeking access to two resou [source,bash,subs="attributes+"] ---- curl -X POST \ - http://${host}:${port}{kc_realms_path}/${realm}/protocol/openid-connect/token \ + http://${host}:${port}{kc_realms_path}/${realm-name}/protocol/openid-connect/token \ -H "Authorization: Bearer ${access_token}" \ --data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" \ --data "audience={resource_server_client_id}" \ @@ -120,7 +120,7 @@ and explicitly granted to the requesting user by other owners are evaluated. [source,bash,subs="attributes+"] ---- curl -X POST \ - http://${host}:${port}{kc_realms_path}/${realm}/protocol/openid-connect/token \ + http://${host}:${port}{kc_realms_path}/${realm-name}/protocol/openid-connect/token \ -H "Authorization: Bearer ${access_token}" \ --data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" \ --data "audience={resource_server_client_id}" @@ -132,7 +132,7 @@ the resource server as part of the authorization process: [source,bash,subs="attributes+"] ---- curl -X POST \ - http://${host}:${port}{kc_realms_path}/${realm}/protocol/openid-connect/token \ + http://${host}:${port}{kc_realms_path}/${realm-name}/protocol/openid-connect/token \ -H "Authorization: Bearer ${access_token}" \ --data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" \ --data "ticket=${permission_ticket} diff --git a/docs/documentation/authorization_services/topics/service-authorization-pushing-claims.adoc b/docs/documentation/authorization_services/topics/service-authorization-pushing-claims.adoc index a943f938a3f..f99d5103487 100644 --- a/docs/documentation/authorization_services/topics/service-authorization-pushing-claims.adoc +++ b/docs/documentation/authorization_services/topics/service-authorization-pushing-claims.adoc @@ -10,7 +10,7 @@ an authorization request to the token endpoint as follows: [source,bash,subs="attributes+"] ---- curl -X POST \ - http://${host}:${port}{kc_realms_path}/${realm}/protocol/openid-connect/token \ + http://${host}:${port}{kc_realms_path}/${realm-name}/protocol/openid-connect/token \ --data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" \ --data "claim_token=ewogICAib3JnYW5pemF0aW9uIjogWyJhY21lIl0KfQ==" \ --data "claim_token_format=urn:ietf:params:oauth:token-type:jwt" \ diff --git a/docs/documentation/authorization_services/topics/service-authorization-uma-authz-process.adoc b/docs/documentation/authorization_services/topics/service-authorization-uma-authz-process.adoc index 32392fc2b6a..aeabd843eda 100644 --- a/docs/documentation/authorization_services/topics/service-authorization-uma-authz-process.adoc +++ b/docs/documentation/authorization_services/topics/service-authorization-uma-authz-process.adoc @@ -19,8 +19,8 @@ of a {project_name} server to where the ticket should be sent in order to obtain [source,bash,subs="attributes+"] ---- HTTP/1.1 401 Unauthorized -WWW-Authenticate: UMA realm="${realm}", - as_uri="https://${host}:${port}{kc_realms_path}/${realm}", +WWW-Authenticate: UMA realm="${realm-name}", + as_uri="https://${host}:${port}{kc_realms_path}/${realm-name}", ticket="016f84e8-f9b9-11e0-bd6f-0021cc6004de" ---- @@ -34,7 +34,7 @@ to obtain the location of the token endpoint and send an authorization request. [source,bash,subs="attributes+"] ---- curl -X POST \ - http://${host}:${port}{kc_realms_path}/${realm}/protocol/openid-connect/token \ + http://${host}:${port}{kc_realms_path}/${realm-name}/protocol/openid-connect/token \ -H "Authorization: Bearer ${access_token}" \ --data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" \ --data "ticket=${permission_ticket} diff --git a/docs/documentation/authorization_services/topics/service-authorization-uma-submiting-permission-requests.adoc b/docs/documentation/authorization_services/topics/service-authorization-uma-submiting-permission-requests.adoc index ebc1e53a5bf..87f3f024f0b 100644 --- a/docs/documentation/authorization_services/topics/service-authorization-uma-submiting-permission-requests.adoc +++ b/docs/documentation/authorization_services/topics/service-authorization-uma-submiting-permission-requests.adoc @@ -26,7 +26,7 @@ with an authorization request to the token endpoint: [source,bash,subs="attributes+"] ---- curl -X POST \ - http://${host}:${port}{kc_realms_path}/${realm}/protocol/openid-connect/token \ + http://${host}:${port}{kc_realms_path}/${realm-name}/protocol/openid-connect/token \ -H "Authorization: Bearer ${access_token}" \ --data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" \ --data "ticket=${permission_ticket} \ diff --git a/docs/documentation/authorization_services/topics/service-protection-permission-api-papi.adoc b/docs/documentation/authorization_services/topics/service-protection-permission-api-papi.adoc index 67cdc88dadc..7b1b912fb2e 100644 --- a/docs/documentation/authorization_services/topics/service-protection-permission-api-papi.adoc +++ b/docs/documentation/authorization_services/topics/service-protection-permission-api-papi.adoc @@ -5,7 +5,7 @@ Resource servers using the UMA protocol can use a specific endpoint to manage pe [source,subs="attributes+"] ---- -http://${host}:${port}{kc_realms_path}/${realm_name}/authz/protection/permission +http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/permission ---- A <<_overview_terminology_permission_ticket, permission ticket>> is a special security token type representing a permission request. Per the UMA specification, a permission ticket is: @@ -38,7 +38,7 @@ To create a permission ticket, send an HTTP POST request as follows: [source,bash,subs="attributes+"] ---- curl -X POST \ - http://${host}:${port}{kc_realms_path}/${realm_name}/authz/protection/permission \ + http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/permission \ -H 'Authorization: Bearer '$pat \ -H 'Content-Type: application/json' \ -d '[ @@ -56,7 +56,7 @@ When creating tickets you can also push arbitrary claims and associate these cla [source,bash,subs="attributes+"] ---- curl -X POST \ - http://${host}:${port}{kc_realms_path}/${realm_name}/authz/protection/permission \ + http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/permission \ -H 'Authorization: Bearer '$pat \ -H 'Content-Type: application/json' \ -d '[ @@ -84,7 +84,7 @@ To grant permissions for a specific resource with id {resource_id} to a user wit [source,bash,subs="attributes+"] ---- curl -X POST \ - http://${host}:${port}{kc_realms_path}/${realm_name}/authz/protection/permission/ticket \ + http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/permission/ticket \ -H 'Authorization: Bearer '$access_token \ -H 'Content-Type: application/json' \ -d '{ @@ -99,7 +99,7 @@ curl -X POST \ [source,bash,subs="attributes+"] ---- -curl http://${host}:${port}{kc_realms_path}/${realm_name}/authz/protection/permission/ticket \ +curl http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/permission/ticket \ -H 'Authorization: Bearer '$access_token ---- @@ -119,7 +119,7 @@ You can use any of these query parameters: [source,bash,subs="attributes+"] ---- curl -X PUT \ - http://${host}:${port}{kc_realms_path}/${realm_name}/authz/protection/permission/ticket \ + http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/permission/ticket \ -H 'Authorization: Bearer '$access_token \ -H 'Content-Type: application/json' \ -d '{ @@ -135,6 +135,6 @@ curl -X PUT \ [source,bash,subs="attributes+"] ---- -curl -X DELETE http://${host}:${port}{kc_realms_path}/${realm_name}/authz/protection/permission/ticket/{ticket_id} \ +curl -X DELETE http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/permission/ticket/{ticket_id} \ -H 'Authorization: Bearer '$access_token ---- diff --git a/docs/documentation/authorization_services/topics/service-protection-policy-api.adoc b/docs/documentation/authorization_services/topics/service-protection-policy-api.adoc index 7dcbc3fe9f1..2bde8c1006b 100644 --- a/docs/documentation/authorization_services/topics/service-protection-policy-api.adoc +++ b/docs/documentation/authorization_services/topics/service-protection-policy-api.adoc @@ -9,7 +9,7 @@ The Policy API is available at: [source,subs="attributes+"] ---- -http://${host}:${port}{kc_realms_path}/${realm_name}/authz/protection/uma-policy/{resource_id} +http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/uma-policy/{resource_id} ---- This API is protected by a bearer token that must represent a consent granted by the user to the resource server to manage permissions on his behalf. The bearer token can be a regular access token obtained from the @@ -136,28 +136,28 @@ To query the permissions associated with a resource, send an HTTP GET request as [source,subs="attributes+"] ---- -http://${host}:${port}{kc_realms_path}/${realm}/authz/protection/uma-policy?resource={resource_id} +http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/uma-policy?resource={resource_id} ---- To query the permissions given its name, send an HTTP GET request as follows: [source,bash,subs="attributes+"] ---- -http://${host}:${port}{kc_realms_path}/${realm}/authz/protection/uma-policy?name=Any people manager +http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/uma-policy?name=Any people manager ---- To query the permissions associated with a specific scope, send an HTTP GET request as follows: [source,subs="attributes+"] ---- -http://${host}:${port}{kc_realms_path}/${realm}/authz/protection/uma-policy?scope=read +http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/uma-policy?scope=read ---- To query all permissions, send an HTTP GET request as follows: [source,subs="attributes+"] ---- -http://${host}:${port}{kc_realms_path}/${realm}/authz/protection/uma-policy +http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/uma-policy ---- When querying the server for permissions use parameters `first` and `max` results to limit the result. diff --git a/docs/documentation/authorization_services/topics/service-protection-resources-api-papi.adoc b/docs/documentation/authorization_services/topics/service-protection-resources-api-papi.adoc index cfcea104ae0..4f5ae729aa0 100644 --- a/docs/documentation/authorization_services/topics/service-protection-resources-api-papi.adoc +++ b/docs/documentation/authorization_services/topics/service-protection-resources-api-papi.adoc @@ -5,7 +5,7 @@ Resource servers can manage their resources remotely using a UMA-compliant endpo [source,subs="attributes+"] ---- -http://${host}:${port}{kc_realms_path}/${realm_name}/authz/protection/resource_set +http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/resource_set ---- This endpoint provides operations outlined as follows (entire path omitted for clarity): @@ -25,7 +25,7 @@ To create a resource you must send an HTTP POST request as follows: [source,bash,subs="attributes+"] ---- curl -v -X POST \ - http://${host}:${port}{kc_realms_path}/${realm_name}/authz/protection/resource_set \ + http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/resource_set \ -H 'Authorization: Bearer '$pat \ -H 'Content-Type: application/json' \ -d '{ @@ -47,7 +47,7 @@ specific user, you can send a request as follows: [source,bash,subs="attributes+"] ---- curl -v -X POST \ - http://${host}:${port}{kc_realms_path}/${realm_name}/authz/protection/resource_set \ + http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/resource_set \ -H 'Authorization: Bearer '$pat \ -H 'Content-Type: application/json' \ -d '{ @@ -67,7 +67,7 @@ To create resources and allow resource owners to manage these resources, you mus [source,bash,subs="attributes+"] ---- curl -v -X POST \ - http://${host}:${port}{kc_realms_path}/${realm_name}/authz/protection/resource_set \ + http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/resource_set \ -H 'Authorization: Bearer '$pat \ -H 'Content-Type: application/json' \ -d '{ @@ -84,7 +84,7 @@ To update an existing resource, send an HTTP PUT request as follows: [source,bash,subs="attributes+"] ---- curl -v -X PUT \ - http://${host}:${port}{kc_realms_path}/${realm_name}/authz/protection/resource_set/{resource_id} \ + http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/resource_set/{resource_id} \ -H 'Authorization: Bearer '$pat \ -H 'Content-Type: application/json' \ -d '{ @@ -103,7 +103,7 @@ To delete an existing resource, send an HTTP DELETE request as follows: [source,bash,subs="attributes+"] ---- curl -v -X DELETE \ - http://${host}:${port}{kc_realms_path}/${realm_name}/authz/protection/resource_set/{resource_id} \ + http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/resource_set/{resource_id} \ -H 'Authorization: Bearer '$pat ---- @@ -113,49 +113,49 @@ To query the resources by `id`, send an HTTP GET request as follows: [source,bash,subs="attributes+"] ---- -http://${host}:${port}{kc_realms_path}/${realm_name}/authz/protection/resource_set/{resource_id} +http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/resource_set/{resource_id} ---- To query resources given a `name`, send an HTTP GET request as follows: [source,bash,subs="attributes+"] ---- -http://${host}:${port}{kc_realms_path}/${realm_name}/authz/protection/resource_set?name=Alice Resource +http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/resource_set?name=Alice Resource ---- By default, the `name` filter will match any resource with the given pattern. To restrict the query to only return resources with an exact match, use: [source,bash,subs="attributes+"] ---- -http://${host}:${port}{kc_realms_path}/${realm_name}/authz/protection/resource_set?name=Alice Resource&exactName=true +http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/resource_set?name=Alice Resource&exactName=true ---- To query resources given an `uri`, send an HTTP GET request as follows: [source,bash,subs="attributes+"] ---- -http://${host}:${port}{kc_realms_path}/${realm_name}/authz/protection/resource_set?uri=/api/alice +http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/resource_set?uri=/api/alice ---- To query resources given an `owner`, send an HTTP GET request as follows: [source,bash,subs="attributes+"] ---- -http://${host}:${port}{kc_realms_path}/${realm_name}/authz/protection/resource_set?owner=alice +http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/resource_set?owner=alice ---- To query resources given an `type`, send an HTTP GET request as follows: [source,bash,subs="attributes+"] ---- -http://${host}:${port}{kc_realms_path}/${realm_name}/authz/protection/resource_set?type=albums +http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/resource_set?type=albums ---- To query resources given an `scope`, send an HTTP GET request as follows: [source,bash,subs="attributes+"] ---- -http://${host}:${port}{kc_realms_path}/${realm_name}/authz/protection/resource_set?scope=read +http://${host}:${port}{kc_realms_path}/${realm-name}/authz/protection/resource_set?scope=read ---- When querying the server for permissions use parameters `first` and `max` results to limit the result. \ No newline at end of file diff --git a/docs/documentation/authorization_services/topics/service-protection-whatis-obtain-pat.adoc b/docs/documentation/authorization_services/topics/service-protection-whatis-obtain-pat.adoc index 96320272003..f554dd6e536 100644 --- a/docs/documentation/authorization_services/topics/service-protection-whatis-obtain-pat.adoc +++ b/docs/documentation/authorization_services/topics/service-protection-whatis-obtain-pat.adoc @@ -14,7 +14,7 @@ Resource servers can obtain a PAT from {project_name} like any other OAuth2 acce curl -X POST \ -H "Content-Type: application/x-www-form-urlencoded" \ -d 'grant_type=client_credentials&client_id=${client_id}&client_secret=${client_secret}' \ - "http://${host}:${port}{kc_realms_path}/${realm_name}/protocol/openid-connect/token" + "http://${host}:${port}{kc_realms_path}/${realm-name}/protocol/openid-connect/token" ---- The example above is using the *client_credentials* grant type to obtain a PAT from the server. As a result, the server returns a response similar to the following: diff --git a/docs/documentation/authorization_services/topics/service-rpt-token-introspection.adoc b/docs/documentation/authorization_services/topics/service-rpt-token-introspection.adoc index 30f69be70cc..78f113c0227 100644 --- a/docs/documentation/authorization_services/topics/service-rpt-token-introspection.adoc +++ b/docs/documentation/authorization_services/topics/service-rpt-token-introspection.adoc @@ -14,7 +14,7 @@ The token introspection is essentially a https://datatracker.ietf.org/doc/html/r [source,subs="attributes+"] ---- -http://${host}:${port}{kc_realms_path}/${realm_name}/protocol/openid-connect/token/introspect +http://${host}:${port}{kc_realms_path}/${realm-name}/protocol/openid-connect/token/introspect ---- To introspect an RPT using this endpoint, you can send a request to the server as follows: diff --git a/docs/documentation/release_notes/topics/22_0_0.adoc b/docs/documentation/release_notes/topics/22_0_0.adoc index 82761e952af..5431790c425 100644 --- a/docs/documentation/release_notes/topics/22_0_0.adoc +++ b/docs/documentation/release_notes/topics/22_0_0.adoc @@ -90,7 +90,7 @@ We still provide two separate Keycloak Admin clients, one with Jakarta EE and th == Support for count users based on custom attributes -The User API now supports querying the number of users based on custom attributes. For that, a new `q` parameter was added to the `/{realm}/users/count` endpoint. +The User API now supports querying the number of users based on custom attributes. For that, a new `q` parameter was added to the `/{realm-name}/users/count` endpoint. The `q` parameter expects the following format `q=: :`. Where `` and `` represent the attribute name and value, respectively. diff --git a/docs/documentation/server_admin/topics/clients/saml/idp-initiated-login.adoc b/docs/documentation/server_admin/topics/clients/saml/idp-initiated-login.adoc index 136620e4d0c..4c4d9865e02 100644 --- a/docs/documentation/server_admin/topics/clients/saml/idp-initiated-login.adoc +++ b/docs/documentation/server_admin/topics/clients/saml/idp-initiated-login.adoc @@ -4,7 +4,7 @@ IDP Initiated Login is a feature that allows you to set up an endpoint on the {project_name} server that will log you into a specific application/client. In the *Settings* tab for your client, you need to specify the *IDP Initiated SSO URL Name*. This is a simple string with no whitespace in it. -After this you can reference your client at the following URL: `root{kc_realms_path}/{realm}/protocol/saml/clients/{url-name}` +After this you can reference your client at the following URL: `root{kc_realms_path}/{realm-name}/protocol/saml/clients/{url-name}` The IDP initiated login implementation prefers _POST_ over _REDIRECT_ binding (check <<_saml, saml bindings>> for more information). Therefore the final binding and SP URL are selected in the following way: @@ -17,7 +17,7 @@ of the client settings) _POST_ binding is used through that URL. If your client requires a special relay state, you can also configure this on the *Settings* tab in the *IDP Initiated SSO Relay State* field. Alternatively, browsers can specify the relay state in a *RelayState* query parameter, i.e. -`root{kc_realms_path}/{realm}/protocol/saml/clients/{url-name}?RelayState=thestate`. +`root{kc_realms_path}/{realm-name}/protocol/saml/clients/{url-name}?RelayState=thestate`. When using <<_identity_broker,identity brokering>>, it is possible to set up an IDP Initiated Login for a client from an external IDP. The actual client is set up for IDP Initiated Login at broker IDP as described above. The external IDP has diff --git a/docs/documentation/server_admin/topics/clients/saml/proc-creating-saml-client.adoc b/docs/documentation/server_admin/topics/clients/saml/proc-creating-saml-client.adoc index 0c6df314566..f20c229e1b0 100644 --- a/docs/documentation/server_admin/topics/clients/saml/proc-creating-saml-client.adoc +++ b/docs/documentation/server_admin/topics/clients/saml/proc-creating-saml-client.adoc @@ -49,7 +49,7 @@ the name, set up a replacement string value. For example, a string value such as Wildcards values are allowed only at the end of a URL. For example, http://host.com/*$$. This field is used when the exact SAML endpoints are not registered and {project_name} pulls the Assertion Consumer URL from a request. -*IDP-Initiated SSO URL name*:: URL fragment name to reference client when you want to do IDP Initiated SSO. Leaving this empty will disable IDP Initiated SSO. The URL you will reference from your browser will be: _server-root_/realms/{realm}/protocol/saml/clients/{client-url-name} +*IDP-Initiated SSO URL name*:: URL fragment name to reference client when you want to do IDP Initiated SSO. Leaving this empty will disable IDP Initiated SSO. The URL you will reference from your browser will be: _server-root_/realms/{realm-name}/protocol/saml/clients/{client-url-name} *IDP Initiated SSO Relay State*:: Relay state you want to send with SAML request when you want to do IDP Initiated SSO. diff --git a/docs/documentation/server_admin/topics/clients/saml/proc-using-an-entity-descriptor.adoc b/docs/documentation/server_admin/topics/clients/saml/proc-using-an-entity-descriptor.adoc index 728ea3edde7..6b577313c1a 100644 --- a/docs/documentation/server_admin/topics/clients/saml/proc-using-an-entity-descriptor.adoc +++ b/docs/documentation/server_admin/topics/clients/saml/proc-using-an-entity-descriptor.adoc @@ -18,6 +18,6 @@ Some SAML client adapters, such as _mod-auth-mellon_, need the XML Entity Descri [source, subs="attributes"] ---- -root{kc_realms_path}/{realm}/protocol/saml/descriptor +root{kc_realms_path}/{realm-name}/protocol/saml/descriptor ---- where _realm_ is the realm of your client. diff --git a/docs/documentation/server_admin/topics/identity-broker/tokens.adoc b/docs/documentation/server_admin/topics/identity-broker/tokens.adoc index aac71ddbe5b..02ece581ded 100644 --- a/docs/documentation/server_admin/topics/identity-broker/tokens.adoc +++ b/docs/documentation/server_admin/topics/identity-broker/tokens.adoc @@ -7,7 +7,7 @@ Application code can retrieve these tokens and responses to import extra user in [source,subs="attributes+"] ---- -GET {kc_realms_path}/{realm}/broker/{provider_alias}/token HTTP/1.1 +GET {kc_realms_path}/{realm-name}/broker/{provider_alias}/token HTTP/1.1 Host: localhost:8080 Authorization: Bearer ---- diff --git a/docs/documentation/server_development/topics/identity-brokering/account-linking.adoc b/docs/documentation/server_development/topics/identity-brokering/account-linking.adoc index d0d77ce1db6..2db64fb3702 100644 --- a/docs/documentation/server_development/topics/identity-brokering/account-linking.adoc +++ b/docs/documentation/server_development/topics/identity-brokering/account-linking.adoc @@ -22,7 +22,7 @@ To initiate the login, the application must fabricate a URL and redirect the use [source,subs="attributes+"] ---- -/{auth-server-root}{kc_realms_path}/{realm}/broker/{provider}/link?client_id={id}&redirect_uri={uri}&nonce={nonce}&hash={hash} +/{auth-server-root}{kc_realms_path}/{realm-name}/broker/{provider}/link?client_id={id}&redirect_uri={uri}&nonce={nonce}&hash={hash} ---- Here's a description of each path and query param: @@ -68,7 +68,7 @@ Here's an example of Java Servlet code that generates the URL to establish the a request.getSession().setAttribute("hash", hash); String redirectUri = ...; String accountLinkUrl = KeycloakUriBuilder.fromUri(authServerRootUrl) - .path("{kc_realms_path}/{realm}/broker/{provider}/link") + .path("{kc_realms_path}/{realm-name}/broker/{provider}/link") .queryParam("nonce", nonce) .queryParam("hash", hash) .queryParam("client_id", clientId) diff --git a/docs/documentation/server_development/topics/identity-brokering/tokens.adoc b/docs/documentation/server_development/topics/identity-brokering/tokens.adoc index a11b0abb382..40c02c6154d 100644 --- a/docs/documentation/server_development/topics/identity-brokering/tokens.adoc +++ b/docs/documentation/server_development/topics/identity-brokering/tokens.adoc @@ -10,7 +10,7 @@ To retrieve a token for a particular identity provider you need to send a reques [source,subs="attributes+"] ---- -GET {kc_realms_path}/{realm}/broker/{provider_alias}/token HTTP/1.1 +GET {kc_realms_path}/{realm-name}/broker/{provider_alias}/token HTTP/1.1 Host: localhost:8080 Authorization: Bearer ---- diff --git a/docs/documentation/server_development/topics/themes.adoc b/docs/documentation/server_development/topics/themes.adoc index 74c177dd5d0..41c3d69c15f 100644 --- a/docs/documentation/server_development/topics/themes.adoc +++ b/docs/documentation/server_development/topics/themes.adoc @@ -105,7 +105,7 @@ You have now created a theme with support for the login type. . For *Login Theme* select *mytheme* and click *Save*. . Open the login page for the realm. + -You can do this either by logging in through your application or by opening the Account Console (`/realms/{realm name}/account`). +You can do this either by logging in through your application or by opening the Account Console (`/realms/{realm-name}/account`). . To see the effect of changing the parent theme, set `parent=keycloak` in `theme.properties` and refresh the login page. diff --git a/docs/documentation/upgrading/topics/changes/changes-23_0_0.adoc b/docs/documentation/upgrading/topics/changes/changes-23_0_0.adoc index 8868d84f7d5..19e39ae86e7 100644 --- a/docs/documentation/upgrading/topics/changes/changes-23_0_0.adoc +++ b/docs/documentation/upgrading/topics/changes/changes-23_0_0.adoc @@ -154,18 +154,18 @@ Stream getTopLevelGroupsStream(RealmModel realm, * new field `subGroupCount` added to inform client how many subgroups are on any given group * `subGroups` list is now only populated on queries that request hierarchy data - * This field is populated from the "bottom up" so cannot be relied on for getting all subgroups for a group. Use a `GroupProvider` or request the subgroups from `GET {keycloak server}/realms/{realm}/groups/{group_id}/children` + * This field is populated from the "bottom up" so cannot be relied on for getting all subgroups for a group. Use a `GroupProvider` or request the subgroups from `GET {keycloak server}/realms/{realm-name}/groups/{group_id}/children` = New endpoint for Group Admin API -Endpoint `GET {keycloak server}/realms/{realm}/groups/{group_id}/children` added as a way to get subgroups of specific groups that support pagination +Endpoint `GET {keycloak server}/realms/{realm-name}/groups/{group_id}/children` added as a way to get subgroups of specific groups that support pagination = RESTEeasy Reactive Relying on RESTEasy Classic is not longer an option because it is not available anymore. Migration will be needed for SPI's and code that is relying on RESTEasy Classic and related packages part of `org.jboss.resteasy.spi.*`. = Partial export requires manage-realm permission -The endpoint `POST {keycloak server}/realms/{realm}/partial-export` and the corresponding action in the admin console now require `manage-realm` permission for execution instead of `view-realm`. This endpoint exports the realm configuration into a JSON file and the new permission is more appropriate. The parameters `exportGroupsAndRoles` and `exportClients`, which include the realm groups/roles and clients in the export respectively, continue managing the same permissions (`query-groups` and `view-clients`). +The endpoint `POST {keycloak server}/realms/{realm-name}/partial-export` and the corresponding action in the admin console now require `manage-realm` permission for execution instead of `view-realm`. This endpoint exports the realm configuration into a JSON file and the new permission is more appropriate. The parameters `exportGroupsAndRoles` and `exportClients`, which include the realm groups/roles and clients in the export respectively, continue managing the same permissions (`query-groups` and `view-clients`). = Removal of the options to trim the event's details length diff --git a/docs/documentation/upgrading/topics/changes/changes-24_0_0.adoc b/docs/documentation/upgrading/topics/changes/changes-24_0_0.adoc index 27c028f4db0..b1f38ee8319 100644 --- a/docs/documentation/upgrading/topics/changes/changes-24_0_0.adoc +++ b/docs/documentation/upgrading/topics/changes/changes-24_0_0.adoc @@ -346,7 +346,7 @@ To be able to enable changing those attributes via UI and REST APIs, perform th = The Admin send-verify-email API now uses the same email verification template ---- -PUT /admin/realms/{realm}/users/{id}/send-verify-email +PUT /admin/realms/{realm-name}/users/{id}/send-verify-email ---- In this release, the API will use the `email-verification.ftl` template instead of `executeActions.ftl`. @@ -368,7 +368,7 @@ A new parameter called `lifespan` will be introduced to allow overriding of the If you prefer the previous behavior, use the `execute-actions-email` API as follows. ---- -PUT /admin/realms/{realm}/users/{id}/execute-actions-email +PUT /admin/realms/{realm-name}/users/{id}/execute-actions-email ["VERIFY_EMAIL"] ---- diff --git a/docs/documentation/upgrading/topics/changes/changes-26_0_0.adoc b/docs/documentation/upgrading/topics/changes/changes-26_0_0.adoc index 81d44b6ecfb..120f91fba71 100644 --- a/docs/documentation/upgrading/topics/changes/changes-26_0_0.adoc +++ b/docs/documentation/upgrading/topics/changes/changes-26_0_0.adoc @@ -167,7 +167,7 @@ As part of the improvements around the scalability of realms and organizations w no longer holds the list of identity providers. However, they are still available from the realm representation when exporting a realm. -To obtain the query the identity providers in a realm, prefer using the `/realms/{realm}/identity-provider/instances` endpoint. +To obtain the query the identity providers in a realm, prefer using the `/realms/{realm-name}/identity-provider/instances` endpoint. This endpoint supports filters and pagination. = CLI import placeholder replacement diff --git a/docs/guides/securing-apps/token-exchange.adoc b/docs/guides/securing-apps/token-exchange.adoc index 1afe142a53e..a49dfe81caa 100644 --- a/docs/guides/securing-apps/token-exchange.adoc +++ b/docs/guides/securing-apps/token-exchange.adoc @@ -48,7 +48,7 @@ a simple grant type invocation on a realm's OpenID Connect token endpoint. [source,subs="attributes+"] ---- -{kc_realms_path}/{realm}/protocol/openid-connect/token +{kc_realms_path}/{realm-name}/protocol/openid-connect/token ---- It accepts form parameters (`application/x-www-form-urlencoded`) as input and the output depends on the type of token you requested an exchange for. diff --git a/docs/guides/server/bootstrap-admin-recovery.adoc b/docs/guides/server/bootstrap-admin-recovery.adoc index 457bcc4401f..ddb9f354b2b 100644 --- a/docs/guides/server/bootstrap-admin-recovery.adoc +++ b/docs/guides/server/bootstrap-admin-recovery.adoc @@ -71,11 +71,11 @@ Passwordless, OTP, or other advanced authentication methods can be enforced for Next, retrieve the `credentialId`. For this example, the OTP credential is the relevant one. Use the following command to get an array of `CredentialRepresentation` objects and find the one with `type` set to `otp`: -<@kc.admin parameters="get users/{userId}/credentials -r {realm}"/> +<@kc.admin parameters="get users/{userId}/credentials -r {realm-name}"/> Finally, the retrieved ID can be used to remove the advanced authentication method (in our case, OTP): -<@kc.admin parameters="delete users/{userId}/credentials/{credentialId} -r {realm}"/> +<@kc.admin parameters="delete users/{userId}/credentials/{credentialId} -r {realm-name}"/> == Default values diff --git a/docs/transient-users.md b/docs/transient-users.md index 000eee277fb..e1aeb887265 100644 --- a/docs/transient-users.md +++ b/docs/transient-users.md @@ -34,12 +34,12 @@ When using transient users, you should be aware of the following: - Roles and groups can be assigned to the transient users only by identity provider mappers of the respective identity provider. - This is especially important for the `default-roles-{realm}` realm role, + This is especially important for the `default-roles-{realm-name}` realm role, which is added to regular users automatically, but has to be assigned to transient users also through a mapper (e.g. the `Hardcoded Role` mapper type). An alternative to the Hardcoded Role mapper approach is to use groups which allows for more flexible role mappings. - To do so, create a group like `transient-users` and assign the `default-roles-{realm}` realm role to it. + To do so, create a group like `transient-users` and assign the `default-roles-{realm-name}` realm role to it. Then add a Hardcoded Group mapper to the identity-provider and select the `transient-users` group. This will ensure that all roles associated with the `transient-users` group are automatically assigned to the brokered users.