Expo (React Native) 애플리케이션에 인증 (Authentication)을 추가하세요
- 다음 데모는 Expo ~50.0.6을 기반으로 구축되었습니다.
- 샘플 프로젝트는 우리의 SDK 저장소에서 확인할 수 있습니다.
사전 준비 사항
- Logto Cloud 계정 또는 셀프 호스팅 Logto.
- Logto 네이티브 애플리케이션 생성.
설치
Logto SDK와 피어 의존성을 선호하는 패키지 관리자를 통해 설치하세요:
- npm
- Yarn
- pnpm
npm i @logto/rn
npm i expo-crypto expo-secure-store expo-web-browser @react-native-async-storage/async-storage
yarn add @logto/rn
yarn add expo-crypto expo-secure-store expo-web-browser @react-native-async-storage/async-storage
pnpm add @logto/rn
pnpm add expo-crypto expo-secure-store expo-web-browser @react-native-async-storage/async-storage
@logto/rn
패키지는 Logto의 SDK입니다. 나머지 패키지들은 피어 의존성입니다. Expo CLI는 네이티브 모듈에 대한 모든 의존성이 루트 프로젝트의 package.json
에 직접 설치되어야 하기 때문에 직접 의존성으로 나열될 수 없습니다.
베어 React Native 앱에 설치하는 경우, 이 추가 설치 지침도 따라야 합니다.
통합
Logto provider 초기화
LogtoProvider
를 가져와 Logto 컨텍스트를 제공합니다:
import { LogtoProvider, LogtoConfig } from '@logto/rn';
const config: LogtoConfig = {
endpoint: '<your-logto-endpoint>',
appId: '<your-application-id>',
};
const App = () => (
<LogtoProvider config={config}>
<YourAppContent />
</LogtoProvider>
);
로그인 및 로그아웃 구현
세부 사항을 살펴보기 전에, 최종 사용자 경험에 대한 간단한 개요를 소개합니다. 로그인 과정은 다음과 같이 간소화될 수 있습니다:
- 귀하의 앱이 로그인 메서드를 호출합니다.
- 사용자는 Logto 로그인 페이지로 리디렉션됩니다. 네이티브 앱의 경우, 시스템 브라우저가 열립니다.
- 사용자가 로그인하고 귀하의 앱으로 다시 리디렉션됩니다 (리디렉션 URI로 구성됨).
리디렉션 기반 로그인에 관하여
- 이 인증 과정은 OpenID Connect (OIDC) 프로토콜을 따르며, Logto는 사용자 로그인을 보호하기 위해 엄격한 보안 조치를 시행합니다.
- 여러 앱이 있는 경우, 동일한 아이덴티티 제공자 (Logto)를 사용할 수 있습니다. 사용자가 한 앱에 로그인하면, Logto는 사용자가 다른 앱에 접근할 때 자동으로 로그인 과정을 완료합니다.
리디렉션 기반 로그인에 대한 이론적 배경과 이점에 대해 더 알고 싶다면, Logto 로그인 경험 설명을 참조하세요.
Logto Console의 애플리케이션 세부 정보 페이지로 이동합니다. 네이티브 리디렉트 URI (예: io.logto://callback
)를 추가한 후 "저장"을 클릭하세요.
-
iOS의 경우,
ASWebAuthenticationSession
클래스가 리디렉트 URI를 등록 여부와 상관없이 수신하므로 리디렉트 URI 스킴은 실제로 중요하지 않습니다. -
Android의 경우, 리디렉트 URI 스킴은 Expo의
app.json
파일에 입력되어야 합니다. 예를 들어:app.json{
"expo": {
"scheme": "io.logto"
}
}
이제 앱으로 돌아가서, useLogto
훅을 사용하여 로그인 및 로그아웃을 할 수 있습니다:
import { useLogto } from '@logto/rn';
import { Button } from 'react-native';
const Content = () => {
const { signIn, signOut, isAuthenticated } = useLogto();
return (
<div>
{isAuthenticated ? (
<Button title="Sign out" onPress={async () => signOut()} />
) : (
// 리디렉트 URI를 자신의 것으로 교체하세요
<Button title="Sign in" onPress={async () => signIn('io.logto://callback')} />
)}
</div>
);
};
체크포인트: 애플리케이션 테스트하기
이제 애플리케이션을 테스트할 수 있습니다:
- 애플리케이션을 실행하면 로그인 버튼이 표시됩니다.
- 로그인 버튼을 클릭하면 SDK가 로그인 프로세스를 초기화하고 Logto 로그인 페이지로 리디렉션됩니다.
- 로그인 후, 애플리케이션으로 다시 리디렉션되어 로그아웃 버튼이 표시됩니다.
- 로그아웃 버튼을 클릭하여 토큰 저장소를 지우고 로그아웃합니다.
사용자 정보 가져오기
사용자 정보 표시
사용자의 정보를 표시하려면 getIdTokenClaims()
메서드를 사용할 수 있습니다:
import { useLogto } from '@logto/rn';
import { Button, Text } from 'react-native';
const Content = () => {
const { getIdTokenClaims, isAuthenticated } = useLogto();
const [user, setUser] = useState(null);
useEffect(() => {
if (isAuthenticated) {
getIdTokenClaims().then((claims) => {
setUser(claims);
});
}
}, [isAuthenticated]);
return (
<div>
{isAuthenticated ? (
<>
<Text>{user?.name}</Text>
<Text>{user?.email}</Text>
<Button title="Sign out" onPress={async () => signOut()} />
</>
) : (
<Button title="Sign in" onPress={async () => signIn('io.logto://callback')} />
)}
</div>
);
};
추가 클레임 요청
getIdTokenClaims()
에서 반환된 객체에 일부 사용자 정보가 누락된 것을 발견할 수 있습니다.
이는 OAuth 2.0 및 OpenID Connect (OIDC)가 최소 권한 원칙 (PoLP)을 따르도록 설계되었기 때문이며,
Logto는 이러한 표준을 기반으로 구축되었습니다.
기본적으로 제한된 클레임 (Claim)만 반환됩니다. 더 많은 정보를 원하시면, 추가적인 스코프 (Scope)를 요청하여 더 많은 클레임에 접근할 수 있습니다.
"클레임 (Claim)"은 주체에 대해 주장하는 내용이며, "스코프 (Scope)"는 클레임의 그룹입니다. 현재의 경우, 클레임은 사용자에 대한 정보입니다.
다음은 스코프 - 클레임 관계의 비규범적 예시입니다:
"sub" 클레임은 "주체"를 의미하며, 이는 사용자의 고유 식별자 (즉, 사용자 ID)입니다.
Logto SDK는 항상 세 가지 스코프를 요청합니다: openid
, profile
, 그리고 offline_access
.
추가 스코프를 요청하려면, 스코프를 LogtoConfig
객체에 전달할 수 있습니다:
import { LogtoProvider, LogtoConfig, UserScope } from '@logto/rn';
const config: LogtoConfig = {
appId: '<your-application-id>',
endpoint: '<your-logto-endpoint>',
scopes: [
UserScope.Email,
UserScope.Phone,
UserScope.CustomData,
UserScope.Identities,
UserScope.Organizations,
],
};
const App = () => <LogtoProvider config={config}>{/* Your app content */}</LogtoProvider>;
네트워크 요청이 필요한 클레임
ID 토큰의 비대화를 방지하기 위해, 일부 클레임은 네트워크 요청을 통해 가져와야 합니다. 예를 들어, custom_data
클레임은 스코프에서 요청되더라도 사용자 객체에 포함되지 않습니다. 이러한 클레임에 접근하려면, fetchUserInfo()
메서드를 사용할 수 있습니다:
import { useLogto } from '@logto/rn';
import { Button, Text } from 'react-native';
const Content = () => {
const { fetchUserInfo, isAuthenticated } = useLogto();
const [user, setUser] = useState(null);
useEffect(() => {
if (isAuthenticated) {
fetchUserInfo().then((userInfo) => {
setUser(userInfo);
});
}
}, [isAuthenticated]);
return (
<div>
{isAuthenticated ? (
<>
<Text>{user?.name}</Text>
<Text>{user?.email}</Text>
<Button title="Sign out" onPress={async () => signOut()} />
</>
) : (
<Button title="Sign in" onPress={async () => signIn('io.logto://callback')} />
)}
</div>
);
};
스코프와 클레임
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
클레임 이름 | 유형 | 설명 | 사용자 정보 필요 여부 |
---|---|---|---|
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 리소스를 적절히 설정하는 방법을 이해하는 것을 권장합니다.
Logto 클라이언트 구성하기
API 리소스를 설정한 후, 애플리케이션에서 Logto를 구성할 때 이를 추가할 수 있습니다:
import { LogtoConfig } from '@logto/rn';
const config: LogtoConfig = {
appId: '<your-application-id>',
endpoint: '<your-logto-endpoint>',
// API 리소스를 추가하세요
resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
};
각 API 리소스는 자체 권한 (스코프)을 가지고 있습니다.
예를 들어, https://shopping.your-app.com/api
리소스는 shopping:read
및 shopping:write
권한을 가지고 있으며, https://store.your-app.com/api
리소스는 store:read
및 store:write
권한을 가지고 있습니다.
이러한 권한을 요청하려면, 애플리케이션에서 Logto를 구성할 때 추가할 수 있습니다:
import { LogtoConfig } from '@logto/rn';
const config: LogtoConfig = {
appId: '<your-application-id>',
endpoint: '<your-logto-endpoint>',
scopes: ['shopping:read', 'shopping:write', 'store:read', 'store:write'],
resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
};
스코프가 API 리소스와 별도로 정의된 것을 알 수 있습니다. 이는 OAuth 2.0을 위한 리소스 지표가 요청의 최종 스코프가 모든 대상 서비스의 모든 스코프의 데카르트 곱이 될 것이라고 명시하기 때문입니다.
따라서 위의 경우, Logto에서 정의된 스코프를 단순화할 수 있으며, 두 API 리소스 모두 접두사 없이 read
및 write
스코프를 가질 수 있습니다. 그런 다음, Logto 구성에서:
import { LogtoConfig } from '@logto/rn';
const config: LogtoConfig = {
appId: '<your-application-id>',
endpoint: '<your-logto-endpoint>',
scopes: ['read', 'write'],
resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
};
모든 API 리소스에 대해 read
및 write
스코프를 요청하게 됩니다.
API 리소스에 정의되지 않은 스코프를 요청해도 괜찮습니다. 예를 들어, API 리소스에 email
스코프가 없더라도 email
스코프를 요청할 수 있습니다. 사용 불가능한 스코프는 안전하게 무시됩니다.
성공적으로 로그인한 후, Logto는 사용자의 역할에 따라 API 리소스에 적절한 스코프를 발급합니다.
API 리소스를 위한 액세스 토큰 가져오기
특정 API 리소스에 대한 액세스 토큰을 가져오려면 getAccessToken
메서드를 사용할 수 있습니다:
import { useLogto } from '@logto/rn';
const AccessToken = () => {
const { isAuthenticated, getAccessToken } = useLogto();
const [accessToken, setAccessToken] = useState('');
useEffect(() => {
(async () => {
if (isAuthenticated) {
const token = await getAccessToken('https://shopping.your-app.com/api');
setAccessToken(token);
}
})();
}, [isAuthenticated, getAccessToken]);
return <p>{{ accessToken }}</p>;
};
이 메서드는 사용자가 관련 권한을 가지고 있을 때 API 리소스에 접근할 수 있는 JWT 액세스 토큰을 반환합니다. 현재 캐시된 액세스 토큰이 만료된 경우, 이 메서드는 자동으로 리프레시 토큰을 사용하여 새로운 액세스 토큰을 얻으려고 시도합니다.
사용자를 위한 조직 토큰 가져오기
조직이 처음이라면, 시작하기 위해 🏢 조직 (다중 테넌시)을 읽어보세요.
Logto 클라이언트를 구성할 때 UserScope.Organizations
스코프를 추가해야 합니다:
import { LogtoConfig, UserScope } from '@logto/rn';
const config: LogtoConfig = {
// ...other configs
scopes: [UserScope.Organizations],
};
사용자가 로그인하면, 사용자에 대한 조직 토큰을 가져올 수 있습니다:
import { useLogto } from '@logto/rn';
import { useEffect, useState } from 'react';
const Organizations = () => {
const { isAuthenticated, getOrganizationToken, getIdTokenClaims } = useLogto();
const [organizationIds, setOrganizationIds] = useState<string[]>();
useEffect(() => {
(async () => {
if (!isAuthenticated) {
return;
}
const claims = await getIdTokenClaims();
console.log('ID token claims', claims);
setOrganizationIds(claims?.organizations);
})();
}, [isAuthenticated, getIdTokenClaims]);
return (
<section>
<ul>
{organizationIds?.map((organizationId) => {
return (
<li key={organizationId}>
<span>{organizationId}</span>
<button
type="button"
onClick={async () => {
console.log('raw token', await getOrganizationToken(organizationId));
}}
>
fetch token (see console)
</button>
</li>
);
})}
</ul>
</section>
);
};
export default Organizations;
문제 해결
@logto/client/shim
을 해결할 수 없음
- SDK 버전 <= v0.3.0을 사용하는 사용자는 아래 지침을 따라 문제를 해결하세요.
- SDK 버전 >= v0.4.0을 사용하는 사용자는 이 섹션을 무시하세요. 이 문제는 최신 버전에서 수정되었습니다.
Expo 프로젝트에서 node_modules/@logto/rn/lib/index.js
에서 Unable to resolve "@logto/client/shim"
오류가 발생하면, metro.config.js
파일에 다음을 추가하여 해결할 수 있습니다:
const config = {
// ...
resolver: {
unstable_enablePackageExports: true,
},
};
module.exports = config;
이 오류는 @logto/rn
패키지가 @logto/client/shim
모듈을 해결할 수 없음을 나타냅니다.
@logto/client
패키지에서 노드 내보내기가 사용되었고, Metro 번들러에서 패키지 내보내기가 기본적으로 활성화되지 않으므로 수동으로 활성화해야 합니다.
자세한 내용은 React Native 패키지 내보내기 지원을 참조하세요.