.NET Core (Blazor WASM) 애플리케이션에 인증 (Authentication)을 추가하세요

팁:

다음 데모는 .NET Core 8.0 및 Blorc.OpenIdConnect를 기반으로 구축되었습니다.
.NET Core 샘플 프로젝트는 GitHub 저장소에서 확인할 수 있습니다.

사전 준비 사항

Logto Cloud 계정 또는 셀프 호스팅 Logto.
Logto 싱글 페이지 애플리케이션 생성.

설치

프로젝트에 NuGet 패키지를 추가하세요:

dotnet add package Blorc.OpenIdConnect

통합

스크립트 참조 추가

index.html 파일에 Blorc.Core/injector.js를 포함하세요:

index.html
<head>
  <!-- ... -->
  <script src="_content/Blorc.Core/injector.js"></script>
  <!-- ... -->
</head>

서비스 등록

다음 코드를 Program.cs 파일에 추가하세요:

Program.cs
using Blorc.OpenIdConnect;
using Blorc.Services;

builder.Services.AddBlorcCore();
builder.Services.AddAuthorizationCore();
builder.Services.AddBlorcOpenIdConnect(
    options =>
    {
        builder.Configuration.Bind("IdentityServer", options);
    });

var webAssemblyHost = builder.Build();

await webAssemblyHost
    .ConfigureDocumentAsync(async documentService =>
    {
        await documentService.InjectBlorcCoreJsAsync();
        await documentService.InjectOpenIdConnectAsync();
    });

await webAssemblyHost.RunAsync();

정보:

Microsoft.AspNetCore.Components.WebAssembly.Authentication 패키지를 사용할 필요가 없습니다. Blorc.OpenIdConnect 패키지가 인증 (Authentication) 과정을 처리할 것입니다.

리디렉션 URI 구성

세부 사항을 살펴보기 전에, 최종 사용자 경험에 대한 간단한 개요를 소개합니다. 로그인 과정은 다음과 같이 간소화될 수 있습니다:

귀하의 앱이 로그인 메서드를 호출합니다.
사용자는 Logto 로그인 페이지로 리디렉션됩니다. 네이티브 앱의 경우, 시스템 브라우저가 열립니다.
사용자가 로그인하고 귀하의 앱으로 다시 리디렉션됩니다 (리디렉션 URI로 구성됨).

이 인증 과정은 OpenID Connect (OIDC) 프로토콜을 따르며, Logto는 사용자 로그인을 보호하기 위해 엄격한 보안 조치를 시행합니다.
여러 앱이 있는 경우, 동일한 아이덴티티 제공자 (Logto)를 사용할 수 있습니다. 사용자가 한 앱에 로그인하면, Logto는 사용자가 다른 앱에 접근할 때 자동으로 로그인 과정을 완료합니다.

리디렉션 기반 로그인에 대한 이론적 배경과 이점에 대해 더 알고 싶다면, Logto 로그인 경험 설명을 참조하세요.

노트:

다음 코드 스니펫에서는, 여러분의 앱이 http://localhost:3000/ 에서 실행되고 있다고 가정합니다.

리디렉션 URI 구성

Logto Console의 애플리케이션 세부 정보 페이지로 이동합니다. 리디렉션 URI http://localhost:3000/callback를 추가하세요.

로그인과 마찬가지로, 사용자는 공유 세션에서 로그아웃하기 위해 Logto로 리디렉션되어야 합니다. 완료되면 사용자를 다시 웹사이트로 리디렉션하면 좋습니다. 예를 들어, 로그아웃 후 리디렉션 URI 섹션에 http://localhost:3000/를 추가하세요.

그런 다음 "저장"을 클릭하여 변경 사항을 저장하세요.

애플리케이션 구성

다음 코드를 appsettings.json 파일에 추가하세요:

appsettings.json
{
// ...
IdentityServer: {
  Authority: 'https://<your-logto-endpoint>/oidc',
  ClientId: '<your-logto-app-id>',
  PostLogoutRedirectUri: 'http://localhost:3000/',
  RedirectUri: 'http://localhost:3000/callback',
  ResponseType: 'code',
  Scope: 'openid profile', // 필요에 따라 더 많은 스코프를 추가하세요
},
}

