리디렉션 URI(회신 URL) 개요 및 제한 사항
사용자를 로그인하려면 앱이 매개 변수로 지정된 리디렉션 URI를 사용하여 Microsoft Entra 권한 부여 엔드포인트에 로그인 요청을 보내야 합니다. 리디렉션 URI는 권한 부여 코드 및 액세스 토큰이 의도한 수신자에게만 전송되도록 하는 중요한 보안 기능입니다. 이 문서에서는 Microsoft ID 플랫폼의 리디렉션 URI 기능 및 제한 사항에 대해 간략하게 설명합니다.
리디렉션 URI란?
리디렉션 URI 또는 회신 URL은 사용자가 성공적으로 권한을 부여하고 인증 코드 또는 액세스 토큰이 부여되면 Microsoft Entra 권한 부여 서버가 사용자를 보내는 위치입니다. 사용자를 로그인하려면 애플리케이션이 매개 변수로 지정된 리디렉션 URI를 사용하여 로그인 요청을 보내야 하므로, 사용자가 성공적으로 로그인한 후 인증 서버는 사용자를 리디렉션하고 로그인 요청에 지정된 리디렉션 URI로 액세스 토큰을 발급합니다.
앱 등록에 리디렉션 URI를 추가해야 하는 이유는 무엇인가요?
보안상의 이유로 권한 부여 서버는 사용자를 리디렉션하거나 앱 등록에 추가되지 않은 URI에 토큰을 보내지 않습니다. Microsoft Entra 로그인 서버는 사용자를 리디렉션하고 토큰을 보내 앱 등록에 추가된 URI를 리디렉션합니다. 로그인 요청에 지정된 리디렉션 URI가 애플리케이션에서 추가한 리디렉션 URI와 일치하지 않으면 AADSTS50011: The reply URL specified in the request does not match the reply URLs configured for the application과 같은 오류 메시지가 표시됩니다.
오류 코드에 대한 자세한 내용은 Microsoft Entra 인증 및 권한 부여 오류 코드를 참조하세요.
앱 등록에 리디렉션 URI를 추가해야 하나요?
앱 등록에 리디렉션 URI를 추가해야 하는지 여부는 애플리케이션에서 사용하는 권한 부여 프로토콜에 따라 달라집니다. 애플리케이션에서 다음 권한 부여 프로토콜을 사용하는 경우 앱 등록에 적절한 리디렉션 URI를 추가해야 합니다.
- OAuth 2.0 인증 코드 흐름
- OAuth 2.0 클라이언트 자격 증명 흐름
- OAuth 2.0 암시적 허용 흐름
- OpenID Connect
- Single Sign-On SAML 프로토콜
애플리케이션이 다음 권한 부여 프로토콜 또는 기능을 사용하는 경우 앱 등록에 리디렉션 URI를 추가할 필요가 없습니다.
- 기본 인증
- OAuth 2.0 디바이스 코드 흐름
- OAuth 2.0 On-Behalf-Of 흐름
- OAuth 2.0 리소스 소유자 암호 자격 증명 부여
- Windows 통합 인증 흐름
- Single Sign-On을 위한 SAML 2.0 IdP(ID 공급자)
리디렉션 URI를 어떤 플랫폼에 추가해야 하나요?
빌드하는 애플리케이션에 앱 등록에 하나 이상의 리디렉션 URI가 포함된 경우 공용 클라이언트 흐름 구성을 사용하도록 설정해야 합니다. 다음 표에서는 애플리케이션을 빌드하는 플랫폼에 따라 추가해야 하거나 추가해서는 안 되는 리디렉션 URI 유형에 대한 지침을 제공합니다.
웹 애플리케이션 리디렉션 URI 구성
| 애플리케이션 유형 | 일반적인 언어/프레임워크 | 앱 등록에서 리디렉션 URI를 추가하는 플랫폼 |
|---|---|---|
| 대부분의 애플리케이션 논리가 서버에서 수행되는 기존 웹 애플리케이션 | Node.js, 웹, ASP.NET, Python, Java, ASP.NET Core, PHP, Ruby, Blazor Server | 웹 |
| 주로 웹 API를 사용하여 웹 서버와 통신하는 웹 브라우저에서 대부분의 사용자 인터페이스 논리가 수행되는 단일 페이지 애플리케이션 | JavaScript, Angular, React, Blazor WebAssembly, Vue.js | SPA(단일 페이지 애플리케이션) |
모바일 및 데스크톱 애플리케이션 리디렉션 URI 구성
| 애플리케이션 유형 | 일반적인 언어/프레임워크 | 앱 등록에서 리디렉션 URI를 추가하는 플랫폼 |
|---|---|---|
| 이 표 아래에 나열된 시나리오를 제외한 iOS 또는 macOS 앱 | Swift, Objective-C, Xamarin | IOS/macOS |
| Android 앱 | Java, Kotlin, Xamarin | Android |
| 모바일 디바이스 또는 데스크톱 머신에서 기본적으로 실행되는 앱 | Node.js electron, Windows 데스크톱, UWP, React Native, Xamarin, Android, iOS/macOS | 모바일 및 데스크톱 애플리케이션 |
다음 방법 중 하나를 사용하여 iOS 앱을 빌드하는 경우 모바일 및 데스크톱 애플리케이션 플랫폼을 사용하여 리디렉션 URI를 추가하세요.
- ADAL(레거시 SDK)을 사용하는 iOS 앱
- 오픈 소스 SDK를 사용하는 iOS 앱(AppAuth)
- 지원하지 않는 cross-plat 기술을 사용하는 iOS 앱(Flutter)
- OAuth 프로토콜을 직접 구현하는 iOS 앱
- 지원하지 않는 cross-plat 기술을 사용하는 macOS 앱(Electron)
리디렉션 URI가 필요하지 않은 애플리케이션
| 애플리케이션 유형 | 예제/참고 항목 | 연결된 OAuth 흐름 |
|---|---|---|
| 키보드가 없는 디바이스에서 실행되는 애플리케이션 | 스마트 TV, IoT 디바이스 또는 프린터에서 실행되는 애플리케이션 | 디바이스 코드 흐름 자세히 알아보기 |
| 암호를 처리하는 애플리케이션은 사용자를 Entra 호스팅 로그인 웹 사이트로 리디렉션하고 Entra가 안전한 방식으로 사용자 암호를 처리하도록 하는 대신 직접 입력합니다. | 권한 부여 코드 흐름과 같은 다른 보안 흐름이 안전하지 않기 때문에 실행 가능하지 않은 경우에만 이 흐름을 사용해야 합니다. | 리소스 소유자 암호 자격 증명 흐름 자세히 알아보기 |
| 웹 계정 관리자 대신 Windows 통합 인증 흐름을 사용하여 Windows 또는 Windows 도메인에 연결된 컴퓨터(AD 또는 Azure AD 조인)에서 실행되는 데스크톱 또는 모바일 애플리케이션 | 사용자가 Entra 자격 증명을 사용하여 Windows PC 시스템에 로그인한 후 자동으로 로그인되어야 하는 데스크톱 또는 모바일 애플리케이션 | Windows 통합 인증 흐름 자세히 알아보기 |
Microsoft Entra 애플리케이션에 대한 리디렉션 URI의 제한 사항은 무엇인가요?
Microsoft Entra 애플리케이션 모델은 URI를 리디렉션하기 위해 다음과 같은 제한 사항을 지정합니다.
리디렉션 URI는 일부 localhost 리디렉션 URI에 대한 예외를 제외하고
https스키마로 시작해야 합니다.리디렉션 URI는 대/소문자를 구분하며 실행 중인 애플리케이션의 URL 경로 대/소문자와 일치해야 합니다.
예:
- 애플리케이션이 경로
.../abc/response-oidc의 일부로 포함하는 경우 리디렉션 URI에.../ABC/response-oidc를 지정하지 마세요. 웹 브라우저는 경로를 대/소문자 구분하여 처리하므로.../abc/response-oidc와 연결된 쿠키는 대/소문자가 일치하지 않는.../ABC/response-oidcURL로 리디렉션되는 경우 제외될 수 있습니다.
- 애플리케이션이 경로
패스 세그먼트로 구성되지 않은 리디렉션 URI는 응답에서 후행 슬래시('
/')와 함께 반환됩니다. 이는 응답 모드가query또는fragment인 경우만 해당합니다.예:
https://contoso.com이https://contoso.com/으로 반환됨http://localhost:7071이http://localhost:7071/으로 반환됨
패스 세그먼트가 포함된 리디렉션 URI의 경우, 응답에 후행 슬래시가 포함되지 않습니다.
예:
https://contoso.com/abc이https://contoso.com/abc으로 반환됨https://contoso.com/abc/response-oidc이https://contoso.com/abc/response-oidc으로 반환됨
리디렉션 URI는 특수 문자를 지원하지 않음 -
! $ ' ( ) , ;리디렉션 URI는 다국어 도메인 이름을 지원하지 않음
리디렉션 URI의 최대 수 및 URI 길이
보안상의 이유로 리디렉션 URI의 최대 수는 늘릴 수 없습니다. 시나리오에 허용된 최대 제한보다 많은 리디렉션 URI가 필요한 경우 다음 상태 매개 변수 방법을 솔루션으로 고려합니다. 다음 표에서는 Microsoft ID 플랫폼에서 앱 등록에 추가할 수 있는 리디렉션 URI의 최대 개수를 보여줍니다.
| 로그인한 계정 | 최대 리디렉션 URI 수 | 설명 |
|---|---|---|
| 모든 조직의 Microsoft Entra 테넌트의 Microsoft 회사 또는 학교 계정 | 256 | 애플리케이션 매니페스트의 signInAudience 필드가 AzureADMyOrg 또는 AzureADMultipleOrgs로 설정됨 |
| 개인 Microsoft 계정 및 회사/학교 계정 | 100 | 애플리케이션 매니페스트의 signInAudience 필드가 AzureADandPersonalMicrosoftAccount로 설정됨 |
앱 등록에 추가하는 각 리디렉션 URI에 대해 최대 256문자를 사용할 수 있습니다.
애플리케이션 및 서비스 주체 개체의 리디렉션 URI
- 항상 애플리케이션 개체에만 리디렉션 URI를 추가합니다.
- 서비스 주체 개체가 애플리케이션 개체와 동기화될 때 이러한 값을 제거할 수 있으므로 서비스 주체에 리디렉션 URI 값을 절대 추가하지 마세요. 이는 두 개체 간의 동기화를 트리거하는 업데이트 작업으로 인해 발생할 수 있습니다.
리디렉션 URI의 쿼리 매개 변수 지원
쿼리 매개 변수는 회사 또는 학교 계정으로 사용자만 로그인하는 애플리케이션에 대한 리디렉션 URI에서 허용됩니다.
쿼리 매개 변수는 Outlook.com(Hotmail), Messenger, OneDrive, MSN, Xbox Live 또는 Microsoft 365와 같은 개인 Microsoft 계정으로 사용자를 로그인시키도록 구성된 앱 등록에 대한 리디렉션 URI에서 허용되지 않습니다.
| 앱 등록 로그인 대상 그룹 | 리디렉션 URI에서 쿼리 매개 변수 지원 |
|---|---|
| 이 조직 디렉터리의 계정만 해당(Contoso 전용 - 단일 테넌트) | 
|
| 모든 조직 디렉터리의 계정(모든 Microsoft Entra 디렉터리 - 다중 테넌트) |
|
| 모든 조직 디렉터리(모든 Microsoft Entra 디렉터리 - 다중 테넌트)의 계정 및 개인 Microsoft 계정(예: Skype 및 Xbox) | 
|
| 개인 Microsoft 계정만 |
|
지원되는 스키마
HTTPS: HTTPS 스키마(https://)는 모든 HTTP 기반 리디렉션 URI에 대해 지원됩니다.
HTTP: HTTP 스키마(http://)는 localhost URI에 대해서만 지원되며, 활성 로컬 애플리케이션 개발 및 테스트 도중에만 사용해야 합니다.
| 리디렉션 URI 예 | 유효성 |
|---|---|
https://contoso.com |
유효 |
https://contoso.com/abc/response-oidc |
유효 |
https://localhost |
유효 |
http://contoso.com/abc/response-oidc |
유효하지 않음 |
http://localhost |
유효 |
http://localhost/abc |
유효 |
Localhost 예외
RFC 8252 섹션 8.3 및 7.3에 대하여, "루프백" 또는 "localhost" 리디렉션 URI는 다음과 같은 두 가지 특별 고려 사항과 함께 제공됩니다.
http리디렉션이 디바이스를 벗어날 수 없기 때문에 URI 스키마가 허용됩니다. 따라서 다음 두 URI를 모두 사용할 수 있습니다.http://localhost/myApphttps://localhost/myApp
- 종종 기본 애플리케이션에서 요구하는 임시 포트 범위 때문에 포트 구성 요소(예:
:5001또는:443)는 리디렉션 URI 일치를 위해 무시됩니다. 따라서 이러한 모든 URI는 동일하게 간주됩니다.http://localhost/MyApphttp://localhost:1234/MyApphttp://localhost:5000/MyApphttp://localhost:8080/MyApp
개발 관점에서 이는 다음과 같은 몇 가지를 의미합니다.
포트가 서로 다른 경우에는 여러 리디렉션 URI를 등록해서는 안 됩니다. 로그인 서버는 항목을 임의로 선택하고 해당 리디렉션 URI와 연결된 동작을 사용합니다(예:
web-,native- 또는spa- 형식 리디렉션 중 하나).이는 인증 코드 부여 및 암시적 흐름과 같이 동일한 애플리케이션 등록에서 다른 인증 흐름을 사용하려는 경우에 특히 중요합니다. 올바른 응답 동작을 각 리디렉션 URI와 연결하려면 로그인 서버에서 리디렉션 URI를 구분할 수 있어야 하며, 포트가 서로 다른 경우에는 이 작업을 수행할 수 없습니다.
Localhost에 여러 리디렉션 URI를 등록하여 개발 중에 다른 흐름을 테스트하려면 URI의 경로 구성 요소를 사용하여 이를 구분합니다. 예를 들어
http://localhost/MyWebApp은http://localhost/MyNativeApp과 같지 않습니다.IPv6 루프백 주소(
[::1])는 현재 지원되지 않습니다.
localhost를 통한 127.0.0.1 선호
잘못 구성된 방화벽 또는 이름이 바뀐 네트워크 인터페이스에 의해 앱이 중단되지 않도록 하려면, localhost 대신 리디렉션 URI에서 IP 리터럴 루프백 주소 127.0.0.1을 사용합니다. 예들 들어 https://127.0.0.1입니다.
그러나 Azure Portal에서 리디렉션 URI 텍스트 상자를 사용하여 http 스키마를 사용하는 루프백 기반 리디렉션 URI를 추가할 수는 없습니다.
127.0.0.1 루프백 주소를 사용하여 http 스키마를 사용하는 리디렉션 URI를 추가하려면 현재 애플리케이션 매니페스트에서 replyUrlsWithType 특성을 수정해야 합니다.
리디렉션 URI의 와일드카드에 대한 제한 사항
https://*.contoso.com과 같은 와일드카드 URI는 편리하게 보일 수 있지만, 보안의 영향을 받을 수 있으므로 피해야 합니다. OAuth 2.0 사양(RFC 6749의 섹션 3.1.2)에 따라 리디렉션 엔드포인트 URI는 절대 URI여야 합니다. 마찬가지로 구성된 와일드카드 URI가 리디렉션 URI와 일치하면 리디렉션 URI의 쿼리 문자열 및 조각이 제거됩니다.
와일드카드 URI는 현재 개인 Microsoft 계정과 회사 또는 학교 계정에 로그인하도록 구성된 앱 등록에서 지원되지 않습니다. 그러나 조직의 Microsoft Entra 테넌트에서 회사 또는 학교 계정에만 로그인하도록 구성된 앱에는 와일드카드 URI를 사용할 수 있습니다.
와일드카드를 사용하는 리디렉션 URI를 회사 또는 학교 계정에 로그인하는 앱 등록에 추가하려면 Azure Portal에서 앱 등록의 애플리케이션 매니페스트 편집기를 사용합니다. 매니페스트 편집기를 사용하여 와일드카드로 리디렉션 URI를 설정할 수 있지만, RFC 6749의 3.1.2 섹션을 준수하도록 강력하게 권장합니다. 또한 절대 URI만 사용하는 것이 좋습니다.
시나리오에 허용되는 최대 제한보다 많은 리디렉션 URI가 필요한 경우 와일드카드 리디렉션 URI를 추가하는 대신 다음 상태 매개 변수 방법을 고려합니다.
상태 매개 변수 사용
여러 하위 도메인을 사용하는 경우 그리고 인증이 성공하면 사용자를 인증이 시작된 동일한 페이지로 리디렉션해야 하는 시나리오에서는 상태 매개 변수를 사용하는 것이 도움이 될 수 있습니다.
이 방법의 경우 다음을 수행합니다.
- 애플리케이션당 "공유" 리디렉션 URI를 만들어 권한 부여 엔드포인트에서 수신하는 보안 토큰을 처리합니다.
- 애플리케이션은 관련 매개 변수에서 애플리케이션 특정 매개 변수(예: 사용자가 시작한 하위 도메인 URL 또는 브랜딩 정보와 같은 항목)를 보낼 수 있습니다. 상태 매개 변수를 사용하는 경우 RFC 6749의 섹션 10.12에 지정된 대로 CSRF 보호를 제공합니다.
- 애플리케이션 관련 매개 변수에는 애플리케이션이 사용자에 대한 올바른 환경을 렌더링하는 데 필요한, 즉 적절한 애플리케이션 상태를 생성하는 데 필요한 모든 정보가 포함됩니다. Microsoft Entra 권한 부여 엔드포인트는 상태 매개 변수에서 HTML을 제거하므로 이 매개 변수에 HTML 콘텐츠를 전달하지 않아야 합니다.
- Microsoft Entra ID가 "공유" 리디렉션 URI에 대한 응답을 보내면 이 URI가 상태 매개 변수를 다시 애플리케이션으로 보냅니다.
- 그런 다음, 애플리케이션은 상태 매개 변수의 값을 사용하여 사용자를 추가로 보낼 URL을 결정할 수 있습니다. CSRF 보호의 유효성을 검사해야 합니다.
경고
이 접근 방식에서는 손상된 클라이언트가 상태 매개 변수에 전송된 추가 매개 변수를 수정하여 사용자를 다른 URL로 리디렉션할 수 있습니다. 이것이 RFC 6819에 설명된 개방형 리디렉터 위협입니다. 따라서 클라이언트는 상태를 암호화하거나 토큰에 대해 리디렉션 URI의 도메인 이름을 확인하는 등의 다른 방법으로 상태를 확인하여 이러한 매개 변수를 보호해야 합니다.
다음 단계
앱 등록 애플리케이션 매니페스트에 대해 알아봅니다.