Azure AD kullanarak kimlik doğrulaması ve Openıd ConnectAuthenticate using Azure AD and OpenID Connect

GitHub Örnek kodGitHub Sample code

Surveys uygulaması, Azure Active Directory (Azure AD) ile kullanıcıların kimliğini doğrulamak için Openıd Connect (OIDC) protokolünü kullanır.The Surveys application uses the OpenID Connect (OIDC) protocol to authenticate users with Azure Active Directory (Azure AD). OIDC için yerleşik ara yazılım olan ASP.NET Core Surveys uygulamasını kullanır.The Surveys application uses ASP.NET Core, which has built-in middleware for OIDC. Aşağıdaki diyagramda, yüksek düzeyde kullanıcı oturum açtığında ne olacağını gösterir.The following diagram shows what happens when the user signs in, at a high level.

Kimlik doğrulama akışı

  1. Kullanıcı uygulamadaki "Oturum Aç" düğmesine tıklar.The user clicks the "sign in" button in the app. Bu eylem, bir MVC denetleyicisi tarafından yönetilir.This action is handled by an MVC controller.
  2. MVC denetleyicisi döndürür bir ChallengeResult eylem.The MVC controller returns a ChallengeResult action.
  3. Ara yazılım karşılar ChallengeResult ve kullanıcının Azure AD oturum açma sayfasına yeniden yönlendiren bir 302 yanıt oluşturur.The middleware intercepts the ChallengeResult and creates a 302 response, which redirects the user to the Azure AD sign-in page.
  4. Kullanıcı Azure AD ile kimlik doğrulaması yapar.The user authenticates with Azure AD.
  5. Azure AD kimlik belirteci uygulamaya gönderir.Azure AD sends an ID token to the application.
  6. Ara yazılım kimlik belirteci doğrular.The middleware validates the ID token. Bu noktada, kullanıcının artık içindeki uygulama kimliği.At this point, the user is now authenticated inside the application.
  7. Ara yazılım, kullanıcının uygulamaya geri yönlendirir.The middleware redirects the user back to application.

Uygulamayı Azure AD'ye kaydetmeRegister the app with Azure AD

Openıd Connect etkinleştirmek için kendi Azure AD kiracısı içindeki uygulama SaaS sağlayıcısı kaydeder.To enable OpenID Connect, the SaaS provider registers the application inside their own Azure AD tenant.

Uygulamayı kaydetmek için adımları izleyin. uygulamaları Azure Active Directory ile tümleştirme, bölümünde bir uygulama eklendiğinde.To register the application, follow the steps in Integrating Applications with Azure Active Directory, in the section Adding an Application.

Bkz: Surveys uygulamasını çalıştırma Surveys uygulamasını için belirli adımlar için.See Run the Surveys application for the specific steps for the Surveys application. Şunlara dikkat edin:Note the following:

  • Çok kiracılı bir uygulama için çok kiracılı seçenek açıkça yapılandırmanız gerekir.For a multitenant application, you must configure the multi-tenanted option explicitly. Bu uygulamaya erişmek için diğer kuruluşlara sağlar.This enables other organizations to to access the application.

  • Yanıt URL'si, Azure AD OAuth 2.0 yanıtlarını burada gönderir URL'dir.The reply URL is the URL where Azure AD will send OAuth 2.0 responses. ASP.NET Core kullanırken, bu yolun içinde kimlik doğrulaması ara yazılımını yapılandırma ile eşleşmesi gerekir (sonraki bölüme bakın).When using the ASP.NET Core, this needs to match the path that you configure in the authentication middleware (see next section).

Kimlik doğrulama ara yazılımını yapılandırmaConfigure the auth middleware

Bu bölümde, Openıd Connect ile çok kiracılı kimlik doğrulaması için ASP.NET Core kimlik doğrulaması ara yazılımını yapılandırma açıklanmaktadır.This section describes how to configure the authentication middleware in ASP.NET Core for multitenant authentication with OpenID Connect.