RedirectUri와 PostLogoutRedirectUri를 Logto 애플리케이션 설정의 허용된 리디렉션 URI 목록에 추가하는 것을 잊지 마세요. 이들은 모두 WASM 애플리케이션의 URL입니다.

`AuthorizeView` 컴포넌트 추가

인증이 필요한 Razor 페이지에 AuthorizeView 컴포넌트를 추가하세요. Home.razor 페이지라고 가정해 봅시다:

Pages/Home.razor
@using Microsoft.AspNetCore.Components.Authorization
@page "/"

<AuthorizeView>
    <Authorized>
        @* 로그인된 뷰 *@
        <button @onclick="OnLogoutButtonClickAsync">
            로그아웃
        </button>
    </Authorized>
    <NotAuthorized>
        @* 인증되지 않은 뷰 *@
        <button @onclick="OnLoginButtonClickAsync">
            로그인
        </button>
    </NotAuthorized>
</AuthorizeView>

인증 설정

Home.razor.cs 파일에 (존재하지 않으면 생성하세요) 다음 코드를 추가하세요:

Pages/Home.razor.cs
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Components;
using Microsoft.AspNetCore.Components.Web;
using Blorc.OpenIdConnect;
using Microsoft.AspNetCore.Components.Authorization;

[Authorize]
public partial class Home : ComponentBase
{
    [Inject]
    public required IUserManager UserManager { get; set; }

    public User<Profile>? User { get; set; }

    [CascadingParameter]
    protected Task<AuthenticationState>? AuthenticationStateTask { get; set; }

    protected override async Task OnInitializedAsync()
    {
        User = await UserManager.GetUserAsync<User<Profile>>(AuthenticationStateTask!);
    }

    private async Task OnLoginButtonClickAsync(MouseEventArgs obj)
    {
        await UserManager.SignInRedirectAsync();
    }

    private async Task OnLogoutButtonClickAsync(MouseEventArgs obj)
    {
        await UserManager.SignOutRedirectAsync();
    }
}

사용자가 인증되면, User 속성에 사용자 정보가 채워질 것입니다.

체크포인트: 애플리케이션 테스트하기

이제 애플리케이션을 테스트할 수 있습니다:

애플리케이션을 실행하면 로그인 버튼이 표시됩니다.
로그인 버튼을 클릭하면 SDK가 로그인 프로세스를 초기화하고 Logto 로그인 페이지로 리디렉션됩니다.
로그인 후, 애플리케이션으로 다시 리디렉션되어 로그아웃 버튼이 표시됩니다.
로그아웃 버튼을 클릭하여 토큰 저장소를 지우고 로그아웃합니다.

사용자 정보 가져오기

사용자 정보 표시

Home.razor 페이지에서 사용자 정보를 표시하는 몇 가지 예시입니다:

<AuthorizeView>
    <Authorized>
        @* 로그인된 뷰 *@
        @* ... *@
        <p>당신은 @(@User?.Profile?.Name ?? "(알 수 없는 이름)")으로 로그인되었습니다.</p>
    </Authorized>
    @* ... *@
</AuthorizeView>

더 많은 속성과 클레임에 대해서는 Blorc.OpenIdConnect 패키지의 User 및 Profile 클래스를 확인하세요.

추가 클레임 요청

User에서 반환된 객체에 일부 사용자 정보가 누락된 것을 발견할 수 있습니다. 이는 OAuth 2.0 및 OpenID Connect (OIDC)가 최소 권한 원칙 (PoLP)을 따르도록 설계되었기 때문이며, Logto는 이러한 표준을 기반으로 구축되었습니다.

기본적으로 제한된 클레임 (Claim)만 반환됩니다. 더 많은 정보를 원하시면, 추가적인 스코프 (Scope)를 요청하여 더 많은 클레임에 접근할 수 있습니다.

정보:

"클레임 (Claim)"은 주체에 대해 주장하는 내용이며, "스코프 (Scope)"는 클레임의 그룹입니다. 현재의 경우, 클레임은 사용자에 대한 정보입니다.

다음은 스코프 - 클레임 관계의 비규범적 예시입니다:

팁:

"sub" 클레임은 "주체"를 의미하며, 이는 사용자의 고유 식별자 (즉, 사용자 ID)입니다.

Logto SDK는 항상 세 가지 스코프를 요청합니다: openid, profile, 그리고 offline_access.

