영업: 1-800-867-1380

Graph API를 사용하여 Azure AD 쿼리

업데이트 날짜: 2014년 5월

note참고
참고: 이 예제는 오래된 버전입니다. 기술, 방법 및/또는 사용자 인터페이스가 새로운 기능으로 대체되었습니다. 유사한 응용 프로그램을 빌드하는 업데이트된 예제를 보려면 WebApp-GraphAPI-DotNet을 참조하십시오.

이 예제 응용 프로그램은 Windows Azure AD(Active Directory)용으로 새 응용 프로그램을 빌드하고 기존 응용 프로그램에 기능을 추가하려는 .NET 개발자를 위한 것입니다. 이 연습은 Windows Azure AD 고객용으로 웹 Single Sign-On 사용자 환경을 제공하는 방법을 보여 주는 예제 응용 프로그램을 생성하는 Azure AD를 사용하여 웹 응용 프로그램에 로그온 기능 추가를 기반으로 하여 작성되었습니다. 이 연습에서는 Windows Azure AD Graph API를 사용하여 디렉터리 데이터를 읽는 방법을 보여 줍니다. Graph API는 응용 프로그램이 고객 Windows Azure 디렉터리 데이터에 액세스하도록 허용하는 RESTful API입니다.

응용 프로그램은 다음을 비롯한 여러 시나리오에서 디렉터리 데이터에 액세스할 수 있어야 합니다.

  • 사용자/그룹 선택을 위해 사용자, 그룹, 연락처 목록 검색

  • 자세한 테넌트, 사용자 및 그룹 정보 읽기

  • 그룹 구성원 자격 확인

  • 사용자, 그룹 및 그룹 구성원 자격 수정

  • 사용자 암호 업데이트

  • 사용자 계정을 사용하지 않도록 설정

note참고
다중 테넌트 응용 프로그램에서 최근 응용 프로그램의 액세스에 동의한 Azure AD 테넌트용 Graph API에 액세스할 수 있는 토큰을 획득하려고 하면 ACS50012 오류로 인해 토큰 요청이 실패할 수 있습니다. 이 문제를 해결하려면 잠시 기다린 후 다시 시도하십시오. 또는 동의를 제공한 테넌트 관리자가 동의한 후 응용 프로그램에 로그인하도록 지정하십시오. 자세한 내용은 ACS 오류 코드를 참조하십시오.

이 문서는 다음 섹션으로 구성되어 있습니다.

이 자습서의 작업을 완료하려면 다음 필수 구성 요소가 필요합니다.

이 연습을 완료하면 Azure AD 테넌트에서 데이터를 읽도록 구성된 응용 프로그램이 완성됩니다. 이 응용 프로그램은 사용자, 그룹, 연락처, 회사 정보, 라이선스 및 역할 디렉터리 엔터티에서 데이터를 읽을 수 있으며 응용 프로그램에 쓰기 권한이 부여된 경우에는 엔터티를 업데이트할 수도 있습니다.

이 예제 응용 프로그램에서는 Azure AD 회사의 디렉터리 데이터를 읽는 방법을 검토합니다. 추가로 제공되는 고급 항목은 다음과 같습니다.

  • 전체 사용자 세부 정보 가져오기

  • 사용자 만들기 및 업데이트

  • 그룹 목록 가져오기

  • 그룹 구성원 자격 업데이트

이 응용 프로그램을 업데이트한 후에도 Graph API에 액세스할 수 있도록 Single Sign-On 환경은 그대로 유지됩니다. 사용자 인증이 정상적으로 완료되면 응용 프로그램은 Azure AD 인증 끝점에서 토큰을 요청하며 요청이 성공하면 응용 프로그램은 Graph API 호출에서 해당 토큰을 사용하여 테넌트의 모든 사용자를 가져옵니다. 응용 프로그램은 사용자의 Display NamesUser Principal Names을 보여 주는 사용자 목록을 표시합니다.

솔루션 아키텍처