İçinde başlangıç sınıfı, Openıd Connect ara yazılımını ekleyin:In your startup class, add the OpenID Connect middleware:

app.UseOpenIdConnectAuthentication(new OpenIdConnectOptions {
    ClientId = configOptions.AzureAd.ClientId,
    ClientSecret = configOptions.AzureAd.ClientSecret, // for code flow
    Authority = Constants.AuthEndpointPrefix,
    ResponseType = OpenIdConnectResponseType.CodeIdToken,
    PostLogoutRedirectUri = configOptions.AzureAd.PostLogoutRedirectUri,
    SignInScheme = CookieAuthenticationDefaults.AuthenticationScheme,
    TokenValidationParameters = new TokenValidationParameters { ValidateIssuer = false },
    Events = new SurveyAuthenticationEvents(configOptions.AzureAd, loggerFactory),
});

Bazı ayarlar çalışma zamanı yapılandırma seçeneğinden alınır dikkat edin.Notice that some of the settings are taken from runtime configuration options. Ara yazılım seçenekleri anlamları şu şekildedir:Here's what the middleware options mean:

  • ClientID.ClientId. Uygulamanın Azure AD'de uygulama kaydedildiğinde, aldığınız istemci kimliği.The application's client ID, which you got when you registered the application in Azure AD.
  • Yetkilisi.Authority. Çok kiracılı bir uygulama için bu ayarı https://login.microsoftonline.com/common/.For a multitenant application, set this to https://login.microsoftonline.com/common/. Kullanıcıların oturum açmak için herhangi bir Azure AD kiracısı sağlayan Azure AD genel uç nokta URL'si, budur.This is the URL for the Azure AD common endpoint, which enables users from any Azure AD tenant to sign in. Ortak uç nokta hakkında daha fazla bilgi için bkz: bu blog gönderisini.For more information about the common endpoint, see this blog post.
  • İçinde tokenvalidationparameters değeriniayarlayın ValidateIssuer false.In TokenValidationParameters, set ValidateIssuer to false. Uygulama Kimliği belirteçteki veren değerini doğrulamak için sorumlu olacağını anlamına gelir.That means the app will be responsible for validating the issuer value in the ID token. (Bir ara yazılım hala belirteci doğrular.) Verici doğrulama hakkında daha fazla bilgi için bkz. veren doğrulama.(The middleware still validates the token itself.) For more information about validating the issuer, see Issuer validation.
  • PostLogoutRedirectUri.PostLogoutRedirectUri. Kullanıcı oturumu kapattıktan sonra yeniden yönlendirmek için bir URL belirtin. Bu anonim isteklere izin veren bir sayfa olmalıdır — genellikle giriş sayfası.Specify a URL to redirect users after the sign out. This should be a page that allows anonymous requests — typically the home page.
  • SignInScheme.SignInScheme. Bu ayar CookieAuthenticationDefaults.AuthenticationScheme.Set this to CookieAuthenticationDefaults.AuthenticationScheme. Bu ayar, kullanıcının kimliği doğrulandıktan sonra kullanıcı talepleri yerel olarak bir tanımlama bilgisinde depolandığı anlamına gelir.This setting means that after the user is authenticated, the user claims are stored locally in a cookie. Bu tanımlama bilgisi, kullanıcı tarayıcı oturumu sırasında günlüğe kaydedilmiş kalır nasıl ' dir.This cookie is how the user stays logged in during the browser session.
  • olaylar.Events. Olay çağırmaları bkz: kimlik doğrulama olaylarını.Event callbacks; see Authentication events.

Ayrıca tanımlama bilgisi kimlik doğrulaması ara yazılım ardışık düzene ekler.Also add the Cookie Authentication middleware to the pipeline. Bu ara yazılım, bir tanımlama bilgisi için kullanıcı taleplerini yazıyor ve ardından sonraki sayfa yüklemeleri sırasında tanımlama bilgisi okuma sorumludur.This middleware is responsible for writing the user claims to a cookie, and then reading the cookie during subsequent page loads.