추가 스코프를 요청하려면, appsettings.json 파일의 IdentityServer.Scope 속성에 유효한 스코프를 추가할 수 있습니다.

{
  // ...
  "IdentityServer": {
    // ...
    "Scope": "openid profile email phone"
  }
}

네트워크 요청이 필요한 클레임

사용자 객체의 비대화를 방지하기 위해, 일부 클레임은 네트워크 요청을 통해 가져와야 합니다. 예를 들어, custom_data 클레임은 스코프에서 요청되더라도 사용자 객체에 포함되지 않습니다. 이러한 클레임을 가져오려면, appsettings.json 파일에서 IdentityServer.LoadUserInfo 속성을 true로 설정할 수 있습니다.

예를 들어, 사용자의 이메일 주소와 custom data를 가져오려면 다음 설정을 사용할 수 있습니다:

{
  // ...
  "IdentityServer": {
    // ...
    "Scope": "openid profile email custom_data",
    "LoadUserInfo": true
  }
}

스코프와 클레임

Logto는 OIDC 스코프 및 클레임 규약을 사용하여 ID 토큰 및 OIDC userinfo 엔드포인트에서 사용자 정보를 가져오기 위한 스코프와 클레임을 정의합니다. "스코프"와 "클레임"은 OAuth 2.0 및 OpenID Connect (OIDC) 사양의 용어입니다.

지원되는 스코프와 해당 클레임 (Claims) 목록은 다음과 같습니다:

openid

클레임 이름	유형	설명	사용자 정보 필요 여부
sub	`string`	사용자의 고유 식별자	아니요

profile

클레임 이름	유형	설명	사용자 정보 필요 여부
name	`string`	사용자의 전체 이름	아니요
username	`string`	사용자의 사용자 이름	아니요
picture	`string`	최종 사용자의 프로필 사진 URL. 이 URL은 이미지 파일 (예: PNG, JPEG, 또는 GIF 이미지 파일)을 참조해야 하며, 이미지를 포함하는 웹 페이지를 참조해서는 안 됩니다. 이 URL은 최종 사용자를 설명할 때 표시하기 적합한 프로필 사진을 구체적으로 참조해야 하며, 최종 사용자가 찍은 임의의 사진을 참조해서는 안 됩니다.	아니요
created_at	`number`	최종 사용자가 생성된 시간. 시간은 유닉스 에포크 (1970-01-01T00:00:00Z) 이후 밀리초 수로 표현됩니다.	아니요
updated_at	`number`	최종 사용자의 정보가 마지막으로 업데이트된 시간. 시간은 유닉스 에포크 (1970-01-01T00:00:00Z) 이후 밀리초 수로 표현됩니다.	아니요

다른 표준 클레임인 family_name, given_name, middle_name, nickname, preferred_username, profile, website, gender, birthdate, zoneinfo, 및 locale도 사용자 정보 엔드포인트를 요청할 필요 없이 profile 스코프에 포함됩니다. 위의 클레임과의 차이점은 이러한 클레임은 값이 비어 있지 않을 때만 반환되며, 위의 클레임은 값이 비어 있을 경우 null을 반환한다는 점입니다.

노트:

표준 클레임과 달리, created_at 및 updated_at 클레임은 초 대신 밀리초를 사용합니다.

email

클레임 이름	유형	설명	사용자 정보 필요 여부
email	`string`	사용자의 이메일 주소	아니요
email_verified	`boolean`	이메일 주소가 검증되었는지 여부	아니요

phone

클레임 이름	유형	설명	사용자 정보 필요 여부
phone_number	`string`	사용자의 전화번호	아니요
phone_number_verified	`boolean`	전화번호가 검증되었는지 여부	아니요

address

주소 클레임의 세부 사항은 OpenID Connect Core 1.0을 참조하세요.

custom_data

클레임 이름	유형	설명	사용자 정보 필요 여부
custom_data	`object`	사용자의 사용자 정의 데이터	예

identities

클레임 이름	유형	설명	사용자 정보 필요 여부
identities	`object`	사용자의 연결된 아이덴티티	예
sso_identities	`array`	사용자의 연결된 SSO 아이덴티티	예

roles

클레임 이름	유형	설명	사용자 정보 필요 여부
roles	`string[]`	사용자의 역할	아니요

urn:logto:scope:organizations

