fix(docs): Update Janssen documentation to align with OAuth 2.1

docs/janssen-server/auth-server/authz-details/README.md

@@ -60,10 +60,17 @@ Sample Authorization Request
 ```
 POST /jans-auth/restv1/authorize HTTP/1.1
 Host: yuriyz-fond-skink.gluu.info
+Content-Type: application/x-www-form-urlencoded
 
-response_type=code&client_id=7a29bf35-96ec-4bbd-a05c-15e1ff9f07cc&scope=openid+profile+address+email+phone+user_name&redirect_uri=https%3A%2F%2Fyuriyz-relaxed-jawfish.gluu.info%2Fjans-auth-rp%2Fhome.htm&state=6cdc7701-178c-4653-adac-5c1e9c6c4aba&nonce=b9a1ecc4-548e-475c-8b29-f019417e1aef&prompt=&ui_locales=&claims_locales=&acr_values=&request_session_id=false&authorization_details=%5B%0A++%7B%0A++++%22type%22%3A+%22demo_authz_detail%22%2C%0A++++%22actions%22%3A+%5B%0A++++++%22list_accounts%22%2C%0A++++++%22read_balances%22%0A++++%5D%2C%0A++++%22locations%22%3A+%5B%0A++++++%22https%3A%2F%2Fexample.com%2Faccounts%22%0A++++%5D%2C%0A++++%22ui_representation%22%3A+%22Read+balances+and+list+accounts+at+https%3A%2F%2Fexample.com%2Faccounts%22%0A++%7D%0A%5D
+response_type=code&client_id=7a29bf35-96ec-4bbd-a05c-15e1ff9f07cc&scope=openid+profile+address+email+phone+user_name&redirect_uri=https%3A%2F%2Fyuriyz-relaxed-jawfish.gluu.info%2Fjans-auth-rp%2Fhome.htm&state=6cdc7701-178c-4653-adac-5c1e9c6c4aba&nonce=b9a1ecc4-548e-475c-8b29-f019417e1aef&prompt=&ui_locales=&claims_locales=&acr_values=&request_session_id=false&authorization_details=%5B%0A++%7B%0A++++%22type%22%3A+%22demo_authz_detail%22%2C%0A++++%22actions%22%3A+%5B%0A++++++%22list_accounts%22%2C%0A++++++%22read_balances%22%0A++++%5D%2C%0A++++%22locations%22%3A+%5B%0A++++++%22https%3A%2F%2Fexample.com%2Faccounts%22%0A++++%5D%2C%0A++++%22ui_representation%22%3A+%22Read+balances+and+list+accounts+at+https%3A%2F%2Fexample.com%2Faccounts%22%0A++%7D%0A%5D&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256
 ```
 
+For the Authorization Code flow, clients should use PKCE with the `S256`
+code challenge method. The client generates a `code_verifier`, derives
+the `code_challenge` using SHA-256 and Base64URL encoding, and includes
+the challenge in the authorization request. The original `code_verifier`
+is sent during the subsequent token request.
+
 Request is rejected if request's `authorization_details` has types which does not have corresponding `AuthzDetailType` custom script.
 
 Check more details about [`AuthzDetailType` custom scripts](../../../script-catalog/authz_detail/AuthzDetail.java)
