Merge pull request #3186 from FusionAuth/main

Get scripts

.github/workflows/contentcheck.yml

@@ -19,7 +19,7 @@ jobs:
       - name: Check for blog posts that have incorrect categories
         run: |
           find astro/src/content/blog/ -type f -name "*.md*" |grep -v swp | xargs grep '^categories:'|sed 's/.*categories: //'|sed 's/, /\n/g'|sort -u  > out
-          RES=`diff out .github/known-blog-categories.txt`
+          RES=`diff out config/contentcheck/known-blog-categories.txt`
           exit $RES
         shell: bash
       - name: Grep for absolute URLs referencing FusionAuth.io

.github/workflows/devlinkcheck.yml

@@ -16,5 +16,5 @@ jobs:
       - uses: actions/checkout@v4
       - uses: filiph/[email protected]
         with:
-          arguments: https://fusionauth.dev/docs/ --skip-file .github/linkcheck-skip.txt --connection-failures-as-warnings
+          arguments: https://fusionauth.dev/docs/ --skip-file config/linkcheck/linkcheck-skip.txt --connection-failures-as-warnings
         name: linkcheck

.github/workflows/exampleappscheck.yml

@@ -3,7 +3,7 @@ name: example_app_check
 on: 
   pull_request:
     paths:
-      - '.github/scripts/count-repos.sh'
+      - 'src/scripts/count-repos.sh'
       - '.github/workflows/exampleappcheck.yml'
       - 'astro/src/content/json/exampleapps.json'
       - 'astro/src/content/quickstarts/**'
@@ -18,4 +18,4 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Check for example app completeness
-        run: .github/scripts/count-repos.sh
+        run: src/scripts/count-repos.sh

.github/workflows/linkcheck.yml

@@ -19,5 +19,5 @@ jobs:
       - uses: actions/checkout@v4
       - uses: filiph/[email protected]
         with:
-          arguments: https://fusionauth.io/ --skip-file .github/linkcheck-skip.txt --connection-failures-as-warnings
+          arguments: https://fusionauth.io/ --skip-file config/linkcheck/linkcheck-skip.txt --connection-failures-as-warnings
         name: linkcheck

.github/workflows/updatesitemap.yml

@@ -21,11 +21,11 @@ jobs:
         with:
           node-version: 20
           cache: 'npm'
-          cache-dependency-path: '.github/scripts/publish_sitemap/package-lock.json'
+          cache-dependency-path: '.src/scripts/publish_sitemap/package-lock.json'
       - name: Install dependencies
-        run: cd .github/scripts/publish_sitemap && npm install 
+        run: cd src/scripts/publish_sitemap && npm install 
       - name: Update sitemap
         env: 
           GOOGLE_SEARCH_CONSOLE_JSON_KEY: ${{ secrets.GOOGLE_SEARCH_CONSOLE_JSON_KEY }}
-        run: node .github/scripts/publish_sitemap/publish_sitemap.js
+        run: node src/scripts/publish_sitemap/publish_sitemap.js
         shell: bash

.spellcheck.yaml

@@ -8,7 +8,7 @@ matrix:
   dictionary:
     encoding: utf-8
     wordlists:
-    - .github/knownwords.txt
+    - config/spellcheck/knownwords.txt
   pipeline:
   - pyspelling.filters.url:
   - pyspelling.filters.html:

.vale.ini

@@ -1,4 +1,4 @@
-StylesPath = .github/vale/styles
+StylesPath = config/vale/styles
 
 Vocab = FusionAuth
 MinAlertLevel = error

DocsDevREADME.md

@@ -175,7 +175,7 @@ Follow everything in the `Content Style Guidelines` section.
 - For site navigation, use double quotes: Navigate to "Tenants" and then to the "Password" tab.
 - For field names, use double quotes: "Login Identifier Attribute".
 - For values, use back ticks: `userPrincipalName`.
