SPA용 Web API 백 엔드를 보호하는 데 사용하는 Identity 방법

ASP.NET Core Identity 는 인증, 권한 부여 및 ID 관리를 처리하는 API를 제공합니다. API를 사용하면 기반 인증을 사용하여 Web API 백 엔드의 엔드포인트를 cookie보호할 수 있습니다. 사용할 cookie수 없는 클라이언트에 대한 토큰 기반 옵션이 있습니다.

이 문서에서는 Angular, React 및 Vue 앱과 같은 SPA용 Web API 백 엔드를 보호하는 방법을 Identity 보여 줍니다. 동일한 백 엔드 API를 사용하여 앱을 보호할 Blazor WebAssembly 수 있습니다.

필수 조건

이 문서에 표시된 단계는 다음을 수행하는 ASP.NET Core Web API 앱에 인증 및 권한 부여를 추가합니다.

• 인증을 위해 아직 구성되지 않았습니다.
• net8.0 대상 이상.
• 최소 API 또는 컨트롤러 기반 API일 수 있습니다.

이 문서의 테스트 지침 중 일부는 프로젝트 템플릿에 포함된 Swagger UI 를 사용합니다. Swagger UI는 Web API 백 엔드와 함께 사용할 Identity 필요가 없습니다.

NuGet 패키지 설치

다음 NuGet 패키지를 설치합니다.

• Microsoft.AspNetCore.Identity.EntityFrameworkCoreIdentity- Entity Framework Core(EF Core)를 사용할 수 있습니다.
• 다음 패키지 중 하나와 같이 데이터베이스를 사용할 수 EF Core 있는 패키지입니다.
  • Microsoft.EntityFrameworkCore.SqlServer 또는
  • Microsoft.EntityFrameworkCore.Sqlite 또는
  • Microsoft.EntityFrameworkCore.InMemory.

가장 빠른 시작 방법은 메모리 내 데이터베이스를 사용합니다.

나중에 데이터베이스를 SQLite 또는 SQL Server로 변경하여 테스트할 때 또는 프로덕션 사용을 위해 세션 간에 사용자 데이터를 저장합니다. 이는 시작 자습서와 같이 EF Core 마이그레이션을 통해 데이터베이스를 만들어야 하므로 메모리 내와 비교하여 약간 복잡합니다.

Visual Studio에서 NuGet 패키지 관리자를 사용하거나 dotnet add package CLI 명령을 사용하여 이러한 패키지를 설치합니다.

IdentityDbContext 만들기

다음에서 IdentityDbContext<TUser>상속되는 명명 ApplicationDbContext 된 클래스를 추가합니다.

using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;

public class ApplicationDbContext : IdentityDbContext<IdentityUser>
{
    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) :
        base(options)
    { }
}

표시된 코드는 다양한 환경에 대해 데이터베이스를 구성할 수 있도록 하는 특수 생성자를 제공합니다.

이러한 단계에 표시된 코드를 추가할 때 필요에 따라 다음 using 지시문 중 하나 이상을 추가합니다.

using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;

EF Core 컨텍스트 구성

앞에서 설명한 것처럼 가장 간단한 시작 방법은 메모리 내 데이터베이스를 사용하는 것입니다. 메모리 내의 각 실행은 새 데이터베이스로 시작되며 마이그레이션을 사용할 필요가 없습니다. 호출 WebApplication.CreateBuilder(args)후 다음 코드를 추가하여 메모리 내 데이터베이스를 사용하도록 구성 Identity 합니다.

builder.Services.AddDbContext<ApplicationDbContext>(
    options => options.UseInMemoryDatabase("AppDb"));

테스트할 때 또는 프로덕션 사용을 위해 세션 간에 사용자 데이터를 저장하려면 나중에 데이터베이스를 SQLite 또는 SQL Server로 변경합니다.

컨테이너에 서비스 추가 Identity

호출 WebApplication.CreateBuilder(args)후 DI(종속성 주입) 컨테이너에 서비스를 추가하도록 호출 AddAuthorization 합니다.

builder.Services.AddAuthorization();

API 활성화 Identity