클레임 이름	유형	설명	사용자 정보 필요 여부
organizations	`string[]`	사용자가 속한 조직 ID	아니요
organization_data	`object[]`	사용자가 속한 조직 데이터	예

urn:logto:scope:organization_roles

클레임 이름	유형	설명	사용자 정보 필요 여부
organization_roles	`string[]`	사용자가 속한 조직 역할, 형식은 `<organization_id>:<role_name>`	아니요

성능과 데이터 크기를 고려할 때, "사용자 정보 필요 여부"가 "예"인 경우, 해당 클레임은 ID 토큰에 나타나지 않으며, userinfo 엔드포인트 응답에서 반환됩니다.

API 리소스

먼저 🔐 역할 기반 접근 제어 (RBAC)를 읽어 Logto RBAC의 기본 개념과 API 리소스를 적절히 설정하는 방법을 이해하는 것을 권장합니다.

기본적으로 User?.AccessToken에 접근하면 짧은 길이의 불투명 토큰 (불투명 토큰) 을 얻게 되며, 이는 JWT (JSON Web Token) 가 아닙니다. 이 토큰은 userinfo 엔드포인트에 접근하는 데 사용됩니다.

구성에 API 리소스 추가하기

Logto에 정의된 API 리소스에 접근할 수 있는 JWT 토큰을 얻으려면, appsettings.json 파일에 다음 매개변수를 추가하세요 (예시로 https://my-api-resource를 사용):

appsettings.json
{
  // ...
  "IdentityServer": {
    // ...
    "Scope": "openid profile email <your-api-scopes>", // 여기에 API 스코프를 추가하세요
    "Resource": "https://my-api-resource",
    "ExtraTokenParams": {
        "resource": "https://my-api-resource" // 키 "resource"가 소문자인지 확인하세요
    }
  }
}

Resource 속성은 인증 요청에 API 리소스를 추가하는 데 사용됩니다. ExtraTokenParams 속성은 토큰 요청에 API 리소스를 추가하는 데 사용됩니다. Logto는 API 리소스에 대해 RFC 8707을 준수하므로 두 속성이 모두 필요합니다.

주의:

WebAssembly는 클라이언트 측 애플리케이션이므로, 토큰 요청은 서버 측으로 한 번만 전송됩니다. 이러한 특성 때문에, LoadUserInfo는 API 리소스를 위한 액세스 토큰을 가져오는 것과 충돌합니다.

액세스 토큰 사용하기

사용자가 인증되면, User?.AccessToken 속성을 사용하여 API 리소스에 접근할 수 있습니다. 예를 들어, HttpClient를 사용하여 API 리소스에 접근할 수 있습니다:

using Blorc.OpenIdConnect;

builder.Services
    .AddHttpClient("MyApiResource", client =>
    {
        client.BaseAddress = new Uri("https://my-api-resource");
    })
    .AddAccessToken(); // 요청 헤더에 액세스 토큰을 추가하세요

추가 읽을거리

최종 사용자 흐름: 인증 흐름, 계정 흐름, 및 조직 흐름 커넥터 구성 API 보호

사전 준비 사항​

설치​

통합​

스크립트 참조 추가​

서비스 등록​

리디렉션 URI 구성​

리디렉션 기반 로그인에 관하여​

리디렉션 URI 구성​

애플리케이션 구성​

AuthorizeView 컴포넌트 추가​

인증 설정​

체크포인트: 애플리케이션 테스트하기​

사용자 정보 가져오기​

사용자 정보 표시​

추가 클레임 요청​

네트워크 요청이 필요한 클레임​

스코프와 클레임​

API 리소스​

구성에 API 리소스 추가하기​

액세스 토큰 사용하기​

추가 읽을거리​

사전 준비 사항

설치

통합

스크립트 참조 추가

서비스 등록

리디렉션 URI 구성

리디렉션 기반 로그인에 관하여

리디렉션 URI 구성

애플리케이션 구성

`AuthorizeView` 컴포넌트 추가

인증 설정

체크포인트: 애플리케이션 테스트하기

사용자 정보 가져오기

사용자 정보 표시

추가 클레임 요청

네트워크 요청이 필요한 클레임

스코프와 클레임

API 리소스

구성에 API 리소스 추가하기

액세스 토큰 사용하기

추가 읽을거리