Merge pull request #386 from chashikajw/idp-docs

Revamp idp docs
wso2 · Oct 6, 2023 · 17d5c8f · 17d5c8f
2 parents 08ada76 + fdc162d
commit 17d5c8f
Show file tree

Hide file tree

Showing 4 changed files with 376 additions and 95 deletions.
diff --git a/en/docs/develop-and-deploy-api/token-issuers/token-issuers.md b/en/docs/develop-and-deploy-api/token-issuers/token-issuers.md
@@ -6,27 +6,39 @@ Follow the steps below to add token issuers to APK.
 
 1. Create a file named `new-token-issuer.yaml` and add the following content to it.
 
-```
-apiVersion: dp.wso2.com/v1alpha1
-kind: TokenIssuer
-metadata:
-  name: new-jwt-issuer
-spec:
-  consumerKeyClaim: azp
-  issuer: https://idp.am.wso2.com/token
-  name: new-service-provider
-  organization: new-org
-  scopesClaim: scope
-  signatureValidation:
-    certificate:
-      secretRef:
-        key: wso2carbon.pem
-        name: apk-test-wso2-apk-enforcer-truststore-secret
-  targetRef:
-    group: gateway.networking.k8s.io
-    kind: Gateway
-    name: default
-```
+    ```
+    apiVersion: dp.wso2.com/v1alpha1
+    kind: TokenIssuer
+    metadata:
+      name: new-jwt-issuer
+    spec:
+      consumerKeyClaim: azp
+      issuer: https://idp.am.wso2.com/token
+      name: new-service-provider
+      organization: new-org
+      scopesClaim: scope
+      signatureValidation:
+        certificate:
+          secretRef:
+            key: wso2carbon.pem
+            name: apk-test-wso2-apk-enforcer-truststore-secret
+      targetRef:
+        group: gateway.networking.k8s.io
+        kind: Gateway
+        name: default
+    ```
+
+    If you need to perform signature validation using the JWKS endpoint, you can add the `signatureValidation:` section as below instead of adding the certificate.
+
+    ```
+
+    signatureValidation:
+      jwks:
+        url: https://idp.am.wso2.com/jwks
+          
+    ```
+
+
 
 2. Run the following command to add the token Issuer to APK.
 