이 연습에서는 OAuth 2.0 클라이언트 자격 증명 흐름을 사용하여 응용 프로그램을 인증합니다. Graph API 끝점에 액세스하기 전에 응용 프로그램은 먼저 Azure AD의 인증 끝점에서 유효한 토큰을 획득해야 하며, 이를 위해 유효한 응용 프로그램 자격 증명(클라이언트 ID 및 암호)을 제시합니다. 자격 증명의 유효성 검사에 성공하면 서명된 토큰이 응용 프로그램에 반환됩니다. 그리고 나면 응용 프로그램은 Graph API 호출의 권한 부여 헤더에 토큰을 포함합니다. Graph API 서비스는 들어오는 요청에 대해 토큰 유효성을 검사합니다. 유효성 검사에 통과하면 다음으로 권한 부여 확인을 수행합니다.

Graph API 및 기본 RBAC(역할 기반 액세스 제어) 서비스가 응용 프로그램 권한 부여를 확인합니다. Graph API 호출은 응용 프로그램의 사용 권한에 의해 제한됩니다. 인증과 권한 부여에 모두 통과하면 데이터가 응용 프로그램에 반환됩니다.

응용 프로그램의 인증 및 권한 부여 구성은 테넌트 디렉터리에 저장된 Service Principal 개체를 사용하여 Azure AD에 저장됩니다. 응용 프로그램은 고유한 ID, 자격 증명 및 사용 권한을 포함하는 Service Principal 개체에 의해 Azure AD에 표시됩니다. 이 개체는 각각 고유한 ID, 자격 증명 및 사용 권한을 소유한 사용자를 표시하는 Active Directory의 User Principal 개체와 비슷합니다.

응용 프로그램의 Service Principal에는 인증에 사용되는 고유한 ID와 암호가 있습니다. 필요한 사용 권한이 있는 역할에 응용 프로그램의 서비스 사용자를 추가하여 권한 부여를 관리합니다. 테넌트 관리자는 Azure AD 관리 포털에서 응용 프로그램 서비스 사용자를 만들어 역할에 추가할 수 있으며 필요한 경우에는 Windows PowerShell을 통해 서비스 사용자를 관리할 수도 있습니다. 자세한 내용은 Windows PowerShell을 사용하여 Azure AD 관리를 참조하십시오.

