From 2ef18cbe17e55e52bc87c7fb80dc7702191b30e3 Mon Sep 17 00:00:00 2001 From: Murad Khateeb Date: Mon, 22 Jul 2024 11:56:59 +0500 Subject: [PATCH 01/13] feat: Add documentation for setting up Apple SSO --- .../04_AppleSSOSetup/01_setupAppleOAuth.md | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md diff --git a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md new file mode 100644 index 000000000000..1e4c21f3687d --- /dev/null +++ b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md @@ -0,0 +1,52 @@ +# 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 user their accounts created on other well known platforms, we also have enable Apple SSO support for IR Studio. This guide scripts down the blueprints to be able to enable it for any perticular application. +# Pre Requisites +* Apple Developer Account +* An Apple Account add 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 Studio` 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 perviously 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 with 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" and click "Continue". +* Fill in the form that opens up. + * Enter the description. + * Enter the Bundle ID which could be a revers-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". +* Click "App IDs" and click "Continue". + * Enter the description. + * Enter the Bundle ID which could be a revers-domain styled string i.e. 'com.domainname.appname' + * Scroll down to "Capabilities" section and check `Sign In with Apple` and click on the "Configure" button beside 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 Return URLs on which the user will be redirected once it is authentication by Apple. + * Click "Continue", verify the details and click Register. + + Please note that 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 "Cretificates, Identifiers & Profiles > Keys". +* Give a Key Name and check the "Sign In With Apple" checkbox. +* Click Configure 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. + + + + + + From 86579ae5098ef750959bf89207452dbce47b82e2 Mon Sep 17 00:00:00 2001 From: Murad Khateeb Date: Wed, 31 Jul 2024 12:59:51 +0500 Subject: [PATCH 02/13] Add docmentation to generate client secret for Apple --- .../04_AppleSSOSetup/01_setupAppleOAuth.md | 61 ++++++++--------- .../02_generateClientSecret.md | 67 +++++++++++++++++++ 2 files changed, 96 insertions(+), 32 deletions(-) create mode 100644 docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md diff --git a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md index 1e4c21f3687d..fbec15580170 100644 --- a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md +++ b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md @@ -1,52 +1,49 @@ -# 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 user their accounts created on other well known platforms, we also have enable Apple SSO support for IR Studio. This guide scripts down the blueprints to be able to enable it for any perticular application. +# 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 user 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. + # Pre Requisites * Apple Developer Account * An Apple Account add 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 Studio` 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 perviously 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 with in your app to be able to let users log in using their apple IDs. +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" and click "Continue". -* Fill in the form that opens up. - * Enter the description. - * Enter the Bundle ID which could be a revers-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. +1. Go to Section named as `Certificates, Ids & Profiles` and click Identifiers. +2. 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. +3. Click "App IDs", App and click "Continue". +4. Fill in the form that opens up. + a. Enter the description. + b. Enter the Bundle ID which could be a reverse-domain styled string i.e. 'com.domainname.appname' + c. Scroll down to "Capabilities" section and check `Sign In with Apple` and click continue. + d. 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". -* Click "App IDs" and click "Continue". - * Enter the description. - * Enter the Bundle ID which could be a revers-domain styled string i.e. 'com.domainname.appname' - * Scroll down to "Capabilities" section and check `Sign In with Apple` and click on the "Configure" button beside 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 Return URLs on which the user will be redirected once it is authentication by Apple. - * Click "Continue", verify the details and click Register. +1. Go to section named as `Certificates, Ids & Profiles` and click Identifiers. +2. Click the '+' button beside the 'identifiers'. +3. Click "Service IDs" and click "Continue". + 1. Enter the description. + 2. Enter the Bundle ID which could be a revers-domain styled string i.e. 'com.domainname.appname' + 3. Click "Continue" and "Register". +4. Edit the service ID that you just created. Check `Sign In with Apple` and click on the "Configure" button beside the checked option. + 4. 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 and the Return URLs on which the user will be redirected once it is authentication by Apple. + 5. Click "Continue", verify the details and click "Save". - Please note that the service ID that you just created will serve as your Client ID while sending authentication requests from your app. + Please note that 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 "Cretificates, Identifiers & Profiles > Keys". -* Give a Key Name and check the "Sign In With Apple" checkbox. -* Click Configure 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. - - - - - +1. Go to "Certificates, Identifiers & Profiles > Keys". +2. Give a Key Name and check the "Sign In With Apple" checkbox. +3. Click Configure and select the App ID we previously created under the "Choose a Primary App ID" key. +4. Click save, verify the details and click Register. +5. 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`. +6. 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 different environments diff --git a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md new file mode 100644 index 000000000000..472e0c7b12c1 --- /dev/null +++ b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md @@ -0,0 +1,67 @@ +# Generate Client Secret for Apple SSO + +We will need to generate a Client Secret for Apple to be able to send authentication requests to Apple. + +# Pre Requisites + +You must have the following credentials already with you. + +- Key ID, +- Team ID, +- Client ID, +- Developer Account's secret Key file + +# Generate the Client Secret + +You can make a request to Apple with the required credentials and generate the Client Secret. Following Code snippet can be used to request the Client Secret from Apple. This is written in Javascript but you can use pretty much any programming language to request a Client Secret from Apple provided that you have all what is listed in the Pre-Req section. + +``` +var jwt = require('jsonwebtoken'); + +const getAppleClientSecret = () => { + const privateKey = fs.readFileSync('Path to the Apple Secret Key'); + AuthKey_2K4W7DYLQL.p8"; + const keyId = "XXXXXXXXXXX"; + const teamId = "XXXXXXXXXXX"; + const clientId = "Client ID for the deployment, you can get it from Apple and also from the Client ID variabels at Admin/Settings#Authentication"; + + const headers = { + kid: keyId, + typ: "JWT", + } + const claims = { + 'iss': teamId, + 'aud': 'https://appleid.apple.com', + 'sub': clientId, + } + token = jwt.sign(claims, privateKey, { + algorithm: 'ES256', + header: headers, + expiresIn: '180d' + }); + + return token + +} +var AppleSecret = getAppleClientSecret(); + +``` + +Please note that this Client Secret will expire in 6 months, we cannot increase the expiry duration of the Client Secret it could at maximum be set to 6 months, so we will have to regenerate it after that save it to wherever it was being used. + +# 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. + +- Generate a new Client Secret as mentioned above. +- on the Deploed 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. + +``` +helm repo update && helm upgrade --reuse-values --set api.extraEnv.APPLE_CALLBACK_URL= --set api.extraEnv.APPLE_CLIENT_ID= --set api.extraEnv.APPLE_CLIENT_SECRET= --set media.extraEnv.APPLE_CALLBACK_URL= --set media.extraEnv.APPLE_CLIENT_ID= --set media.extraEnv.APPLE_CLIENT_SECRET=""
etherealengine/etherealengine +``` + +# Future Work/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. From 6d87df5c16f7d449b7e6d941a8492a8f057346e3 Mon Sep 17 00:00:00 2001 From: Murad Khateeb Date: Tue, 6 Aug 2024 12:47:17 +0500 Subject: [PATCH 03/13] Client Secret can also be generated from IR Engine's scripts --- .../04_AppleSSOSetup/02_generateClientSecret.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md index 472e0c7b12c1..41283406ae5e 100644 --- a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md +++ b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md @@ -49,6 +49,12 @@ var AppleSecret = getAppleClientSecret(); Please note that this Client Secret will expire in 6 months, we cannot increase the expiry duration of the Client Secret it could at maximum be set to 6 months, so we will have to regenerate it after that save it to wherever it was being used. +You can run the above script as an independent Javascript code to generate the Apple Client Secret or you can also use the script written in the IR Engine's repository and generate an Apple key secret by running the following command on the root folder. + +``` +npm run create-apple-sso-secret -- --secretKeyPath --keyId --teamId --clientId +``` + # 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. From 5d8f92ad74a417efbc99c3b4eb1965fc6c276cc7 Mon Sep 17 00:00:00 2001 From: Murad Khateeb Date: Tue, 6 Aug 2024 13:40:07 +0500 Subject: [PATCH 04/13] Fix documentations as per the documentation rules --- .../04_AppleSSOSetup/01_setupAppleOAuth.md | 10 +++++----- .../04_AppleSSOSetup/02_generateClientSecret.md | 6 +++--- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md index fbec15580170..7faf1bf219f5 100644 --- a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md +++ b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md @@ -2,9 +2,9 @@ Just as we have other OAuth providers that allow users to sign in user 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. # Pre Requisites -* Apple Developer Account -* An Apple Account add 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 Studio` in our case. +- Apple Developer Account +- An Apple Account add 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 Studio` 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. @@ -34,7 +34,7 @@ In the Apple Developer account, do the following. 4. 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 and the Return URLs on which the user will be redirected once it is authentication by Apple. 5. Click "Continue", verify the details and click "Save". - Please note that the Service ID that you just created will serve as your Client ID while sending authentication requests from your app. + :::Note: Please note that 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. @@ -46,4 +46,4 @@ We will also need to create a secret key that we can then use to generate the `C 5. 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`. 6. 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 different environments +:::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 different environments diff --git a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md index 41283406ae5e..a93b4377cf83 100644 --- a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md +++ b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md @@ -47,12 +47,12 @@ var AppleSecret = getAppleClientSecret(); ``` -Please note that this Client Secret will expire in 6 months, we cannot increase the expiry duration of the Client Secret it could at maximum be set to 6 months, so we will have to regenerate it after that save it to wherever it was being used. +:::Note: Please note that this Client Secret will expire in 6 months, we cannot increase the expiry duration of the Client Secret it could at maximum be set to 6 months, so we will have to regenerate it after that save it to wherever it was being used. You can run the above script as an independent Javascript code to generate the Apple Client Secret or you can also use the script written in the IR Engine's repository and generate an Apple key secret by running the following command on the root folder. ``` -npm run create-apple-sso-secret -- --secretKeyPath --keyId --teamId --clientId +npm run create-apple-sso-secret -- --secretKeyPath \ --keyId \ --teamId \ --clientId \ ``` # Updating the Client Secret in IR Studio @@ -65,7 +65,7 @@ Every 6 months, when the Client Secret will expire, you will have to get it upda - 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. ``` -helm repo update && helm upgrade --reuse-values --set api.extraEnv.APPLE_CALLBACK_URL= --set api.extraEnv.APPLE_CLIENT_ID= --set api.extraEnv.APPLE_CLIENT_SECRET= --set media.extraEnv.APPLE_CALLBACK_URL= --set media.extraEnv.APPLE_CLIENT_ID= --set media.extraEnv.APPLE_CLIENT_SECRET=""
etherealengine/etherealengine +helm repo update && helm upgrade --reuse-values --set api.extraEnv.APPLE_CALLBACK_URL=\ --set api.extraEnv.APPLE_CLIENT_ID=\ --set api.extraEnv.APPLE_CLIENT_SECRET=\ --set media.extraEnv.APPLE_CALLBACK_URL=\ --set media.extraEnv.APPLE_CLIENT_ID=\ --set media.extraEnv.APPLE_CLIENT_SECRET="\" \
etherealengine/etherealengine ``` # Future Work/Recommendations From 2b75e944d45f262f354b675994a0014df39546e8 Mon Sep 17 00:00:00 2001 From: Murad Khateeb Date: Wed, 7 Aug 2024 12:21:10 +0500 Subject: [PATCH 05/13] Fix MT formating --- .../04_AppleSSOSetup/01_setupAppleOAuth.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md index 7faf1bf219f5..cbea9ddf4db7 100644 --- a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md +++ b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md @@ -16,10 +16,10 @@ In the Apple Developer account, do the following. 2. 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. 3. Click "App IDs", App and click "Continue". 4. Fill in the form that opens up. - a. Enter the description. - b. Enter the Bundle ID which could be a reverse-domain styled string i.e. 'com.domainname.appname' - c. Scroll down to "Capabilities" section and check `Sign In with Apple` and click continue. - d. Verify details and click register. + a. Enter the description. + b. Enter the Bundle ID which could be a reverse-domain styled string i.e. 'com.domainname.appname' + c. Scroll down to "Capabilities" section and check `Sign In with Apple` and click continue. + d. Verify details and click register. # Create a Service ID In the Apple Developer account, do the following. @@ -27,12 +27,12 @@ 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 the 'identifiers'. 3. Click "Service IDs" and click "Continue". - 1. Enter the description. - 2. Enter the Bundle ID which could be a revers-domain styled string i.e. 'com.domainname.appname' - 3. Click "Continue" and "Register". + a. Enter the description. + b. Enter the Bundle ID which could be a revers-domain styled string i.e. 'com.domainname.appname' + c. Click "Continue" and "Register". 4. Edit the service ID that you just created. Check `Sign In with Apple` and click on the "Configure" button beside the checked option. - 4. 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 and the Return URLs on which the user will be redirected once it is authentication by Apple. - 5. Click "Continue", verify the details and click "Save". + a. 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 and the Return URLs on which the user will be redirected once it is authentication by Apple. + b. Click "Continue", verify the details and click "Save". :::Note: Please note that the Service ID that you just created will serve as your Client ID while sending authentication requests from your app. From 33763cec9d6e986e6c97b8316ef1988da837dcb0 Mon Sep 17 00:00:00 2001 From: Murad Khateeb Date: Wed, 7 Aug 2024 12:25:02 +0500 Subject: [PATCH 06/13] Fix formating --- .../03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md index cbea9ddf4db7..f06e9ffe3a8c 100644 --- a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md +++ b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md @@ -28,7 +28,7 @@ In the Apple Developer account, do the following. 2. Click the '+' button beside the 'identifiers'. 3. Click "Service IDs" and click "Continue". a. Enter the description. - b. Enter the Bundle ID which could be a revers-domain styled string i.e. 'com.domainname.appname' + b. Enter the Bundle ID which could be a reverse-domain styled string i.e. 'com.domainname.appname' c. Click "Continue" and "Register". 4. Edit the service ID that you just created. Check `Sign In with Apple` and click on the "Configure" button beside the checked option. a. 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 and the Return URLs on which the user will be redirected once it is authentication by Apple. From feb41337a9a5cf0ce781018ace96b96f6bbca1f5 Mon Sep 17 00:00:00 2001 From: Murad Khateeb Date: Wed, 7 Aug 2024 12:37:31 +0500 Subject: [PATCH 07/13] Fix documentation as per comments from reviewer --- .../04_AppleSSOSetup/01_setupAppleOAuth.md | 21 ++++++++++--------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md index f06e9ffe3a8c..5a8fc8fd7722 100644 --- a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md +++ b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md @@ -16,10 +16,10 @@ In the Apple Developer account, do the following. 2. 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. 3. Click "App IDs", App and click "Continue". 4. Fill in the form that opens up. - a. Enter the description. - b. Enter the Bundle ID which could be a reverse-domain styled string i.e. 'com.domainname.appname' - c. Scroll down to "Capabilities" section and check `Sign In with Apple` and click continue. - d. Verify details and click register. + 1. Enter the description. + 1. Enter the Bundle ID which could be a reverse-domain styled string i.e. 'com.domainname.appname' + 1. Scroll down to "Capabilities" section and check `Sign In with Apple` and click continue. + 1. Verify details and click register. # Create a Service ID In the Apple Developer account, do the following. @@ -27,21 +27,22 @@ 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 the 'identifiers'. 3. Click "Service IDs" and click "Continue". - a. Enter the description. - b. Enter the Bundle ID which could be a reverse-domain styled string i.e. 'com.domainname.appname' - c. Click "Continue" and "Register". + -. Enter the description. + -. Enter the Bundle ID which could be 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 beside the checked option. a. 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 and the Return URLs on which the user will be redirected once it is authentication by Apple. b. Click "Continue", verify the details and click "Save". - :::Note: Please note that the Service ID that you just created will serve as your Client ID while sending authentication requests from your app. + \ Keys". +1. Go to "Certificates, Identifiers & Profiles > Keys". +2. Click the '+' button beside the 'keys'. 2. Give a Key Name and check the "Sign In With Apple" checkbox. -3. Click Configure and select the App ID we previously created under the "Choose a Primary App ID" key. +3. 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. 4. Click save, verify the details and click Register. 5. 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`. 6. Click Done. From 8c0cb6467bdfe60b237abd967f10a9eddc3d40d5 Mon Sep 17 00:00:00 2001 From: Murad Khateeb Date: Wed, 7 Aug 2024 13:58:13 +0500 Subject: [PATCH 08/13] Fix formating --- .../04_AppleSSOSetup/01_setupAppleOAuth.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md index 5a8fc8fd7722..2a5be3bb998d 100644 --- a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md +++ b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md @@ -27,9 +27,9 @@ 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 the 'identifiers'. 3. 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". + - Enter the description. + - Enter the Bundle ID which could be 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 beside the checked option. a. 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 and the Return URLs on which the user will be redirected once it is authentication by Apple. b. Click "Continue", verify the details and click "Save". From 867642db280e98373ee45ec8293eb3621840b93f Mon Sep 17 00:00:00 2001 From: Murad Khateeb Date: Wed, 7 Aug 2024 14:04:52 +0500 Subject: [PATCH 09/13] Fix formating for MD --- .../04_AppleSSOSetup/01_setupAppleOAuth.md | 29 ++++++++++--------- .../02_generateClientSecret.md | 4 +-- 2 files changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md index 2a5be3bb998d..0a7a3da69c19 100644 --- a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md +++ b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md @@ -12,14 +12,14 @@ Go to [Apple Developer Account](https://idmsa.apple.com/IDMSWebAuth/signin?appId # 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, 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. -3. Click "App IDs", App and click "Continue". -4. Fill in the form that opens up. - 1. Enter the description. - 1. Enter the Bundle ID which could be a reverse-domain styled string i.e. 'com.domainname.appname' - 1. Scroll down to "Capabilities" section and check `Sign In with Apple` and click continue. - 1. Verify details and click register. +- 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", App 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. @@ -27,14 +27,15 @@ 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 the 'identifiers'. 3. 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". + - Enter the description. + - Enter the Bundle ID which could be 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 beside the checked option. a. 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 and the Return URLs on which the user will be redirected once it is authentication by Apple. b. Click "Continue", verify the details and click "Save". - \ { var AppleSecret = getAppleClientSecret(); ``` - -:::Note: Please note that this Client Secret will expire in 6 months, we cannot increase the expiry duration of the Client Secret it could at maximum be set to 6 months, so we will have to regenerate it after that save it to wherever it was being used. +**NOTE** +the Client Secret it could at maximum be set to 6 months, so we will have to regenerate it after that save it to wherever it was being used. You can run the above script as an independent Javascript code to generate the Apple Client Secret or you can also use the script written in the IR Engine's repository and generate an Apple key secret by running the following command on the root folder. From 75037d3015b27f44681e4cee455b8f2e9f091f89 Mon Sep 17 00:00:00 2001 From: Murad Khateeb Date: Wed, 7 Aug 2024 14:49:59 +0500 Subject: [PATCH 10/13] Resolve PR comments --- .../04_AppleSSOSetup/01_setupAppleOAuth.md | 40 ++++++++------- .../02_generateClientSecret.md | 50 +++---------------- 2 files changed, 29 insertions(+), 61 deletions(-) diff --git a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md index 0a7a3da69c19..52a7b7f2300f 100644 --- a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md +++ b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md @@ -14,25 +14,26 @@ 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", App and click "Continue". +- Click "App IDs" click "Continue". +- Click "App" in next windown 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. + - 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. -1. Go to section named as `Certificates, Ids & Profiles` and click Identifiers. -2. Click the '+' button beside the 'identifiers'. -3. Click "Service IDs" and click "Continue". +- 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". -4. Edit the service ID that you just created. Check `Sign In with Apple` and click on the "Configure" button beside the checked option. - a. 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 and the Return URLs on which the user will be redirected once it is authentication by Apple. - b. Click "Continue", verify the details and click "Save". +- 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** Please note that the Service ID that you just created will serve as your Client ID while sending authentication requests from your app. @@ -40,12 +41,13 @@ In the Apple Developer account, do the following. # 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'. -2. Give a Key Name and check the "Sign In With Apple" checkbox. -3. 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. -4. Click save, verify the details and click Register. -5. 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`. -6. Click Done. +- 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 different environments +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 different environments. \ No newline at end of file diff --git a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md index 0f27edc8c3a6..e4d878c283e3 100644 --- a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md +++ b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md @@ -6,61 +6,27 @@ We will need to generate a Client Secret for Apple to be able to send authentica You must have the following credentials already with you. -- Key ID, -- Team ID, -- Client ID, -- Developer Account's secret Key file +- 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." 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. "ZLWKHWSK48" +- Team ID, "The team IT of the developer account. It can be obtained from the App ID that you have created for this deplooyment." +- Client ID, "This is the service ID that you have created which can now be used as a client ID" e.g,e.g. "com.ir-engine.qat-dev.id" # Generate the Client Secret -You can make a request to Apple with the required credentials and generate the Client Secret. Following Code snippet can be used to request the Client Secret from Apple. This is written in Javascript but you can use pretty much any programming language to request a Client Secret from Apple provided that you have all what is listed in the Pre-Req section. +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. ``` -var jwt = require('jsonwebtoken'); - -const getAppleClientSecret = () => { - const privateKey = fs.readFileSync('Path to the Apple Secret Key'); - AuthKey_2K4W7DYLQL.p8"; - const keyId = "XXXXXXXXXXX"; - const teamId = "XXXXXXXXXXX"; - const clientId = "Client ID for the deployment, you can get it from Apple and also from the Client ID variabels at Admin/Settings#Authentication"; - - const headers = { - kid: keyId, - typ: "JWT", - } - const claims = { - 'iss': teamId, - 'aud': 'https://appleid.apple.com', - 'sub': clientId, - } - token = jwt.sign(claims, privateKey, { - algorithm: 'ES256', - header: headers, - expiresIn: '180d' - }); - - return token - -} -var AppleSecret = getAppleClientSecret(); - +npm run generate-apple-sso-token -- --secretKeyPath --keyId --teamId --clientId ``` **NOTE** -the Client Secret it could at maximum be set to 6 months, so we will have to regenerate it after that save it to wherever it was being used. - -You can run the above script as an independent Javascript code to generate the Apple Client Secret or you can also use the script written in the IR Engine's repository and generate an Apple key secret by running the following command on the root folder. - -``` -npm run create-apple-sso-secret -- --secretKeyPath \ --keyId \ --teamId \ --clientId \ -``` +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 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. - Generate a new Client Secret as mentioned above. -- on the Deploed instance, go to '/admin/settings#authentication'. +- 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. From 8642e652d6fcc2bc3457a64355c88e2b525c5fb9 Mon Sep 17 00:00:00 2001 From: Murad Khateeb Date: Wed, 7 Aug 2024 15:28:22 +0500 Subject: [PATCH 11/13] Resolve Comments from the PR --- .../04_AppleSSOSetup/01_setupAppleOAuth.md | 36 +++++++++---------- .../02_generateClientSecret.md | 10 +++--- 2 files changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md index 52a7b7f2300f..7e79c28d36a4 100644 --- a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md +++ b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md @@ -1,10 +1,10 @@ # 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 user 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. +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. # Pre Requisites - Apple Developer Account -- An Apple Account add 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 Studio` in our case. +- 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. 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. @@ -12,15 +12,15 @@ Go to [Apple Developer Account](https://idmsa.apple.com/IDMSWebAuth/signin?appId # Create an App ID In the Apple Developer account, do the following. -- Go to Section named as `Certificates, Ids & Profiles` and click Identifiers. +- 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 windown and 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. + - 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. @@ -28,21 +28,21 @@ 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". + - 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". + - 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** - Please note that the Service ID that you just created will serve as your Client ID while sending authentication requests from your app. + 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. +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'. +- 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. @@ -50,4 +50,4 @@ We will also need to create a secret key that we can then use to generate the `C - 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 different environments. \ No newline at end of file +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. \ No newline at end of file diff --git a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md index e4d878c283e3..e86c07d7c81a 100644 --- a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md +++ b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md @@ -6,10 +6,10 @@ We will need to generate a Client Secret for Apple to be able to send authentica 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." 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. "ZLWKHWSK48" -- Team ID, "The team IT of the developer account. It can be obtained from the App ID that you have created for this deplooyment." -- Client ID, "This is the service ID that you have created which can now be used as a client ID" e.g,e.g. "com.ir-engine.qat-dev.id" +- **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" # Generate the Client Secret @@ -28,7 +28,7 @@ Every 6 months, when the Client Secret will expire, you will have to get it upda - 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. +- 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. ``` helm repo update && helm upgrade --reuse-values --set api.extraEnv.APPLE_CALLBACK_URL=\ --set api.extraEnv.APPLE_CLIENT_ID=\ --set api.extraEnv.APPLE_CLIENT_SECRET=\ --set media.extraEnv.APPLE_CALLBACK_URL=\ --set media.extraEnv.APPLE_CLIENT_ID=\ --set media.extraEnv.APPLE_CLIENT_SECRET="\" \
etherealengine/etherealengine From 242e73ef08f591da0dc003552e65c904e8f20745 Mon Sep 17 00:00:00 2001 From: Murad Khateeb Date: Mon, 12 Aug 2024 16:29:37 +0500 Subject: [PATCH 12/13] Add an example command to create apple client secret --- .../04_AppleSSOSetup/02_generateClientSecret.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md index e86c07d7c81a..d0e59fe9559e 100644 --- a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md +++ b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md @@ -16,8 +16,15 @@ You must have the following credentials already with you. 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. ``` -npm run generate-apple-sso-token -- --secretKeyPath --keyId --teamId --clientId +npm run generate-apple-client-secret -- --secretKeyPath --keyId --teamId --clientId ``` + +For Instance. + +``` +npm run generate-apple-client-secret -- --secretKeyPath '/home/SecretFiles/AuthKey_M98LQ25T3Z.p8' --keyId 'M98LQ25T3Z' --teamId 'ZLWKHWSK48'--clientId 'com.ir-engine.qat-dev.id' +``` + **NOTE** The Client Secret's expiry could at maximum be set to 6 months, so we will have to regenerate it after that. From 319df1b845942c63909e7be290ecc88a69117707 Mon Sep 17 00:00:00 2001 From: Armando Salazar Date: Mon, 26 Aug 2024 13:54:00 -0400 Subject: [PATCH 13/13] Improves the updated guides according to our internal style guides. --- .../04_AppleSSOSetup/01_setupAppleOAuth.md | 106 ++++++++++-------- .../02_generateClientSecret.md | 43 +++---- 2 files changed, 80 insertions(+), 69 deletions(-) diff --git a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md index 7e79c28d36a4..c1ef4222cb53 100644 --- a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/01_setupAppleOAuth.md +++ b/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. \ No newline at end of file +## 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. +::: diff --git a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md b/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md index d0e59fe9559e..36acbfa53e68 100644 --- a/docs/manual/03_modules/05_infrastructure/03_devopsDeployment/04_AppleSSOSetup/02_generateClientSecret.md +++ b/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 --keyId --teamId --clientId ``` -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=\ --set api.extraEnv.APPLE_CLIENT_ID=\ --set api.extraEnv.APPLE_CLIENT_SECRET=\ --set media.extraEnv.APPLE_CALLBACK_URL=\ --set media.extraEnv.APPLE_CLIENT_ID=\ --set media.extraEnv.APPLE_CLIENT_SECRET="\" \
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.