Now generally available: the ASP.NET Core Identity Provider for Amazon Cognito

We’re pleased to announce the general availability of the ASP.NET Core Identity Provider for Amazon Cognito, which enables ASP.NET Core developers to easily integrate with Amazon Cognito in their web applications.

Targeting .NET Standard 2.0, the custom ASP.NET Core Identity Provider for Amazon Cognito extends the ASP.NET Core Identity membership system by providing Amazon Cognito as a custom storage provider for ASP.NET Identity. In a few lines of code, you can add authentication and authorization that’s based on Amazon Cognito to your ASP.NET Core application.

Getting started with the sample web application

You can quickly try out the library by cloning and exploring the sample web application from the GitHub repository.

To use the sample application with your Amazon Cognito user pool, just make the necessary changes to the following properties in the appsettings.json file:

"AWS": {
    "Region": "<your region id goes here>",
    "UserPoolClientId": "<your user pool client id goes here>",
    "UserPoolClientSecret": "<your user pool client secret goes here>",
    "UserPoolId": "<your user pool id goes here>"
}

Migrating an existing web application to use the ASP.NET Core Identity Provider for Amazon Cognito

To upgrade an existing web application to use Amazon Cognito as the Identity provider, you need to add the following NuGet dependencies to your ASP.NET Core web application:

To add Amazon Cognito as an Identity provider, add a call to services.AddCognitoIdentity(); in the ConfigureServices method.

public void ConfigureServices(IServiceCollection services)
{
    // Adds Amazon Cognito as Identity Provider
    services.AddCognitoIdentity();
    ...
}

Finally, if it isn’t already active, enable the support for authentication in ASP.NET Core in your Startup.cs file:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    // If not already enabled, you need to enable ASP.NET Core authentication
    app.UseAuthentication();
    ...
}

Using the CognitoUser class as your web application user class

Once you add Amazon Cognito as the default ASP.NET Core Identity provider, you need to use the newly introduced CognitoUser class, instead of the default ApplicationUser class.
These changes are required in any existing Razor views and controllers. Here is an example with a Razor view.

@using Microsoft.AspNetCore.Identity
@using Amazon.Extensions.CognitoAuthentication
@inject SignInManager<CognitoUser> SignInManager
@inject UserManager<CognitoUser> UserManager

The ASP.NET Core Identity Provider for Amazon Cognito comes with custom implementations of the ASP.NET Core Identity classes UserManager and SigninManager (CognitoUserManager and CognitoSigninManager). These implementations are designed to support Amazon Cognito use cases, such as:

User account management (account registration, account confirmation, user attributes update, account deletion)
User password management (password update, password reset)
User login and user logout (with or without two-factor authentication)
Roles and claims management
Authorization

Using Amazon Cognito as an Identity membership system is as simple as using CognitoUserManager and CognitoSigninManager in your existing scaffolded Identity controllers.

public async Task<IActionResult> OnPostAsync(string returnUrl = null)
{
    returnUrl = returnUrl ?? Url.Content("~/");
    if (ModelState.IsValid)
    {
        // Retrieves a new user with the pool configuration set up
        CognitoUser user = _pool.GetUser(Input.UserName);
        // Sets the required user email
        user.Attributes.Add(CognitoAttributesConstants.Email, Input.Email);
        // Set additional attributes required by the user pool
        user.Attributes.Add("custom:domain", "foo.bar");
        // Registers the user in the pool
        SigninResult result = await _userManager.CreateAsync(user, Input.Password);
        if (result.Succeeded)
        {
            _logger.LogInformation("User created a new account with password.");
            
            await _signInManager.SignInAsync(user, isPersistent: false);
            // Redirects to the account confirmation page
            return RedirectToPage("./ConfirmAccount");
        }
        foreach (var error in result.Errors)
        {
            ModelState.AddModelError(string.Empty, error.Description);
        }
    }

    // If we got this far, something failed, redisplay form
    return Page();
}

You can find complete samples in the Amazon Cognito ASP.NET Core Identity Provider GitHub repository, including the following:

User registration
User login with and without two-factor authentication
Account confirmation
How to change or reset a user password

Feel free to explore other examples in the documentation guide available on GitHub.

Authentication and authorization

By default, authentication is supported by the Amazon CognitoAuthentication Extension Library using the Secure Remote Password protocol. In addition, ASP.NET Core authorization provides a simple, declarative role and a rich policy-based model to handle authorization.

We use Amazon Cognito groups to support role-based authorization. Restricting access to only users who are part of an “Admin” group is as simple as adding the following attribute to the controllers or methods you want to restrict access to:

[Authorize(Roles = "Admin")]
public class AdminController : Controller
{
}

Similarly, we use Amazon Cognito users attributes to support claim-based authorization. Amazon Cognito prefixes custom attributes with the key “custom:”.

The following snippets shows how you could restrict access to resources to Amazon Cognito users with a specific “domain” attribute value by creating a custom policy and applying it to your resources. You can do this in the ConfigureServices method of your Startup.cs file:

public void ConfigureServices(IServiceCollection services)
{
    List<string> authorizedDomains = new List<string>()
    {
        "amazon.com",
        "foo.bar"
    };

    services.AddAuthorization(options =>
    {
        options.AddPolicy("AuthorizedDomainsOnly", policy => policy.RequireClaim("custom:domain", authorizedDomains));
    });
    
    ...
}

[Authorize(Policy = "AuthorizedDomainsOnly")]
public class RestrictedController : Controller
{
}

Providing feedback

We would love to know how you’re using the ASP.NET Core Identity Provider for Amazon Cognito. Please give us any feedback and check out the source on GitHub!

Submit a feature request or up-vote existing ones on the GitHub Issues page.

AWS Developer Tools Blog