Merge pull request #1 from himeshsiriwardana/pr-5532

added a description for clarity

Author: JeethJJ

en/includes/guides/authentication/oidc/discover-oidc-configs.md

@@ -1,29 +1,41 @@
-# Discover OpenID Connect endpoints of {{ product_name }}
+# Discover OpenID Connect endpoints and configurations
 
-When you build OpenID Connect login in your application using {{ product_name }} as your identity provider, you need to get the OpenID Connect endpoints and configurations from {{ product_name }}.
+When building OpenID Connect (OIDC) login in your application using {{product_name}} as your identity provider, your application needs the relevant OIDC endpoints and configurations. Your application can get these endpoints in **two main steps**:
 
-You can do this by invoking the discovery endpoint API or by using the {{ product_name }} Console as explained below.
+1. **Discover the issuer (Optional)**:
 
-## Prerequisite
+    When the issuer URL of the OpenID Provider is not known in advance, your application can dynamically discover it using the **WebFinger** endpoint.
+
+2. **Retrieve the OpenID Connect metadata from the issuer**:
+
+    Once your application discovers the issuer URL (either via WebFinger or because it’s already configured), your application can fetch the OpenID Connect metadata. This includes all the necessary endpoints (authorization, token, introspection, revocation, logout, etc.), supported scopes, response types, claims, and client authentication methods.
+
+For clients or SDKs that cannot dynamically fetch these endpoints, you can get them manually from the {{product_name}} Console.
+
+This guide explains how to discover the OpenID Connect endpoints of {{ product_name }} using both the API and the Console.
+
+## Prerequisites
 
 To get started, you need to have an application registered in {{ product_name }}:
 
 - Register a [single-page app with OIDC]({{base_path}}/guides/applications/register-single-page-app/).
 - Register a [web app with OIDC]({{base_path}}/guides/applications/register-oidc-web-app/).
 
-## Use the discovery endpoint
+## Use the API
 
-### Discover the issuer
+This section explains how your application can dynamically discover the OpenID Connect endpoints.
 
-OpenID Provider issuer discovery refers to the process of determining the location
-of the OpenID Provider. The following endpoint is responsible for revealing the OpenID Provider's
-issuer after validating the required parameters (Resource, Host and rel).
+### Step 1: Discover the issuer
+
+OpenID Provider issuer discovery, process allows a client application to automatically find the location (issuer URL) of the OpenID Provider.
+
+You can use the following endpoint to retrieve the issuer information.
 
 ```bash
 {{ product_url_format }}/.well-known/webfinger
 ```
 
-Following information is required when making a request to discover the issuer's location.
+The endpoint accepts the following required parameters.
 
  <table>
  <thead>
@@ -35,24 +47,24 @@ Following information is required when making a request to discover the issuer's
  </thead>
  <tbody>
  <tr class="odd">
- <td>Resource</td>
- <td>Identifier for the target end user that is the subject of the discovery request.</td>
+ <td><code>resource</code></td>
+ <td>The identifier of the user whose OpenID Provider (issuer) you want to discover.</td>
  <td>acct:admin@localhost</td>
  </tr>
  <tr class="even">
- <td>HostServer</td>
- <td>Where the WebFinger service is hosted.</td>
- <td>localhost</td>
+ <td><code>host</code></td>
+ <td>Specify the domain or server that hosts the WebFinger service.</td>
+ <td>localhost:9443</td>
  </tr>
  <tr class="odd">
- <td>rel</td>
- <td>URI identifying the type of service whose location is being requested.</td>
+ <td><code>rel</code></td>
+ <td>Specify the URI that identifies the type of service you want to locate.</td>
  <td>http://openid.net/specs/connect/1.0/issuer</td>
  </tr>
  </tbody>
  </table>
 
-**Sample request**
+#### Sample request
 
 === "cURL"
 
@@ -104,7 +116,8 @@ Following information is required when making a request to discover the issuer's
     ```
 
 
-**Sample response**
+#### Sample response
+
 ```json
 {
    "subject": "acct:admin@localhost",
@@ -117,23 +130,25 @@ Following information is required when making a request to discover the issuer's
 }
 ```
 
-### Discover the issuer metadata
+### Step 2: Discover the issuer metadata
 
-OpenID Connect Discovery <!-- [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)--> allows you to discover the metadata such as endpoints, scopes, response types, claims, and supported client authentication methods of identity providers such as {{ product_name }}.
+[OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) allows you to discover the metadata such as endpoints, scopes, response types, claims, and supported client authentication methods of identity providers such as {{ product_name }}.
 
 Applications can dynamically discover the OpenID Connect identity provider metadata by calling the OpenID Connect discovery <!-- [OpenID Connect discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest)--> endpoint. The structure of the request URL is as follows: `<issuer>/.well-known/openid-configuration`.  
 
-**Issuer of {{ product_name }}**
-```bash
-{{ product_url_format }}/oauth2/token
-```
+- Issuer of {{ product_name }}
 
-**Discovery endpoint of {{ product_name }}**
-```bash
-{{ product_url_format }}/oauth2/token/.well-known/openid-configuration
-```
+    ```bash
+    {{ product_url_format }}/oauth2/token
+    ```
 
-**Sample request**
+- Discovery endpoint of {{ product_name }}
+
+    ```bash
+    {{ product_url_format }}/oauth2/token/.well-known/openid-configuration
+    ```
+
+#### Sample request
 
 === "cURL"
 
@@ -175,8 +190,9 @@ Applications can dynamically discover the OpenID Connect identity provider metad
         });
     ```
 
-**Sample response**
-```json 
+#### Sample response
+
+```json
 {
    "introspection_endpoint" : "{{ product_url_sample }}/oauth2/introspect",
    "end_session_endpoint" : "{{ product_url_sample }}/oidc/logout",
@@ -189,15 +205,13 @@ Applications can dynamically discover the OpenID Connect identity provider metad
 }
 ```
 
-## Use the console
-
-Some applications and SDKs are not capable of dynamically resolving endpoints from OpenID Connect discovery. For such applications, you need to configure endpoints manually.
+## Use the Console
 
-You can get the endpoints from the console as follows:
+For applications and SDKs that can't dynamically resolve OpenID Connect endpoints, you can manually copy the relevant information from the Console. To do so,
 
 1. On the {{ product_name }}, go to **Applications**.
 
-2. Select an OIDC application from the list.
+2. Select your OIDC application from the list.
 
 3. Go to the **Info** tab of the application and find the server endpoints to your organization.