app.UseCookieAuthentication(new CookieAuthenticationOptions {
    AutomaticAuthenticate = true,
    AutomaticChallenge = true,
    AccessDeniedPath = "/Home/Forbidden",
    CookieSecure = CookieSecurePolicy.Always,

    // The default setting for cookie expiration is 14 days. SlidingExpiration is set to true by default
    ExpireTimeSpan = TimeSpan.FromHours(1),
    SlidingExpiration = true
});

Kimlik doğrulaması akışı başlatmaInitiate the authentication flow

ASP.NET MVC'de kimlik doğrulaması akışı başlatmak için dönüş bir ChallengeResult contoller'nden:To start the authentication flow in ASP.NET MVC, return a ChallengeResult from the contoller:

[AllowAnonymous]
public IActionResult SignIn()
{
    return new ChallengeResult(
        OpenIdConnectDefaults.AuthenticationScheme,
        new AuthenticationProperties
        {
            IsPersistent = true,
            RedirectUri = Url.Action("SignInCallback", "Account")
        });
}

Bu ara yazılım kimlik doğrulaması uç noktaya yönlendiren 302 (bulunamadı) yanıt döndürmesine olanak sağlar.This causes the middleware to return a 302 (Found) response that redirects to the authentication endpoint.

Kullanıcı oturum açma oturumlarıUser login sessions

Kullanıcının ilk oturum açtığı zaman belirtildiği gibi tanımlama bilgisi kimlik doğrulaması ara yazılım bir tanımlama bilgisi için kullanıcı taleplerini yazar.As mentioned, when the user first signs in, the Cookie Authentication middleware writes the user claims to a cookie. Bundan sonra HTTP istekleri tanımlama bilgisi okuyarak doğrulanır.After that, HTTP requests are authenticated by reading the cookie.

Varsayılan olarak, tanımlama bilgisi Ara Yazar bir oturum tanımlama bilgisinin, tarayıcıyı kapattığında hangi alır, sonra kullanıcı silindi.By default, the cookie middleware writes a session cookie, which gets deleted once the user closes the browser. Kullanıcı, sonraki siteyi ziyaret başlatıldığında bunlar yeniden oturum açın gerekecektir.The next time the user next visits the site, they will have to sign in again. Ancak ayarlarsanız IsPersistent true olarak ChallengeResult, tarayıcı kapatıldıktan sonra kullanıcı, oturum açmış uyumlu şekilde ilerlemesi için kalıcı bir tanımlama bilgisi ara yazılım yazar.However, if you set IsPersistent to true in the ChallengeResult, the middleware writes a persistent cookie, so the user stays logged in after closing the browser. Tanımlama bilgisi süre sonunu yapılandırabilirsiniz; bkz: tanımlama bilgisi seçeneklerini denetleme.You can configure the cookie expiration; see Controlling cookie options. Kalıcı tanımlama bilgileri, kullanıcı için daha kullanışlı, ancak her zaman içinde oturum açmasını istediğiniz bazı uygulamalar (örneğin, bankacılık uygulama) için uygun olabilir.Persistent cookies are more convenient for the user, but may be inappropriate for some applications (say, a banking application) where you want the user to sign in every time.

Openıd Connect ara yazılım hakkındaAbout the OpenID Connect middleware

Openıd Connect ara yazılımını ASP.NET çoğu protokol ayrıntılarını gizler.The OpenID Connect middleware in ASP.NET hides most of the protocol details. Bu bölüm, Protokolü akışını anlamak için yararlı olabilecek uygulanmasıyla ilgili bazı notlar içerir.This section contains some notes about the implementation, that may be useful for understanding the protocol flow.