호출 WebApplication.CreateBuilder(args)후 , 호출 AddIdentityApiEndpoints<TUser>(IServiceCollection) 및 AddEntityFrameworkStores<TContext>(IdentityBuilder).

builder.Services.AddIdentityApiEndpoints<IdentityUser>()
    .AddEntityFrameworkStores<ApplicationDbContext>();

기본적으로 s 및 독점 토큰은 모두 cookie활성화됩니다. Cookie로그인 엔드포인트의 쿼리 문자열 매개 변수가 있는 경우 useCookies 로그인 시 s 및 토큰이 발급됩니다 true.

경로 매핑 Identity

호출 builder.Build()후 엔드포인트를 매핑 Identity 하기 위한 호출MapIdentityApi<TUser>(IEndpointRouteBuilder):

app.MapIdentityApi<IdentityUser>();

선택한 엔드포인트 보안

엔드포인트를 보호하려면 경로를 정의하는 호출에서 Map{Method} 확장 메서드를 사용합니다RequireAuthorization. 예시:

app.MapGet("/weatherforecast", (HttpContext httpContext) =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = summaries[Random.Shared.Next(summaries.Length)]
        })
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi()
.RequireAuthorization();

이 메서드를 RequireAuthorization 사용하여 다음을 수행할 수도 있습니다.

• 다음 예제와 같이 Swagger UI 엔드포인트를 보호합니다.

  app.MapSwagger().RequireAuthorization();
  

• 다음 예제와 같이 특정 클레임 또는 권한으로 보호합니다.

  .RequireAuthorization("Admin");
  

컨트롤러 기반 웹 API 프로젝트에서 [] 특성을 컨트롤러 또는 작업에 적용하여 Authorize엔드포인트를 보호합니다.

API 테스트

인증을 테스트하는 빠른 방법은 프로젝트 템플릿에 포함된 메모리 내 데이터베이스 및 Swagger UI를 사용하는 것입니다. 다음 단계에서는 Swagger UI를 사용하여 API를 테스트하는 방법을 보여줍니다. Swagger UI 엔드포인트가 보호되지 않는지 확인합니다.

보안 엔드포인트에 액세스 시도

• 앱을 실행하고 Swagger UI로 이동합니다.
• 웹 API 템플릿에서 만든 프로젝트와 같이 /weatherforecast 보안 엔드포인트를 확장합니다.
• 사용해 보기를 선택합니다.
• 실행을 선택합니다. 응답은 .입니다 401 - not authorized.

테스트 등록

• 확장 /register 하여 사용해 보세요.

• UI의 매개 변수 섹션에서 샘플 요청 본문이 표시됩니다.

  {
    "email": "string",
    "password": "string"
  }
  

• "string"을 유효한 전자 메일 주소 및 암호로 바꾼 다음 실행을 선택합니다.

  기본 암호 유효성 검사 규칙을 준수하려면 암호 길이가 6자 이상이어야 하며 다음 문자 중 하나 이상을 포함해야 합니다.

  • 대문자
  • 소문자
  • 숫자 숫자
  • 무수 문자

  잘못된 전자 메일 주소 또는 잘못된 암호를 입력하면 결과에 유효성 검사 오류가 포함됩니다. 유효성 검사 오류가 있는 응답 본문의 예는 다음과 같습니다.

  {
    "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": {
      "PasswordTooShort": [
        "Passwords must be at least 6 characters."
      ],
      "PasswordRequiresNonAlphanumeric": [
        "Passwords must have at least one non alphanumeric character."
      ],
      "PasswordRequiresDigit": [
        "Passwords must have at least one digit ('0'-'9')."
      ],
      "PasswordRequiresLower": [
        "Passwords must have at least one lowercase ('a'-'z')."
      ]
    }
  }
  

  오류는 클라이언트가 구문 분석하고 필요에 따라 유효성 검사 오류를 표시할 수 있도록 ProblemDetails 형식으로 반환됩니다.

  등록에 성공하면 응답이 발생합니다 200 - OK .

로그인 테스트

