> For the complete documentation index, see [llms.txt](https://docs.zongsoft.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zongsoft.com/documentation/en/framework/security.md).

# Security

Connect the Core security contract, persistent identity permissions, web interface and verification code to establish a complete security call chain.

Zongsoft's security capabilities are divided into public contracts, default persistence implementations, and optional web interfaces. [Core](https://github.com/Zongsoft/framework/tree/main/Zongsoft.Core) defines models such as identity, credentials, and permissions; Zongsoft.Security implements user, role, member, and permission services and saves them through the data engine; Web and Captcha plugins provide HTTP interfaces and human-computer challenges respectively.

## Let’s First Distinguish Three Issues

**Authentication**confirms who the requester is, such as verifying identity and secrets and issuing credentials.**Authorize**determines whether the subject can perform operations on a resource.**Human-machine challenge** reduces automated abuse, it is neither a proof of identity nor a replacement for authorization.

For example, after a user successfully logs in, he may still not have the permission to delete orders; having the permission to read orders does not mean that he can read orders from other tenants. The complete rule needs to be combined with operation authorization and data scope, see [Authentication and Authorization](/documentation/en/framework/security/authentication.md).

## Deployment Components

{% code title="Security.deploy(fragment)" %}

```ini
[plugins zongsoft data]
nuget:Zongsoft.Data

[plugins zongsoft security]
nuget:Zongsoft.Security

[plugins zongsoft security web]
nuget:Zongsoft.Security.Web
```

{% endcode %}

Append these entries to the existing web host, and separately deploy the target database driver, configure the Security connection, initialize the corresponding database structure, and cache the credentials required. Pure backend use does not require the Web child plugin. The deployer skips some Zongsoft transitive dependencies by default, so the deployment plan must be composed explicitly.

Security manifest mounts modules, authenticators, authorizers, and user, role, member, and permission services. Applications typically use them through public security contracts and service APIs, without constructing persistence implementations within controllers or directly modifying permission tables.

## Initialization Sequence

1. Check [Data driven and connected](/documentation/en/framework/data/connections.md), use the test database.
2. Prepare [Security database script](https://github.com/Zongsoft/framework/tree/main/Zongsoft.Security/database) against the target database, keeping it consistent with the mapped version.
3. Deploy Security manifests, options, mappings and dependencies, configure credential caching and authentication policies.
4. Verify a successful login, a failed login, an authorized and a denied operation, and then verify renewals and exits.

{% hint style="warning" %}
🚨 The default configuration of the package identity allows password length to be 0 and strength to be None. They are framework defaults, not production policies. Passwords, authentication, credential expiration, and administrative roles should be clear to the application before deployment.
{% endhint %}

## Configuration Entry

The main configurations are located at `/Security/Identity`, `/Security/Authentication`, `/Security/Authorization`. Authentication configuration includes deadlines, failed attempt windows, and scenario deadlines; authorization configuration includes management roles. The configuration file must be entered into the application by pressing [Option matching rules](/documentation/en/references/option-files.md), and you cannot only edit files that have not been loaded.

Verification code independent integration, see [CAPTCHAs and Confirmation Tokens](/documentation/en/framework/security/captcha.md). See [Core permissions](/documentation/en/framework/core/security/privileges.md) for the basic permission model.

Implementation basis: [security plugin assembly](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Security/src/Zongsoft.Security.plugin), [Default options](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Security/src/Zongsoft.Security.option).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.zongsoft.com/documentation/en/framework/security.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.