@@ -98,7 +105,7 @@ Content-Type: application/json
 Accept: application/json
 
 {
-  "grant_types" : [ "authorization_code", "implicit" ],
+  "grant_types" : [ "authorization_code" ],
   "subject_type" : "public",
   "application_type" : "web",
   "authorization_details_types" : [ "demo_authz_detail" ],
@@ -148,8 +155,7 @@ X-Xss-Protection: 1; mode=block
     "id_token_signed_response_alg": "RS256",
     "access_token_as_jwt": false,
     "grant_types": [
-        "authorization_code",
-        "implicit"
+        "authorization_code"
     ],
     "subject_type": "public",
     "authorization_details_types": ["demo_authz_detail"],

docs/janssen-server/auth-server/client-management/client-configuration.md

@@ -27,6 +27,13 @@ The client can register a list of URIs as a value for redirect URI parameter. Re
   matches with the regex provided by the client. Great care should be exercised when using regex to ensure that it
   accurately matches with the intended patterns only. This feature can be turned on or off via
   [feature flag](../../reference/json/feature-flags/janssenauthserver-feature-flags.md)
+
+    For new integrations, register exact redirect URIs whenever possible.
+    Avoid broad regular expressions or wildcard-style matching because
+    they can allow authorization responses to be redirected to unintended
+    destinations. Use redirect URI regular expressions only when required
+    for compatibility, and restrict them to explicitly trusted destinations.
+
 - When using client type as `web`, the redirect URI generally takes the form of `<schema>://<host-name>:<port>/<path>`.
   It must use `https` schema. The exception to **schema rule** is made when  
   `localhost` or loopback ip `127.0.0.1` is used as the hostname. 
@@ -114,17 +121,30 @@ tokens. The table below shows grant types and flows that should be used for vari
 | Client Type                                                                                     | Recommended Grant Type                         | Flow                         |
 |-------------------------------------------------------------------------------------------------|------------------------------------------------|------------------------------|
 | Backend App (Example: batch processes) that need to access its own resources                    | `client_credentials`                           | Client Credentials           |
-| Server backend of a web-application needs access token                                          | `authorization_code`                           | Authorization Code           |
-| Web-application that needs user information via id_token on browser and access token on backend | `authorization_code`                           | Hybrid Flow                  |
+| Server backend of a web-application needs access token                                          | `authorization_code`                           | Authorization Code with PKCE |
+| Web application requiring an ID token and an access token                                       | `authorization_code`                           | OpenID Connect Authorization Code with PKCE |
 | Browser based single page applications or Mobile applications                                   | `authorization_code`                           | Authorization Code with PKCE |
-| Browser based single page applications or Mobile applications that only intend to get id_token  | -                                              | Implicit Flow with Form Post |
+| Browser-based or mobile application requiring only an ID token                                  | `authorization_code`                           | OpenID Connect Authorization Code with PKCE |
 | Input constrained devices (Example: TV)                                                         | `urn:ietf:params:oauth:grant-type:device_code` | Device Flow                  |
-| Highly trusted applications where redirect based flows are not feasible to implement            | `password`                                     | Resource Owner Password Flow |
+| Existing legacy integrations only                                                               | `password` (legacy; not recommended)            | Resource Owner Password Flow |
+
+For new applications, use the Authorization Code Flow with PKCE
+(`code_challenge_method=S256`) when user authorization is required.
+This recommendation applies to both public and confidential clients.
+
+Janssen Server may continue to support the Implicit Flow, Hybrid Flow,
+and Resource Owner Password Credentials Grant for compatibility with
+existing applications. However, these flows are not recommended for
+new integrations. Existing clients should migrate to the Authorization
+Code Flow with PKCE where applicable.
 
 !!! Note
 
-    Certain grant types should not be used together. For example, implicit flow with hybrid flow. Or using authorization
-    code flow with hybrid flow. This allows a downgrade attack from more secure flow to less secure flow.
+    Configure only the grant types and response types required by the
+    client. Avoid enabling legacy implicit or hybrid response types
+    alongside Authorization Code Flow unless needed for an existing
+    integration. Restricting unnecessary response types reduces the
+    risk of authorization flow downgrade attacks.
 
 
 ## Pre-authorization
@@ -146,15 +166,28 @@ Janssen Server's well-known [configuration endpoint](../endpoints/configuration.
 https://janssen.server.host/jans-auth/.well-known/openid-configuration
 ```
 
-Claim `response_types_supported` lists all the supported grant types in the response.
+Claim `response_types_supported` lists all the supported response types in the response.
 
 When registering client using dynamic client registration, if the `response_type` parameter is not specified, it'll
 default to `code`.
 
 ### Response Type Recommendations
 
-- Avoid using response type `token`. This response type is 
-[deprecated](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07#section-10.1) by OAuth 2.1. 
+- For new integrations, use `response_type=code` with PKCE
+  (`code_challenge_method=S256`).
+- Avoid `response_type=token` and any combination containing it, such as
+  `id_token token` or `code token`. OAuth 2.1 removes the Implicit Grant.
+- Avoid `response_type=id_token` and hybrid types such as `code id_token`
+  for new integrations. These are OpenID Connect response types and are not
+  removed by OAuth 2.1, but they return tokens through the browser. Use
+  `response_type=code` with PKCE to get the ID Token from the token endpoint.
+- By default, Janssen Server rejects authorization requests whose
+  `response_type` contains `token` or `id_token`, because they require the
+  `implicit` grant type, which is not in the default `grantTypesSupported`.
+  To support existing applications, add `implicit` to `grantTypesSupported`
+  and to the client's grant types. Alternatively, set
+  `allowIdTokenWithoutImplicitGrantType` to `true` to allow `id_token`
+  without the `implicit` grant.
 - Grant types allowed for a client determines which response types are permitted in authorization requests. 
 Make sure appropriate grant types are configured in Janssen Server client configuration. Janssen Server will reject 
 authorization requests containing response types not permitted for respective client.

docs/janssen-server/auth-server/endpoints/authorization.md

@@ -7,11 +7,22 @@ tags:
 ---
 # Authorization Endpoint
 
+Janssen Server exposes an authorization endpoint defined in
+[OAuth 2.0 (RFC 6749)](https://www.rfc-editor.org/rfc/rfc6749#section-3.1),
+with security behavior aligned with the
+[OAuth 2.1 draft](https://datatracker.ietf.org/doc/draft-ietf-oauth-v2-1/).
 
-Janssen Server exposes authorization endpoint compliant with [OAuth2 framework](https://www.rfc-editor.org/rfc/rfc6749#section-3.1).
-A client uses authorization endpoint to obtain an authorization grant. Based on response type requested by the client,
-the authorization endpoint issues an authorization code or an access token. Authorization endpoint is a protected endpoint
-which will require end-user authentication before issuing authorization code or access token.
+A client uses this endpoint to initiate an authorization request and
+obtain an authorization grant.
+
+For new integrations, use the Authorization Code Flow with PKCE
+(`code_challenge_method=S256`). The authorization endpoint returns an
+authorization code, which the client exchanges for tokens at the token
+endpoint after successful end-user authentication and authorization.
+
+Janssen Server may also support legacy implicit and hybrid response
+types, depending on server and client configuration. These response
+types are not recommended for new integrations.
 
 URL to access authorization endpoint on Janssen Server is listed in the response of Janssen Server's well-known
 [configuration endpoint](./configuration.md) given below.
@@ -57,19 +68,28 @@ navigate via `Auth Server`->`Properties`.
 
 ## Required Client Configuration
 
-Clients must be registered with Janssen Server as using [code](https://www.rfc-editor.org/rfc/rfc6749#section-4.1)
-and/or [implicit](https://www.rfc-editor.org/rfc/rfc6749#section-4.2) grant types in order to use authorization endpoint.
+Clients must be registered for an authorization flow supported by the running server.
+Authorization Code is the recommended flow. The Implicit Grant is a legacy option and is
+not included in the default supported grant types.
 
 Using [Janssen Text-based UI(TUI)](../../config-guide/config-tools/jans-tui/README.md), client can be registered for appropriate grant type by
 navigating to `Auth-Server`->`Clients`->`Add Client`
 
 ## Using PKCE
 
-Janssen Server [supports PKCE](../oauth-features/pkce.md), which recommended and more secure method for using `code`
-grant.
+Janssen Server [supports PKCE](../oauth-features/pkce.md) for the
+Authorization Code Flow. PKCE is required by default, and new integrations
+should use the `S256` code challenge method.
+
+PKCE enforcement is controlled by the
+[requirePkce](../../reference/json/properties/janssenauthserver-properties.md#requirepkce)
+property, which defaults to `true`. If the global property is set to
+`false`, PKCE is still required for clients that have `requirePkce`
+enabled individually.
 
-PKCE can be enabled/disable by setting [requirePkce](../../reference/json/properties/janssenauthserver-properties.md#requirepkce)
-property. Janssen server supports `plain` as well as `s256` code challenge methods.
+When PKCE is required, the client must send a `code_challenge` with
+`code_challenge_method=S256` in the authorization request and provide
+the corresponding `code_verifier` at the token endpoint.
 
 ## Using Request Objects
 

docs/janssen-server/auth-server/endpoints/clientinfo.md

@@ -30,6 +30,9 @@ Since clientinfo endpoint is an OAuth2 protected resource, a valid access token
 access the endpoint. More information about request and response of the clientinfo endpoint can be found in
 the OpenAPI specification of [jans-auth-server module](https://gluu.org/swagger-ui/?url=https://raw.githubusercontent.com/JanssenProject/jans/vreplace-janssen-version/jans-auth-server/docs/swagger.yaml#/Client_Info).
 
+Send this access token in the HTTP `Authorization: Bearer` header and do not send as a URL query
+parameter.
+
 ## Disabling The Endpoint Using Feature Flag
 
 `/clientinfo` endpoint can be enabled or disable using [clientinfo feature flag](../../reference/json/feature-flags/janssenauthserver-feature-flags.md#clientinfo).

docs/janssen-server/auth-server/endpoints/introspection.md

@@ -29,12 +29,25 @@ the OpenAPI specification of [jans-auth-server module](https://gluu.org/swagger-
 - `token_type_hint` - OPTIONAL.  A hint about the type of the token submitted for introspection. Not used in current implementation of the AS. 
 - `response_as_jwt` - OPTIONAL. Boolean value with default value false. If true, returns introspection response as JWT (signed based on client configuration used for authentication to Introspection Endpoint).
 
-## Sample GET Request
+The `token` parameter is the token being inspected, and it is distinct from the credential
+used to authenticate the caller to the introspection endpoint. Authenticate the request
+using the configured client authentication method or an `Authorization: Bearer` header
+where supported.
+
+## Sample POST Request (recommended)
+
+Send the token being inspected in the form-encoded request body. This keeps
+it out of URLs, which servers, proxies and browsers can log.
 
 ### Request
 
 ```shell
-curl -X 'GET'   'https://janssen.server.host/jans-auth/restv1/introspection?token=368fea2b-be14-4d30-bd57-bcc4cde2033c&response_as_jwt=false'   -H 'accept: application/json' -H   "Authorization: Bearer 111d51a4-2828-4b47-abce-77034cddcfb5"
+curl -X POST 'https://janssen.server.host/jans-auth/restv1/introspection' \
+  -H 'Accept: application/json' \
+  -H 'Content-Type: application/x-www-form-urlencoded' \
+  -H 'Authorization: Bearer <CALLER_ACCESS_TOKEN>' \
+  --data-urlencode 'token=<TOKEN_TO_INSPECT>' \
+  --data-urlencode 'response_as_jwt=false'
 ```
 
 ### Response
@@ -45,29 +58,28 @@ curl -X 'GET'   'https://janssen.server.host/jans-auth/restv1/introspection?toke
     "iss": "https://janssen.server.host",
     "active": true,
     "token_type": "Bearer",
-    "client_id": "1800.df1bb233-10b8-40ed-bbb9-07da50892a35",
-    "aud": "1800.df1bb233-10b8-40ed-bbb9-07da50892a35",
+    "client_id": "3000.5829c1f8-7554-41ab-a7d6-3513a5e9c4ad",
+    "aud": "3000.5829c1f8-7554-41ab-a7d6-3513a5e9c4ad",
     "nbf": null,
-    "scope": "https://jans.io/oauth/config/scripts.write",
+    "scope": "",
     "acr_values": null,
     "cnf": null,
-    "exp": 1668705523,
-    "iat": 1668705223,
+    "exp": 1668941216,
+    "iat": 1668781885,
     "jti": null,
     "username": null
 }
 ```
-## Sample POST Request
+
+## Sample GET Request
+
+GET is supported for compatibility. It places the inspected token in the URL
+query, where it can appear in server, proxy and browser logs. Prefer POST.
 
 ### Request
 
 ```shell
-curl -X 'POST' \
-  'https://janssen.server.host/jans-auth/restv1/introspection' \
-  -H 'accept: application/json' \
-  -H 'Content-Type: application/x-www-form-urlencoded' \
-  -d 'token=eyJra....3ZkB-Ajwg'  
-  -H "Authorization: Bearer eyJra...BpKo7g"
+curl -X 'GET'   'https://janssen.server.host/jans-auth/restv1/introspection?token=368fea2b-be14-4d30-bd57-bcc4cde2033c&response_as_jwt=false'   -H 'accept: application/json' -H   "Authorization: Bearer 111d51a4-2828-4b47-abce-77034cddcfb5"
 ```
 
 ### Response
@@ -78,14 +90,14 @@ curl -X 'POST' \
     "iss": "https://janssen.server.host",
     "active": true,
     "token_type": "Bearer",
-    "client_id": "3000.5829c1f8-7554-41ab-a7d6-3513a5e9c4ad",
-    "aud": "3000.5829c1f8-7554-41ab-a7d6-3513a5e9c4ad",
+    "client_id": "1800.df1bb233-10b8-40ed-bbb9-07da50892a35",
+    "aud": "1800.df1bb233-10b8-40ed-bbb9-07da50892a35",
     "nbf": null,
-    "scope": "",
+    "scope": "https://jans.io/oauth/config/scripts.write",
     "acr_values": null,
     "cnf": null,
-    "exp": 1668941216,
-    "iat": 1668781885,
+    "exp": 1668705523,
+    "iat": 1668705223,
     "jti": null,
     "username": null
 }