• 확장 /login 하여 사용해 보세요. 요청 본문 예제에서는 두 개의 추가 매개 변수를 보여 줍니다.

  {
    "email": "string",
    "password": "string",
    "twoFactorCode": "string",
    "twoFactorRecoveryCode": "string"
  }
  

  이 예제에는 추가 JSON 속성이 필요하지 않으며 삭제할 수 있습니다. useCookies를 true로 설정합니다.

• "string"을 등록하는 데 사용한 전자 메일 주소 및 암호로 바꾼 다음 실행을 선택합니다.

  로그인에 성공하면 응답 헤더에 200 - OK 응답이 cookie 표시됩니다.

보안 엔드포인트 다시 테스트

성공적으로 로그인한 후 보안 엔드포인트를 다시 실행합니다. 인증 cookie 은 요청과 함께 자동으로 전송되고 엔드포인트는 권한이 부여됩니다. Cookie-based authentication은 브라우저에 안전하게 기본 제공되고 "작동"합니다.

비브로우저 클라이언트를 사용하여 테스트

일부 웹 클라이언트는 기본적으로 헤더에 s를 포함하지 cookie않을 수 있습니다.

• API를 테스트하기 위해 도구를 사용하는 경우 설정에서 S를 사용하도록 설정 cookie해야 할 수 있습니다.

• JavaScript fetch API는 기본적으로 포함되지 cookie않습니다. 옵션의 값 include 으로 설정하여 사용하도록 설정합니다credentials.

• HttpClient 앱에서 실행하려면 Blazor WebAssembly 다음 예제와 같이 자격 증명을 포함해야 합니다HttpRequestMessage.

  request.SetBrowserRequestCredential(BrowserRequestCredentials.Include);
  

토큰 기반 인증 사용

지원하지 cookie않는 클라이언트의 경우 로그인 API는 토큰을 요청하는 매개 변수를 제공합니다. 후속 요청을 인증하는 데 사용할 수 있는 사용자 지정 토큰(ASP.NET Core ID 플랫폼에 소유하는 토큰)이 발급됩니다. 토큰은 헤더에 Authorization 전달자 토큰으로 전달됩니다. 새로 고침 토큰도 제공됩니다. 이 토큰을 사용하면 사용자가 다시 로그인하도록 강제하지 않고 이전 토큰이 만료되면 애플리케이션에서 새 토큰을 요청할 수 있습니다.

토큰은 표준 JSON 웹 토큰(JWT)이 아닙니다. 기본 제공 Identity API는 주로 간단한 시나리오를 위한 것이므로 사용자 지정 토큰의 사용은 의도적입니다. 토큰 옵션은 완전한 기능을 갖춘 ID 서비스 공급자 또는 토큰 서버가 아니라 사용할 cookie수 없는 클라이언트에 대한 옵션의 대안 cookie 입니다.

토큰 기반 인증을 사용하려면 엔드포인트를 useCookies 호출할 때 쿼리 문자열 매개 변수를 /loginfalse 설정합니다. 토큰은 전달자 인증 체계를 사용합니다. 호출에서 반환된 토큰을 /login사용하여 보호된 엔드포인트에 대한 후속 호출은 액세스 토큰이 있는 <token> 헤더 Authorization: Bearer <token> 를 추가해야 합니다. 자세한 내용은 이 문서의 뒷부분에 있는 POST /login 엔드포인트 사용을 참조하세요.

로그아웃

사용자가 로그아웃할 수 있는 방법을 제공하려면 다음 예제와 /logout 같이 엔드포인트를 정의합니다.

app.MapPost("/logout", async (SignInManager<IdentityUser> signInManager,
    [FromBody] object empty) =>
{
    if (empty != null)
    {
        await signInManager.SignOutAsync();
        return Results.Ok();
    }
    return Results.Unauthorized();
})
.WithOpenApi()
.RequireAuthorization();

이 엔드포인트를 호출할 때 요청 본문에 빈 JSON 개체({})를 제공합니다. 다음 코드는 로그아웃 엔드포인트에 대한 호출의 예입니다.