İlk olarak, ASP.NET (uygulama ve Azure AD arasında OIDC Protokolü akışın ayrıntıları yoksayar) açısından kimlik doğrulaması akışı inceleyelim.First, let's examine the authentication flow in terms of ASP.NET (ignoring the details of the OIDC protocol flow between the app and Azure AD). Aşağıdaki diyagramda işlemi gösterilmektedir.The following diagram shows the process.

Oturum açma akışı

Bu diyagramda iki MVC denetleyicisi vardır.In this diagram, there are two MVC controllers. Hesap Denetleyicisi oturum açma isteklerini işler ve giriş denetleyicisine giriş sayfası sunar.The Account controller handles sign-in requests, and the Home controller serves up the home page.

Kimlik doğrulama işlemi aşağıdaki verilmiştir:Here is the authentication process:

  1. Kullanıcı "Oturum açma" düğmesine tıklar ve tarayıcı bir GET isteği gönderir.The user clicks the "Sign in" button, and the browser sends a GET request. Örneğin: GET /Account/SignIn/.For example: GET /Account/SignIn/.
  2. Hesap denetleyicisi döndürür bir ChallengeResult.The account controller returns a ChallengeResult.
  3. OIDC ara yazılımı için Azure AD yeniden yönlendirme, bir tarayıcıya HTTP 302 yanıtı döndürür.The OIDC middleware returns an HTTP 302 response, redirecting to Azure AD.
  4. Tarayıcı için Azure AD kimlik doğrulama isteği gönderir.The browser sends the authentication request to Azure AD
  5. Kullanıcı oturum açtığında Azure AD'ye ve Azure AD kimlik doğrulama yanıtı geri gönderir.The user signs in to Azure AD, and Azure AD sends back an authentication response.
  6. OIDC ara yazılım talep sorumlusu oluşturur ve tanımlama bilgisi kimlik doğrulaması Ara yazılımıyla geçirir.The OIDC middleware creates a claims principal and passes it to the Cookie Authentication middleware.
  7. Tanımlama bilgisi Ara talep sorumlusu serileştirir ve bir tanımlama bilgisi ayarlar.The cookie middleware serializes the claims principal and sets a cookie.
  8. OIDC ara yazılım, uygulamanın geri çağırma URL'si için yönlendirir.The OIDC middleware redirects to the application's callback URL.
  9. Tarayıcı tanımlama bilgisi istek gönderirken bir yeniden yönlendirme izler.The browser follows the redirect, sending the cookie in the request.
  10. Tanımlama bilgisi Ara tanımlama bilgisi için bir talep sorumlusu seri durumdan çıkarır ve ayarlar HttpContext.User talep sorumlusu eşittir.The cookie middleware deserializes the cookie to a claims principal and sets HttpContext.User equal to the claims principal. İstek için MVC denetleyicisi yönlendirilir.The request is routed to an MVC controller.

Kimlik doğrulaması biletiAuthentication ticket

Doğrulama başarılı olursa, kullanıcı talepleri içeren bir talep sorumlusu içeren bir kimlik doğrulaması bileti OIDC ara yazılım oluşturur.If authentication succeeds, the OIDC middleware creates an authentication ticket, which contains a claims principal that holds the user's claims. Biletini erişebileceğiniz AuthenticationValidated veya TicketReceived olay.You can access the ticket inside the AuthenticationValidated or TicketReceived event.

Not

Tüm kimlik doğrulama akışı tamamlanana kadar HttpContext.User hala bir anonim sorumlusu tutan değil kimliği doğrulanmış kullanıcı.Until the entire authentication flow is completed, HttpContext.User still holds an anonymous principal, not the authenticated user. Anonim sorumlusu boş talep koleksiyonu vardır.The anonymous principal has an empty claims collection. Kimlik doğrulaması tamamlandıktan sonra uygulama yeniden yönlendirmeler, tanımlama bilgisi Ara seri durumdan çıkarır ve kimlik doğrulama tanımlama bilgisi ayarlar HttpContext.User için kimliği doğrulanmış bir kullanıcıyı temsil eden bir talep sorumlusu.After authentication completes and the app redirects, the cookie middleware deserializes the authentication cookie and sets HttpContext.User to a claims principal that represents the authenticated user.