docs/janssen-server/auth-server/endpoints/token.md

@@ -13,9 +13,14 @@ Token endpoint is defined in the [OAuth 2.0 framework](https://datatracker.ietf.
 [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) specification and other specifications relevant
 to them.
 
-Tokens granted by this endpoint depends on grant type and scopes that are specified in the token request. The token
-endpoint is used with every authorization grant type except for the implicit grant type (since an access token is issued
-directly).
+Tokens issued by this endpoint depend on the grant type, requested scopes,
+and applicable client and server configuration. The endpoint processes
+grant types supported and enabled by the running server.
+
+The Implicit Grant is a legacy flow in which access tokens are issued
+directly from the authorization endpoint rather than the token endpoint.
+It is not recommended for new integrations and is not included in the
+default supported grant types.
 
 Based on request, this endpoint can grant following types of tokens:
 
@@ -129,15 +134,20 @@ navigate via `Auth Server`->`Clients`->`Add Client`->`Basic`-> `Authn Method Tok
 Token endpoint supports below mentioned grant types.
 
 - [Authorization Code](../oauth-features/auth-code-grant.md)
-- [Implicit](../oauth-features/implicit-grant.md)
 - [Refresh Token](../oauth-features/README.md)
 - [Client Credentials](../oauth-features/client-credential-grant.md)
-- [Password](../oauth-features/password-grant.md)
 - [Token Exchange](../oauth-features/token-exchange.md)
 - [Transaction Tokens](../tokens/oauth-tx-tokens.md)
 - [Device Grant](../oauth-features/device-grant.md)
 - [JWT Grant](../oauth-features/jwt-grant.md)
+- [UMA](../uma-features/rpt-endpoint.md)
 - [CIBA](./backchannel-authentication.md)
+- [Password](../oauth-features/password-grant.md) (legacy; not recommended).
+  Not in the default `grantTypesSupported`. Add `password` to
+  `grantTypesSupported` and to the client's grant types to use it.
+
+The [Implicit](../oauth-features/implicit-grant.md) grant (legacy) does not
+use the token endpoint. Its tokens come from the authorization endpoint.
 
 Client can configure all the possible grant types it can request from token endpoint during client configuration.
 To select the available grant types using

docs/janssen-server/auth-server/endpoints/userinfo.md

@@ -11,6 +11,9 @@ tags:
 Userinfo endpoint is an OAuth2 protected endpoint that is used to retrieve claims about an authenticated end-user.
 Userinfo endpoint is defined in the [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo).
 
+Send the access token that authorizes the UserInfo request in the HTTP
+`Authorization: Bearer` header. Do not send this access token in the URL query string.
+
 URL to access userinfo endpoint on Janssen Server is listed in the response of Janssen Server's well-known
 [configuration endpoint](./configuration.md) given below.