public signOut() {
  return this.http.post('/logout', {}, {
    withCredentials: true,
    observe: 'response',
    responseType: 'text'

MapIdentityApi<TUser> 엔드포인트

앱에 MapIdentityApi<TUser> 다음 엔드포인트를 추가하는 호출입니다.

• POST /register
• POST /login
• POST /refresh
• GET /confirmEmail
• POST /resendConfirmationEmail
• POST /forgotPassword
• POST /reset Password
• POST /manage/2fa
• GET /manage/info
• POST /manage/info

POST /register 엔드포인트 사용

요청 본문에는 다음과 같은 속성이 EmailPassword 있어야 합니다.

{
  "email": "string",
  "password": "string",
}

자세한 내용은 다음을 참조하세요.

• 이 문서의 앞부분에서 등록 을 테스트합니다.
• RegisterRequest.

POST /login 엔드포인트 사용

요청 본문 EmailPassword 에서 필수입니다. 2FA(2단계 인증)를 사용하도록 설정한 경우 또는 TwoFactorCodeTwoFactorRecoveryCode 필수입니다. 2FA를 사용하도록 설정하지 않으면 둘 다 twoFactorCode 생략하고 twoFactorRecoveryCode. 자세한 내용은 이 문서의 뒷부분에 있는 POST /manage/2fa 엔드포인트 사용을 참조하세요.

다음은 2FA를 사용할 수 없는 요청 본문 예제입니다.

{
  "email": "string",
  "password": "string"
}

다음은 2FA를 사용하도록 설정된 요청 본문 예제입니다.

• {
    "email": "string",
    "password": "string",
    "twoFactorCode": "string",
  }
  

• {
    "email": "string",
    "password": "string",
    "twoFactorRecoveryCode": "string"
  }
  

엔드포인트에는 쿼리 문자열 매개 변수가 필요합니다.

• useCookies - -based authentication에 true 대해 cookie설정됩니다. 토큰 기반 인증에 false 대해 설정하거나 생략합니다.

-based authentication에 대한 cookie자세한 내용은 이 문서의 앞부분에 있는 테스트 로그인을 참조하세요.

토큰 기반 인증

false 지정되거나 생략된 경우 useCookies 토큰 기반 인증을 사용하도록 설정됩니다. 응답 본문에는 다음 속성이 포함됩니다.

{
  "tokenType": "string",
  "accessToken": "string",
  "expiresIn": 0,
  "refreshToken": "string"
}

이러한 속성에 대한 자세한 내용은 다음을 참조하세요 AccessTokenResponse.

다음 예제와 같이 헤더에 액세스 토큰을 넣어 인증된 요청을 수행합니다.

Authorization: Bearer {access token}

액세스 토큰이 만료되려고 하면 /refresh 엔드포인트를 호출합니다.

POST /refresh 엔드포인트 사용

토큰 기반 인증에만 사용합니다. 사용자가 다시 로그인하도록 강제하지 않고 새 액세스 토큰을 가져옵니다. 액세스 토큰이 만료되려고 할 때 이 엔드포인트를 호출합니다.

요청 본문에는 RefreshToken. 요청 본문 예제는 다음과 같습니다.

{
  "refreshToken": "string"
}

호출에 성공하면 다음 예제와 같이 응답 본문은 새 AccessTokenResponse본문입니다.

{
  "tokenType": "string",
  "accessToken": "string",
  "expiresIn": 0,
  "refreshToken": "string"
}

GET /confirmEmail 엔드포인트 사용

전자 메일 확인을 위해 설정된 경우 Identity 엔드포인트에 /register 대한 성공적인 호출은 엔드포인트에 대한 링크가 포함된 전자 메일을 /confirmEmail 보냅니다. 링크에는 다음 쿼리 문자열 매개 변수가 포함됩니다.

• userId
• code
• changedEmail - 사용자가 등록하는 동안 전자 메일 주소를 변경한 경우에만 포함됩니다.

기본적으로 전자 메일 제목은 "전자 메일 확인"이며 전자 메일 본문은 다음 예제와 같습니다.

 Please confirm your account by <a href='https://contoso.com/confirmEmail?userId={user ID}&code={generated code}&changedEmail={new email address}'>clicking here</a>.

속성이 RequireConfirmedEmail 설정된 true경우 전자 메일의 링크를 클릭하여 전자 메일 주소가 확인될 때까지 사용자가 로그인할 수 없습니다. /confirmEmail 엔드포인트:

• 전자 메일 주소를 확인하고 사용자가 로그인할 수 있도록 합니다.
• 응답 본문에 "이메일을 확인해 주셔서 감사합니다."라는 텍스트를 반환합니다.

전자 메일 확인을 위해 설정 Identity 하려면 설정할 RequireConfirmedEmail 코드를 Program.cs 추가하고 DI 컨테이너에 true 구현하는 클래스를 추가합니다IEmailSender. 예시:

builder.Services.Configure<IdentityOptions>(options =>
{
    options.SignIn.RequireConfirmedEmail = true;
});

builder.Services.AddTransient<IEmailSender, EmailSender>();

앞의 예제 EmailSender 에서 구현하는 클래스입니다 IEmailSender. 구현IEmailSender하는 클래스의 예제를 비롯한 자세한 내용은 ASP.NET Core의 계정 확인 및 암호 복구를 참조하세요.

POST /resendConfirmationEmail 엔드포인트 사용

등록된 사용자에 대해 주소가 유효한 경우에만 전자 메일을 보냅니다.

요청 본문에는 Email. 요청 본문 예제는 다음과 같습니다.

{
  "email": "string"
}

자세한 내용은 이 문서의 앞부분에 있는 GET /confirmEmail 엔드포인트 사용을 참조하세요.

POST /forgotPassword 엔드포인트 사용

암호 재설정 코드가 포함된 이메일을 생성합니다. 새 암호를 사용하여 /resetPassword 해당 코드를 보냅니다.

요청 본문에는 Email. 예를 들면 다음과 같습니다.

{
  "email": "string"
}

전자 메일을 보낼 수 있도록 설정하는 Identity 방법에 대한 자세한 내용은 엔드포인트 사용을 GET /confirmEmail 참조하세요.

POST /resetPassword 엔드포인트 사용

엔드포인트를 호출하여 다시 설정 코드를 얻은 후 이 엔드포인트를 호출합니다 /forgotPassword .

요청 본문에는 다음이 ResetCodeNewPassword필요합니다.Email 예를 들면 다음과 같습니다.

{
  "email": "string",
  "resetCode": "string",
  "newPassword": "string"
}

POST /manage/2fa 엔드포인트 사용

사용자에 대한 2FA(2단계 인증)를 구성합니다. 2FA를 사용하도록 설정하면 성공적으로 로그인하려면 이메일 주소 및 암호 외에도 인증자 앱에서 생성한 코드가 필요합니다.

2FA 사용

현재 인증된 사용자에 대해 2FA를 사용하도록 설정하려면 다음을 수행합니다.

• 엔드포인트를 호출하여 /manage/2fa 요청 본문에 빈 JSON 개체({})를 보냅니다.

• 응답 본문은 이 시점에서 필요하지 않은 몇 가지 다른 속성과 함께 제공합니다 SharedKey . 공유 키는 인증자 앱을 설정하는 데 사용됩니다. 응답 본문 예제:

  {
    "sharedKey": "string",
    "recoveryCodesLeft": 0,
    "recoveryCodes": null,
    "isTwoFactorEnabled": false,
    "isMachineRemembered": false
  }
  

• 공유 키를 사용하여 시간 기반 TOTP(일회성 암호)를 가져옵니다. 자세한 내용은 ASP.NET Core에서 TOTP 인증자 앱에 대한 QR 코드 생성 사용을 참조하세요.

• 엔드포인트를 /manage/2fa 호출하여 TOTP 및 "enable": true 요청 본문을 보냅니다. 예시:

  {
    "enable": true,
    "twoFactorCode": "string"
  }
  

• 응답 본문은 trueRecoveryCodes임을 IsTwoFactorEnabled 확인하고 . 복구 코드 인증자 앱을 사용할 수 없는 경우 로그인하는 데 사용됩니다. 2FA를 사용하도록 설정한 후의 응답 본문 예제:

  {
    "sharedKey": "string",
    "recoveryCodesLeft": 10,
    "recoveryCodes": [
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string"
    ],
    "isTwoFactorEnabled": true,
    "isMachineRemembered": false
  }
  

2FA로 로그인

엔드포인트를 /login 호출하여 요청 본문에 전자 메일 주소, 암호 및 TOTP를 보냅니다. 예시:

{
  "email": "string",
  "password": "string",
  "twoFactorCode": "string"
}

사용자가 인증자 앱에 액세스할 수 없는 경우 2FA를 사용하도록 설정할 때 제공된 복구 코드 중 하나를 사용하여 엔드포인트를 호출 /login 하여 로그인합니다. 요청 본문은 다음 예제와 같습니다.

{
  "email": "string",
  "password": "string",
  "twoFactorRecoveryCode": "string"
}

복구 코드 다시 설정

새 복구 코드 컬렉션을 얻으려면 이 엔드포인트를 로 ResetRecoveryCodes 설정하여 호출합니다true. 요청 본문 예제는 다음과 같습니다.

{
  "resetRecoveryCodes": true
}

공유 키 다시 설정

새 임의 공유 키를 얻으려면 다음으로 설정된 이 엔드포인트를 ResetSharedKey 호출합니다 true. 요청 본문 예제는 다음과 같습니다.

{
  "resetSharedKey": true
}

키를 다시 설정하면 이후 요청에 의해 다시 사용하도록 설정될 때까지 인증된 사용자에 대한 2단계 로그인 요구 사항이 자동으로 비활성화됩니다.

컴퓨터 잊어버리기

있는 경우 "내 플래그 기억"을 cookie 지우려면 true로 ForgetMachine 설정된 이 엔드포인트를 호출합니다. 요청 본문 예제는 다음과 같습니다.

{
  "forgetMachine": true
}

이 엔드포인트는 토큰 기반 인증에 영향을 주지 않습니다.

GET /manage/info 엔드포인트 사용

로그인한 사용자의 전자 메일 주소 및 전자 메일 확인 상태 가져옵니다. 보안상의 이유로 이 엔드포인트에서 클레임을 생략했습니다. 클레임이 필요한 경우 서버 쪽 API를 사용하여 클레임에 대한 엔드포인트를 설정합니다. 또는 모든 사용자의 클레임을 공유하는 대신 클레임을 수락하고 사용자에게 클레임이 있는지 여부를 응답하는 유효성 검사 엔드포인트를 제공합니다.

요청에는 매개 변수가 필요하지 않습니다. 응답 본문에는 다음 예제와 같이 및 IsEmailConfirmed 속성이 포함됩니다Email.

{
  "email": "string",
  "isEmailConfirmed": true
}

POST /manage/info 엔드포인트 사용

로그인한 사용자의 전자 메일 주소 및 암호를 업데이트. NewPassword다음 예제와 OldPassword 같이 요청 본문에서 < a0/>를 보냅니NewEmail다.

{
  "newEmail": "string",
  "newPassword": "string",
  "oldPassword": "string"
}

응답 본문의 예는 다음과 같습니다.

{
  "email": "string",
  "isEmailConfirmed": false
}

참고 항목

자세한 내용은 다음 리소스를 참조하세요.

• ID 관리 솔루션 선택
• Identity .NET 웹앱에 대한 관리 솔루션
• ASP.NET Core의 간단한 권한 부여
• ASP.NET Core 프로젝트에서 Identity에 사용자 데이터 추가, 다운로드 및 삭제
• 권한 부여로 보호된 사용자 데이터를 사용한 ASP.NET Core 앱 만들기
• ASP.NET Core의 계정 확인 및 암호 복구
• ASP.NET Core에서 TOTP 인증 앱에 QR 코드 생성 사용
• SPA 용 샘플 Web API 백 엔드 .http 파일은 토큰 기반 인증을 표시합니다. 예:
  • 설정되지 않음 useCookies
  • 권한 부여 헤더를 사용하여 토큰 전달
  • 사용자가 다시 로그인하도록 강제하지 않고 세션을 확장하기 위한 새로 고침 표시
• Web API 백 엔드를 보호하는 데 사용하는 Identity 샘플 Angular 앱