Microsoft ID 플랫폼 UserInfo 엔드포인트

아티클
12/19/2023

OIDC(OpenID Connect) 표준의 일부인 UserInfo 엔드포인트는 인증된 사용자에 대한 정보를 반환합니다.

잘 알려진 구성 엔드포인트 찾기

https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration에서 OpenID 구성 문서의 userinfo_endpoint 필드를 읽어 프로그래밍 방식으로 UserInfo 엔드포인트를 찾을 수 있습니다. 애플리케이션에서 UserInfo 엔드포인트를 하드 코딩하지 않는 것이 좋습니다. 대신 OIDC 구성 문서를 사용하여 런타임에 엔드포인트를 찾습니다.

UserInfo 엔드포인트는 일반적으로 사용자에 대한 정보를 얻기 위해 OIDC 규격 라이브러리에서 자동으로 호출됩니다. OIDC 표준에서 확인된 클레임 목록에서 Microsoft ID 플랫폼은 사용 가능하고 동의할 경우 이름 클레임, 제목 클레임 및 이메일을 생성합니다.

ID 토큰을 대신 사용하도록 고려

ID 토큰의 정보는 UserInfo 엔드포인트에서 사용할 수 있는 정보의 상위 집합입니다. UserInfo 엔드포인트를 호출하는 토큰을 가져오는 동시에 ID 토큰도 가져올 수 있으므로 UserInfo 엔드포인트를 호출하는 대신 토큰에서 사용자 정보를 가져오는 것이 좋습니다. UserInfo 엔드포인트를 호출하는 대신 ID 토큰을 사용하면 최대 두 개의 네트워크 요청이 제거되어 애플리케이션의 대기 시간이 줄어듭니다.

관리자나 직위와 같은 사용자에 대한 자세한 정보가 필요한 경우 Microsoft Graph /user API를 호출합니다. 선택적 클레임을 사용하여 ID 및 액세스 토큰에 추가 사용자 정보를 포함할 수도 있습니다.

UserInfo 엔드포인트 호출

UserInfo는 Microsoft Graph에서 호스트하는 표준 OAuth 전달자 토큰 API입니다. Microsoft Graph에 대한 액세스를 요청하는 경우 애플리케이션에서 받은 액세스 토큰을 사용하여 Microsoft Graph API에서와 마찬가지로 UserInfo 엔드포인트를 호출합니다. UserInfo 엔드포인트는 사용자에 대한 클레임이 포함된 JSON 응답을 반환합니다.

사용 권한

다음 OIDC 사용 권한을 사용하여 UserInfo API를 호출합니다. openid 클레임은 필수이며 profile 및 email 범위는 추가 정보가 응답에 제공되도록 합니다.

권한 유형	사용 권한
위임됨(회사 또는 학교 계정)	`openid`(필수), `profile`, `email`
위임됨 (개인 Microsoft 계정)	`openid`(필수), `profile`, `email`
애플리케이션	해당 없음

팁

브라우저에서 이 URL을 복사하여 UserInfo 엔드포인트에 대한 액세스 토큰과 ID 토큰을 가져옵니다. 클라이언트 ID 및 리디렉션 URI를 앱 등록의 값으로 바꿉니다.

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=<yourClientID>&response_type=token+id_token&redirect_uri=<YourRedirectUri>&scope=user.read+openid+profile+email&response_mode=fragment&state=12345&nonce=678910

다음 섹션의 쿼리에서 반환되는 액세스 토큰을 사용할 수 있습니다.

Microsoft Graph는 앱의 읽기 또는 유효성 검사 기능에 영향을 줄 수 있는 특수 토큰 발급 패턴을 사용합니다. 다른 Microsoft Graph 토큰과 마찬가지로 여기서 받는 토큰은 JWT가 아닐 수 있으며 앱은 이를 불투명한 것으로 간주합니다. Microsoft 계정 사용자가 로그인한 경우 암호화된 토큰 형식이 됩니다. 그러나 이러한 요소는 모두 UserInfo 엔드포인트에 대한 요청에서 액세스 토큰을 사용하는 앱의 기능에 영향을 주지 않습니다.

API 호출

UserInfo API는 GET 및 POST 요청을 모두 지원합니다.

GET or POST /oidc/userinfo HTTP/1.1
Host: graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJub25jZSI6Il…

UserInfo 응답

{
    "sub": "OLu859SGc2Sr9ZsqbkG-QbeLgJlb41KcdiPoLYNpSFA",
    "name": "Mikah Ollenburg", // all names require the “profile” scope.
    "family_name": " Ollenburg",
    "given_name": "Mikah",
    "picture": "https://graph.microsoft.com/v1.0/me/photo/$value",
    "email": "mikoll@contoso.com" // requires the “email” scope.
}

응답에 표시된 클레임은 UserInfo 엔드포인트에서 반환할 수 있는 모든 클레임입니다. 이러한 값은 ID 토큰에 포함된 것과 동일한 값입니다.

UserInfo 엔드포인트에 대한 참고 사항 및 제한 사항

UserInfo 엔드포인트에서 반환된 정보는 추가하거나 사용자 지정할 수 없습니다.

인증 및 권한 부여 중에 ID 플랫폼에서 반환되는 정보를 사용자 지정하려면 클레임 매핑 및 선택적 클레임을 사용하여 보안 토큰 구성을 수정합니다.

다음 단계

ID 토큰의 콘텐츠를 검토합니다.
선택적 클레임을 사용하여 ID 토큰의 콘텐츠를 사용자 지정합니다.
OAuth2 프로토콜을 사용하여 액세스 토큰 및 ID 토큰을 요청합니다.

다음을 통해 공유