diff --git a/en/docs/setup/identity-platform/idp/asgardeo-idp.md b/en/docs/setup/identity-platform/idp/asgardeo-idp.md
@@ -24,35 +24,116 @@ Follow the instructions below to use Asgardeo as the Identity Provider (IdP) to
 
 4. [Share application with sub-organizations](https://wso2.com/asgardeo/docs/guides/organization-management/manage-b2b-organizations/share-applications/).
 
-## Step 5 - Update the Helm Chart
+## Step 5 - Add a new token issuer for the IDP
 
-1. Follow the instructions outlined in [Customize Configurations](../../Customize-Configurations.md). These instructions will guide you through the process of acquiring the `values.yaml` file. Open the `values.yaml` file.
-2. Update the IDP related configurations in the `idp` section.
-3. Create a K8s Secret with retrieved `clientId` and `clientSecret` from Step 4 with name `apk-idp-secret`.
+1. Access the endpoints that correspond to the application, which is available in the asgradeo portal.
+
+
+2. Create two file named `idp-system-token-issuer.yaml` and `idp-org-token-issuer.yaml` add the following content to it.
+
+    | **Parameter** | **Description** |
+    |---------------|-----------------|
+    | `issuer:` | The IdP's issuer URL. |
+    | `jwksEndpoint:` |  The URL of the IdP's JSON Web Key Set (JWKS) endpoint.  |
+    | `usernameClaim:` |  The claim in the IdP's token that represents the user's username.  |
+    | `organizationClaim:` |  The claim in the IdP's token that represents the user's organization, This should always be `orgId`.   |
+    | `organization:` |  The organization of IDP. To invoke system APIs, this should be `apk-system`. To invoke particular organizaiton's APIs, this should be organization claim value.  |
+
+
+    === "For System APIs"
       ```
-        idp:
-          issuer: ""
-          jwksEndpoint: ""      
-          usernameClaim: ""
-          organizationClaim: ""
+        apiVersion: dp.wso2.com/v1alpha1
+        kind: TokenIssuer
+        metadata:
+          name: auth0-idp-issuer
+        spec:
+          claimMappings:
+          - localClaim: x-wso2-organization
+            remoteClaim: org_id
+          consumerKeyClaim: azp
+          issuer: https://<asgardeo.domain>/
+          name: new-service-provider
+          organization: apk-system
+          scopesClaim: scope
+          signatureValidation:
+            jwks:
+              url: "https://<asgardeo.domain>/.well-known/jwks"
+          targetRef:
+            group: gateway.networking.k8s.io
+            kind: Gateway
+            name: default
       ```
-      
-       - `organizationClaim` - This should always be `user_organization`.
-       - Update all other values based on the Service Endpoint details that you came across in Step 4.
 
-## Step 6 - Install WSO2 APK
+    === "For Organization APIs"
+      ```
+        apiVersion: dp.wso2.com/v1alpha1
+        kind: TokenIssuer
+        metadata:
+          name: auth0-idp-issuer
+        spec:
+          claimMappings:
+          - localClaim: x-wso2-organization
+            remoteClaim: org_id
+          consumerKeyClaim: azp
+          issuer: https://<asgardeo.domain>/
+          name: new-service-provider
+          organization: default
+          scopesClaim: scope
+          signatureValidation:
+            jwks:
+              url: "https://<asgardeo.domain>/.well-known/jwks"
+          targetRef:
+            group: gateway.networking.k8s.io
+            kind: Gateway
+            name: default
+      ```
+
+
+3. Run the following commands to add the token Issuers to APK.
+
+
+    ```
+    kubectl apply -f idp-system-token-issuer.yaml
+    ```
+
+    ```
+    kubectl apply -f idp-org-token-issuer.yaml
+    ```
+
+
+!!!Optional
+    
+        If you need to configure the IdP as the primary IdP instead of adding multiple IdPs, execute the following steps as the 5th step.
+
+        ## Step 5 - Update the Helm Chart
+
+        1. Follow the instructions outlined in [Customize Configurations](../../Customize-Configurations.md). These instructions will guide you through the process of acquiring the `values.yaml` file. Open the `values.yaml` file.
+        2. Update the IDP related configurations in the `idp` section.
+        3. Create a K8s Secret with retrieved `clientId` and `clientSecret` from Step 4 with name `apk-idp-secret`.
+              ```
+                idp:
+                  issuer: ""
+                  jwksEndpoint: ""      
+                  usernameClaim: ""
+                  organizationClaim: ""
+              ```
+              
+              - `organizationClaim` - This should always be `org_id`.
+              - Update all other values based on the Service Endpoint details that you came across in Step 4.3.
+
+        ## Step 5.1 - Install WSO2 APK
 
-=== "Format"
-	```console
-	helm install <helm-chart-name> .
-	```
+        === "Format"
+          ```console
+          helm install <helm-chart-name> .
+          ```
 
-=== "Example"
-	```console
-	helm install apk-test .
-	```
+        === "Example"
+          ```console
+          helm install apk-test .
+          ```
 
-## Step 7 - Generate an Access Token
+## Step 6 - Generate an Access Token
 
 1. Open Postman and create a new request to generate the auth code token.
 2. Navigate to the Authorization tab of the request.
@@ -76,6 +157,6 @@ Follow the instructions below to use Asgardeo as the Identity Provider (IdP) to
 
      You will receive an access token when the token call is successful.
 
-## Step 8 - Invoke the System API
+## Step 7 - Invoke the APIs
 
- Use the JWT token that you received in the previous step to invoke the System APIs.
+ Use the JWT token that you received in the previous step to invoke the System APIs and other APIs.
diff --git a/en/docs/setup/identity-platform/idp/auth0-idp.md b/en/docs/setup/identity-platform/idp/auth0-idp.md
@@ -32,38 +32,145 @@ If you have not created the user already, [create a user](https://auth0.com/docs
 
        - Define the type of users that will log in to this application - `Individuals`
 
-## Step 6 - Update the Helm Chart
+## Step 5 - Add a custom claim for the organization
+
+You need to add a [custom claim](https://auth0.com/docs/secure/tokens/json-web-tokens/create-custom-claims) to the tokens to identify the organization.
+
+
+1. Create a custom action for the login flow.
+
+    - Go to **Actions > Flows > Login > Custom** and click the + button in the top-right corner, then select **Build custom**.
+    - Create an action named `addOrgclaim`.
+    - Add the follwing code to the editor and Deploy the action. You should add a proper organization identfier as the `orgId` claim value.
+
+        ```
+        exports.onExecutePostLogin = async (event, api) => {
+          api.idToken.setCustomClaim('orgId', 'org1');
+        };
+        ```
+
+        | **Field** | **Description** |
+        |---------------|-----------------|
+        | `orgId (claim name)` | Custom claim name to identify the organization. This should be `orgId` |
+        | `org1 (claim value)` |  A value to identify the organization. You can add any identifier for the organization like organization name.  |
+
+
+1. Apply the custom action to the Post Login flow.
+    - Go to **Actions > Flows > Login > Custom** and select the created action `addOrgclaim` and drop that to the flow.
+
+
+
+## Step 6 - Add a new token issuer for the IDP
 
 1. [Access the endpoints that correspond to the application](https://auth0.com/docs/get-started/applications/application-settings#endpoints), which is available in the **Advanced Settings** section.
-2. Follow the instructions outlined in [Customize Configurations](../../Customize-Configurations.md). These instructions will guide you through the process of acquiring the `values.yaml` file. Open the `values.yaml` file.
-3. Update the IDP related configurations in the `idp` section.
-4. Create a K8s Secret with retrieved `clientId` and `clientSecret` from Step 4 with name `apk-idp-secret`.
 
+
+2. Create two file named `idp-system-token-issuer.yaml` and `idp-org-token-issuer.yaml` add the following content to it.
+
+    | **Parameter** | **Description** |
+    |---------------|-----------------|
+    | `issuer:` | The IdP's issuer URL. |
+    | `jwksEndpoint:` |  The URL of the IdP's JSON Web Key Set (JWKS) endpoint.  |
+    | `usernameClaim:` |  The claim in the IdP's token that represents the user's username.  |
+    | `organizationClaim:` |  The claim in the IdP's token that represents the user's organization, This should always be `orgId`.   |
+    | `organization:` |  The organization of IDP. To invoke system APIs, this should be `apk-system`. To invoke particular organizaiton's APIs, this should be organization claim value.  |
+
+
+    === "For System APIs"
+      ```
+        apiVersion: dp.wso2.com/v1alpha1
+        kind: TokenIssuer
+        metadata:
+          name: auth0-idp-issuer
+        spec:
+          claimMappings:
+          - localClaim: x-wso2-organization
+            remoteClaim: orgId
+          consumerKeyClaim: azp
+          issuer: https://<auth0domain>.auth0.com/
+          name: new-service-provider
+          organization: apk-system
+          scopesClaim: scope
+          signatureValidation:
+            jwks:
+              url: "https://<auth0domain>.auth0.com/.well-known/jwks.json"
+          targetRef:
+            group: gateway.networking.k8s.io
+            kind: Gateway
+            name: default
       ```
-       idp:
-         issuer: ""
-         jwksEndpoint: ""      
-         usernameClaim: ""
-         organizationClaim: ""
+
+    === "For Organization APIs"
+      ```
+        apiVersion: dp.wso2.com/v1alpha1
+        kind: TokenIssuer
+        metadata:
+          name: auth0-idp-issuer
+        spec:
+          claimMappings:
+          - localClaim: x-wso2-organization
+            remoteClaim: orgId
+          consumerKeyClaim: azp
+          issuer: https://<auth0domain>.auth0.com/
+          name: new-service-provider
+          organization: default
+          scopesClaim: scope
+          signatureValidation:
+            jwks:
+              url: "https://<auth0domain>.auth0.com/.well-known/jwks.json"
+          targetRef:
+            group: gateway.networking.k8s.io
+            kind: Gateway
+            name: default
       ```
 
-      - `organizationClaim` - This should always be `org_id`.
-      - Update all other values based on the Endpoint details that you came across in Step 6.1.
 
-## Step 7 - Restart WSO2 APK
+3. Run the following commands to add the token Issuers to APK.
+
+
+    ```
+    kubectl apply -f idp-system-token-issuer.yaml
+    ```
+
+    ```
+    kubectl apply -f idp-org-token-issuer.yaml
+    ```
+
+!!!Optional
+    
+        If you need to configure the IdP as the primary IdP instead of adding multiple IdPs, execute the following steps as the 6th step.
+
+        ## Step 6 - Update the Helm Chart
+        
+        1. Follow the instructions outlined in [Customize Configurations](../../Customize-Configurations.md). These instructions will guide you through the process of acquiring the `values.yaml` file. Open the `values.yaml` file.
+        2. Update the IDP related configurations in the `idp` section.
+        3. Create a K8s Secret with retrieved `clientId` and `clientSecret` from Step 4 with name `apk-idp-secret`.
+
+              ```
+              idp:
+                issuer: ""
+                jwksEndpoint: ""      
+                usernameClaim: ""
+                organizationClaim: ""
+              ```
+
+              - `organizationClaim` - This should be the custom organization claim(`orgId`) which configured in Step 5.1.
+              - Update all other values based on the Endpoint details that you came across in Step 6.1.
+        
+        ## Step 6.1 - Install WSO2 APK
 
-=== "Format"
-	```
-	helm install <helm-chart-name> .
-	```
+        === "Format"
+          ```console
+          helm install <helm-chart-name> .
+          ```
 
-=== "Example"
-	```
-	helm install apk-test .
-	```
+        === "Example"
+          ```console
+          helm install apk-test .
+          ```
 
 
-## Step 8 - Generate an Access Token
+## Step 7 - Generate an Access Token
 
 1. Open Postman and create a new request to generate the auth code token.
 2. Navigate to the Authorization tab of the request.
@@ -83,6 +190,6 @@ If you have not created the user already, [create a user](https://auth0.com/docs
 8. Copy the ID token that you see listed as the `id_token`.
 
 
-## Step 9 - Invoke the System API
+## Step 8 - Invoke the APIs
 
- Use the JWT token that you received in the previous step to invoke the system APIs.
+ Use the JWT token that you received in the previous step to invoke the System APIs and other APIs.