Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Secure and monitor restructure #3280

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ Imagine a security system that not only asks for your credentials but also reads

What's truly fascinating about adaptive MFA is its dynamic nature. It's not just about adding layers of security; it's about adding the right layers, at the right time. This approach minimizes friction for users, making security feel less like a series of hoops to jump through and more like a smart, responsive ally. It's a dance between convenience and caution, where security measures are tailored in real-time, based on the perceived level of risk. This not only enhances the user experience but also fortifies defenses, ensuring that the keys to the kingdom aren't handed over too easily, nor kept under lock and key unnecessarily.

You can also use the same principles for initial authentication (for instance, requiring a CAPTCHA if a user logs in from a new device). Read more about adaptive approaches in our [Advanced Threat Detection](/docs/operate/secure-and-monitor/advanced-threat-detection) features.
You can also use the same principles for initial authentication (for instance, requiring a CAPTCHA if a user logs in from a new device). Read more about adaptive approaches in our [Advanced Threat Detection](/docs/operate/secure/advanced-threat-detection) features.

## Why Use Multi-factor Authentication (MFA)?

Expand Down
2 changes: 1 addition & 1 deletion astro/src/content/blog/announcing-fusionauth-1-47.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ All in all there are 21 issues, enhancements, and bug fixes included in the 1.47

There were a number of performance improvements in these releases, as the team focused on making FusionAuth even faster and more scalable.

Some improvements are only applicable for Enterprise clients. This included lowering the memory overhead when downloading and storing the IP location database. This IP data is used by [Advanced Threat Detection](/docs/operate/secure-and-monitor/advanced-threat-detection).
Some improvements are only applicable for Enterprise clients. This included lowering the memory overhead when downloading and storing the IP location database. This IP data is used by [Advanced Threat Detection](/docs/operate/secure/advanced-threat-detection).

Other improvements apply to all FusionAuth users. These include:

Expand Down
2 changes: 1 addition & 1 deletion astro/src/content/blog/announcing-fusionauth-1-48.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ If they match, you can be certain the payload is unchanged.
But it's not just webhook signing. There were other webhook related improvements too, including:

* Webhook test messages now include more information if the webhook does not succeed.
* You can use [key master](/docs/operate/secure-and-monitor/key-master) to manage webhook certificates. This is the recommended solution going forward.
* You can use [key master](/docs/operate/secure/key-master) to manage webhook certificates. This is the recommended solution going forward.
* A bug was fixed. Previously tenant specific webhooks were removed when `PATCH`-ing a tenant, and now they are not.
* Test messages sent using the admin UI now preserve the body payload, making it easier to develop webhooks.

Expand Down
2 changes: 1 addition & 1 deletion astro/src/content/blog/javascript-sdks.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ A client library, in contrast, is a wrapper over [FusionAuth APIs](/docs/apis/).

If you want to compare a client library to a child's toy, it is like legos. Engineers build a script or program using a client library to extend or configure FusionAuth. Some examples of tasks well suited to a client library:

