From 680eae0f04636d0878cfe02ccb32f4392dca2d21 Mon Sep 17 00:00:00 2001 From: Chris Lee Date: Mon, 20 Jan 2025 17:04:35 +0000 Subject: [PATCH] docs: update Backstage links in README files (SDKS-3707) --- README.md | 42 +++++++-------- packages/javascript-sdk/README.md | 88 ++++++++++--------------------- packages/token-vault/README.md | 16 +++--- 3 files changed, 55 insertions(+), 91 deletions(-) diff --git a/README.md b/README.md index 62e28339d..74b0315f5 100644 --- a/README.md +++ b/README.md @@ -3,9 +3,9 @@

- Logo + Logo -

ForgeRock SDK for JavaScript

+

Ping SDK for JavaScript

Change Log · @@ -15,9 +15,9 @@

-The ForgeRock JavaScript SDK enables you to quickly integrate the [ForgeRock Identity Platform](https://www.forgerock.com/digital-identity-and-access-management-platform) into your client-side JavaScript apps. +The Ping SDK for JavaScript enables you to quickly integrate Ping products into your JavaScript apps. -Use the SDKs to leverage _[Intelligent Authentication](https://www.forgerock.com/platform/access-management/intelligent-authentication)_ in [ForgeRock's Access Management (AM)](https://www.forgerock.com/platform/access-management) product, to easily step through each stage of an authentication tree by using callbacks. +Use the SDKs to leverage _[Intelligent Access](https://www.pingidentity.com/en/platform/capabilities/intelligent-access.html)_ to easily step through each stage of an authentication tree by using callbacks. @@ -26,7 +26,8 @@ Use the SDKs to leverage _[Intelligent Authentication](https://www.forgerock.com - ForgeRock Identity Platform - - Access Management (AM) 6.5.2+ + - Ping Advanced Identity Cloud + - PingAM 6.5.2+ - Browsers: @@ -39,8 +40,6 @@ Use the SDKs to leverage _[Intelligent Authentication](https://www.forgerock.com - npm - npm 7+ is required to use this project and the sample apps, since npm workspaces are used to install dependencies in sub-projects such as the sample apps -> **Tip**: Older browsers (like IE11) may require multiple [polyfills, which can be found in our documentation](https://sdks.forgerock.com/javascript/polyfills/). - @@ -52,9 +51,9 @@ npm install @forgerock/javascript-sdk ## Samples -ForgeRock provides these samples to help demonstrate SDK functionality/implementation. They are provided "as is" and are not official products of ForgeRock and are not officially supported. +ForgeRock provides these samples to help demonstrate SDK functionality/implementation. They are provided "as is" and are not official products of Ping Identity Corporation and are not officially supported. -To try out the ForgeRock JavaScript SDK please look at one of our samples: +To try out the Ping SDK for JavaScript please look at one of our samples: - [**Embedded login - `samples/embedded-login`**](https://github.com/ForgeRock/sdk-sample-apps/blob/main/embedded-login/README.md) @@ -69,10 +68,10 @@ To try out the ForgeRock JavaScript SDK please look at one of our samples: ## Documentation -Documentation for the SDKs is provided at ****, and includes topics such as: +Documentation for the SDKs is provided at ****, and includes topics such as: - Introducing the SDK Features -- Preparing AM for use with the SDKS +- Preparing your server for use with the SDKS - API Reference documentation @@ -80,16 +79,16 @@ Documentation for the SDKs is provided at ****, and ## Support -If you encounter any issues, be sure to check our **[Troubleshooting](https://backstage.forgerock.com/knowledge/kb/article/a83789945)** pages. +If you encounter any issues, be sure to check our **[Troubleshooting](https://support.pingidentity.com/s/article/How-do-I-troubleshoot-the-ForgeRock-SDK-for-JavaScript)** pages. Support tickets can be raised whenever you need our assistance; here are some examples of when it is appropriate to open a ticket (but not limited to): - Suspected bugs or problems with ForgeRock software. -- Requests for assistance - please look at the **[Documentation](https://sdks.forgerock.com)** and **[Knowledge Base](https://backstage.forgerock.com/knowledge/kb/home/g32324668)** first. +- Requests for assistance - please look at the **[Documentation](https://docs.pingidentity.com/sdks)** and **[Knowledge Base](https://support.pingidentity.com/s/knowledge-base)** first. -You can raise a ticket using **[BackStage](https://backstage.forgerock.com/support/tickets)**, our customer support portal that provides one stop access to ForgeRock services. +You can raise a ticket using the **[Ping Identity Support Portal](https://support.pingidentity.com/s/)** that provides one stop access to support services. -BackStage shows all currently open support tickets and allows you to raise a new one by clicking **New Ticket**. +The support portal shows all currently open support tickets and allows you to raise a new one by clicking **New Ticket**. ## Version History @@ -102,16 +101,15 @@ BackStage shows all currently open support tickets and allows you to raise a new If you would like to contribute to this project you can fork the repository, clone it to your machine and get started. - - -Be sure to check out our [Coding Style and Guidelines](https://wikis.forgerock.org/confluence/display/devcom/Coding+Style+and+Guidelines) page. - ## Disclaimer -> **This code is provided by ForgeRock on an “as is” basis, without warranty of any kind, to the fullest extent permitted by law. ForgeRock does not represent or warrant or make any guarantee regarding the use of this code or the accuracy, timeliness or completeness of any data or information relating to this code, and ForgeRock hereby disclaims all warranties whether express, or implied or statutory, including without limitation the implied warranties of merchantability, fitness for a particular purpose, and any warranty of non-infringement. ForgeRock shall not have any liability arising out of or related to any use, implementation or configuration of this code, including but not limited to use for any commercial purpose. Any action or suit relating to the use of the code may be brought only in the courts of a jurisdiction wherein ForgeRock resides or in which ForgeRock conducts its primary business, and under the laws of that jurisdiction excluding its conflict-of-law provisions.** +> **This code is provided by Ping Identity Corporation ("Ping") on an "as is" basis, without warranty of any kind, to the fullest extent permitted by law. +> Ping Identity Corporation does not represent or warrant or make any guarantee regarding the use of this code or the accuracy, timeliness or completeness of any data or information relating to this code, and Ping Identity Corporation hereby disclaims all warranties whether express, or implied or statutory, including without limitation the implied warranties of merchantability, fitness for a particular purpose, and any warranty of non-infringement. +> Ping Identity Corporation shall not have any liability arising out of or related to any use, implementation or configuration of this code, including but not limited to use for any commercial purpose. +> Any action or suit relating to the use of the code may be brought only in the courts of a jurisdiction wherein Ping Identity Corporation resides or in which Ping Identity Corporation conducts its primary business, and under the laws of that jurisdiction excluding its conflict-of-law provisions.** @@ -122,6 +120,4 @@ This project is licensed under the MIT License - see the [LICENSE](./packages/ja --- -© Copyright 2020 ForgeRock AS. All Rights Reserved. - -[forgerock-logo]: https://www.forgerock.com/themes/custom/forgerock/images/fr-logo-horz-color.svg 'ForgeRock Logo' +© Copyright 2020-2025 Ping Identity. All Rights Reserved diff --git a/packages/javascript-sdk/README.md b/packages/javascript-sdk/README.md index 67ca80f5d..ab2cbcc97 100644 --- a/packages/javascript-sdk/README.md +++ b/packages/javascript-sdk/README.md @@ -3,9 +3,9 @@

- Logo + Logo -

ForgeRock SDK for JavaScript

+

Ping SDK for JavaScript

Change Log · @@ -15,9 +15,9 @@

-The ForgeRock JavaScript SDK enables you to quickly integrate the [ForgeRock Identity Platform](https://www.forgerock.com/digital-identity-and-access-management-platform) into your client-side JavaScript apps. +The Ping SDK for JavaScript enables you to quickly integrate Ping products into your JavaScript apps. -Use the SDKs to leverage _[Intelligent Authentication](https://www.forgerock.com/platform/access-management/intelligent-authentication)_ in [ForgeRock's Access Management (AM)](https://www.forgerock.com/platform/access-management) product, to easily step through each stage of an authentication tree by using callbacks. +Use the SDKs to leverage _[Intelligent Access](https://www.pingidentity.com/en/platform/capabilities/intelligent-access.html)_ to easily step through each stage of an authentication tree by using callbacks. @@ -26,7 +26,8 @@ Use the SDKs to leverage _[Intelligent Authentication](https://www.forgerock.com - ForgeRock Identity Platform - - Access Management (AM) 6.5.2+ + - Ping Advanced Identity Cloud + - PingAM 6.5.2+ - Browsers: - Chrome 87 @@ -35,8 +36,6 @@ Use the SDKs to leverage _[Intelligent Authentication](https://www.forgerock.com - Edge 87 (Chromium) - Edge 44 (Legacy): requires one polyfill for TextEncoder, [`fast-text-encoding` is recommended](https://www.npmjs.com/package/fast-text-encoding) -> **Tip**: Older browsers (like IE11) may require multiple [polyfills, which can be found in our documentation](https://sdks.forgerock.com/javascript/polyfills/). - @@ -51,75 +50,47 @@ npm install @forgerock/javascript-sdk ## Getting Started -To try out the ForgeRock JavaScript SDK, perform these steps: - -1. Setup CORS support in an Access Management (AM) instance. - - See [Enabling CORS Support](https://sdks.forgerock.com/js/01_prepare-am/#enabling-cors-support) in the Documentation. +To try out the Ping SDK for JavaScript, perform these steps: -2. Create an authentication tree in AM. +1. Setup your PingOne Advanced Identity Cloud tenant or PingAM instance. - See [Creating a User Authentication Tree](https://sdks.forgerock.com/js/01_prepare-am/#creating-a-user-authentication-tree) in the Documentation. + See [Server configuration](https://docs.pingidentity.com/sdks/latest/sdks/tutorials/javascript/00_before-you-begin.html#server_configuration) in the Documentation. -3. Clone this repo: +2. Clone this repo: ``` - git clone https://github.com/ForgeRock/forgerock-javascript-sdk.git + git clone https://github.com/ForgeRock/sdk-sample-apps.git ``` -4. In the root folder of the repo, use NPM to install dependencies: +3. In the root folder of the repo, use NPM to install dependencies: ``` npm install ``` -5. Build the ForgeRock JavaScript SDK: - - ``` - pnpm run build - ``` - -6. Open `samples/embedded-login/index.html` and edit the configuration values to match your AM instance. +4. Open `javascript/embedded-login/.env.example` and edit the configuration values to match your server. -7. Serve the `samples` directory by using a simple HTTP server. +5. Save the file as `.env` in the same folder. - - Run `pnpm run start:samples` +6. Run the sample app by using a simple HTTP server. -8. Edit your `/etc/hosts` file to point your localhost (e.g. `127.0.0.1`) to `sdkapp.example.com` + - Run `npm run start:embedded-login` -9. In a [supported web browser](#requirements), navigate to `https://sdkapp.example.com:8443`, and then click **Embedded Login**. +7. In a [supported web browser](#requirements), navigate to `https://localhost:8443`. ## Samples -ForgeRock provides these samples to help demonstrate SDK functionality/implementation. They are provided "as is" and are not official products of ForgeRock and are not officially supported. - -- **Embedded login - `/samples/embedded-login`** - - In most real-world scenarios, you will want to have full control over the UI. In these cases, you can use `FRAuth` to obtain typed callback instances from authentication trees and render the UI in whatever way makes sense for your application. - - You can run this sample app with the `pnpm run start:samples` command. Please [see the Getting Started instructions](#getting-started) for more details. - -- **Central login - `/samples/central-login`** - - In cases in which a centralized login application is desired, in contrast to an embedded login form, the SDK provides a method for leveraging an OAuth flow known as Authorization Code Flow (with PKCE). By using an option (login of "redirect") provided by `TokenManager` to request OAuth/OIDC tokens, when the user is not authenticated, the SDK will redirect the user to the configured login application with the ForgeRock platform. Once authenticated, the user will be redirected back to the original application to attain OAuth/OIDC tokens to complete the user flow. - - You can run this sample app with the `pnpm run start:samples` command. Please [see the Getting Started instructions](#getting-started) for more details. - -- **React todos - `/samples/reactjs-todos`** - - A sample React JS application is provided to demonstrate how the JavaScript SDK can be implemented within a React context. You can read more about this application by [visiting its README.md file](samples/reactjs-todo/README.md). - - Since this sample app uses npm's workspaces feature, npm 7 or higher is required. When on npm 7+, dependencies are already installed when running `npm install`. You can run this sample app with: `npx nx run reactjs-todo:serve`. +We provide a [sample repo](https://github.com/ForgeRock/sdk-sample-apps) to help demonstrate SDK functionality. ## Documentation -Documentation for the SDKs is provided at ****, and includes topics such as: +Documentation for the SDKs is provided at ****, and includes topics such as: - Introducing the SDK Features - Preparing AM for use with the SDKS @@ -130,16 +101,16 @@ Documentation for the SDKs is provided at ****, and ## Support -If you encounter any issues, be sure to check our **[Troubleshooting](https://backstage.forgerock.com/knowledge/kb/article/a83789945)** pages. +If you encounter any issues, be sure to check our **[Troubleshooting](https://support.pingidentity.com/s/article/How-do-I-troubleshoot-the-ForgeRock-SDK-for-JavaScript)** pages. Support tickets can be raised whenever you need our assistance; here are some examples of when it is appropriate to open a ticket (but not limited to): - Suspected bugs or problems with ForgeRock software. -- Requests for assistance - please look at the **[Documentation](https://sdks.forgerock.com)** and **[Knowledge Base](https://backstage.forgerock.com/knowledge/kb/home/g32324668)** first. +- Requests for assistance - please look at the **[Documentation](https://docs.pingidentity.com/sdks)** and **[Knowledge Base](https://support.pingidentity.com/s/knowledge-base)** first. -You can raise a ticket using **[BackStage](https://backstage.forgerock.com/support/tickets)**, our customer support portal that provides one stop access to ForgeRock services. +You can raise a ticket using the **[Ping Identity Support Portal](https://support.pingidentity.com/s/)** that provides one stop access to support services. -BackStage shows all currently open support tickets and allows you to raise a new one by clicking **New Ticket**. +The support portal shows all currently open support tickets and allows you to raise a new one by clicking **New Ticket**. ## Version History @@ -152,16 +123,15 @@ BackStage shows all currently open support tickets and allows you to raise a new If you would like to contribute to this project you can fork the repository, clone it to your machine and get started. - - -Be sure to check out our [Coding Style and Guidelines](https://wikis.forgerock.org/confluence/display/devcom/Coding+Style+and+Guidelines) page. - ## Disclaimer -> **This code is provided by ForgeRock on an “as is” basis, without warranty of any kind, to the fullest extent permitted by law. ForgeRock does not represent or warrant or make any guarantee regarding the use of this code or the accuracy, timeliness or completeness of any data or information relating to this code, and ForgeRock hereby disclaims all warranties whether express, or implied or statutory, including without limitation the implied warranties of merchantability, fitness for a particular purpose, and any warranty of non-infringement. ForgeRock shall not have any liability arising out of or related to any use, implementation or configuration of this code, including but not limited to use for any commercial purpose. Any action or suit relating to the use of the code may be brought only in the courts of a jurisdiction wherein ForgeRock resides or in which ForgeRock conducts its primary business, and under the laws of that jurisdiction excluding its conflict-of-law provisions.** +> **This code is provided by Ping Identity Corporation ("Ping") on an "as is" basis, without warranty of any kind, to the fullest extent permitted by law. +> Ping Identity Corporation does not represent or warrant or make any guarantee regarding the use of this code or the accuracy, timeliness or completeness of any data or information relating to this code, and Ping Identity Corporation hereby disclaims all warranties whether express, or implied or statutory, including without limitation the implied warranties of merchantability, fitness for a particular purpose, and any warranty of non-infringement. +> Ping Identity Corporation shall not have any liability arising out of or related to any use, implementation or configuration of this code, including but not limited to use for any commercial purpose. +> Any action or suit relating to the use of the code may be brought only in the courts of a jurisdiction wherein Ping Identity Corporation resides or in which Ping Identity Corporation conducts its primary business, and under the laws of that jurisdiction excluding its conflict-of-law provisions.** @@ -172,6 +142,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file --- -© Copyright 2020 ForgeRock AS. All Rights Reserved. - -[forgerock-logo]: https://www.forgerock.com/themes/custom/forgerock/images/fr-logo-horz-color.svg 'ForgeRock Logo' +© Copyright 2020-2025 Ping Identity. All Rights Reserved diff --git a/packages/token-vault/README.md b/packages/token-vault/README.md index 720283794..a5903bd28 100644 --- a/packages/token-vault/README.md +++ b/packages/token-vault/README.md @@ -1,6 +1,6 @@ # Token Vault -Token Vault is a feature by ForgeRock that provides an additional layer of security for storing OAuth/OIDC tokens in a JavaScript application (SPA). This is useful for applications that need a higher level of security or have third-party code execution in their application that is not fully trusted. Once configured and setup, you can build your app, [use the ForgeRock SDK](https://backstage.forgerock.com/docs/sdks/latest/whatsnew/index.html), and interact with protected resources as you normally would. Token Vault is entirely framework and library agnostic. +Token Vault is a feature by ForgeRock that provides an additional layer of security for storing OAuth/OIDC tokens in a JavaScript application (SPA). This is useful for applications that need a higher level of security or have third-party code execution in their application that is not fully trusted. Once configured and setup, you can build your app, [use the Ping SDKs](https://docs.pingidentity.com/sdks/latest/sdks/index.html), and interact with protected resources as you normally would. Token Vault is entirely framework and library agnostic. Token Vault is a plugin to our [JavaScript SDK](https://www.npmjs.com/package/@forgerock/javascript-sdk). It is developed around the idea of "Origin Isolation", which you can [read more about in this article](https://github.com/ForgeRock/appAuthHelper/blob/master/origin_isolation.md). To accomplish this, it uses both a Service Worker to intercept allowlisted URLs from emitted `fetch` requests (what we will call an Interceptor) and an `iframe` hosted on a different origin that acts as a proxy and OAuth/OIDC token management layer (what we'll call the Proxy. @@ -32,7 +32,7 @@ We won't go into too much detail here, so let's start with the basics. The end r ### Browser Storage -Whether it's Web Storage API or IndexedDB, any data stored within the browser is restricted by the web app's origin (aka. scheme, domain and port), which is [known as the Same-Origin Policy](https://www.w3.org/Security/wiki/Same_Origin_Policy). We will be leveraging this "same-origin" restriction to store the OAuth/OIDC Tokens (just "tokens" from here on out) we collect using the [Authorization Code Flow](https://backstage.forgerock.com/docs/am/7/oauth2-guide/oauth2-authz-grant-pkce.html) and keep them out of reach from malicious actors. +Whether it's Web Storage API or IndexedDB, any data stored within the browser is restricted by the web app's origin (aka. scheme, domain and port), which is [known as the Same-Origin Policy](https://www.w3.org/Security/wiki/Same_Origin_Policy). We will be leveraging this "same-origin" restriction to store the OAuth/OIDC Tokens (just "tokens" from here on out) we collect using the [Authorization Code Flow](https://docs.pingidentity.com/pingam/7.5/oauth2-guide/oauth2-authz-grant-pkce.html) and keep them out of reach from malicious actors. ### Iframe (aka the Proxy) @@ -48,19 +48,19 @@ This restricted list of URLs are the configured endpoints that need _interceptio ### The Sequence, Simplified -When your application requests tokens from the ForgeRock server (Authorization Server) using the SDK, it will use the [Authorization Code Flow with PKCE](https://backstage.forgerock.com/docs/am/7/oauth2-guide/oauth2-authz-grant-pkce.html). The last request in this flow is a call to the `/access_token` endpoint. This request is intercepted and forwarded to the Proxy. When the Proxy receives the tokens in the response, it will store them within its origin, which should be different than the main app. +When your application requests tokens from the ForgeRock server (Authorization Server) using the SDK, it will use the [Authorization Code Flow with PKCE](https://docs.pingidentity.com/pingam/7.5/oauth2-guide/oauth2-authz-grant-pkce.html). The last request in this flow is a call to the `/access_token` endpoint. This request is intercepted and forwarded to the Proxy. When the Proxy receives the tokens in the response, it will store them within its origin, which should be different than the main app. Before it returns the response to the main app, it redacts the token values from the response body. This ensures the main app never receives or stores the tokens. The Proxy then stores the tokens on behalf of the main app and will be available as a proxy to be used for any future "protected calls" that require the Access Token to be attached to the request. When any request is made by the main app that is configured for authorization the Interceptor will forward it to the Proxy. This includes the usual requests made from the SDK, like requesting user info or revoking tokens. The Proxy will attach the Access Token to the outbound request, and then return the response to the main app with it resolves. If the tokens have expired or become invalid, the main app will receive a 400 response from the proxy. -## ForgeRock Server Setup +## Server Setup Configuration is the key to success with this setup, so take extra care to ensure it's correct and consistent throughout your setup. ### CORS -First, configure your [ForgeRock server's CORS settings](https://backstage.forgerock.com/docs/idcloud/latest/tenants/configure-cors.html) (if using ForgeRock's Identity Cloud product, there's a [preset JavaScript SDK CORS configuration](https://backstage.forgerock.com/docs/sdks/latest/serverconfiguration/cloud/allow-am-resource-requests-trusted-domains.html) that can be used as a starter): +First, configure your [server's CORS settings](https://docs.pingidentity.com/sdks/latest/sdks/tutorials/javascript/00_before-you-begin.html#server_configuration) (if using ForgeRock's Identity Cloud product, there's a [preset JavaScript SDK CORS configuration](https://docs.pingidentity.com/pingoneaic/latest/tenants/configure-cors.html) that can be used as a starter): 1. **Accepted origins**: these should be the origins (scheme, domain and port) for your app AND proxy 2. **Accepted methods**: `GET` and `POST` are enough @@ -71,7 +71,7 @@ An example or your origins can be `http://localhost:5173` and `http://localhost: ### OAuth -Configure your [OAuth client within the ForgeRock server](https://backstage.forgerock.com/docs/sdks/latest/serverconfiguration/cloud/create-oauth2-client.html): +Configure your [OAuth client](https://docs.pingidentity.com/sdks/latest/sdks/tutorials/javascript/00_before-you-begin.html#server_configuration): 1. **Client ID**: Any alphanumeric string can be used here to identity this client 2. **Client secret**: keep this blank @@ -149,7 +149,7 @@ Let's take a look at some of the more important files. First, `app/src/index.html`: ```html - + @@ -367,7 +367,7 @@ Note: for Vite users, we've had the best results with bundling into an IIFE. Web ## Using the Token Vault -Once the Token Vault is properly setup, you can use the JavaScript SDK and any HTTP/fetch library to request protected resources. With the exception of using Refresh Tokens and the token storage mechanism, the remainder of the [documentation for the ForgeRock JavaScript SDK](https://backstage.forgerock.com/docs/sdks/latest/whatsnew/index.html) will remain consistent. The Token Vault will manage your token's lifecycle automatically and, if Refresh Token is enabled in your OAuth client, automatic Access Token refreshing will be handled by the Token Vault as well. +Once the Token Vault is properly setup, you can use the JavaScript SDK and any HTTP/fetch library to request protected resources. With the exception of using Refresh Tokens and the token storage mechanism, the remainder of the [documentation for the Ping SDK for JavaScript](https://docs.pingidentity.com/sdks/latest/sdks/index.html) will remain consistent. The Token Vault will manage your token's lifecycle automatically and, if Refresh Token is enabled in your OAuth client, automatic Access Token refreshing will be handled by the Token Vault as well. ### Requesting & Using Tokens