Kimlik doğrulama olaylarıAuthentication events

Kimlik doğrulama işlemi sırasında Openıd Connect ara yazılım bir dizi olayı başlatan:During the authentication process, the OpenID Connect middleware raises a series of events:

  • RedirectToIdentityProvider.RedirectToIdentityProvider. Doğrudan ara yazılım kimlik doğrulaması uç noktaya yönlendiren önce çağrılır.Called right before the middleware redirects to the authentication endpoint. Bu olay, yeniden yönlendirme URL'sini değiştirmek için kullanabilirsiniz; Örneğin, istek parametreleri eklemek için şunu yazın.You can use this event to modify the redirect URL; for example, to add request parameters. Bkz: yönetici onay istemi ekleme örneği.See Adding the admin consent prompt for an example.
  • AuthorizationCodeReceived.AuthorizationCodeReceived. Yetkilendirme koduyla çağrılır.Called with the authorization code.
  • TokenResponseReceived.TokenResponseReceived. Ara yazılım bir erişim IDP'den belirteci aldıktan sonra ancak bunu doğruladıktan önce çağrılır.Called after the middleware gets an access token from the IDP, but before it is validated. Yalnızca yetkilendirme kod akışı için geçerlidir.Applies only to authorization code flow.
  • TokenValidated.TokenValidated. Ara yazılım kimlik belirteci doğruladıktan sonra çağrılır.Called after the middleware validates the ID token. Bu noktada, uygulamanın kullanıcı hakkında doğrulanan talepler kümesi vardır.At this point, the application has a set of validated claims about the user. Bu olay taleplere ek doğrulama gerçekleştirmek için ya da talepleri dönüştürmek üzere kullanabilirsiniz.You can use this event to perform additional validation on the claims, or to transform claims. Bkz: talep ile çalışma.See Working with claims.
  • UserInformationReceived.UserInformationReceived. Ara yazılım kullanıcı bilgisi uç noktasından kullanıcı profili alırsa çağrılır.Called if the middleware gets the user profile from the user info endpoint. Yalnızca yetkilendirme kod akışı ve yalnızca uygulanır GetClaimsFromUserInfoEndpoint = true ara yazılımı seçenekleri.Applies only to authorization code flow, and only when GetClaimsFromUserInfoEndpoint = true in the middleware options.
  • TicketReceived.TicketReceived. Kimlik doğrulaması tamamlandığında çağırılır.Called when authentication is completed. Söz konusu kimlik doğrulamasını başarılı olduğu varsayılırsa, son olay budur.This is the last event, assuming that authentication succeeds. Bu olay işlenen sonra kullanıcı uygulamada oturum imzalanır.After this event is handled, the user is signed into the app.
  • AuthenticationFailed.AuthenticationFailed. Kimlik doğrulaması başarısız olursa çağrılır.Called if authentication fails. Kimlik doğrulama hataları işlemek için bu olayı kullanın — Örneğin, bir hata sayfası için yeniden yönlendirme tarafından.Use this event to handle authentication failures — for example, by redirecting to an error page.

Bu olaylar için geri çağırmaları sağlamak üzere ayarlama olayları ara yazılım seçeneği.To provide callbacks for these events, set the Events option on the middleware. Olay işleyicileri bildirmek için iki farklı yolu vardır: Lambda ifadeleri, türetilen bir sınıfta veya satır içi OpenIdConnectEvents.There are two different ways to declare the event handlers: Inline with lambdas, or in a class that derives from OpenIdConnectEvents. Bunlar, başlangıç sınıfı hale getirmeyin için herhangi bir önemli mantık, olay geri çağırmaları varsa, ikinci yaklaşım önerilir.The second approach is recommended if your event callbacks have any substantial logic, so they don't clutter your startup class. Başvuru uygulamamızda bu yaklaşımı kullanır.Our reference implementation uses this approach.