Azure AD를 사용하여 웹 응용 프로그램에 로그온 기능 추가 연습에서는 Azure AD 관리 포털에서 응용 프로그램 사용 권한을 구성하여 Azure AD 사용자 자격 증명을 사용한 Single Sign-On을 허용하도록 응용 프로그램에 권한을 부여했습니다. 이제 Expense Reporting 응용 프로그램이 Graph API에 인증을 하고 Graph API 호출 권한을 가지도록 응용 프로그램 구성을 업데이트합니다. 이를 위해 다음 단계를 수행합니다.

  • 권한 부여: 디렉터리에 대한 읽기/쓰기 권한을 허용하도록 응용 프로그램 사용 권한을 구성합니다.

  • 인증: 응용 프로그램 키(응용 프로그램 암호)를 가져옵니다. 키는 Graph API에 응용 프로그램을 인증하는 데 사용됩니다.

  1. Microsoft Azure 관리 포털(https://manage.WindowsAzure.com)로 이동하여 로그인한 다음 Active Directory를 클릭합니다. (문제 해결 팁: "Active Directory" 항목이 없거나 사용할 수 없음)

  2. 디렉터리를 클릭하여 선택하고 응용 프로그램을 클릭한 다음 Single Sign-On 연습에서 만든 Expense Reporting 예제 응용 프로그램을 클릭합니다.



    외부 액세스

  3. 페이지 아래쪽에서 액세스 관리를 클릭합니다.

  4. 이 응용 프로그램의 디렉터리 액세스 권한 변경을 선택합니다.



    원하는 옵션을 선택하십시오.
  5. Single Sign-on, 디렉터리 데이터 읽기를 선택합니다. 그런 다음 확인 표시를 클릭하여 변경 내용을 저장합니다.



    디렉터리 액세스

  1. Expense Reporting 응용 프로그램 페이지에서 응용 프로그램이 디렉터리 데이터를 읽거나 쓰도록 설정을 확장합니다. 키 만들기 섹션에서 키 구성을 선택합니다.



    키 구성

  2. 키를 추가하려면 구성 페이지의 섹션에서 키의 수명(기본값은 1년)을 선택하고 화면 아래쪽의 저장을 클릭합니다. 그러면 키 값(응용 프로그램 암호)이 생성됩니다.

    Warning경고
    키 값은 키를 만들고 나면 표시되지만 나중에 검색할 수는 없습니다. 따라서 키 값을 즉시 복사해 나중에 참조할 수 있도록 안전한 곳에 저장해 두어야 합니다. 또한 테스트 및 프로덕션용으로 키를 하나 이상 사용하는 등 응용 프로그램에는 키가 여러 개 있을 수 있습니다.



    그래프 키

이제 클라이언트 ID(응용 프로그램 ID)와 응용 프로그램 키(키 값)를 만들었으며 응용 프로그램에 대해 읽기 권한을 구성했습니다.

note참고
이 연습의 예제 응용 프로그램에서는 키 값을 암호로 사용하여 응용 프로그램을 인증합니다. OAuth 2.0 용어로는 이러한 인증을 클라이언트 자격 증명 부여 흐름이라고 합니다(grant_type=client_credentials).

Visual Studio를 열고 이전에 작성한 Single Sign-On 연습 프로젝트인 "Expense Reporting"을 엽니다. 다음 단계를 통해 Single Sign-On 연습 응용 프로그램을 수정할 것입니다.

  1. Graph Helper 클래스 프로젝트 추가

  2. WCF Data Services 5.3 이상으로 업데이트

  3. Web.config 파일 업데이트

  4. HomeController 수정

  5. 사용자용 새 뷰 추가

  6. 공통 _Layout 뷰 업데이트

Azure AD Graph API Helper 라이브러리를 다운로드합니다. Graph Helper 클래스 프로젝트에는 Graph API에 대한 인증 및 호출을 쉽게 수행할 수 있도록 하는 라이브러리와 클래스가 포함되어 있습니다. 또한 이 연습의 일부분으로 포함하고 작성해야 하는 소스 코드도 포함되어 있습니다.

  1. Expense Reporting 프로젝트에 Graph Helper를 추가하려면 솔루션 'ExpenseReport' 솔루션을 마우스 오른쪽 단추로 클릭하고 추가, 기존 프로젝트를 차례로 클릭합니다.

  2. 기존 프로젝트 추가 대화 상자에서 Graph Helper 경로로 이동한 다음 Microsoft.WindowsAzure.ActiveDirectory.GraphHelper.csproj 프로젝트 파일을 엽니다.

Graph Helper 프로젝트가 ExpenseReport 솔루션에 추가되었습니다.

Web.config 파일의 appSettings 섹션에는 응용 프로그램별 구성 정보가 있습니다. ClientIdPassword 키-값 쌍을 응용 프로그램의 Web.config 파일에 추가합니다.

  • ClientId: Azure AD 관리 포털 응용 프로그램 관리 페이지의 클라이언트 ID 값과 같습니다.

  • Password: Azure AD 관리 포털 응용 프로그램 관리 페이지의 응용 프로그램 키 값과 같습니다. 이 값은 검색할 수 없으므로 키를 만드는 이전 단계에서 이 값을 기록해 두었어야 합니다. 이전 키를 잊어버렸거나 분실한 경우에는 같은 응용 프로그램에서 다른 키를 만드십시오.

<appSettings>
    <add key="ClientId" value="<insert your ClientId here>"/>
    <add key="Password" value="<insert your Application Key here>"/>
    ...

변경을 마친 후 Web.config 파일을 저장합니다.

  1. Visual Studio에서 Expense Reporting 프로젝트 참조 폴더를 마우스 오른쪽 단추로 클릭하고 참조 추가...를 클릭합니다.

  2. 참조 관리자 대화 상자에서 확장을 클릭하고 Microsoft.Data.OData 버전 5.3.0.0 어셈블리 및 Microsoft.Data.Services.Client 버전 5.3.0.0 어셈블리를 선택합니다.



    OData 참조
  3. 같은 참조 관리자 대화 상자에서 왼쪽의 솔루션 메뉴를 확장하고 Microsoft.WindowsAzure.ActiveDirectory.GraphHelper의 확인란을 클릭합니다. 확인을 누르면 참조가 프로젝트에 추가됩니다.



    그래프 도우미 참조 추가

컨트롤러 폴더에 있는 HomeController.cs 파일을 엽니다. 파일에 다음 어셈블리를 추가하고 파일을 저장합니다.

using System.Configuration;
using System.Security.Claims;
using System.Data.Services.Client;
using Microsoft.WindowsAzure.ActiveDirectory;
using Microsoft.WindowsAzure.ActiveDirectory.GraphHelper;

HomeController.cs 파일에서 기존 ActionResults(Index, About, Contact)가 있는 HomeController 클래스를 찾습니다. 아래와 같이 Users라는 새 ActionResult를 추가합니다.

       public ActionResult Users()
       {
            //get the tenantName
            string tenantName = ClaimsPrincipal.Current.FindFirst("http://schemas.microsoft.com/identity/claims/tenantid").Value;



            // retrieve the clientId and password values from the Web.config file
            string clientId = ConfigurationManager.AppSettings["ClientId"];
            string password = ConfigurationManager.AppSettings["Password"];



            // get a token using the helper
            AADJWTToken token = DirectoryDataServiceAuthorizationHelper.GetAuthorizationToken(tenantName, clientId, password);

            // initialize a graphService instance using the token acquired from previous step
            DirectoryDataService graphService = new DirectoryDataService(tenantName, token);

            //  get Users
            //
            var users = graphService.users;
            QueryOperationResponse<User> response;
            response = users.Execute() as QueryOperationResponse<User>;
            List<User> userList = response.ToList();
            ViewBag.userList = userList;


            //  For subsequent Graph Calls, the existing token should be used.
            //  The following checks to see if the existing token is expired or about to expire in 2 mins
            //  if true, then get a new token and refresh the graphService
            //
            int tokenMins = 2;
            if (token.IsExpired || token.WillExpireIn(tokenMins))
            {
                AADJWTToken newToken = DirectoryDataServiceAuthorizationHelper.GetAuthorizationToken(tenantName, clientId, password);
                token = newToken;
                graphService = new DirectoryDataService(tenantName, token);
            }

            //  get tenant information
            //
            var tenant = graphService.tenantDetails;
            QueryOperationResponse<TenantDetail> responseTenantQuery;
            responseTenantQuery = tenant.Execute() as QueryOperationResponse<TenantDetail>;
            List<TenantDetail> tenantInfo = responseTenantQuery.ToList();
            ViewBag.OtherMessage = "User List from tenant: " + tenantInfo[0].displayName;


            return View(userList);
       }

뷰/홈 폴더 아래에 Users.cshtml라는 새 뷰를 만들고 다음 코드를 추가합니다.

@model IEnumerable<Microsoft.WindowsAzure.ActiveDirectory.User> 
@{
    ViewBag.Title = "Users";
}

<h1>@ViewBag.Message</h1>
<h2>@ViewBag.OtherMessage</h2>
<table>
    <tr>
        <th>
            DisplayName
        </th>
        <th>
            UPN
        </th>
        <th></th>
    </tr>

@if (User.Identity.IsAuthenticated)
{

  foreach (var user in Model) {
    <tr>
        <td>
         @Html.DisplayFor(modelItem => user.displayName)    
        </td>
        <td>
         @Html.DisplayFor(modelItem => user.userPrincipalName)
        </td>
   </tr>
  }
}
</table>

뷰/공유 폴더에서 _Layout.cshtml 파일을 엽니다. 파일의 <header> 섹션에 있는 <nav> 요소에 새 목록 항목을 "<li>@Html.ActionLink("Users", "Users", "Home")</li>"과 같이 추가하고 파일을 저장합니다.

               <nav>
                        <ul id="menu">
                            <li>@Html.ActionLink("Home", "Index", "Home")</li>
                            <li>@Html.ActionLink("About", "About", "Home")</li>
                            <li>@Html.ActionLink("Contact", "Contact", "Home")</li>
                            <li>@Html.ActionLink("Users", "Users", "Home")</li>
                        </ul>
                    </nav>

응용 프로그램을 실행하려면 F5 키를 누릅니다. 메시지가 표시되면 Azure AD 디렉터리의 사용자(디렉터리 도메인에 조직 계정이 있는 사용자) 자격 증명을 사용하여 로그인합니다.

이전 연습에서 확인했던 것과 마찬가지로 Single Sign-On 환경에서는 Azure AD 자격 증명을 사용하여 로그인해야 합니다. 응용 프로그램을 웹 사이트에 게시한 경우에는 이 연습의 업데이트를 통해 업데이트해야 합니다. 사용자가 인증되고 나면 오른쪽 위 메뉴에서 사용자 탭을 선택합니다.

사용자 표시

응용 프로그램이 먼저 Azure AD 인증 끝점에서 토큰을 요청하여 Graph API 호출 프로세스를 시작합니다. 요청이 성공하면 응용 프로그램은 후속 Graph 호출에서 해당 토큰을 사용하여 테넌트의 모든 사용자를 가져옵니다. 그런 다음 사용자의 Display NamesUser Principal Names을 보여 주는 사용자 목록을 표시합니다.

이것으로 Graph API 연습 응용 프로그램용 코딩이 완료되었습니다. 다음 섹션에는 추가적인 읽기 및 쓰기 작업을 보여 주는 고급 Graph API 예제 응용 프로그램에 대한 링크 및 자세한 내용이 나와 있습니다.

Single Sign-On이 정상적으로 완료되면 응용 프로그램은 인증을 위한 테넌트 이름(로그온된 사용자의 테넌트 ID 클레임에서 가져옴), 클라이언트 ID 및 암호를 사용하여 Azure AD 권한 부여 끝점에서 토큰을 요청합니다. 토큰 획득을 지원하는 메서드의 세부 정보는 DirectoryDataServiceAuthorizationHelper 클래스(같은 이름의 파일에 있음)에서 확인할 수 있습니다. GetAuthorization 메서드는 유효한 테넌트 이름(테넌트 소유의 확인된 도메인), 클라이언트 ID 및 암호를 제공하여 Azure AD 인증에서 JWT(JSON 웹 토큰)를 획득하는 과정을 관리합니다.

요청이 성공하면 Graph API 호출에 사용할 JWT 토큰이 반환되어 후속 요청의 권한 부여 헤더에 삽입됩니다. 모든 사용자를 가져오기 위한 Graph API 호출은 다음 헤더를 포함하는 HTTP GET 요청입니다.

Content-Type: application/json; odata=minimalmetadata
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1T….

후속 요청을 위해 응용 프로그램에서 JWT 토큰을 캐시하는 것이 좋습니다. 예제 응용 프로그램에서는 두 번째 Graph API 호출을 수행하기 전에 JWT 토큰 만료를 확인합니다. 토큰이 만료된 경우에는 새 토큰을 가져옵니다. 만료된 토큰을 사용하여 Graph API를 호출하면 다음 오류 응답이 반환되며 클라이언트는 새 토큰을 요청해야 합니다.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="contoso.com", error="invalid_token", error_description="Your access token has expired. Please renew it before submitting the request.", 

note참고
현재는 Azure AD 인증 토큰 획득을 관리하는 AAL(Azure 인증 라이브러리) 미리 보기가 제공되고 있습니다. AAL이 출시되면 AAL을 사용하도록 예제 응용 프로그램과 설명서를 업데이트할 예정입니다. AAL 미리 보기의 설명서는 여기서 확인할 수 있습니다.

읽기 및 쓰기 메서드를 비롯한 추가 REST 호출 기능은 여기서 다운로드 가능한 다른 MVC4 예제 응용 프로그램에서 확인할 수 있습니다.

이 예제에서는 다음을 포함한 추가 REST 기능을 보여 줍니다.

  • 사용자 세부 정보 가져오기/설정(미리 보기 사진 포함)

  • 그룹 만들기/업데이트

  • 그룹 구성원 자격 업데이트

  • 많은 수의 반환된 개체를 처리하는 페이징

이 정보가 도움이 되었습니까?
(1500자 남음)
의견을 주셔서 감사합니다.

커뮤니티 추가 항목

표시:
© 2014 Microsoft