-- Put each blog post into one or more of the known categories. [Here's the list](https://github.com/FusionAuth/fusionauth-site/blob/main/.github/known-blog-categories.txt). You can separate categories with commas.
+- Put each blog post into one or more of the known categories. [Here's the list](https://github.com/FusionAuth/fusionauth-site/blob/main/config/contentcheck/known-blog-categories.txt). You can separate categories with commas.
 - Use tags. They are separated with commas. These are freeform, so feel free to add multiple and choose what works. The first one is what is used to show related posts, unless there's a `featuredTag` value in the front matter. You can [learn more about the logic by reviewing the layout](https://github.com/FusionAuth/fusionauth-site/blob/main/astro/src/layouts/Blog.astro).
 - You can use the `get-images-from-markdown.rb` script to extract images from markdown and store them in a directory.
 - All references to `stackoverflow.com` should be updated and direct to the community forum at `https://fusionauth.io/community/forum/`
@@ -452,9 +452,9 @@ The main configuration file is located at [`.vale.ini`](./.vale.ini), where we s
 
 ### Rules
 
-- The rules _(or, as Vale calls them, "styles")_ are located at [`.github/vale/styles`](./.github/vale/styles).
-- Right now, we're using [`write-good`](./.github.vale/styles/write-good), a collection of simple rules to avoid common mistakes and awkward sentences.
-- We also have a custom vocabulary at [`.github/vale/styles/config/vocabularies/FusionAuth/accept.txt`](./.github/vale/styles/config/vocabularies/FusionAuth/accept.txt) with known words.
+- The rules _(or, as Vale calls them, "styles")_ are located at [`config/vale/styles`](./config/vale/styles).
+- Right now, we're using [`write-good`](./config/vale/styles/write-good), a collection of simple rules to avoid common mistakes and awkward sentences.
+- We also have a custom vocabulary at [`config/vale/styles/config/vocabularies/FusionAuth/accept.txt`](./config/vale/styles/config/vocabularies/FusionAuth/accept.txt) with known words.
   - Note that this file can use regular expressions to match words in a case-insensitive manner, as described [in their docs](https://vale.sh/docs/topics/vocab/).
 
 ### GitHub Actions
@@ -488,7 +488,7 @@ $ vale --filter=".Name == 'Vale.Spelling'" astro/path/to/file
 Whenever you receive an error, you need to determine if you should:
 
 - Actually fix the word (e.g. if you received an error like _"Use 'Id' instead of 'ID'."_); or
-- Add a known word to [`the vocabulary`](./.github/vale/styles/config/vocabularies/FusionAuth/accept.txt) if it's a language, library, company name, etc. But make sure you have the correct capitalization to avoid having duplicates there; or
+- Add a known word to [`the vocabulary`](./config/vale/styles/config/vocabularies/FusionAuth/accept.txt) if it's a language, library, company name, etc. But make sure you have the correct capitalization to avoid having duplicates there; or
 - In case of custom Astro components, you'd probably need to add a new `TokenIgnores` item in [`.vale.ini`](./.vale.ini).
 
 ## Pull request review process

astro/src/components/mermaid/SequenceDiagram.astro

@@ -48,12 +48,12 @@ props.infoBoxes.forEach(i => {
 
 {
   cache[uniqueKey] && (
-    <div class="mermaid-diagram">
+    <div class="mermaid-diagram flex justify-center">
       <Fragment set:html={cache[uniqueKey]} data-test="mermaid" />
     </div>
   )
 }
 { props.alt &&
   <p class="italic not-prose text-blue-600 text-center dark:text-orange-200"> {props.alt} </p>
 }
-<style set:html={css}/>
+<style set:html={css}/>

astro/src/content/docs/_shared/_admin-user-form.mdx

@@ -16,6 +16,12 @@ user.data.favoriteColor=Favorite Color
 
 This field is not localizable, so you'll only need to modify the default messages file. [Learn more about modifying the messages file in your theme](/docs/customize/look-and-feel/localization#messages).
 
+You can also add a tooltip by adding a related key to the messages file:
+
+```
+{tooltip}user.data.favoriteColor=A user's favorite color. This is used to generate a custom logo with the correct color scheme.
+```
+
 Configure the FusionAuth admin UI to use these forms by navigating to <Breadcrumb>Tenants -> Your Tenant -> General</Breadcrumb> and then to the <Breadcrumb>Form settings</Breadcrumb> section. Set the <InlineField>Admin user form</InlineField> field to your new form.
 
 Learn more in the [Tenant documentation](/docs/get-started/core-concepts/tenants#general).

astro/src/content/docs/_shared/_admin-user-registration-form.mdx

@@ -14,6 +14,13 @@ You should modify your theme to add labels for these custom fields for proper di
 registration.data.backgroundColor=Desired Background Color
 ```
 
+You can also add a tooltip by adding a related key to the messages file:
+
+```
+{tooltip}registration.data.backgroundColor=The desired background color. This will be used in the application and should be a hex code.
+```
+
+
 This field is not localizable, so you'll only need to modify the default messages file. [Learn more about modifying the messages file in your theme](/docs/customize/look-and-feel/localization#messages).
 
 Then, configure the FusionAuth admin UI to use these forms by navigating to <Breadcrumb>Applications -> Your Application -> Registration</Breadcrumb> and then to the <Breadcrumb>Form settings</Breadcrumb> section. Set the <InlineField>Admin Registration</InlineField> field to your new form.

astro/src/content/docs/get-started/run-in-the-cloud/cloud.mdx

@@ -14,7 +14,6 @@ import AccountSectionsOverview from 'src/content/docs/get-started/_account-secti
 import CloudUserNote from 'src/content/docs/get-started/_cloud-user-note.mdx';
 import SettingUpPortalAccount from 'src/content/docs/get-started/_setting-up-portal-account.mdx';
 
-
 ## Overview
 
 FusionAuth Cloud is an entirely managed FusionAuth instance in the cloud. As the owner of that server, you have complete access to the administrative user interface and can create API keys and manage the instance via client libraries or APIs. But you have no access to the servers or networks where the instance runs.
@@ -390,10 +389,11 @@ You can migrate the user data FusionAuth holds for you in a number of ways:
 * From a different auth provider into FusionAuth.
 * Away from FusionAuth to a different auth provider.
 
-If you are interested in migrating to FusionAuth from an auth system other than FusionAuth, check out the [Migration Guide](/docs/lifecycle/migrate-users/).
+If you want to retrieve your user data from FusionAuth Cloud in order to migrate to a different auth provider, see [Accessing User Data](#accessing-user-data). To retrieve user data from a self-hosted FusionAuth instance, query the database.
+
+### Migrating From A Different Auth Provider
 
-If you want to retrieve your user data from FusionAuth Cloud in order to migrate to a different auth provider, see [Accessing User Data](#accessing-user-data).
-To get user data from a self-hosted FusionAuth instance, query the database.
+If you are interested in migrating to FusionAuth from an auth system other than FusionAuth, check out the [Migration Guide](/docs/lifecycle/migrate-users/). 
 
 ### Migrating To FusionAuth Cloud
 
@@ -422,7 +422,6 @@ After your data is uploaded, upgrade your deployment to any subsequent FusionAut
 | [ ]   | Encrypted the database export.                                                                             |
 | [ ]   | Provided the decryption password via a separate communication channel.                                     |
 
-
 ### Migrating Away From FusionAuth Cloud
 
 To migrate from FusionAuth Cloud to a self-hosted instance, please request a database export, as documented in [Accessing User Data](#accessing-user-data).

astro/src/content/docs/lifecycle/authenticate-users/identity-providers/overview-samlv2.mdx

@@ -189,6 +189,23 @@ Once you complete your SAML v2 Identity Provider configuration, if your CORS con
 
 <img src="/img/docs/lifecycle/authenticate-users/identity-providers/identity-provider-samlv2-cors-warning.png" alt="SAMLv2 CORS Warning" width="1200" role="bottom-cropped" />
 
+## Redirects
+
+After a user has logged into their SAML IdP and then sent back to FusionAuth, they can be redirected to another URL. To do so, follow these steps:
+
+* Determine the URL you want the user to arrive at after logging in. Suppose that URL is `https://example.com/welcome`.
+* Make sure that `https://example.com/welcome` is added to the <InlineField>Authorized Redirect URLs</InlineField> field in the Application configuration.
+* URL encode the URL. `https://example.com/welcome` becomes `https%3A%2F%2Fexample.com%2Fwelcome`.
+* Append the URL encoded value to the ACS you are putting in the IdP. It might look something like this: `https://local.fusionauth.io/samlv2/acs?RelayState=https%3A%2F%2Fexample.com%2Fwelcome`.
+
+If you do not provide a `RelayState` parameter, the user will be redirected to the first Authorized redirect URI found in the FusionAuth Application OAuth configuration. 
+
+See [SAML v2 Integration Details](/docs/lifecycle/authenticate-users/identity-providers/overview-samlv2#saml-v2-integration-details) for additional details.
+
+### Redirects And Lambdas
+
+While you can configure a lambda to be executed when a user logs in to FusionAuth using SAML, they cannot affect the end destination of a user. Instead, they allow you to examine a read-only SAML response and add, modify, or remove attributes from the user or registration objects.
+
 ## Troubleshooting
 
 <IdpManagedDomainsTroubleshooting idp_type_name="SAML" />

astro/src/content/docs/lifecycle/migrate-users/_performance-tips.mdx

@@ -0,0 +1,20 @@
+import Aside from 'src/components/Aside.astro';
+
+For best performance, do the following:
+
+* Minimize the number of network hops; load the data from a server on the same network.
+* Run with the `validateDBConstraints` set to `false`.
+* Make sure the JSON is minified.
+* Load in batches of 100k.
+* If you have tens of millions of users and are self-hosting, consider [switching to the database search engine](/docs/lifecycle/manage-users/search/switch-search-engines). With that option, FusionAuth won't sync user data to Elasticsearch during the import. If you require Elasticsearch for advanced searching capabilities, switch back to Elasticsearch after the migration is complete. This option is not available when using [FusionAuth Cloud](/docs/get-started/run-in-the-cloud/cloud).
+* Disable the `user.bulk.create` webhook. This may not be possible if you need FusionAuth to send an event with created users to another system.
+* Set the HTTP timeout to a large value on your API requests. Exactly how to do this varies based on the tool you're using to make the HTTP request. The import API is currently a synchronous operation, though there are plans to make it asynchronous (see [this GitHub issue for more](https://github.com/FusionAuth/fusionauth-issues/issues/944)).
+* If you only provide a `password` field, then FusionAuth will assume the password is in plaintext and hash it for you. Hashing a password negatively affects load time, performance and throughput. If you provide the `salt`, `password`, `encryptionScheme` and `factor` values when importing, then FusionAuth assumes the value in the `password` field is a hashed password, and it will not be hashed.
+* Deduplicate any emails. In FusionAuth, each email address may be associated with only one user account per tenant.
+* Stage your data by exporting current user data into separate JSON files. This will make debugging easier, since you can load one file at a time, and you can repeat a data load if there are issues. It will also be more performant than loading data across a network or from a database.
+
+<Aside type="note">
+The easiest and fastest way to load bulk user data into FusionAuth is to loop over a directory of JSON files that each contain 100,000 users. These JSON files should be clean, have unique emails per tenant and be minified.
+
+In FusionAuth testing, this approach resulted in loading 100,000 users in 62 seconds to an HA FusionAuth Cloud deployment from one EC2 region to another. Performance is dependent on user data complexity, hardware, network and database constraints, but this should give you a good idea of the order of magnitude.
+</Aside>