Openıd connect uç noktalarıOpenID connect endpoints

Azure AD destekler Openıd Connect Discovery, burada görüntülerle kimlik sağlayıcıyı (IDP) JSON meta verileri belgesinden döndürür bir iyi bilinen bir uç nokta.Azure AD supports OpenID Connect Discovery, wherein the identity provider (IDP) returns a JSON metadata document from a well-known endpoint. Meta veri belgesi gibi bilgileri içerir:The metadata document contains information such as:

  • Yetkilendirme uç noktası URL'si.The URL of the authorization endpoint. Burada kullanıcının kimliğini doğrulamak için uygulamayı yönlendiren budur.This is where the app redirects to authenticate the user.
  • Burada kullanıcının oturumunu açmak için uygulama gider "oturumunu sona erdirme" uç noktasının URL'si.The URL of the "end session" endpoint, where the app goes to log out the user.
  • İstemcinin IDP'den alır OIDC belirteçleri doğrulamak için imzalama anahtarları almak için URL.The URL to get the signing keys, which the client uses to validate the OIDC tokens that it gets from the IDP.

Varsayılan olarak, bu meta veriler getirilemedi nasıl OIDC ara yazılım bilir.By default, the OIDC middleware knows how to fetch this metadata. Ayarlama yetkilisi seçeneğindeki ara yazılım ve ara yazılım meta verileri URL'sini oluşturur.Set the Authority option in the middleware, and the middleware constructs the URL for the metadata. (Ayarlayarak meta veri URL'sini geçersiz kılabilirsiniz MetadataAddress seçeneği.)(You can override the metadata URL by setting the MetadataAddress option.)

Openıd connect akışıOpenID connect flows

Varsayılan olarak, biçim gönderme yanıtı Modu'ndan ile karma akış OIDC ara yazılım kullanır.By default, the OIDC middleware uses hybrid flow with form post response mode.

  • Karma akış istemci elde edebilecekleri bir kimlik belirteci ve bir yetkilendirme kodu aynı gidiş dönüş için yetkilendirme sunucusu anlamına gelir.Hybrid flow means the client can get an ID token and an authorization code in the same round-trip to the authorization server.
  • Form post yanıt modu yetkilendirme sunucusu bir HTTP POST isteği uygulamaya kimlik belirteci ve yetkilendirme kodu göndermek için kullandığı anlamına gelir.Form post reponse mode means the authorization server uses an HTTP POST request to send the ID token and authorization code to the app. Form-urlencoded değerler (içerik türü "application/x-www-form-urlencoded işlemek" =).The values are form-urlencoded (content type = "application/x-www-form-urlencoded").

OIDC ara yazılım yetkilendirme uç noktasına yönlendirir, sorgu dizesi parametreleri tarafından OIDC gerekli tüm yeniden yönlendirme URL'sini içerir.When the OIDC middleware redirects to the authorization endpoint, the redirect URL includes all of the query string parameters needed by OIDC. Karma akış için:For hybrid flow:

  • client_id.client_id. Bu değer kümesindeki ClientID seçeneğiThis value is set in the ClientId option
  • Kapsam = "OIDC isteği olduğundan ve kullanıcının profili istediğimiz openıd profili".scope = "openid profile", which means it's an OIDC request and we want the user's profile.
  • response_type "id_token code" =.response_type = "code id_token". Bu karma akış belirtir.This specifies hybrid flow.
  • response_mode = "form_post".response_mode = "form_post". Bu form gönderi yanıtı belirtir.This specifies form post response.

Farklı bir akış belirtmek için ayarlayın ResponseType özellik seçenekleri.To specify a different flow, set the ResponseType property on the options. Örneğin:For example:

app.UseOpenIdConnectAuthentication(options =>
{
    options.ResponseType = "code"; // Authorization code flow

    // Other options
}

SonrakiNext