Improves the updated guides according to our internal style guides.

docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md

@@ -1,53 +1,63 @@
-# How to set up Apple SSO to be able to let users sign in
-Just as we have other OAuth providers that allow users to sign in using their accounts created on other well known platforms, we also have enabled Apple SSO support for IR Studio. This guide scripts down the blueprints to be able to enable it for any particular application.
+---
+sidebar_label: Set up Apple SSO for users
+---
 
-# Pre Requisites
-- Apple Developer Account
-- An Apple Account added into the developer account with all the right permissions to be able to edit and udpate app details.
-- An app where you want to enable Apple SSO, `IR Engine` in our case. 
+# Set up Apple SSO for users
+
+Just as we have other OAuth providers that allow users to sign in using their accounts created on other well known platforms, we also have enabled Apple SSO support for IR Studio. This guide lays out the blueprints to enable it for any particular application.
 
+## Prerequisites
+
+- Apple Developer Account
+- An Apple Account added into the developer account with all the right permissions to be able to edit and update app details.
+- An app where you want to enable Apple SSO, **IR Engine** in our case.
 
 Go to [Apple Developer Account](https://idmsa.apple.com/IDMSWebAuth/signin?appIdKey=891bd3417a7776362562d2197f89480a8547b108fd934911bcbea0110d07f757&path=%2Faccount%2F&rv=1) and sign in with and apple Developer account which should have been added to the developer account previously and must have the right permissions. There, you will need to create an App ID, a Service ID and later on a Private Key, these will give you the credentials that you can then use in your app to be able to let users log in using their Apple IDs.
 
-# Create an App ID
-In the Apple Developer account, do the following. 
-
-- Go to section named as `Certificates, Ids & Profiles` and click Identifiers.
-- Create a new identifier, which usually can be created by clicking a small '+' icon besides the identifiers headline. If you do not see that, your logged in user might not have the necessary permissions to add the app ID. Please get your users the right permissions before moving ahead. 
-- Click "App IDs" click "Continue".
-- Click "App" in next window and click "Continue".
-- Fill in the form that opens up.
-  - Enter the description.
-  - Enter the Bundle ID which could be a reverse-domain styled string i.e. 'com.domainname.appname'
-  - Scroll down to "Capabilities" section and check `Sign In with Apple` and click continue. 
-  - Verify details and click register.
-
-# Create a Service ID
-In the Apple Developer account, do the following. 
-
-- Go to section named as `Certificates, Ids & Profiles` and click Identifiers.
-- Click the '+' button beside the 'identifiers'.
-- Click "Service IDs" and click "Continue".
-  - Enter the description.
-  - Enter the Bundle ID which could be a reverse-domain styled string i.e. 'com.domainname.appname'
-  - Click "Continue" and "Register".
-- Edit the service ID that you just created. Check `Sign In with Apple` and click on the "Configure" button besides the checked option.
-  - You will see a screen for "Web Auhentication Configuration". Select the App ID we created previously as the "Primary App ID". You can add the domains e.g, `ir-engine-qat-dev-api.theinfinitereality.io` and the Return URLs e.g, `https://ir-engine-qat-dev-api.theinfinitereality.io/oauth/apple/callback` on which the user will be redirected once it is authentication by Apple. 
-- Click "Continue", verify the details and click "Save".
-
- **NOTE**
- The Service ID that you just created will serve as your Client ID while sending authentication requests from your app.
-
-# Create the Secret Key
-We will also need to create a secret key that we can then use to generate the "Client Secret" which again will be used while sending an authentication request to Apple.
-
-- Go to "Certificates, Identifiers & Profiles > Keys".
-- Click the '+' button beside the 'keys'.
-- Give a Key Name and check the "Sign In With Apple" checkbox.
-- Click Configure next to the "Sign In With Apple" checkbox and select the App ID we previously created under the "Choose a Primary App ID" key. 
-- Click save, verify the details and click Register.
-- Download the Key and Keep it in a safe and secure place. `Please note that this can only be downloaded once, so save it to a safe and secure location`.
-- Click Done.
-
-**NOTE**
-You can keep one App ID and a Secret Key and multiple Service IDs for each environment. But a better practice would be to decouple the App IDs, Service ID and Secret Key for each environments.
+## Create an App ID
+
+In the Apple Developer account, do the following:
+
+1. Go to section named as **Certificates, Ids & Profiles** and click **Identifiers**.
+2. Create a new identifier by clicking the small **+** icon icon besides the identifiers headline. If you do not see that, your logged in user might not have the necessary permissions to add the app ID. Ensure your users have the right permissions before moving ahead.
+3. Click **App IDs** and click **Continue**.
+4. Click **App** in next window and click **Continue**.
+5. Fill in the form that opens up.
+   1. Enter the description.
+   2. Enter the Bundle ID which could be a reverse-domain styled string i.e. `com.domainname.appname`
+   3. Scroll down to **Capabilities** section and check **Sign In with Apple**. Click **Continue**.
+   4. Verify details and click **Register**.
+
+## Create a Service ID
+
+In the Apple Developer account, do the following:
+
+1. Go to section named as **Certificates, Ids & Profiles** and click **Identifiers**.
+2. Click the **+** button beside identifiers.
+3. Click **Service IDs** and click **Continue**.
+   - Enter the description.
+   - Enter the **Bundle ID** which are a reverse-domain styled string i.e., `com.domainname.appname`.
+   - Click "**Continue**" and "**Register**".
+4. Edit the service ID that you just created. Check **Sign In with Apple** and click on the **Configure** button besides the checked option.
+   - You will see a screen for **Web Auhentication Configuration**. Select the App ID we created previously as the **Primary App ID**. You can add the domains e.g, `ir-engine-qat-dev-api.theinfinitereality.io` and the **Return URLs** e.g, `https://ir-engine-qat-dev-api.theinfinitereality.io/oauth/apple/callback` on which the user will be redirected once it is authentication by Apple.
+5. Click **Continue**, verify the details and click **Save**.
+
+:::note
+The Service ID that you just created will serve as your Client ID while sending authentication requests from your app.
+:::
+
+## Create the Secret Key
+
+We will also need to create a secret key that we can then use to generate the **Client Secret** which again will be used while sending an authentication request to Apple.
+
+1. Go to **Certificates**, **Identifiers & Profiles** > **Keys**.
+2. Click the **+** button beside the keys.
+3. Give a **Key Name** and check the **Sign In With Apple** checkbox.
+4. Click **Configure** next to the **Sign In With Apple** checkbox and select the App ID we previously created under the **Choose a Primary App ID** key.
+5. Click **Save**, verify the details and click **Register**.
+6. Download the Key and keep it in a safe and secure place. **Warning**: You can only download the key once.
+7. Click **Done**.
+
+:::note
+You can keep one App ID and a Secret Key and multiple Service IDs for each environment. But a better practice would be to decouple the App IDs, Service ID and Secret Key for each environments.
+:::

docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md

@@ -2,45 +2,46 @@
 
 We will need to generate a Client Secret for Apple to be able to send authentication requests to Apple.
 
-# Pre Requisites
+## Prerequisites
 
 You must have the following credentials already with you.
 
-- **Developer Account's secret Key file**: This refers to the file that you had created while creating the secret key on Apple Developer account for this deployment. The path of the file could look something simiar to `/home/SecretFiles/AuthKey_M98LQ25T3Z.p8`
-- **Key ID**: Key ID of the Secret key that you may have generated on Apple Developer account for this deployment. e.g. "M98LQ25T3Z". Note that the key identifier in your secret key file name is matching with the Key ID.
-- **Team ID**: The team ID of the developer account. It can be obtained from the App ID that you have created for this deployment. e.g, "ZLWKHWSK48"
-- **Client ID**: This is the service ID that you have created which can now be used as a client ID. e.g. "com.ir-engine.qat-dev.id" 
+- **Developer Account's secret Key file**: This refers to the file you create on Apple Developer account. The path of the file looks something simiar to `/home/SecretFiles/AuthKey_M98LQ25T3Z.p8`
+- **Key ID**: Key ID of the Secret key that you generate on Apple Developer account, e.g., `M98LQ25T3Z`. Note that the key identifier in your secret key file name matches the Key ID.
+- **Team ID**: The team ID of the developer account. It can be obtained from your App ID, e.g., `ZLWKHWSK48`.
+- **Client ID**: This is the service ID that you have created which can now be used as a client ID. e.g. `com.ir-engine.qat-dev.id`.
 
-# Generate the Client Secret
+## Generate the Client Secret
 
-You can make a request to Apple with the required credentials and generate the Client Secret. You can use the script written in the IR Engine's repository under `scripts/generate-apple-sso-token.ts` and generate an Apple key secret by running the following command on the root folder. Please refer to the Pre-Req section for details of the values being used in the command below. 
+You can make a request to Apple with the required credentials and generate the Client Secret. You can use the script written in the IR Engine's repository under `scripts/generate-apple-sso-token.ts` and generate an Apple key secret by running the following command on the root folder. Please refer to the prerequisites section for details of the values being used in the command below.
 
-```
+```shell
 npm run generate-apple-client-secret -- --secretKeyPath <Secret_Key_Path>  --keyId <Secret_Key_ID> --teamId <Developer_Account_Team_ID> --clientId <ClientID_For_ServiceID>
 ```
 
-For Instance.
+For instance:
 
-```
+```shell
 npm run generate-apple-client-secret -- --secretKeyPath '/home/SecretFiles/AuthKey_M98LQ25T3Z.p8'  --keyId 'M98LQ25T3Z' --teamId 'ZLWKHWSK48'--clientId 'com.ir-engine.qat-dev.id'
 ```
 
-**NOTE**
+:::note
 The Client Secret's expiry could at maximum be set to 6 months, so we will have to regenerate it after that.
+:::
 
-# Updating the Client Secret in IR Studio
+## Updating the Client Secret in IR Studio
 
-Every 6 months, when the Client Secret will expire, you will have to get it updated in the running instances of IR Studio as per the following.
+Every 6 months, when the Client Secret expires, you have to get it updated in the running instances of IR Studio as per the following.
 
-- Generate a new Client Secret as mentioned above.
-- On the deployed instance, go to '/admin/settings#authentication'.
-- Update the Apple Client Secret and hit save, it should take a couple of minutes to restart the API pods and should be done then.
-- Also update the Client Secret value in the "Values.yaml" file for both the main release and builder. You can use the following command as reference for updating the Client Secret in Values.yaml files of the deployments. Run the command separately for Main and Builder release while updating the corresponding values accordingly.
- 
-```
+1. Generate a new Client Secret as mentioned above.
+2. On the deployed instance, go to '/admin/settings#authentication'.
+3. Update the Apple Client Secret and hit save, it should take a couple of minutes to restart the API pods and should be done then.
+4. Also update the Client Secret value in the "Values.yaml" file for both the main release and builder. You can use the following command as reference for updating the Client Secret in Values.yaml files of the deployments. Run the command separately for Main and Builder release while updating the corresponding values accordingly.
+
+```shell
 helm repo update && helm upgrade --reuse-values --set api.extraEnv.APPLE_CALLBACK_URL=\<CallbackURL> --set api.extraEnv.APPLE_CLIENT_ID=\<ClientID> --set api.extraEnv.APPLE_CLIENT_SECRET=\<ClientSecret> --set media.extraEnv.APPLE_CALLBACK_URL=\<CallbackURL> --set media.extraEnv.APPLE_CLIENT_ID=\<ClientID> --set media.extraEnv.APPLE_CLIENT_SECRET="\<ClientSecret>" \<Main and builder Release Name> etherealengine/etherealengine
 ```
 
-# Future Work/Recommendations
+## Future Work and Recommendations
 
-We could always make the client Secret generation automatic, provided that the Secret Key is placed in a separate and security accesable location which then can be used to generate Client secrets on the go. We could update the App's code to be able to dynamically generate and save the client secret so you do not have to mannually get it updated every 6 months. At the moment we are figuring out to place the Secret file in a secure yet accessable location and we can then update our code to generate the Client secret automatically.
+We could always make the client Secret generation automatic, provided that the Secret Key is placed in a separate and securely accessible location which then can be used to generate Client secrets on the go. We could update the App's code to be able to dynamically generate and save the client secret so you do not have to manually get it updated every 6 months. At the moment we are figuring out to place the Secret file in a secure yet accessable location and we can then update our code to generate the Client secret automatically.