.NET Core Client Library
On this page
The .NET Core client library integrates FusionAuth with your .NET Core application. The source code is in the .NET Core client GitHub repository.
Install#
Install the FusionAuth.Client NuGet package:
Install-Package FusionAuth.Client
Usage Suggestions#
Choose a Use Case#
Client libraries wrap the REST API. You can use a client library for two tasks.
The main task is calling the FusionAuth APIs from code. You get auto-completion and typed objects, which helps when you script configuration, automate common tasks, or copy existing Applications and Groups. The API documentation lists the JSON structure of every request and which fields each call requires. When you need the details, read the API documentation and the library source code.
The secondary task is exchanging an authorization code for tokens in the Authorization Code grant. For this task, use an OAuth library for your language instead. For a list of libraries, see the community curated list.
Client libraries don't provide higher level functionality such as token management. To request that functionality, comment on or upvote the open issue.
When a client library doesn't fit your needs, call the REST API directly.
Requests and Responses#
Each library maps a request object to the JSON that the matching API method requires. Depending on the API call, the request object is a set of string parameters or a complex object. When you use a language without static typing, read the API documentation for the operation to learn the expected fields.
Each library returns a response object with these fields:
- A status that matches the HTTP status code from the API. The status is
-1when no HTTP request succeeded. - A JSON success object when the call succeeds.
- A JSON error object with a message when the status is
4xxor5xx. - An exception object when the library sent no request or the server returned no usable response.
Use Separate Clients for API Key Scopes#
When a script calls endpoints with different API key scopes, create one client instance per scope. For example, Entities accept a tenant-scoped API key, but Entity Types and Lambdas require a global API key.
Follow these rules when your library lets you set a Tenant Id on the client instance:
- Set the Tenant Id on the tenant-scoped client only.
- Don't change the Tenant Id on a shared client between calls.
- Don't send a tenant header to a global-only endpoint. The endpoint fails with a
401.
PATCH Requests#
Available since1.14.0
PATCH operations modify only parts of an object in FusionAuth. The .NET Core client library is statically typed, so the library doesn't use strongly typed objects for a PATCH request. Instead, you pass a hash, dictionary, or map of key value pairs. Build a multi-level dictionary that creates JSON with nested keys. Otherwise the PATCH request fails.
For example, to change only the name of an Application with PATCH, send this JSON:
{
"application": {
"name": "hooli-bought-us"
}
}
A typed request object serializes with empty arrays and other default values. Those values change the object in ways you don't expect. Nested key value pairs avoid the problem.
This limitation comes from the current implementation of the .NET Core client library and FusionAuth PATCH support. To support typed objects, the domain objects would need no default values, and the serializer would need to omit empty objects, empty arrays, and other empty values.
To use typed objects today, retrieve the object, modify the object in memory, and then update the object. This sequence works the same as a single PATCH operation.
For more information about future support, see the open issue to handle PATCH requests with more nuance. The issue may add options for configuring a JSON serializer to allow typed domain objects with PATCH.
FusionAuth Templates for .NET#
FusionAuth publishes .NET templates as a NuGet package. The templates create new secured .NET applications from the .NET CLI or Visual Studio. The new applications use FusionAuth for authentication and authorization, and the applications use only standard .NET security libraries.
The package includes the following templates:
fusionauthblazorservercreates a Blazor Server application.fusionauthmvcwebappcreates an MVC application.fusionauthwebapicreates a Web API application.
Requirements#
Before you use the templates, make sure you have:
- A FusionAuth installation. For more information, see Install FusionAuth.
- The .NET Core 7.0 SDK or later.
- Visual Studio 2022 for Mac or Windows, version 17.6 or later, to create projects from Visual Studio. This requirement is optional.
Install the Templates#
Run the following command in a terminal:
dotnet new install FusionAuth.Templates::1.0.0
The templates then appear in the .NET CLI and Visual Studio. The installation works the same on Windows and macOS.
Set Up FusionAuth#
To create a valid Application in FusionAuth, use the Kickstart file from the example repository. For setup instructions, see the templates README. For more information about Kickstart, see Kickstart.
When you don't use the Kickstart file, create the Application manually with the values in the kickstart.json file.
The Kickstart file is designed for the first startup of FusionAuth, such as with docker compose up.
The Kickstart file assumes that your .NET project runs on HTTPS on port 5001. When your project runs on a different port, update the authorizedRedirectURL and logoutURL variables in the kickstart.json file. Visual Studio picks a random port when port 5001 is in use, and IIS or another web server can use a different port too. At any time after the Kickstart file runs, you can also update the URLs on the OAuth tab of the Application settings in the Admin UI. For more information, see Applications.
Handle the Client Secret#
Some templates prompt for a FusionAuth Client Secret when you create a project. Use a non-sensitive secret from a local FusionAuth installation. When you use the Kickstart file, the Client Secret is change-this-in-production-to-be-a-real-secret.
Don't enter a production or sensitive Client Secret at the prompt. The template stores the secret in plain text in the appsettings.Development.json file, and the file may end up committed to your repository.
In production, provide the Client Secret with one of the secure methods that Microsoft recommends. To use an environment variable, set the platform-independent key FusionAuth__ClientSecret. For more information, see Safe storage of app secrets in development in ASP.NET Core and the environment variable instructions.
Create a Project#
Create a project with the .NET CLI, Visual Studio for macOS, or Visual Studio for Windows.
.NET CLI#
Navigate to your new project directory and run the following command:
dotnet new [template-name] [options]
Replace [template-name] with one of the template names listed above. Use [options] to provide your FusionAuth URL and FusionAuth Application Client Id. The following options are available:
--issueris the fully qualified URL of your FusionAuth server. The default value ishttp://localhost:9011.--client-idis the Client Id of your Application. The default value is3c219e58-ed0e-4b18-ad48-f4f92793ae32.--portis the HTTPS port that Kestrel uses. The default value is5001. After installation, you can change the port in theappsettings.Development.jsonfile in the project root directory and in thelaunchSettings.jsonfile in thePropertiesdirectory.
Visual Studio for macOS#
The templates require Visual Studio for macOS version 17.6 or later. To create a project:
- Create or open a Solution.
- Select File -> New Project .
- In the New Project dialog, select Custom from the left-hand menu.
- Select the FusionAuth template you want to use and click Continue .
- Enter the fully qualified URL of your FusionAuth server and the Client Id of your FusionAuth Application, and click Continue .
- Set the project name and click Create .
Visual Studio for Windows#
The templates require Visual Studio for Windows version 17.6 or later. To create a project:
- Create or open a Solution.
- Select File -> New Project .
- In the New Project dialog, select
FusionAuthfrom the All project types dropdown. - Select the FusionAuth template you want to use.
- Set the project name and click Next .
- Enter the fully qualified URL of your FusionAuth server and the Client Id of your FusionAuth Application.
- Click Create .
Test a Project#
For instructions on testing projects that you create from the templates, see the testing section of the templates README.
Uninstall the Templates#
Run the following command:
dotnet new uninstall FusionAuth.Templates
Then restart Visual Studio for the change to take effect.
Example Apps#
- .NET API quickstart - .NET API quickstart tutorial showing how to integrate FusionAuth with a .NET API
- .NET quickstart - .NET quickstart tutorial showing how to integrate FusionAuth with a .NET application
- ASP.NET Core webapp - An ASP.NET Core 3.1 web application using FusionAuth as the identity server
- Example Windows Forms Application Using FusionAuth APIs - This application uses C# to call the FusionAuth APIs to create a user, delete a user, and add a user to a group in a Windows Form application.
- User management - Using the FusionAuth .NET client library to add and remove users and applications
Update Policy#
FusionAuth releases new versions of the SDKs and client libraries to track the FusionAuth API. SDKs and client libraries may also receive bug fixes, security patches, tests, code samples, and documentation changes.
These releases may update dependencies, language engines, and operating systems, because FusionAuth follows the deprecation and sunsetting policies of the underlying technologies. When the maintainer deprecates a language, framework, or operating system, FusionAuth deprecates the SDKs and client libraries that depend on the technology. FusionAuth then updates the SDKs and client libraries to use a newer version.
For more information, see Update a Client Library.