* [rotating client secrets or API keys](/docs/operate/secure-and-monitor/key-rotation) to improve your security posture
* [rotating client secrets or API keys](/docs/operate/secure/key-rotation) to improve your security posture
* pulling user data every night for data warehouse ingestion
* creating a new FusionAuth tenant every time a client signs up for your app
* offering a unique, custom login or registration experience not supported by the [FusionAuth hosted login pages](/docs/get-started/core-concepts/integration-points#hosted-login-pages)
Expand Down
2 changes: 1 addition & 1 deletion astro/src/content/blog/log4j-fusionauth.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ To learn more about the CVE, you can:

## What about Elasticsearch

Elasticsearch is used by many FusionAuth installations. However, in general the Elasticsearch service is not publicly accessible, if [following the recommended security guidance](/docs/operate/secure-and-monitor/securing).
Elasticsearch is used by many FusionAuth installations. However, in general the Elasticsearch service is not publicly accessible, if [following the recommended security guidance](/docs/operate/secure/securing).

<Aside type="note" nodark="true">
You should never allow internet connections to Elasticsearch.
Expand Down
4 changes: 2 additions & 2 deletions astro/src/content/docs/_shared/_client-side-api-keys.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,6 @@ The client code then sends requests to the server side component, and the server
This is the **recommended option**.
* Create an API key with extremely limited permissions and distribute it.
Since stealing the key when used on the client side is trivial--all an attacker has to do is 'view source'--make sure you have carefully considered the risk and result of someone stealing and using the key outside of your application.
You can also monitor FusionAuth usage with webhooks, use [IP ACLs](/docs/operate/secure-and-monitor/advanced-threat-detection/#ip-access-control-lists) to limit where the API key can be used from, or place an [HTTP proxy](/docs/operate/deploy/proxy-setup) in front of FusionAuth to further limit access.
Plan to [rotate the key regularly](/docs/operate/secure-and-monitor/key-rotation) to limit the impact.
You can also monitor FusionAuth usage with webhooks, use [IP ACLs](/docs/operate/secure/advanced-threat-detection/#ip-access-control-lists) to limit where the API key can be used from, or place an [HTTP proxy](/docs/operate/deploy/proxy-setup) in front of FusionAuth to further limit access.
Plan to [rotate the key regularly](/docs/operate/secure/key-rotation) to limit the impact.

2 changes: 1 addition & 1 deletion astro/src/content/docs/_shared/_update-key-note.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
Only the name of the Key may be changed; all other fields will remain the same. If you need to update a Key with a new certificate, algorithm or other attributes, please [Import a Key](/docs/apis/keys#import-a-key).

For example, if you have a Key with an associated expiring certificate, you'll need to follow the steps similar to those outlined in the [JWT signing key rotation documentation](/docs/operate/secure-and-monitor/key-rotation#jwt-signing-key-rotation):
For example, if you have a Key with an associated expiring certificate, you'll need to follow the steps similar to those outlined in the [JWT signing key rotation documentation](/docs/operate/secure/key-rotation#jwt-signing-key-rotation):

* Import this key, keypair or certificate into FusionAuth. This will create a new Key entity in FusionAuth.
* Update the appropriate configuration with this new Key (JWT signing configuration, SAML validation configuration, etc).
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ import JSON from 'src/components/JSON.astro';
<ReactorStatusValues />
</APIField>
<APIField name="status.breachedPasswordDetection" type="String">
The status for [Breached Password Detection](/docs/operate/secure-and-monitor/breached-password-detection). The possible following values:
The status for [Breached Password Detection](/docs/operate/secure/breached-password-detection). The possible following values:

* `ACTIVE` - the feature is active
* `DISCONNECTED` - the feature is currently disconnected
Expand Down
4 changes: 2 additions & 2 deletions astro/src/content/docs/apis/hosted-backend.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ _Response Codes_
|------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 200 | There was an error. The route will serve up an error page with HTML and details on what went wrong. |
| 302 | A successful request will redirect the user to `/oauth2/authorize` to log in. |
| 403 | A forbidden response typically means that the Origin of this request did not pass the FusionAuth CORS filter. Add your app origin to your [CORS Configuration](/docs/operate/secure-and-monitor/cors) as an <InlineField>Allowed Origin</InlineField>. |
| 403 | A forbidden response typically means that the Origin of this request did not pass the FusionAuth CORS filter. Add your app origin to your [CORS Configuration](/docs/operate/secure/cors) as an <InlineField>Allowed Origin</InlineField>. |
| 500 | There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files. |

## Register
Expand Down Expand Up @@ -148,7 +148,7 @@ _Response Codes_
|------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 200 | There was an error. The route will serve up an error page with HTML and details on what went wrong. |
| 302 | A successful request will redirect the user to `/oauth2/register` to register. |
| 403 | A forbidden response typically means that the Origin of this request did not pass the FusionAuth CORS filter. Add your app origin to your [CORS Configuration](/docs/operate/secure-and-monitor/cors) as an <InlineField>Allowed Origin</InlineField>. |
| 403 | A forbidden response typically means that the Origin of this request did not pass the FusionAuth CORS filter. Add your app origin to your [CORS Configuration](/docs/operate/secure/cors) as an <InlineField>Allowed Origin</InlineField>. |
| 500 | There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files. |

## Callback
Expand Down
2 changes: 1 addition & 1 deletion astro/src/content/docs/apis/login.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -598,6 +598,6 @@ The response for this API will contain a compressed zip of the audit logs.
```

<Aside type="note">
The location information is only included in exports when [Advanced Threat Detection](/docs/operate/secure-and-monitor/advanced-threat-detection) is enabled.
The location information is only included in exports when [Advanced Threat Detection](/docs/operate/secure/advanced-threat-detection) is enabled.
</Aside>

2 changes: 1 addition & 1 deletion astro/src/content/docs/apis/reactor.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ This API does not return a JSON response body.
## Deactivate Reactor license

This API is used to deactivate a Reactor license.
If [Breached Password Detection](/docs/operate/secure-and-monitor/breached-password-detection/) was being used it will no longer work, licensed features can no longer be enabled, and existing configurations may no longer work if they use licensed features.
If [Breached Password Detection](/docs/operate/secure/breached-password-detection/) was being used it will no longer work, licensed features can no longer be enabled, and existing configurations may no longer work if they use licensed features.

### Request

Expand Down
4 changes: 2 additions & 2 deletions astro/src/content/docs/apis/system.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -245,7 +245,7 @@ The Status API is used to retrieve the current status and metrics for FusionAuth
By default, this API requires authentication. If you prefer to allow unauthenticated access to this endpoint from local scrapers, you may set `fusionauth-app.local-metrics.enabled=true`. See the [configuration reference](/docs/reference/configuration) for more info.

<Aside type="note">
FusionAuth also supports a system status check [using Prometheus](/docs/operate/secure-and-monitor/prometheus).
FusionAuth also supports a system status check [using Prometheus](/docs/operate/monitor/prometheus).
</Aside>

### Request
Expand Down Expand Up @@ -332,7 +332,7 @@ The Version API is used to retrieve the current version of FusionAuth.

## Retrieve System Metrics Using Prometheus

This page contains the API that is used for retrieving FusionAuth application metrics to be used with Prometheus. Please refer to the [Prometheus setup](/docs/operate/secure-and-monitor/prometheus#) guide to understand how to set up Prometheus with the FusionAuth metrics endpoint.
This page contains the API that is used for retrieving FusionAuth application metrics to be used with Prometheus. Please refer to the [Prometheus setup](/docs/operate/monitor/prometheus) guide to understand how to set up Prometheus with the FusionAuth metrics endpoint.

By default, this API requires authentication. If you prefer to allow unauthenticated access to this endpoint from local scrapers, you may set `fusionauth-app.local-metrics.enabled=true`. See the [configuration reference](/docs/reference/configuration) for more info.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -147,7 +147,7 @@ The security settings may be used to require authentication in order to submit a
The password to be used for HTTP Basic Authentication.
</APIField>
<APIField name="Certificate" optional>
The [Key](/docs/operate/secure-and-monitor/key-master) containing an SSL certificate to be used when connecting to the webhook.
The [Key](/docs/operate/secure/key-master) containing an SSL certificate to be used when connecting to the webhook.

If you need to add a certificate for use with this webhook, navigate to <strong>Settings -> Key Master</strong> and import a certificate. The certificate will then be shown as an option in this form control.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ Keys are generated or imported from <strong>Settings -> Key Master</strong>. Web

EC and RSA keys allow you to make public keys available through the `/.well-known/jwks.json` endpoint, which facilitates key rotation. If your webhook listener cannot make outbound network connections or you prefer to manually configure your key in your webhook listener, HMAC keys are a good option.

For this example, we'll use an RSA key pair. More information on keys is available in the [Key Master Guide](/docs/operate/secure-and-monitor/key-master).
For this example, we'll use an RSA key pair. More information on keys is available in the [Key Master Guide](/docs/operate/secure/key-master).

Next, you configure your webhook to sign the event with this key. From <strong>Settings -> Webhooks</strong>, click on the Edit button for your webhook (or create a new webhook). Select the <strong>Security</strong> tab panel. Once you enable <InlineField>Sign events</InlineField>, a <InlineField>Signing key</InlineField> select dropdown allows you to choose the generated key. Be sure to click Save in the upper right corner.

Expand Down Expand Up @@ -84,7 +84,7 @@ The [Webhook Testing](/docs/extend/events-and-webhooks#test-a-webhook) page prov

### Key Rotation

[Rotating keys](/docs/operate/secure-and-monitor/key-rotation) regularly is an important part of a defense-in-depth strategy. The type of key used for signing webhook events and the method used for fetching that key determines the process for rotating keys.
[Rotating keys](/docs/operate/secure/key-rotation) regularly is an important part of a defense-in-depth strategy. The type of key used for signing webhook events and the method used for fetching that key determines the process for rotating keys.

* Signatures validated using a public key (RSA or EC) where signature verification dynamically fetches public key from `.well-known/jwks.json` endpoint
* Generate new key in FusionAuth
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -174,4 +174,4 @@ There are a number of other integration points in FusionAuth beyond the APIs.
* [Lambdas](/docs/extend/code/lambdas/) allow you to run business logic at certain points in the authentication lifecycle.
* [Plugins](/docs/extend/code/password-hashes/) allow you to extend FusionAuth with custom Java code. Currently the main use is to allow you to use custom password hashing. This allows you to import user data from existing systems without requiring user password changes.
* [Webhooks](/docs/extend/events-and-webhooks/) allow you to send data to external systems when events occur in FusionAuth.
* [Monitoring](/docs/operate/secure-and-monitor/monitor) provides insight into a FusionAuth instance's debug messages, performance metrics and other data.
* [Monitoring](/docs/operate/monitor/monitor) provides insight into a FusionAuth instance's debug messages, performance metrics and other data.
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ See the [Keys API](/docs/apis/keys) for more, including supported algorithms and

## Updating Keys

FusionAuth can manage keys, secrets, and certificates, using [Key Master](/docs/operate/secure-and-monitor/key-master). You can update a Key managed by FusionAuth, with some limits.
FusionAuth can manage keys, secrets, and certificates, using [Key Master](/docs/operate/secure/key-master). You can update a Key managed by FusionAuth, with some limits.

<UpdateKeyNote />

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -689,7 +689,7 @@ If you no longer need an IP address on the allow list, please [log a support tic
If you encounter a CAPTCHA during manual testing, ensure you have local browser caching enabled. Using browser developer tools to disable caching often leads to CAPTCHA presentation. Consult the documentation for your browser to learn more.

<Aside type="note">
The CAPTCHA described here is separate from the CAPTCHA configured using [Advanced Threat Detection](/docs/operate/secure-and-monitor/advanced-threat-detection) and can only be managed by the FusionAuth team.
The CAPTCHA described here is separate from the CAPTCHA configured using [Advanced Threat Detection](/docs/operate/secure/advanced-threat-detection) and can only be managed by the FusionAuth team.
</Aside>

## Custom FusionAuth Cloud Features
Expand Down Expand Up @@ -799,7 +799,7 @@ Since it is a managed service, there are additional limitations as well:
* You cannot self-service downgrade the version of a FusionAuth Cloud deployment. For example, you cannot change the version from `1.35.0` to `1.34.0`.
* If you have a deployment with backups, you can roll back by [restoring from backup](/docs/get-started/run-in-the-cloud/cloud#restoring-from-backup).
* You cannot run a [Kickstart file](/docs/get-started/download-and-install/development/kickstart) on a FusionAuth Cloud deployment. (yet! 😎)
* There is no support for proxy customization to add, for example, [tenant routing](/docs/operate/deploy/proxy-setup#proxies-and-tenants). To accomplish such goals, add your own proxy layer such as CloudFlare, with FusionAuth Cloud as an origin. Make sure you configure the [trusted proxies](/docs/operate/secure-and-monitor/networking).
* There is no support for proxy customization to add, for example, [tenant routing](/docs/operate/deploy/proxy-setup#proxies-and-tenants). To accomplish such goals, add your own proxy layer such as CloudFlare, with FusionAuth Cloud as an origin. Make sure you configure the [trusted proxies](/docs/operate/secure/networking).
* You cannot modify `X-Forwarded-Port` or `X-Forwarded-Proto`. For example, you can't proxy a FusionAuth Cloud instance to make it appear as if it was running at `http://localhost` or another non-TLS endpoint.
* Use of port 25 is not allowed. To connect to an SMTP server such as Mailgun or SES, use a different port.
* The IP addresses of a FusionAuth Cloud deployment are not fixed. Whenever possible, use the domain name, which is fixed. If you need IP addresses of the FusionAuth service nodes, follow the instructions in the [Deployment IP Addresses](#deployment-ip-addresses) section found above. Be aware that even after determining the assigned IP addresses, they are subject to change.
Expand Down
Loading