An overview of Azure Active Directory B2C

Introduction

Ongoing digital relationships and connectivity with people and things are fundamental to the success of today's organizations.

Identity is the foundational technology enabling this. Regardless of their size, organizations need a single way to do identity, whether it be for employees, customers, partners or devices. Anything must be able to have a digital relationship - and connect to anything else.

Azure Active Directory (Azure AD) is Microsoft's vehicle for responding to this requirement by providing Identity Management as-a-Service (IDaaS) capabilities in a cloud or hybrid environment.

By leveraging efficiencies of the cloud and automation to get efficiencies in identity, IDaaS service can:

• Offer all the necessary security and privacy capabilities – while maintaining usability.
• Provide a business centric portal for configuring identity services.
• Sustain easy-to-integrate/easy-to-customize (self-services) identity experiences.
• And finally cut costs thanks to superior cloud economics.

These requirements and capabilities will drive almost all organizations to subscribe to identity services that are cheaper, broader in scope, more unifying and more capable than the systems of today.

Because of its enterprise relationships, and its early commitment to build an enterprise grade identity service at cloud scale, Microsoft's approach to IDaaS is deeply grounded in – and extends – the proven concepts of on-premises Active Directory (AD).

AD is a Microsoft brand for identity related capabilities. Microsoft has earned widespread adoption of its on-premises identity technology, a suite of capabilities packaged and branded as Windows Server Active Directory (WSAD or simply AD).

In the on-premises world, AD provides a set of identity capabilities. AD is used extensively by governments and enterprises world-wide. AD is widely deployed in the Fortune 1000 and the Global 5000 today as their authoritative identity and access management system as well as in small and medium enterprises and we will not describe it further except to underline one essential point: to meet the requirements of hybrid deployment AD can be extended into public clouds and/or into private clouds.

Azure AD is AD reimagined for the cloud, hardened for the realities and dangers of the cloud environment, and designed to help you solving the new identity and access challenges that come with the shift to a cloud-centric world.

Azure AD is a comprehensive identity and access management cloud solution, utilizing the enterprise-grade quality and proven capabilities of AD on-premises. It combines core directory services, advanced identity governance, security and analytics, and application access management.

Azure AD has been designed to easily extend AD (in whole or in part) into the public Azure cloud as a directory whose content is owned and controlled by the organization providing the information.

Azure AD is NOT a monolithic directory of information belonging to Microsoft, but rather different directories belonging to and completely controlled by different organizations. This architecture and commitment is called "multi-tenant" and great care has been provided to insulate tenants (organizations) from each other and from their service operator – Microsoft. Azure AD is a vast network of independent identity systems and directories owned by organizations.

Azure AD is indeed trusted by millions of organizations serving hundreds of millions of identities for access to Software as a Service (SaaS) applications, including Office 365 and thousands of other partner applications.

We have indeed re-engineered AD, to support massive scale, devices based on any operating system or architecture, modern business applications, modern protocols, high availability, and integrated disaster recovery. Azure AD is delivered in a highly-available, fault-tolerant architecture from over 32 regions worldwide.

Note     The service operates more than 10 million of tenants and actually processes more than 1.3 billion, with a B, authentications every week. Since the release of the service, Azure AD has processed 1 trillion identity authentications. This is a real testament to the level of scale we can handle. At a high level, Azure AD is a high availability, geo-redundant, multi-tenanted, multi-tiered cloud service that has delivered 99.99% uptime for over a year now.

As outlined above, we run it across 32 regions around the world. Azure AD has stateless gateways, front end servers, application servers, and sync servers in all of those data centers. Azure AD also has a distributed data tier that is at the heart of our high availability strategy. Our data tier holds more than 750 million objects.

Given the numbers cited in this note and its track record since we first talked about it in November 2011, Azure AD has shown itself to be a robust identity and access management service for Microsoft cloud services. No other cloud directory offers this level of enterprise reliability or proven scale.

Furthermore, last year, Gartner in their Magic Quadrant (MQ) for Identity Management as a Service (IDaaS) has placed Azure AD after its only first year of availability in the "Visionaries" MQ. As of this writing, Gartner has just released their MQ for IDaaS for 2016 and Azure AD Premium has been placed in the "Leaders" quadrant, and positioned very strongly for our completeness of vision.

Important note    The above graphic was published by Gartner, Inc. as part of the larger research document - a complimentary access is provided here- and should be evaluated in the context of the entire document. Gartner does not endorse any vendor, product or service depicted in its research publications, and does not advise technology users to select only those vendors with the highest ratings or other designation. Gartner research publications consist of the opinions of Gartner's research organization and should not be construed as statements of fact. Gartner disclaims all warranties, expressed or implied, with respect to this research, including any warranties of merchantability or fitness for a particular purpose.

As Alex Simons, Director of Program Management, Microsoft Identity and Security Services Division, says, "we're thrilled with the result. It really validates our vision of providing a complete solution for hybrid identity and access for supporting employees, partners and customers all backed by world class security based on Microsoft's intelligent security graph. This result says a lot about our commitment in the identity and access management space but more importantly about our customers, implementation partners and ISV partners who have worked together with us. They have been awesome about sharing their time and energy every day, to make sure that the products and services we build meet their needs and are helping them position their companies to thrive in the emerging world of cloud and devices.

You might be surprised to know that Microsoft also is the only vendor in the Leader quadrant across Gartner's Magic Quadrants for IDaaS, Cloud Infrastructure as a Service (IaaS), Server Virtualization, Application Platform as a Service, Cloud Storage Services, and as a leader across the data platform and productivity services. This really shows you why customers are choosing Microsoft across the full spectrum of cloud computing – our services are well integrated and also among the best available in their individual categories."

Note    For information on the available Azure AD editions, see later in this document and/or the article Azure Active Directory editions.

Alex Simons adds: "our effort doesn't stop here. We have a lot of hard work ahead of us and we are planning to deliver more innovative capabilities to further improve our position in the "leaders" quadrant.".

In this context, Azure AD extends its capabilities to embrace identity management (IDM) of individual consumers with a new service for Business-to-Consumer: Azure AD B2C, now in GA.

Azure AD B2C is a comprehensive, cloud-based, consumer identity management solution for your consumer-facing applications that can be easily integrated into any platform and accessed from any device.

As of this writing, Azure AD B2C is in GA in North America, and in public preview elsewhere.

Note    For more information, see article Azure Active Directory B2C: Production-scale vs. preview B2C tenants.

This service is available on a pay-as-you-go (PAYG) basis. You can get with a free tier up to 50,000 users and 50,000 authentications per month, and when you will have more end users and traffic to your consumer-facing application(s), a fraction of a cent per stored identity and authentication will be charged. An Azure subscription is required.

Note    For more information on usage model, see article Azure Active Directory B2C Pricing.

Objectives of this paper

This document is intended as an overview document for discovering and understanding the benefits of Azure AD B2C, and how your application can leverage this new service.

While much of the technology of Azure AD must remain the same (e.g. directory), the IDM of employees and IDM of consumers also have many different requirements – thus the need for technologies that interact but are honed to specific problems. To master these requirements, Microsoft has worked closely with a number of customers during the private and public previews.

Built on existing Microsoft's documentation, knowledge base articles, and blog posts, this document provides a complete walkthrough to test, and evaluate Azure AD B2C. It provides additional guidance if any.

Note    You can also share your thoughts on the Azure AD B2C using User Voice with the phrase "AzureADB2C:" in the title of your post so that it can be found.

Non-objectives of this paper

This document is not intended as an overview document for the Azure AD offerings but rather focusses on this new Azure AD B2C identity service.

Note    For additional information, see article Getting started with Azure AD. As well as the whitepapers Active Directory from the on-premises to the cloud and An overview of Azure AD as part of the same series of documents.

Likewise, it doesn't provide either in-depth description on how to implement a specific covered feature or capability. Where necessary, it instead refers to more detailed documents, articles, and blog posts that describe a specific feature or capability.

Note    Please make sure you periodically check the Azure Active Directory B2C: FAQs, Azure AD community forum as well as the Enterprise Mobility + Security (EMS) Team blog for notification of upcoming enhancement and changes that pertain to Azure AD.

Organization of this paper

To cover the aforementioned objectives, this document is organized in the following four sections:

• Supporting Business-to-Consumer scenarios.
• Introducing Azure AD B2C.
• Getting started with Azure AD B2C.
• A sneak peak of what's coming next.

These sections provide the information details necessary to understand the new capabilities introduced in Azure AD for Business-to-Consumer (B2C) scenarios, and successfully evaluate all the available features.

About the audience

This document is intended for IT professionals, system architects, and developers who are interested in understanding how Azure AD B2C help managing identities for their consumer-facing application(s) in their (hybrid) cloud environment and how to leverage the related features.

Supporting Business-to-Consumer scenarios

Managing identities at scale

It is evident that enterprises and governments will use their (hybrid) IDaaS services to manage the authentication and authorization of internal employees.

But in the outward looking world that is emerging so quickly it will be just as important to manage access to services by an organization's supply chain, its customers (including individuals), its leads and prospects. In the same way, governments will benefit from these services when interacting with other government agencies, enterprises and citizens.

Today, enterprises and governments struggle to manage the accounts, credentials and entitlements of their huge populations of external users that are not well served by existing identity and access control systems. 

From an organization's perspective, this population of "external users" represents all the people who interact with its online applications and APIs, but who are not directly members of the organization itself. Consumers, customers, clients, citizens, retirees, partners, etc. are chief amongst them. Typical populations of these "external users" dwarf the size of an organization's internal workforce.

Current best practices – maintaining local accounts and passwords – can lead to debilitating financial and personnel costs, and front-page security and privacy disasters. The on-premises solutions in place to sustain the above interactions indeed face a multitude of challenges.

This obviously starts with the security and privacy risks that must be adequately addressed when storing credentials and personally identify information (PII)/ or sensitive personal information (SPI) in various application databases.

From an implementation standpoint, organizations typically have to cope with heterogeneous stove-piped identity systems that are custom built, acquired from 3^rd parties, part of legacy systems, etc. along with different data types and formats, different types of extensibility/states of modifications possible, different application platforms and systems (and even blurred system boundaries), etc.

Beyond the subsequent lack of a unified view, this usually results in high total cost of ownership (TCO) with not only the software licensing, maintenance, and upgrade costs implied with such an on-premises infrastructure but also with 7 x 24 operations and the support staff required to ensure the service.

This leads both to quality of service (QoS) challenges (given the absence of a high availability and/or disaster recovery infrastructure) and a lack of scalability (up to millions of these "external users") since legacy systems have no elasticity when it comes to demand spikes.

Organizations need a specialized service that handle identity at the appropriate scale while assuring the necessary security and privacy. – This demands an increased level of specialization and professionalization adequate to emerging cyber threats. Once this is understood it becomes obvious why you get more capability for less money by leveraging cloud capabilities.

A specialized identity service directly attacks the above challenges – simplifying life for enterprises, ISVs, government agencies and their "external identities".

Kim Cameron, Microsoft Chief Identity Architect, is convinced that "organizations will find they need new identity management capabilities to take full advantage of the cloud and integrate cloud services with their on-premises environment. They will also find that the most reliable and cost-effective way to obtain these capabilities is through using the cloud to master the cloud."

Extending Azure AD for external identities

In addition to managing their employees and mobile workforce access the required SaaS and (cloud-based, hybrid, and on-premises) Line-Of-Business (LOB) applications, Azure AD can help organizations manage their external users, and thus deliver (web and mobile) applications, such as a retail store front to consumers.

Note    The word "consumer" is used here to refer to the ultimate consumer, customer, client, citizen, retiree, or a supporter of a business, government or charity, someone who is acting as an individual, and not as a

This is what the new service Azure AD B2C should be used for to meet the growing needs organizations looking to connect their consumers via such applications. In the aforementioned research document, Gartner says that "B2C use cases have grown in importance as organizations look to replace a mixture of custom-developed IAM products and traditional on-premises IAM products".

While much of the technology of Azure AD must remain the same (e.g. directory), Azure AD B2C allows to accommodate many different requirements – thus the need for technologies that interact but are honed to specific problems. In fact, the Azure AD and Azure AD B2C services can be thought of as a continuum, so approaches need to be able to be mixed and deployed flexibly.

Understanding Azure AD B2C key objectives

Azure AD B2C is designed to solve the identity management challenges that have emerged, as economic and competitive pressures drive commercial enterprises, ISVs, educational institutions, and government agencies to shift their service delivery channels from face-to-face engagements to online web applications, web API, as well as native mobile applications.

Azure AD B2C extends Azure AD to deliver all of the functionality required of a cloud era IDaaS solution for connecting all your consumer-facing modern applications, that can be integrated in any platform, and accessible from any device.

Azure AD B2C acts on behalf of a consumer-facing application (aka relying party or RP) by automating and managing all the mechanisms through which it obtains digital identity information to enable the RP to make informed access control and personalization decisions about a transaction requested by an external user. Consequently, Azure AD B2C supports a spectrum of identity services from high security (e.g. phone-based multi-factor authentication) to satisfy organizational "Know Your Consumer" (KYC) requirements.

Azure AD B2C has characteristics shaped by the importance of identity for both the protection of assets and the enhancement of relationships as we enter the era of the social enterprise. There is general agreement on the need to provide individuals and organizations with more "secure, efficient, easy-to-use, and interoperable identity solutions to access online services in a manner that promotes confidence, privacy, choice, and innovation".

Azure AD B2C service has been developed out of a broad dialog internationally and in conformance with requirements from a great many expert sources in government and industry, and is being exercised in multiple pilots globally, and even more like with the Real Madrid, the #1 sports franchise in the world, that needed to directly engage with its 450 million fans:

"For user authentication and profile storage, the solution uses a preview version of the Azure Active Directory Business to Consumer (B2C) identity service. Fans get simplified registration and login through use of social accounts like Facebook, or they can use traditional username/passwords for a seamless experience across mobile applications on any platform. Using a standard service built on the established Azure Active Directory platform significantly reduced custom code while giving Real Madrid customized branding and alleviating concerns about security, data breaches, and scalability."

Azure AD B2C can scale to large populations (up to hundreds of millions per organization) of consumers and is built on the same enterprise-grade (high-availability, geo-redundant, secure, etc.) Azure AD technology platform that supports Office 365. Built on an enterprise-grade secure platform, Azure AD B2C keeps your business and your consumers protected.

Introducing Azure AD B2C

Considering all the objectives outlined in the previous section, the features of Azure AD B2C are articulated around five main pillars:

1. Social and local account.
2. Multi-factor authentication.
3. Sign up, sign in, password reset and profile editing.
4. User experience customization.
   1. Seamless integration for development.

Let's consider them in the next sections where a specific section will be devoted to each pillar.

As a whole, these pillars enable Azure AD B2C to provide a unified view of the consumer (sign up, sign in, and profile editing) across all the consumer facing applications exposed by your organization.

Using social accounts and local accounts

For consumers, social media is emerging as a key source of identity. Real world examples of this include organizations that have internet-centric business models. Consider music download sites such as Spotify that allow users to login using their Facebook identities make it far easier for users to sign up.

Furthermore, usage of social identities appears to be expanding into more conservative areas; for example, the UK government has evaluated Facebook as part of the Identity Assurance (IDA) program, a way of better enabling secure transactions between public sector bodies and citizens.

At the same time these changes present new challenges for the consumer-facing applications (both on-premises and in the cloud) that represent identity lifecycle management, provisioning, role management, authentication and security of users and devices requiring granular access. The net result is to propel identity to first rank of importance.

In terms of authentication to a consumer-facing application, Azure AD B2C gives end users a choice between:

• "Bringing their own Identities" (BYOI) by using one of their existing social accounts, such as Amazon, Facebook, Google+, LinkedIn, or Microsoft Account (MSA),

-or-

• Creating a new local account (arbitrary email address / username with password). 

Beyond local accounts, enabling BYOI ensures user adoption, given that there are millions of consumer identities in use today from the aforementioned social identity providers and end users are more likely to remember a password they use daily rather than a few times a year.

Benefiting from multi-factor authentication

Enabling BYOI is only the first part of the solution. Clearly these social identities are self-asserted and of such low identity assurance that they are not sufficient to authorize access to valuable or sensitive information.

To address this concern, Azure AD B2C can improve organizational security by requiring end users to employ an additional authentication method when the use case warrants it. Azure AD B2C indeed allows organizations to seamlessly benefit from an optional (phone-based) multi-factor authentication whenever needed.

Note    For more information, see article Azure Active Directory B2C: Enable Multi-Factor Authentication in your consumer-facing applications.

This authentication is based on Azure Multi-Factor Authentication.

Note    For more information, see related documentation as well as the whitepaper Leverage Multi-Factor Authentication with Azure AD in the same series of document.

Leveraging friction-free out-of-the-box user experiences

To make it easy for your external users to get to your consumer-facing application(s), Azure AD B2C is as its core a flexible, policy-based, data-driven identity exchange service that orchestrates authentication with attribute requests. In this context, a flexible policy framework provides granular control over seamless user experiences and behaviors for your consumer-facing applications.

This policy framework allows the creation of these enterprise-level policies. These policies enable you to instantiate/refine supported out-of-the-box (OOB) user experiences or journeys for the consumer facing-applications.

Understanding the supported OOB user journeys

Let's see how this works starting from the supported OOB user journeys, and what can be defined and configured.

Azure AD B2C supports the following five OOB user journeys: i) self-service sign-up (Sign-up), ii) single sign-on (Sign-in), iii) sign-up or sign-in (Sign-up or Sign-in), iv) profile editing (Edit your profile), and v) self-service password reset (Reset your password) for local accounts.

These OOB user journeys encompass as series of actions in sequence in terms of authentication and information collection.

As such, the Sign-up user journey provides self-service consumer registration. It allows the end user to:

• Choose a social identity provider to sign in (or) create a new local account.
• Sign in with social provider (or) create a new 'local account' with email address verification and request additional information from the user.
• Collect additional information if user signed in with social identity provider.
• Collect a phone number from the user and do a phone challenge via SMS or voice if multi-factor authentication is enabled.

Likewise, the Sign in user journey basically allows the end user to:

• Choose a social identity provider (or) a 'local account' to sign in.
• Sign in with social identity provider (or) local account.
• Do a phone challenge if multi-factor authentication is enabled.

Note    A phone number will be collected if no number is present in the B2C tenant for the user. (See later in this document).

Note    Self-service password reset (SSPR) management can be provided for local accounts as part of the Sign in journey.

Above steps are skipped if the user is already signed in.

Based on the above journeys, the unified" Sign-up or Sign-in journey indeed allows the end user to switch into Sign-up mode the first time the end user employs a social identity.

The Edit your profile journey provides self-service capabilities such as self-service profile management. It notably allows to:

• Choose a social identity provider (or) 'local account' to sign in.
• Sign-in with social identity provider (or) local account.
• Do a phone challenge via text message or voice if multi-factor is enabled and phone number is on file.

Steps are skipped if already signed in.

And eventually, the Reset your password journey provides self-service capabilities such as self-service password resets for local accounts. To get back a local account, it notably allows to:

• Specify a local account id.
• Receive an account verification code email to the verified email address of the local account.
• Reset the password upon successful verification of the code.

Defining the related enterprise-level policies

As introduced above, from a practical standpoint, these OOB user journeys are defined through related enterprise-level policies created through a policy framework. As such, a corresponding policy category is provided for each type of supported OOB user journeys, i.e. i) sign-up policy, ii) sign-in policy, iii) sign-up or sign-in policy, iv) profile editing policy, and v) password reset policy.

From an application perspective, the developer just redirects to B2C specifying which policy he wants and gets back the authenticated result of the journey as a set of claims with zero app complexity. (see section later in this document). All of the logic resides in the policy and is orchestrated by Azure AD B2C's Identity Experience Engine. You don't need to code any of this.

Note    For more information, see article Azure Active Directory B2C: Extensible policy framework.

Considering the above, a sign-up policy enables sign-up in your application and allows:

• The selection of social identity providers from which the user can sign in form during sign up,
• The selection of sign up attributes that you want to collect from the user during sign up.

Note    Sign up attributes can be built-in user attributes and/or custom user attributes via an extensible directory schema,

• The selection of application claims that you want returned in the tokens back to your application after a successful sign up journey,
• The optional use of optional use of multifactor authentication during sign up,
• The UI customization for (most of) the pages served by Azure AD B2C to sustain the user interaction. (See section § Customizing the overall user experience.)

Likewise, a sign-in policy enables sign-in in your application and allows:

• The selection of social identity providers from which the user can sign in form during sign in,
• The selection of application claims that you want returned in the tokens back to your application after a successful sign in journey,
• The optional use of multifactor authentication during sign in,
• The UI customization for (most of) the pages served by Azure AD B2C to sustain the user interaction. (See section § Customizing the overall user experience.)

A "unified" sign-up or sign-in policy enables sign-up or sign-in in your application. Typically, an application provides two separate buttons for sign up and sign in that users have to pick from. With "unified" sign-up or sign-in policy, your application can provide a single click experience for sign up or sign in based on context. When both new and existing end-users click on a button called "Join / Sign in" they are given the choice to:

• Sign in with a social identity provider
• Sign in with an existing local account.
• Create a new local account.

For that purpose, "unified" sign-up or sign-in policy allows all what the aforementioned policies allow. In addition, the UI on every page of this experience served by Azure AD B2C is fully customizable. (See section § Customizing the overall user experience.)

A profile editing policy allows:

• The selection of attributes,
• The selection of application claims,
• The UI customization for (most of) the pages served by Azure AD B2C to sustain the user interaction. (See section § Customizing the overall user experience.)

And eventually, a reset password policy allows to create and use multiple, fully customizable password reset experiences. This means that all applications don't have to share a single common password reset experience. The UI on every page of this experience served by Azure AD B2C is fully customizable. (See section § Customizing the overall user experience.)

Policies have a consistent "developer" interface that allows a graphical and fully guided definition of the policies. Azure AD B2C supports the live run of the policy straight from the UI to test the policy without a single line of code.

Even more interestingly, policies are units of re-use for applications. In other words, such policies once created typically constitute reusable user journeys. You can create multiple policies of the same type and use any policy in any application at runtime.

Indeed, policies can be articulated on an application by application basis. In other words, a registered consumer facing-application can then in turn adhere to them – one policy per type of user journey - thus enabling to drive the application compliance.

You invoke them in your application using standard identity protocol requests to Azure AD B2C and you receive tokens with claims (customized by you) as responses. (See section § Seamlessly integrating your consumer facing applications.)

To ease the re-use and the modification of policies, policies can be exported and downloaded from the UI as an XML file. The following code snippet illustrates a sign-up policy named B2C_1_B2CSignUp.

<TrustFrameworkPolicy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                      xmlns:xsd="http://www.w3.org/2001/XMLSchema"  
                      xmlns="http://schemas.microsoft.com/online/cpim/schemas/2013/06" 
                      PolicySchemaVersion="0.3.0.0" 
                      TenantId="contoso369b2c.onmicrosoft.com" 
                      PolicyId="B2C_1_B2CSignUp" 
                      PublicPolicyUri="http://contoso369b2c.onmicrosoft.com/">
  <BasePolicy>
    <TenantId>contoso369b2c.onmicrosoft.com</TenantId>
    <PolicyId>base-v1</PolicyId>
  </BasePolicy>
  <ClaimsProviders>
    <ClaimsProvider>
      <DisplayName>PhoneFactor</DisplayName>
      <TechnicalProfiles>
        <TechnicalProfile Id="PhoneFactor-Common">
          <EnabledForUserJourneys>OnClaimsExistence</EnabledForUserJourneys>
        </TechnicalProfile>
      </TechnicalProfiles>
    </ClaimsProvider>
    <ClaimsProvider>
      <DisplayName>Self Asserted</DisplayName>
      <TechnicalProfiles>
        <TechnicalProfile Id="SelfAsserted-Input">
          <InputClaims>
            <InputClaim ClaimTypeReferenceId="state" />
            <InputClaim ClaimTypeReferenceId="postalCode" />
            <InputClaim ClaimTypeReferenceId="extension_LoyaltyNumber" />
            <InputClaim ClaimTypeReferenceId="city" />
            <InputClaim ClaimTypeReferenceId="displayName" />
          </InputClaims>
          <OutputClaims>
            <OutputClaim ClaimTypeReferenceId="state" />
            <OutputClaim ClaimTypeReferenceId="postalCode" />
            <OutputClaim ClaimTypeReferenceId="extension_LoyaltyNumber" />
            <OutputClaim ClaimTypeReferenceId="city" />
            <OutputClaim ClaimTypeReferenceId="displayName" />
          </OutputClaims>
        </TechnicalProfile>
      </TechnicalProfiles>
    </ClaimsProvider>
    <ClaimsProvider>
      <DisplayName>Azure Active Directory</DisplayName>
      <TechnicalProfiles>
        <TechnicalProfile Id="AAD-WriteCommon">
          <PersistedClaims>
            <PersistedClaim ClaimTypeReferenceId="state" />
            <PersistedClaim ClaimTypeReferenceId="postalCode" />
            <PersistedClaim ClaimTypeReferenceId="extension_LoyaltyNumber" />
            <PersistedClaim ClaimTypeReferenceId="city" />
            <PersistedClaim ClaimTypeReferenceId="displayName" />
          </PersistedClaims>
        </TechnicalProfile>
      </TechnicalProfiles>
    </ClaimsProvider>
  </ClaimsProviders>
  <UserJourneys>
    <UserJourney Id="B2CSignUp">
      <OrchestrationSteps>
        <OrchestrationStep Order="1" 
                           Type="ClaimsProviderSelection" 
                           ContentDefinitionReferenceId="api.idpselections.signup">
          <ClaimsProviderSelections>
            <ClaimsProviderSelection TargetClaimsExchangeId="GoogleExchange" />
            <ClaimsProviderSelection TargetClaimsExchangeId="SignUpWithLogonEmailExchange" />
            <ClaimsProviderSelection TargetClaimsExchangeId="FacebookExchange" />
          </ClaimsProviderSelections>
        </OrchestrationStep>
      </OrchestrationSteps>
    </UserJourney>
  </UserJourneys>
  <RelyingParty>
    <DefaultUserJourney ReferenceId="B2CSignUp" />
    <TechnicalProfile Id="PolicyProfile">
      <DisplayName>PolicyProfile</DisplayName>
      <Protocol Name="OpenIdConnect" />
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="state" />
        <OutputClaim ClaimTypeReferenceId="objectId" />
        <OutputClaim ClaimTypeReferenceId="postalCode" />
        <OutputClaim ClaimTypeReferenceId="identityProvider" />
        <OutputClaim ClaimTypeReferenceId="extension_LoyaltyNumber" />
        <OutputClaim ClaimTypeReferenceId="displayName" />
        <OutputClaim ClaimTypeReferenceId="emails" />
        <OutputClaim ClaimTypeReferenceId="city" />
        <OutputClaim ClaimTypeReferenceId="sub" />
      </OutputClaims>
      <SubjectNamingInfo ClaimType="sub" />
    </TechnicalProfile>
  </RelyingParty>
</TrustFrameworkPolicy>

If you want to, such an XML file can then serve as a template to define a new policy.

Illustrating the provisioning workflow

Considering the above, let's illustrate a typical logical provisioning workflow. Let's suppose that, at this stage, your organization is in the process to define, create and deploy suitable policies for its App1 consumer-facing application.

The workflow is as follows:

1. Security and business analysts at your organization determine the user requirements and security constraints for their App1 consumer-facing application. For example, business analysts might want to reduce user drop off by leveraging social identities but require step-up authentication when the application needs increased assurance. OUTCOME: Determination that multiple steps are required for a suitable sign-up policy, one for the initial social identity login and a second one for the step-up authentication which requires stronger authentication and registration details. Same is true for the sign-in policies where they also want to have a second authentication factor in addition to the login at the social identity provider.
2. An administrator of your organization, maybe yourself, accesses the Azure AD B2C in the Azure portal and defines a sign-up policy B2CSignUp-A, selecting social identity providers, the required attributes to satisfy organizational "Know Your Customer" (KYC) requirements, the needed claims to send in turn, and the additional authentication factor. The administrator does the same with the definition of a sign-on policy B2CSignIn-1, selecting social identity providers, the required claims to send to the application, and the additional authentication factor. AOUTCOME: Organization's administrator has generated 2 policies, one for B2CSignUp-1 and one for B2CSignIn-1.
   1. Your organization's developers build or update the App1 consumer-facing application and integrate with Azure AD B2C by doing simple web redirection (see later in this document). In our example, for the initial user journey for signing-up, the App1 application does a redirect to Azure AD B2C passing the B2CSignIn-1 policy to honor in the query string of the URL. When the application requires to sign-in, the App1 application does a redirect to Azure AD B2C with the B2CSignIn-1 policy in the URL. OUTCOME: Azure AD B2C will orchestrate the application requests according to the different policies and the required claims will be returned to the App1 application.
3. The developers use the claims that are posted back to their App1 application by Azure AD B2C in order to personalize and authenticate their application.
4. Your organization deploys the App1 consumer-facing application to a production environment.

Let's see how Azure AD B2C orchestrates and enforces the above policies at runtime.

Illustrating the resulting orchestration at runtime

The Azure AD B2C policy enforcement engine receives a redirect from your App1 consumer-facing application which includes the B2CSignUp-1 policy to orchestrate, which in turn enforces it at runtime. The following example illustrates how Azure AD B2C orchestrates the various implied requests and operations to establish the claims as required by a sign-up policy:

1. The user is redirected to the social identity provider, in this case Facebook. If authentication succeeds the returned token is cached and orchestration continues to the second authentication factor, as dictated by the policy.
2. The user is taken through the process of binding a second factor to the account. Once a second authentication factor is bound to an account, it can then be used to challenge the user. As of this writing, a proof of possession of a phone could be used, using Azure Multi-Factor Authentication.
3. On successful verification of the second factor, the orchestrator initiates the registration process where the user self-asserts information. For that purpose, Azure AD B2C displays a policy-based customized UI for collecting from the user a specific set of built-in or custom ones.

Once all the requirements of the policy are met, Azure AD B2C returns as per sign-up policy the configured set of claims for the App1 application to evaluate. The App1 application may in turn confirm that the received set of claims match a dataset in its authoritative system of record, and if so, can use accordingly the now "verified" claims.

As a final step in the elevation flow, the App1 application may use the "verified" claims received to put the user through a final out of band proof process. Such a process can for instance consist in sending address confirmation mail to the user at the "verified" postal address. In the case of the above illustration, a confirmation code is simply sent by email.

Customizing the overall user experience

UI customization for a relating seamless user experience is key for any Business-to-Consumer solution. By seamless user experience, we mean an experience, whether on device or browser, where a user's journey through our service cannot be distinguished from that of the customer service they are using.

Azure AD B2C allows you to customize the look-and-feel of user experience on the various pages that can be potentially served and displayed by a user journey via the defined policies.

For that purpose, Azure AD B2C code in your consumer's browser and uses the modern and standard approach Cross-Origin Resource Sharing (CORS) to load custom content from a specific URL that you specify in a policy to point to your own HTML5/CSS files: "Cross-origin resource sharing (CORS) is a mechanism that allows restricted resources (e.g. fonts) on a web page to be requested from another domain outside the domain from which the resource originated."

Compared to the old traditional way, where template pages are owned by the solution where you provided limited text and images, where limited control of layout and feel was offered leading to more than difficulties to achieve a seamless experience, the CORS way supports HTML5 and CSS and allow you to:

• Host the content and the solution injects its controls using client side script.
• Have full control over every pixel of layout and feel.

You can provide as many content pages as you like by crafting HTML5/CSS files as appropriate.

Note    For security reasons, the use of JavaScript is currently blocked for customization.

In each of your HTML5 files, you provide an "anchor" element, which corresponds to the required <div id="api"> element in the HTML or the content page as illustrate hereafter. The request orchestration core function indeed requires that all content pages have this specific div.

<!DOCTYPE html>
<html>
  <head>
    <title>Your page content's tile!</title>
  </head>
  <body>


    <div id="api"></div>


  </body>
</html>

Azure AD B2C-related content for the page will be injected into this div, while the rest of the page is yours to control. The Azure AD B2C's JavaScript code pulls in your content and injects our HTML into this specific div element. Azure AD B2C injects the following controls as appropriate: account chooser control, login controls, multi-factor (currently phone-based) controls, and attribute collection controls. In terms of commitment, we will ensure that i) all our controls are HTML5 compliant and accessible, ii) all our controls can be fully styled, and iii) a control version will not regress.

Note    For more information, see article Azure Active Directory B2C: Customize the Azure AD B2C user interface (UI).

The merged content is eventually displayed as the dynamic document to your consumer.

To ensure of the above works as expected, you must:

• Ensure your content is HTML5 compliant and accessible
• Ensure your content server is enabled for CORS.

Note     To verify that the site you are hosting your content on has CORS enabled and test CORS requests, you can use the site http://test-cors.org/. Thanks to this site, you can simply either send the CORS request to a remote server (to test if CORS is supported), or send the CORS request to a test server (to explore certain features of CORS).

Note     The site http://enable-cors.org/ also constitutes a more than useful resources on CORS.

• Serve content over HTTPS.
• Use absolute URLS such as https://yourdomain/content for all links and CSS content.

Thank to this CORS-based approach, the end users will then have consistent experiences between an application provided by a brand and the pages served by Azure AD B2C.

The aforementioned policies integrate for that purpose the definition of page templates for the user journey to accommodate the various organization's requirements in this space:

• As per sign-up policy: identity provider selection page, local account sign-up page, social account sign-up page, and error page.
  • As per sign-in policy: identity provider selection page, and error page.
  • As per "unified" sign-up or sign-in policy: unified sign-up or sign-in page, local account sign-up page, social account sign-up page, and multifactor authentication page, and error page.
  • As per profile editing policy: identity provider selection page, profile update page, and error page.
  • As per reset password policy: forgot password page, and error page.

Note    As of this writing, local account sign-in, and verification emails are only customizable using the company branding feature and not by the above mechanism. For more information, see articles Azure Active Directory B2C: Limitations and restrictions and Add company branding to your sign-in and Access Panel pages.

Note    For more information, see article Azure Active Directory B2C: Customize the Azure AD B2C user interface (UI).

Seamlessly integrating your consumer facing applications

In today's world, consumer facing modern applications live in an environment that includes a broad spectrum of mobile and native clients, server to server communication, and web APIs, in addition to traditional browser-and-website interactions. Let's consider how Azure AD B2C allow to embrace the diversity of the situations in a standard fashion.

Embracing industry standard modern protocols and tokens for your applications

Interoperability with your consumer-facing applications is maintained with support for industry standard modern protocols, and notably the OpenID Connect 1.0 protocol and the OAuth 2.0 protocol.

Through such standards, Azure AD (B2C), as a next generation authentication platform, is designed to address new requirements that accompany the requirements of the above modern applications.

Note    For more information, see article Azure AD B2C: Authentication protocols.

OAuth 2.0 is more than gaining popularity in the Internet as an authorization protocol for accessing information. This is the primarily protocol for authorization and delegated authentication. Generally speaking, using OAuth 2.0, an application can gain access (with consent from the resource owner – which could be the end user or the administrator user) to impersonate the user, or users in his organization to access the resource.

Note    For more information, see article Authorize access to web applications using OAuth 2.0 and Azure Active Directory.

OpenID Connect 1.0 defines an identity layer on top of OAuth 2.0 and represents the state of the art in modern authentication protocols. It's a suite of lightweight specifications that provide a framework for identity interactions via REST like APIs. It is based on OAuth 2.0.

Note    For more information, see article Authorize access to web applications using OpenID Connect and Azure Active Directory.

Note    The OpenID Foundation has recently launched a certification program for OpenID Connect 1.0 implementations. For more information, see article The OpenID Foundation Launches OpenID Connect Certification Program. Azure AD has successfully passed the certification and is certified as an OpenID Connect 1.0 identity provider.

Having an OpenID Connect certification program provides confidence that certified implementations will "just work" together. This represents another important step on the road to widely-available secure interoperable digital identity for all the devices and applications that people use. Microsoft is proud to be a key contributor to the development of OpenID Connect 1.0 and now of its certification program.

Note     Many of you might not realize it, but every time you log into the Azure portal you are using OpenID Connect 1.0 and OAuth 2.0 and to do so. OpenID Connect 1.0 is used to authenticate you and the management portal uses OAuth 2.0 to acquire an access token and a refresh token which it then uses to communicate with the Azure service management REST API (RDFE) on your behalf. For more information, see article Service Management REST API Reference.

Many of the tokens issued by Azure AD B2C via the OpenID Connect 1.0 and OAuth 2.0 protocols are implemented with the JSON Web Token (JWT) format. JWT is a compact token format that is especially apt for REST-based development. JWT use is growing, and products supporting the format are increasingly common in the industry.

Note    For more information, see article Azure AD B2C: Token reference.

Controlling the token lifetime

The ability to control the lifetimes of ID tokens, and refresh tokens (as well as access tokens) issued by Azure AD B2C is important both for user experience and for organizations to tune the consumption rate.

The same kind of considerations also applies on how sessions are handled across applications and policies. Azure AD B2C allows you to configure these knobs by editing your existing enterprise-level policies. A few use cases this feature enables are as follows:

• Allow an end-user to stay signed into a mobile application indefinitely, as long as they are continually active on it.
• Meet your security and compliance requirements by setting the right token lifetimes.
• Disable SSO between two applications using the same sign in policy.
• Force re-authentication when a user accesses a high-security part of your application.

Exposing directory-specific endpoints for your policies

Azure AD B2C supports the above standard protocols via a STS: the login.microsoftonline.com sign in service that serves all authentication requests from the consumer-facing applications.

For that purposes, login.microsoftonline.com publishes OpenID Connect 1.0 and OAuth 2.0 directory-specific endpoints for the consumer-facing applications. Once registered, these applications (can) communicate with Azure AD B2C by sending requests to theses endpoints.

As depicted hereafter, the above enterprise-level policies are simply specified as an additional p policy parameter at the end of the query string of the request. Such an extension to the aforementioned protocols allows to perform much more than simple authentication and authorization with a full description of the identity experiences such as sign-up, sign-in, and profile editing as you can expect with these policies.

Let's describe what are these endpoints.

First of all, Azure AD B2C publishes an OpenID Connect 1.0 provider configuration information endpoint, which allows an application to fetch information about Azure AD B2C at runtime. This endpoint is as follows;

https://login.microsoftonline.com/<YourDirectory>.onmicrosoft.com/v2.0/.well-known/openid-configuration?p=<YourPolicy>

Where <YourDirectory> is the name of your B2C tenant used to authenticate the user, and <YourPolicy> an enterprise-level sign-up, sign-in, or profile editing policy created in that B2C tenant and used to acquire a security token.

For example, for the B2C tenant contoso369b2c.onmicrosoft.com, and the B2C_1_B2CSignUp policy the that will be both later created in this document as part of the suggested walkthrough, this corresponds to:

https://login.microsoftonline.com/contoso369b2c.onmicrosoft.com/v2.0/.well-known/openid-configuration?p=b2c_1_b2csignup

This configuration information endpoint provides a JSON configuration document (openid-configuration.json) as per OpenID Connect Discovery specification. This metadata document in JSON format provides configuration information such as the OpenID Connect 1.0 and OAuth 2.0 endpoint locations for the considered policy, the token contents, the token signing key and issuer values to validate, etc.

{
  "issuer": "https://login.microsoftonline.com/5de99415-f87f-4d44-b293-cac70508ba24/v2.0/",
   "authorization_endpoint": 
     "https://login.microsoftonline.com/contoso369b2c.onmicrosoft.com/oauth2/v2.0/authorize?p=b2c_1_b2csignup",
  "token_endpoint": "https://login.microsoftonline.com/contoso369b2c.onmicrosoft.com/oauth2/v2.0/token?p=b2c_1_b2csignup",
  "end_session_endpoint": 
     "https://login.microsoftonline.com/contoso369b2c.onmicrosoft.com/oauth2/v2.0/logout?p=b2c_1_b2csignup",
  "jwks_uri": "https://login.microsoftonline.com/contoso369b2c.onmicrosoft.com/discovery/v2.0/keys?p=b2c_1_b2csignup",

 {
  "response_modes_supported": [
    "query",
    "fragment",
    "form_post"
  ],
  "response_types_supported": [
    "code",
    "id_token",
    "code id_token"
  ],
  "scopes_supported": [
    "openid"
  ],
  "subject_types_supported": [
    "pairwise"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post"
  ],
  "claims_supported": [
    "state",
    "oid",
    "postalCode",
    "idp",
    "name",
    "emails",
    "city",
    "extension_LoyaltyNumber",
    "sub"
  ]
}

As listed in the above JSON file, and to sustain the several flows defined in OAuth 2.0, 2 public endpoints are published:

1. One endpoint at which an application can obtain an id_token (authorization) token, as follows:

https://login.microsoftonline.com/te/<YourDirectory>.onmicrosoft.com/oauth2/v2.0/authorize?p=<YourPolicy>

For the B2C tenant contoso369b2c.onmicrosoft.com and the B2C_1_B2CSignUp policy, this corresponds to:

https://login.microsoftonline.com/contoso369b2c.onmicrosoft.com/oauth2/v2.0/authorize?p=b2c_1_b2csignup

1. And another endpoint at which applications can obtain an "access" token, as follows:

https://login.microsoftonline.com/<YourDirectory>.onmicrosoft.com/oauth2/v2.0/token?p=<YourPolicy>

For the B2C tenant contoso369b2c.onmicrosoft.com and the B2C_1_B2CSignUp policy, this corresponds to:

https://login.microsoftonline.com/contoso369b2c.onmicrosoft.com/oauth2/v2.0/token?p=b2c_1_b2csignup

After an application is authenticated, Azure AD B2C will issue the application an id_token that allows the application to call the requested web API.

In addition, for OpenID Connect 1.0, one sign-out endpoint is also published as follows:

• One sign-out endpoint for the logout as follows:

https://login.microsoftonline.com/<YourDirectory>.onmicrosoft.com/oauth2/v2.0/logout?p=<YourPolicy>

For the B2C tenant contoso369b2c.onmicrosoft.com and the B2C_1_B2CSignUp policy, this corresponds to:

https://login.microsoftonline.com/contoso369b2c.onmicrosoft.com/oauth2/v2.0/logout?p=b2c_1_b2csignup

Such an endpoint is described in the OpenID Connect session management specification.

• One additional endpoint to download a JSON Web Key Set (JWK) (keys.json) document.:

https://login.microsoftonline.com/<YourDirectory>.onmicrosoft.com/discovery/v2.0/keys?p=<YourPolicy>

For the B2C tenant contoso369b2c.onmicrosoft.com and the B2C_1_B2CSignUp policy, this corresponds to:

https://login.microsoftonline.com/contoso369b2c.onmicrosoft.com/discovery/v2.0/keys?p=b2c_1_b2csignup

This JSON document allows the applications to get the signing keys in order to validate signatures from the OpenID Connect provider of Azure AD B2C.

The following diagram synthetizes the above endpoints:

From an application perspective, a sign-up, sign-in, or profile editing request simply consists in a redirect to the OAuth 2.0 authorize endpoint to execute a policy, i.e. a HTTP GET request to the following URL:

https://login.microsoftonline.com/<YourDirectory>.onmicrosoft.com/oauth2/v2.0/authorize?p=<YourPolicy>&<ProtocolStandardQueryParameters>

Where <YourDirectory> is your B2C tenant, <YourPolicy> the name of respectively your sign-up, sign-in, or profile editing request, and <ProtocolStandardQueryParameters> the expected parameters for the protocol along with context and state information.

The user completes the policy in accordance to the policy definition. The application receives from the endpoint a response that contains a JWT security token, for example an ID token (id_token). A ID token represents the user's identity and provides information about the user in the form of claims. These claims are configured in the policy.

Likewise, a sign-out request for the application is as simply expressed as the following request:

https://login.microsoftonline.com/<YourDirectory>.onmicrosoft.com/oauth2/v2.0/logout?p=<YourPolicy>& ProtocolStandardQueryParameters>

Let's consider an actual example of a real query with all the parameters in lieu of p=<YourPolicy>& ProtocolStandardQueryParameters>. As illustrated later in this document with a sample web app, when an end user clicks on the sign-in button in the app, the OpenID Connect 1.0 sign-in request will look like (line split for readability):

GET https://login.microsoftonline.com/contoso369b2c.onmicrosoft.com/oauth2/v2.0/authorize

?p=b2c_1_b2csignin

&client_id=2a2681b1-ac24-4cb3-9829-ce2315500117

&redirect_uri=https%3a%2f%2flocalhost%3a44316%2f

&response_mode=form_post

&response_type=id_token

&scope=openid

&state=OpenIdConnect.AuthenticationProperties%3dhG6CwJrhmPWMS5n1kIGr6QwI3QwqdpGZ4Q8kcWE_ZX6cdtQgvMDXiXEOuPr9o4D6T2h0R2JuETB2NoMhmx327EiNVSI1abOUMNkjG87_WFOGuTOhqMkK2tQpTvmKhEWqcXbjUO73bN-wlLkSvBrLDFZHmCnbrEuIM-1rMjyqVluXW63BxUQACg8Z1xdbmR2KLgp_Rc79WIAzbSVNVEd7lQ

&nonce=635788649787252713.YjlmZjZmMzYtNzdmMi00N2FjLWEzOTEtY2VlNjgyZWJiMzIxMjY2M2JlOTctNjhlOS00Y2MzLTkxNTAtNGI1YWRiMjQxNjdj

HTTP/1.1

Note    The values of state and nonce are opaque to Azure AD B2C. These values are inserted and interpreted by your web application, and more specifically by the code that generated the request, here the OWIN middleware (see below).

As you now understand, the p policy parameter in this illustration invokes a sign-in policy called b2c_1_b2csignin. The OpenID Connect 1.0 response from Azure AD B2C contains an id_token as usual and as expected, carrying the claims you'll configured later in the policy as part of the suggested walkthrough:

POST https://localhost:44316/  

id_token= eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IklkVG9rZW5TaWduaW5nS2V5Q29udGFpbmVyIn0.eyJleHAiOjE0NDMyNzE3ODUsIm5iZiI6MTQ0MzI2ODE4NSwidmVyIjoiMS4wIiwiaXNzIjoiaHR0cHM6Ly9sb2dpbi5taWNyb3NvZnRvbmxpbmUuY29tLzVkZTk5NDE1LWY4N2YtNGQ0NC1iMjkzLWNhYzcwNTA4YmEyNC92Mi4wLyIsImFjciI6ImIyY18xX2IyY3NpZ25pbiIsInN1YiI6Ik5vdCBzdXBwb3J0ZWQgY3VycmVudGx5LiBVc2Ugb2lkIGNsYWltLiIsImF1ZCI6IjJhMjY4MWIxLWFjMjQtNGNiMy05ODI5LWNlMjMxNTUwMDExNyIsIm5vbmNlIjoiNjM1Nzg4NjQ5Nzg3MjUyNzEzLllqbG1aalptTXpZdE56ZG1NaTAwTjJGakxXRXpPVEV0WTJWbE5qZ3laV0ppTXpJeE1qWTJNMkpsT1RjdE5qaGxPUzAwWTJNekxUa3hOVEF0TkdJMVlXUmlNalF4TmpkaiIsImlhdCI6MTQ0MzI2ODE4NSwiYXV0aF90aW1lIjoxNDQzMjY4MTg1LCJuYW1lIjoiUGhpbGlwcGUgQmVyYXVkIChGYWNlYm9vaykiLCJpZHAiOiJmYWNlYm9vay5jb20iLCJvaWQiOiI5ZmE1OWZlYy04ZTMxLTRhMjYtOWIwOC0yY2NhMDUwNmMyZTciLCJzdGF0ZSI6IldBIiwicG9zdGFsQ29kZSI6Ijk4MDUyIn0.ACbKkxaXSm4ZqbjPqU74LTatTBENxV_9NysB88b0PAg0VNg3F2mTWEvynVGECpwi83K3AHoSSFEL2zrimPvwR5SbtQ-HmoASydyti12yzYM1Fso95uEvDK-GF0G56_HbqOizu2j7h_xQGl55aYrk5urCURFxIYZmLxEmIFsVr0z9kS8WiluOABxv6ItTgcc__2sCqaOimulABCVFPtOPkO1CePfnio34WUqMxkxVOeAvMXvR8VbvFUaiiGVOIAAcCnd7HBKRrnRpJSfyr4s4P6_vOhmgDQdsKnmPX4DBU747cYKxvLNn996CcdWJ4WI9M_dsG1MCJG8msvQvLLPXyg

Decoding the URLBase64 id_token from the response yields the following claims decoded in JSON:

Note     Since the JWT tokens issued by Azure AD B2C are signed but not encrypted, you can easily inspect the content of such a token for debugging purposes. There are several tools available to do so sur as the JWT Decoder and JWT.io.

{
 typ: "JWT",
 alg: "RS256",
 kid: "IdTokenSigningKeyContainer"
}.
{
 exp: 1443271785,
 nbf: 1443268185,
 ver: "1.0",
 iss: "https://login.microsoftonline.com/5de99415-f87f-4d44-b293-cac70508ba24/v2.0/",
 acr: "b2c_1_b2csignin",
 sub: "Not supported currently. Use oid claim.",
 aud: "2a2681b1-ac24-4cb3-9829-ce2315500117",
 nonce: "635788649787252713.YjlmZjZmMzYtNzdmMi00N2FjLWEzOTEtY2VlNjgyZWJiMzIxMjY2M2JlOTctNjhlOS00Y2MzLTkxNTAtNGI1YWRiMjQxNjdj",
 iat: 1443268185,
 auth_time: 1443268185,

 name: "Philippe Beraud (Facebook)",
 idp: "facebook.com",
 oid: "9fa59fec-8e31-4a26-9b08-2cca0506c2e7",
 state: "WA",
 postalCode: "98052"

}

Supporting the most common primary scenarios

Since Azure AD B2C is in fact at the core Azure AD, it unsurprisingly has the programming model.

Azure AD B2C provides or will soon provide a support for the following primary scenarios:

• Note    For more information, see articles Azure Active Directory B2C: Types of applications and Azure Active Directory B2C: Limitations and restrictions.
• Web browser to web application with OpenID Connect 1.0. A user needs to sign in to a web application (written in .NET, PHP, Java, Ruby, Node.js, etc.) that is secured by Azure AD B2C. For that purpose, the application issues an OpenID Connect 1.0 authentication request to Azure AD B2C as previously described, and obtain in return an ID token.

Note    For more information, see article Azure Active Directory B2C: Web sign-in with OpenID Connect.

• Web application to web API with OAuth 2.0 authorization code flow. A web application needs to get resources from a web API secured by Azure AD B2C. The application performs in this case a combined OpenID Connect 1.0 and OAuth 2.0 flow, and acquires tokens using authorization codes and refresh tokens.

Note    For more information, see article Azure Active Directory B2C: OAuth 2.0 authorization code flow.

Azure AD B2C no longer only supports web APIs that are accessed by their own well-known clients. So, in other words, all components are no longer compelled to share a single Client ID/Application ID with the support in public preview of access tokens.

Note    For more information, see blog post Azure AD B2C Access Tokens now in public preview and article Azure AD B2C: Requesting Access Tokens.

• Single Page Application (SPA) with the OAuth 2.0 implicit flow. A single page application (primarily written in JavaScript, and often using dedicated frameworks like AngularJS, Durandal, Ember.js, etc.) that uses Azure AD B2C to secure its web APIs back end.

Note    For more information, see article Azure Active Directory B2C: Sign-in for Single-Page Apps using OAuth 2.0 Implicit Flow.

• Mobile and native application to web API with OAuth 2.0 authorization code flow. A mobile or native application that runs on a phone, tablet, or PC needs to authenticate a user to get resources from a web API that is secured by Azure AD B2C.
• Daemon or server side processes to web API with the OAuth 2.0 client credentials flow (coming soon). A daemon application or a server side process with no web user interface needs to get resources from a web API secured by Azure AD B2C.

  Such applications can authenticate and get tokens using an application's identity (rather than using a user's delegated identity) with the OAuth 2.0 client credentials flow. This scenario isn't yet available in Azure AD B2C since applications can only get tokens after an interactive user flow has occurred.

  Support for the client credentials flow will be added in the near future.

  • Standalone web APIs. See above.

Leveraging the Azure AD v2.0 endpoints

From a programming standpoint, Azure AD B2C conforms to Azure AD's next generation app model: the Azure AD v2.0 endpoints (a.k.a. Azure AD app model v2.0).

Note    For more information, see articles What's different about the v2.0 endpoint?, App types for the Azure Active Directory v2.0 endpoint, v2.0 Protocols - OAuth 2.0 & OpenID Connect, and Azure Active Directory v2.0 tokens reference.

The Azure AD v2.0 endpoints allow you to make protocol calls directly by constructing the HTTP messages necessary to communicate with the Azure AD B2C endpoints. This makes identity management possible on virtually almost every platform and device.

Moreover, there are many open sources libraries available for validating JWT tokens depending on the language of your choice.

Leveraging standard–based development platform and developer libraries

Many developers would rather use language-specific APIs rather than looking at the HTTP payload. Others work in organizations where use of APIs has been mandated,

For them, Azure AD B2C allows leveraging standard–based development platform and developer libraries that already support the app model v2.0 and that take care in this context of the "ugly" protocol details for you. The following table gives you some examples of such client libraries of server-side SDKs.

In addition, the same REST-based Azure AD Graph API based management capabilities as Azure AD - including users and groups - can be used in this context from any platform so that your application can make an informed access control decision about a transaction requested by the signed end user.

Note     Azure AD Graph API is a RESTful API that provides a directory programming surface for querying and updating the directory, and thus to sustain the identities lifecycle management as whole. For more information, see articles Azure AD B2C: Use the Graph API and Azure AD Graph API REST.

You can complete one of the quick start tutorials provided by the Azure AD B2C documentation to get up and running with the above developer libraries.

Note    For more information, see section § Build a Quick Start Application of the article Azure Active Directory B2C: how to Register your Application.

All the quick start applications are available on GitHub on at https://github.com/AzureADQuickStarts/.

To easily identify the code samples in the repo, their name starts with the B2C- prefix such as the B2C-WebApp-WebAPI-OpenIDConnect-DotNet project, a.NET MVC web application code sample, secured by Azure AD B2C, that calls a web API.

Now that you're equipped with some understanding on how to integrate your consumer facing applications, let's continue by an exploration of the service.

Note    For the latest information that pertains to how to integrate applications and APIs in Azure AD B2C as covered in this document, please refer to the related section of the Azure AD B2C section of the Azure Active Directory Developer's Guide. This online developer's guide indeed constitutes the de-facto reference content on this subject by providing overviews on implementation, key features, and protocols of Azure AD (B2C).

Interestingly enough, it also provides a collection of quick start guides with complete instructions to perform fundamental development tasks with Azure AD (B2C), designed to help you getting up and running as efficiently as possible.

You can also see the whitepaper Leveraging Azure AD for modern business applications in the same series of document.

Important note    if needed, and beyond and above information, you can get help on Stack Overflow using the azure-active-directory or adal tags.

Programmatically managing your users

You can use the Azure AD Graph API for programmatic user management, i.e., to create, read, update and delete (CRUD) local accounts in your B2C tenant.

The Azure AD Graph API provides REST interfaces for that purpose. This feature is available on a major version, e.g. 1.6 of the API.

Note     For more information, see article Azure AD Graph API REST.

POST https://graph.windows.net/contoso369b2c.onmicrosoft.com/users?api-version=1.6
{
    "accountEnabled": true,
    "SignInNames": [     // Controls what identifier the user uses to sign into their account
       {
           "type": "emailAddress",       // Can be 'emailAddress' or 'userName'
           "value": "joedoe@gmail.com"
       }
    ],
    "creationType": "LocalAccount",      // Always set to 'LocalAccount'
    "displayName": "Joe Doe",              
    "mailNickname": "joe",                     
    "passwordProfile": {
              "password": "Pass@word1",
               "forceChangePasswordNextLogin": false
    },
    "passwordPolicies": "DisablePasswordExpiration"
}

Note    For more information, see article Azure AD B2C: Use the Graph API.

Programmatically getting access to consumer activity reports

Finally, for this introduction of Azure AD B2C, you can leverage the REST-based Azure AD reporting API to get access to rich consumer activity reports.

Note    For more information, see article Getting started with the Azure Active Directory reporting API of the Azure AD Reporting Guide.

You can easily pipe the data from these reports into business intelligence and analytics tools, such as Microsoft Power BI, for detailed analyses.

As of this writing, the following four activity reports are currently available:

• tenantUserCount. Total number of consumers in your Azure AD B2C tenant (per day for the last 30 days). You can also get a breakdown by the number of local accounts (password-based accounts) and social accounts (Facebook, Google, etc.).
• b2cAuthenticationCount. Total number of successful authentications (sign-up, sign-in, etc.) within a specified period.
• b2cAuthenticationCountSummary: Daily count on successful authentications for the last 30 days.
• b2cMfaRequestCountSummary. Daily count of multi-factor authentications (MFA) for the last 30 days.

Note    For more information, see article Accessing usage reports in Azure AD B2C via the reporting API.

Getting started with Azure AD B2C

The following end-to-end walkthrough from creating a new B2C tenant to successfully running a B2C web application registered on that B2C tenant illustrates the various features of Azure AD B2C.

Note    For more information, see article Azure Active Directory B2C: Sign up and sign in consumers in your applications, and the link https://azure.microsoft.com/en-us/trial/get-started-active-directory-b2c/.

Getting an Azure subscription

An Azure AD B2C test directory can be created through an Azure Subscription. This subscription is only needed to access the Azure portal.

Note    If you don't already have an Azure subscription, you can sign-up for a free one-month trial Azure account by following the link https://azure.microsoft.com/en-us/free/.

Creating an Azure AD B2C directory

Note    For more information, see article Azure Active Directory B2C: Create an Azure AD B2C tenant.

Creating a new Azure AD B2C tenant

Important note    As of this writing, B2C features can't be turned on in your existing directories, if you have any. It is thus required that you create a new directory to try out the Azure AD B2C service, rather than re-using one of your existing organizational tenants.

To create a new Azure AD B2C tenant, proceed with the following steps:

1. Open a browsing session and navigate to the Azure portal at https://portal.azure.com/.

1. Sign in to the Azure portal as the Subscription admin user. This is for instance the same Microsoft Account that you used to sign up for Azure as per previous section.
2. Click New (or the + button if collapsed) and in Search the marketplace, type "Azure Active Directory B2C" and press ENTER.

1. In the result, click Azure Active Directory B2C. A new blade opens with the details on Azure AD 2C.

1. Click Create to start configuring a new Azure Active Directory B2C tenant.

1. In Select New or Existing Tenant, click Create a new Azure AD B2C Tenant. An Azure AD B2C Create Tenant blade opens.

1. Configure the basic properties for your new B2C tenant, i.e. its name, default domain name, and the country or region as follows:

• In Organization name, choose a name for the B2C directory (that will help distinguish it from your other directories in your Azure subscription), for example in our illustration "Contoso 369 Corporation".
• In Initial domain name, choose a default domain name which you can use to bootstrap usage of this B2C directory, for example "contoso369b2c.onmicrosoft.com".
• In Country or region, choose a country or region for your B2C directory. This setting is used by Azure AD to determine the datacenter region(s) for your B2C directory. It cannot be changed later.

1. Click Create to create your B2C tenant. This may take a few minutes, you will be alerted in your notifications when it is complete.

Your user account is included in that new B2C tenant, and you're assigned to the global administrator role. (Other administrator can be added later as required.)

This enables you to manage the B2C tenant you created without signing in as a different user of that directory.

For the course of this walkthrough, we've created the contoso369b2c.onmicrosoft.com B2C directory/tenant. You will have to choose in lieu of a B2C directory name of your choice whose name is currently not in used.

Whenever a reference to contoso369b2c.onmicrosoft.com is made in a procedure, it has to be replaced by the B2C directory name of your choice to reflect accordingly the change in naming.

Navigating to the B2C features blade

You can directly navigate to the B2C settings blade of your B2C tenant using the following URL:

https://portal.azure.com/<NewlyCreatedDomain>.onmicrosoft.com/?Microsoft_AAD_B2CAdmin=true#blade/Microsoft_AAD_B2CAdmin/TenantManagementBlade/id/<NewlyCreatedDirectory>.onmicrosoft.com

And sign in with the Admin credentials, where <NewlyCreatedDirectory> is the B2C tenant you've created, for example in our illustration:

https://portal.azure.com/contoso369b2c.onmicrosoft.com/?Microsoft_AAD_B2CAdmin=true#blade/Microsoft_AAD_B2CAdmin/TenantManagementBlade/id/contoso369b2c.onmicrosoft.com

An enabled Browse entry point on the Azure Admin portal is also available to improve discoverability of B2C Admin features.

When signed in with the Admin credentials of your B2C tenant, click Browse on the left hand navigation, and then Azure AD B2C to access the B2C settings blade. If you are already signed in to a different tenant, switch tenants (on the top-right corner).

Configuring the local account provider

A local account provider is created by default on your newly created B2C tenant.

To select how to create local accounts, proceed with the following steps:

1. Switch back to the B2C features blade or navigate to the related URL (see above).
2. On the B2C features blade, click Identity providers. An Identity providers blade opens.

1. In Local accounts, choose how users will create their accounts local to this B2C tenant:
   1. Email (default). Users will be prompted for an email address which will be verified at sign-up and become their user identifier.
   2. Username. Users may create their own unique user identifier. An email address will be collected from the user and verified at sign-up.

Configuring social identity providers

You now have to proceed with the configuration of the social identity providers you want to use on your B2C tenant. Before you complete the configuration, you need to create first application registrations on the related social identity provider developer portals and supply them with the right parameters to work properly with the Azure AD B2C service.

This section shows you how to configure Facebook and Google+ as social identity providers on your B2C tenant.

Note    For more information, see articles Azure Active Directory B2C: Provide sign-up and sign-in to consumers with Facebook accounts, and Azure Active Directory B2C: Provide sign-up and sign-in to consumers with Google+ accounts.

Note    For instructions on configuring Amazon, LinkedIn an Microsoft Accounts, see articles Azure Active Directory B2C: Provide sign-up and sign-in to consumers with Amazon accounts, Azure Active Directory B2C: Provide sign-up and sign-in to consumers with LinkedIn accounts, Azure Active Directory B2C: Provide sign-up and sign-in to consumers with Microsoft accounts^.

Creating a Facebook application

To use Facebook as a social identity provider in Azure AD B2C, you will first need to create a Facebook application and supply it with the right parameters.

You need a Facebook account to perform the following steps. If you don't have one, create one at https://www.facebook.com/.

To create a Facebook application, proceed with the following steps:

1. Open a separate browser window / tab and navigate to the Facebook Developers website at https://developers.facebook.com/. Click Log In in the toolbar.

1. Sign-in with your Facebook account credentials.
2. If you have not already registered, click My Apps.
3. Click Register as a Developer.
4. Accept the policy and follow the registration steps.
5. Click My Apps, and then Add a New App. An eponym dialog shows up.

1. Choose Website as the platform, and then click Skip and Create App ID in the upper right corner. A Create a New App ID dialog shows up to register the "app" with Facebook.

1. Fill out the relevant details in the dialog.
   1. In Display Name, type a name for your B2C tenant, for example in our configuration "Contoso369 B2C directory".
   2. In Category, select Business.
   3. Click Create App ID.
   4. In the Security Check dialog, select all the appropriate photos, and then select Submit.
2. Once the application is created, a dashboard is displayed.

1. Click Settings on the left hand navigation.

1. In Contact Email, specify a valid email.
2. Click Add Platform. A Select Platform dialog shows up.

1. Select Website. A Website pane is added.

1. In Site URL field, type in "https://login.microsoftonline.com/".
2. Click Save Changes.
3. You will need the value of both App ID and App Secret to configure Facebook as a social identity provider in your B2C tenant. Note down these values that will be later respectively referred as to the "Client ID" and "Client Secret" values.
   1. Copy the value of App ID.

1. Click Show in App Secret. A Please Re-enter Your Password security dialog shows up.

Note     App Secret is an important security credential.

1. Re-enter your password and click Submit. Copy the value of App Secret.

1. Click Advanced.

1. As invited, you should configure a valid OAuth redirect URI. Scroll down to Client OAuth Settings.

1. In Valid OAuth redirect URIs, you will need to specify:

https://login.microsoftonline.com/te/<YourDirectory>.onmicrosoft.com/oauth2/authresp

where <YourDirectory> is the B2C tenant you've created, for example in our illustration:

https://login.microsoftonline.com/te/contoso369b2c.onmicrosoft.com/oauth2/authresp

1. Click Save Changes at the bottom of page after you are done.
2. Finally, in order to make this Facebook application usable by Azure AD B2C, you need to grant general public access to it:
   1. Click Status & Review on the left navigation.

1. Select Yes in the access switch. A Make App Public dialog shows up.

1. Click Confirm.

Creating a Google application

You need a Google account perform the following steps. If you don't have one, you can get it at https://accounts.google.com/SignUp.

To create a Google application, proceed with the following steps:

1. Navigate to the Google Developers Console at https://console.developers.google.com/ in a separate browser window or tab and sign-in with your Google account credentials.
2. From the Google Developers Console toolbar, click Select a project, and then select Create a project...

1. A New Project dialog shows up to registers the application with Google.

1. In Project name, type a name for your B2C tenant, for example in our configuration "Contoso369 B2C directory". The Project ID will then be "contoso369-b2c-directory".
2. Check I agree that my use of any services and related APIs is subject to my compliance with the applicable Terms of Service.
3. Click Create. An activity is then executed to create the project.
4. Wait until the activity completion.

1. Once the application is created, a dashboard is displayed.

1. Click APIs & auth on the left hand navigation, and then select Credentials underneath.
2. Click Add credentials.

1. Click OAuth 2.0 client ID. A Create Client ID page shows up.

1. Click Configure consent screen.

1. In Product Name, type a product name, for example in our configuration "Contoso369 B2C directory".
2. Click Save.
3. Select Web Application.

1. In Authorized JavaScript origins, specify the following JavaScript origin: https://login.microsoftonline.com
2. In Authorized Redirects URIS, specify the following Redirect URI:

   "https://login.microsoftonline.com/te/<YourDirectory>.onmicrosoft.com/oauth2/authresp"

   where <YourDirectory> is the B2C tenant you've created, for example in our illustration:

   https://login.microsoftonline.com/te/contoso369b2c.onmicrosoft.com/oauth2/authresp

Note    URI must be all lower case. Upper case character cause redirect URI mismatch error.

1. Click Create. An OAuth client dialog shows up.

1. Note down the values of client ID and client secret. You will need the value of both client ID and client Secret to configure Google as a social identity provider in your B2C tenant. Note down these values that will be later respectively referred as to the "Client ID" and "Client Secret" values.

Note    Client Secret is an important security credential.

1. Click OK.

Configuring Facebook and Google as social identity providers in your B2C tenant

To configure both Facebook and Google on your B2C tenant, proceed with the following steps:

1. Switch back to the B2C features blade or navigate to the related URL, for example in our illustration:

   https://portal.azure.com/ contoso369b2c.onmicrosoft.com/?Microsoft_AAD_B2CAdmin=true#blade/Microsoft_AAD_B2CAdmin/TenantManagementBlade/id/contoso369b2c.onmicrosoft.com

2. On the B2C features blade, click Identity providers. An Identity providers blade opens.

1. Click Add at the top of the blade.

1. In the Add social identity provider blade, provide a friendly name for the social identity provider configuration, for example "Facebook (Contoso 369)".
2. Click Identity provider type, a Select social identity provider blade openss.

1. Select Facebook, and then click OK.
2. Click Set up this identity provider. An eponym blade opens.

1. Enter respectively in Client ID and Client secret the "Client ID" and "Client Secret" values you received during the creation of the Facebook application.
2. Click OK, and then click Create to save the configuration.
3. Repeat the same steps for Google and use the "Client ID" and "Client Secret" values noted down during the creation of the Google application.

1. Close the Identity providers blade. Leave the B2C features blade open.

Registering an application on your B2C tenant

Note    For more information, see article Azure Active Directory B2C: Register your application.

To register an application on your B2C tenant, proceed with the followings steps:

1. On the B2C features blade on the Azure Portal, click Applications.
   1. Click Add at the top of the blade. A Relying Party App Information blade shows up.

1. In Name, provide an application name that will describe your application to consumers, for example in our configuration "Contoso 369 B2C App".
2. Since we're going to configure a web-based application later in this document, toggle the Include web app / web API switch to Yes.

Note    If you are rather writing a mobile application, toggle the Include native client switch to Yes. Copy down the default Redirect URI automatically created for you.

1. In Reply URLs, type "https://localhost:44316", which the default value of the sample web application provided. Reply URLs are endpoints where Azure AD B2C will return any tokens your application requests.

Note    If the application top register also includes a web API that needs to be secured, you'll want to create (and copy) an Application Secret as well by clicking Generate key.

1. Click Create to register your application.
   1. Click the application that you just created and Note down the application's globally unique Application Client ID that you'll use later in the application's code: 197da538-760c-4868-afca-94bd5e40b0c1.

1. This value will be later referred as to the "Application Client ID" value.

Creating policies using default user journeys

As covered before, you can create policies for the Sign up, Sign in, and Profile Editing user journeys. Such policies describe the experiences that users will go through during respectively sign up, sign in, and profile editing.

Let's start with the sign-up policy and the related operations and steps.

Creating and running a sign-up policy

A sign-up policy describes the journeys that users will go through during sign up and the contents of tokens that the application will receive on successful sign ups.

Note    For more information, see article Azure Active Directory B2C: Extensible policy framework.

To create a sign-up policy, proceed with the following steps:

1. On the B2C features blade, click Sign-up policies,
2. Click Add at the top of the blade. An Add sign-up policy blade opens.

1. In Name, type a name for the policy, for example in our illustration "B2CSignUp". This name determines the sign-up policy name used by your application.
2. Click Identity providers. A Select identity providers blade opens.

1. Select Google (Contoso 369) to allow users to sign up with their existing Google account.
2. Select Facebook (Contoso 369) to alternatively allow users to sign up with their existing Facebook account.
3. Select Email signup to alternatively allow users to sign up and create a local account with their email address.
4. Click OK.

1. Click Sign-up attributes to choose attributes that you want to collect from the user during sign up. A Select sign-up attributes opens.

1. For the purpose of this walkthrough, select City, Display Name, and Postal Code, and State/Province. This will construct the web form that the end user sees during sign up.
2. Click OK.

1. Click Applications claims. An Application claims opens.

1. Select City, Display Name, Emails, Identity Provider, Postal Code, State/Province, and User's Object ID. After an end user signs up, these claims are sent back to the app in a token.
2. Click OK.

1. Click Create to complete the creation of the sign-up policy.

A B2C_1_ fragment is added to the front of the policy name you've specified in the steps above: B2C_1_SignUp.

You can click on the policy that you just created and click Run Now to experience the self-service sign up flow without a single line of code.

To test the policy, proceed with the following steps:

1. Click the B2C_1_B2CSignUp policy. An eponym blade opens.

1. In Select application to run policy, select Contoso 369 B2C App.
2. in Select Redirect URI, select https://localhost:44316.
3. Click Run now. A new browser tab opens and you can run through the user journey of signing up for your application (line split for readability):

https://login.microsoftonline.com/contoso369b2c.onmicrosoft.com/oauth2/v2.0/authorize

?p=B2C_1_B2CSignUp

&client_Id=2a2681b1-ac24-4cb3-9829-ce2315500117

&nonce=defaultNonce

&redirect_uri=https%3A%2F%2Flocalhost%3A44316

&scope=openid

&response_type=id_token

&prompt=login

1. Go back to the browser tab where the Azure Portal is open. Close the two blades just opened.
2. Leave the B2C features blade open.

Finally, the policy blade enables you to export and download the newly created policy as an XML file as mentioned before.

To download the policy, proceed with the following steps:

1. Click Download at the top of the blade.

You're the invited to save an <YourDirectory>.onmicrosoft.com-B2C_1_<YourPolicyName>.xml file for the B2C_1_<YourPolicyName> policy in the <YourDirectory>.onmicrosoft.com tenant.

1. Click Save.
2. Open the contoso369b2c.onmicrosoft.com-B2C_1_B2CSignUp.xml XML file.

Creating a sign-in policy

A sign-in policy describes the journeys that that users will go through during sign in and the contents of tokens that the application will receive on successful sign ins.

Note    For more information, see article Azure Active Directory B2C: Extensible policy framework.

To create a sign-in policy, proceed with the following steps:

1. On the B2C features blade, click Sign-in policies. An eponym blade opens.
2. Click Add at the top of the blade. An Add sign-in policy blade opens.

1. In Name, type a name for the policy, for example in our illustration "B2CSignIn".
2. Click Identity providers. A Select identity providers blade opens.

1. Select Google (Contoso 369), and Facebook (Contoso 369) to allows users to sign in with their existing Google or Facebook account.
2. Also select Local Account SignIn to alternatively allow users to sign in with their email address.
3. Click OK.

1. Click Application claims to choose the claims that you want returned in the tokens back to your application after a successful sign in journey. A select applications claims blade opens.

1. Select Display Name, Identity Provider, Postal Code, State/Province, and User's Object ID. After an end user signs in, these claims are sent back to the app in a token.
2. Click OK.

1. Click Create to create the policy.

As previously outlined, the B2C_1_ fragment is automatically added as a prefix to the name of the policy: B2C_1_B2CSignIn. Run now allows you to test the policy you've just created and consequently to experience the sign in flow without a single line of code.

1. Close the blade just opened. Leave the B2C features blade open.

Creating a profile editing policy

Creating a profile editing policy is similar to creating a self-service sign up policy.

Note    For more information, see article Azure Active Directory B2C: Extensible policy framework.

To create a profile editing policy, proceed with the following steps:

1. On the B2C features blade, click Profile editing policies,
2. Click Add at the top of the blade. An Add profile editing policy blade opens.

1. In Name, type a name for the policy, for example in our illustration "B2CUserProfileUpdate".
   1. Click Identity providers. A Select identity providers blade opens.

1. Select Google (Contoso 369), and Facebook (Contoso 369) to allows users to sign in with their existing Google or Facebook account. Also select Local Account SignIn to alternatively allow users to sign in with their email address.
2. Click OK.

1. Click Profile attributes. A Select profiles attributes blade opens.

1. Select City, Display Name, Postal Code, and State/Province.
2. Click OK.

1. Click Application claims. A Select application claims blade opens.

1. Select City, Display Name, Postal Code, State/Province, and User's Object ID.
2. Click OK.

1. Click Create.

   The B2C_1_ fragment is automatically added as a prefix to the name of the policy: B2C_1_B2CUserProfileUpdate. As before, Run now allows you to test the policy you've just created Close the blade just opened. Leave the B2C features blade open.

Noting down the policy IDs

Note    All policies have the B2C_1_ fragment added to the front of all the policy names you created in the steps above.

Capture policy names to add to the web sample in the step below, for example in our illustration:

• The "Application Client ID" value, i.e. 2a2681b1-ac24-4cb3-9829-ce2315500117 (See section § Register an application on your B2C tenant)
• B2C_1_B2CSignUp
• B2C_1_B2CSignIn
• B2C_1_B2CUserProfileUpdate

Configuring and running a sample application

Now that you have an application registered with Azure AD B2C, and "suitable" policies defined, you can add, configure, and run a sample application on your favorite platform and IDE.

For that purpose, you can complete one of the quick start tutorials provided by the Azure AD B2C documentation to get up and running.

Note    For more information, see section § Build a Quick Start Application of the article Azure Active Directory B2C: how to Register your Application.

For the purpose of this overview, we will use the .NET MVC sample application.

Note    For more information, see article Azure AD B2C: Build a .NET web app.

Installing Visual Studio Community 2015

Visual Studio Community 2015 is a free, fully-featured, and extensible IDE for creating modern applications for Windows, Android, and iOS, as well as web applications and APIs, and cloud services.

To install Visual Studio Community 2015, proceed with the following steps:

1. Open a browsing session and navigate to https://www.visualstudio.com/vs/community/.
2. Click Download Community 2015.

1. Click Save to download the setup file (vs_community_ENU__1511326103.1482352600.exe file).
2. Click Run, and follow the instructions to setup the environment.

Getting a sample application from the GitHub

For the purpose of this walkthrough, we are going to build and add a sample .NET MVC web application. The code for this sample application is maintained on GitHub: B2C-WebApp-OpenIdConnect-DotNet.

However, for the sake of brevity, we will use an almost completed version for this sample application.

Note    To build the sample as you go, you can instead download a skeleton project as a .zip or clone the skeleton:

git clone --branch skeleton https://github.com/AzureADQuickStarts/B2C-WebApp-OpenIdConnect-DotNet.git

Related instructions are provided in above article Azure AD B2C: Build a .NET web app.

To get this almost completed sample application, proceed with the following steps:

1. Download the B2C-WebApp-OpenIdConnect-DotNet-complete.zip file from GitHub and save it to your computer if you haven't done so already.

1. Click Save and save it on your computer.
2. Extract the B2C-WebApp-OpenIdConnect-DotNet-complete.zip file.

Configuring the sample application

We will configure the sample to use the sign-up, sign-in, and update profile policies created in the B2C tenant. This will allow the sample B2C-WebApp-OpenIdConnect-DotNet application to issue sign-up and sign-in requests to the Azure AD B2C service.

The OpenID Connect OWIN middleware (Microsoft.Owin.Security.OpenIdConnect) enables the sample application to seamlessly use OpenID Connect for authentication. This middleware is available as NuGet package for the Visual Studio development environment.

To configure the sample application, proceed with the following steps:

1. Open the solution in Visual Studio Community 2015.

• Click File | Open | Project/Solution
• Navigate to the extracted complete.zip file

1. Open the WebApp-OpenIDConnect-DotNet-B2C.sln solution file.
2. Open the Solution Explorer if it's not already the case.

1. The References section of the WebApp-OpenIDConnect-DotNet-B2C shows a series of unresolved references with an exclamation mark.
2. Under WebApp-OpenIDConnect-DotNet-B2C, right-click References, and then select Manage NuGet Packages... to (try to) resolve them. A NuGet window opens and is docked as a tabbed document.

1. Click Restore. The missing NuGet packages are then downloaded to resolve the above unresolved references.

1. Back to the Solution Explorer window, select WebApp-OpenIDConnect-DotNet-B2C
2. Open the web.config file in the root folder of the project.

<?xml version="1.0" encoding="utf-8"?>
<!--
  For more information on how to configure your ASP.NET application, please visit
  http://go.microsoft.com/fwlink/?LinkId=301880
  -->
<configuration>
   <appSettings>
    <add key="webpages:Version" value="3.0.0.0" />
    <add key="webpages:Enabled" value="false" />
    <add key="ClientValidationEnabled" value="true" />
    <add key="UnobtrusiveJavaScriptEnabled" value="true" />
     <add key="ida:Tenant" value="[Enter the name of your B2C tenant, e.g. contoso.onmicrosoft.com]" />
    <add key="ida:ClientId" value="[Enter the Application Id assinged to your app by the Azure portal, e.g.580e250c-8f26-
                                    49d0-bee8-1c078add1609]" />
    <add key="ida:AadInstance" value="https://login.microsoftonline.com/{0}{1}{2}" />
    <add key="ida:RedirectUri" value="https://localhost:44316/" />
    <add key="ida:SignUpPolicyId" value="[Enter your sign up policy name, e.g. b2c_1_sign_up" />
    <add key="ida:SignInPolicyId" value="[Enter your sign in policy name, e.g. b2c_1_sign_in]" />
    <add key="ida:UserProfilePolicyId" value="[Enter your edit profile policy name, e.g. b2c_1_profile_edit" />
  </appSettings>
  …
</configuration>

1. In web.config, find 'ida:Tenant' and replace the value with your B2C tenant name, for example in our configuration "contoso369b2c.onmicrosoft.com".
2. Find the app key 'ida:ClientId' and replace the value with the "Application Client ID" value you copied from the B2C features blade "197da538-760c-4868-afca-94bd5e40b0c1".
3. Leave "ida:RedirectUri" as-it: "https://localhost:44316/".
4. Replace the value in the 'ida:SignUpPolicyId', 'ida:SignInPolicyId', and 'ida:UserProfilePolicyId' by the name of the corresponding previously created policy, for example in our configuration "B2C_1_B2CSignUp", "B2C_1_B2CSignIn", and "B2C_1_B2CUserProfileUpdate".

<?xml version="1.0" encoding="utf-8"?>
<!--
  For more information on how to configure your ASP.NET application, please visit
  http://go.microsoft.com/fwlink/?LinkId=301880
  -->
<configuration>
  <appSettings>
    <add key="webpages:Version" value="3.0.0.0" />
    <add key="webpages:Enabled" value="false" />
    <add key="ClientValidationEnabled" value="true" />
    <add key="UnobtrusiveJavaScriptEnabled" value="true" />
    <add key="ida:Tenant" value="contoso369b2c.onmicrosoft.com" />
    <add key="ida:ClientId" value="197da538-760c-4868-afca-94bd5e40b0c1" />
    <add key="ida:AadInstance" value="https://login.microsoftonline.com/{0}{1}{2}" />
    <add key="ida:RedirectUri" value="https://localhost:44316/" />
    <add key="ida:SignUpPolicyId" value="B2C_1_B2CSignUp" />
    <add key="ida:SignInPolicyId" value="B2C_1_B2CSignUp" />
    <add key="ida:UserProfilePolicyId" value="B2C_1_B2CUserProfileUpdate" />
  </appSettings>
  …
</configuration>

1. Save the file. Click File | Save All.

Running the sample application

You are almost done securing the sample application with Azure AD B2C.

To run the sample application, proceed with the following steps:

1. Clean the Visual Studio solution. Click Build | Clean Solution.

1. Rebuild the Visual Studio solution. Click Build | Rebuild Solution.
2. Run the sample application. Press F5 to run the solution.

Signing up to sample application

To sign up to sample application, click Sign up. You're redirected to an identity provider selection page provided by Azure AD B2C as per B2C_1_B2CSignUp policy.

Signing up as a Facebook account

To sign up as a Facebook account, proceed with the following step:

1. Click the Facebook icon. You are now redirected to Facebook to log in.

1. Enter your Facebook credentials, and then click Log In.

1. Click Okay. You're redirected back to a social account sign-up page provided by Azure AD B2C as per B2C_1_B2CSignUp policy.

1. Complete the form and click Create. Whist your account is being created, the following message is displayed: "Hold on while we finish setting up your account and signing you in". Once completed, you're now logged in the application.

1. Click Claims in the upper left corner after sign-up to see the contents of tokens received.

1. Click the display name in the upper right corner, and then select Edit Profile. You're redirected back to a profile update page provided by Azure AD B2C as per B2C_1_B2CUserProfileUpdate policy.

1. Click Cancel, and then click Sign out in the upper right corner. Do not close the running sample application.

Signing up as a Google account

To sign up as a Google account, proceed with the following step:

1. Whilst still in the sample application, click Sign in, and then click this time the Google icon. You are now redirected to Google to sign in.

1. Enter your Google email address, and then click Next.

1. Enter your Google account credential, and then click Sign in.

1. Click Allow. You're redirected back to a page.

1. Complete the form, and then click Create. Once the account has been created in your B2C tenant, you're now logged in the application.
   1. Click Sign out in the upper right corner.

Signing up as a B2C tenant local account

To sign up as a local account, proceed with the following step:

1. Whilst still in the sample application, click Sign in, and then click this time Email signup. You're redirected back to a local account sign-up page provided by Azure AD B2C as per B2C_1_B2CUserProfileUpdate policy.

1. Click Send verification code.

1. In Verification code, enter the received code, and then click Verify code.

1. Click Create. While your account is being created, the following message is displayed: "Hold on while we finish setting up your account and signing you in".
2. Click Sign out in the upper right corner.

Viewing the users of the B2C tenant

If you've followed the instructions provided in the previous section, you should now have some users created in the B2C tenant.

To view the users of the B2C tenant, proceed with the following steps:

1. Switch back to the (classic) Azure portal or navigate to it at https://manage.windowsazure.com. Sign in as the Subscription Administrator if needed. This is the same work or school account or the same Microsoft Account that you used to create your B2C tenant above.
2. Navigate to the B2C tenant on the ACTIVE DIRECTORY extension by clicking in our configuration Contoso 369 Corporation.
3. Click USERS.

End users that signed up with a social identity are listed as cpim_<user#>@<YourDirectory>.onmicrosoft.com, where <YourDirectory> is the B2C tenant you created, and <user#> an allocated user number, for example in our configuration: cpim_964916140232284@contoso369b2c.onmicrosoft.com.

Likewise, end users that signed up locally with a verified address mail are listed as <VerifiedEmailAddress>1#EXT#@<YourDirectory>.onmicrosoft.com, <VerifiedEmailAddress> is the verified email address where @ is replaced by an underscore.

Adding Multi-Factor Authentication

As previously depicted, Azure AD B2C integrates directly with Azure MFA to allow you to smoothly add an additional factor of authentication to sign-up and sign-in experiences in your consumer-facing applications

Note    For more information, see article Azure Active Directory B2C: Enable Multi-Factor Authentication in your consumer-facing applications.

https://portal.azure.com/contoso369b2c.onmicrosoft.com/?Microsoft_AAD_B2CAdmin=true#blade/Microsoft_AAD_B2CAdmin/TenantManagementBlade/id/contoso369b2c.onmicrosoft.com

1. Click Sign-up policies.
   1. Click the previously configured B2C_1_B2CSignUp sign-up policy to open it.

1. Click Edit at the top of the blade, and then click Multifactor authentication.

1. Toggle State to ON.
2. Click OK.
3. Click Save at the top of the blade.

A consumer account gets created in your B2C tenant before the multifactor authentication step occurs. During the step, the consumer is asked to provide their phone number and verify it. If verification is successful, the phone number is attached to the consumer account for later use. Even if the consumer cancels or drops out, the consumer can be asked to verify a phone number again during next sign-in (with multifactor authentication enabled).

Modifying the sign-in policy to enable multi-factor authentication

To enable a multi-factor authentication in the sign-in policy, repeat steps 1 to 6 of the previous section but select this time the previously configured B2C_1_B2CSignIn sign-in policy.

Let's see the user's experience since for the moment no phone number has been attached to the already created accounts.:

1. Whilst still in the sample application – or rerun it from Visual Studio if needed -, click Sign in. You're redirected to an identity provider selection page provided by Azure AD B2C as per B2C_1_B2CSignIn policy.
2. Click for example the Facebook icon. You are now redirected to Facebook to log in.
3. Once logged in, you're redirected back to a multifactor authentication page as per above policy.

Since no phone number is attached to the account, you're asked to provide one and verify it.

1. Specify your phone number, and then click Send Code. The following message is displayed: "We're sending you a text message at <ProvidedPhoneNumber>".

1. Once received, enter the verification code, and then click Verify Code. The following message is displayed: "We're verifying the code sent to <ProvidedPhoneNumber>".
2. On successful verification, you're logged in. In the meantime, the verified phone number has been attached for later use to the related account in the B2C tenant.
3. Click Sign out in the upper right corner, and then click Sign in again.
4. Select the Facebook icon again. As the result of the roundtrip, you're redirected to the multifactor authentication page as per policy.

1. Click Send Code again. Enter the new verification code, and then click Verify Code. On successful verification, you're logged in.

Resetting a local account password

Azure AD B2C provides a self-service password reset (SSRP). This feature allows the users who have signed up for local accounts to reset their passwords on their own.

As on can easily imagine, this significantly contributes to reduce the burden on your organization's support staff, especially if your application has millions of consumers using it on a regular basis. However, your B2C tenant will not have the self-service password reset capability turned on by default.

Note    For more information, see article Azure Active Directory B2C: Set up self-service password reset for your consumers.

Enabling self-service password reset

To turn it on, proceed with the following steps:

1. Switch back to the (classic) Azure portal or navigate to it at https://manage.windowsazure.com.
2. Navigate to the created B2C tenant on the ACTIVE DIRECTORY extension by clicking in our configuration Contoso 369 Corporation.
3. Click CONFIGURE.
4. Scroll down to the user password reset policy section.

1. Toggle users enabled for password reset to YES.

1. Please note that Alternate Email Address is checked. As of this writing, only using a verified email address as a recovery method is supported. One can expect additional recovery methods (verified phone number, security questions, etc.) in the future.

   Leave it as-is.

2. Click SAVE at the bottom of the tray.

Performing a self-service password reset

To perform a self-service password reset, proceed with the following steps:

• Whilst still in the sample application – or rerun it from Visual Studio if needed -, click Sign in.
• Select Local Account Signin.

• On the local account sign-in page, click Can't access your account?. You're redirected to a Get back into your account page at https://passwordreset.microsoftonline.com.

• Specify your user ID, pass the captcha, and then click Next.

• Click Email. An account email verification code email is then sent to the verified email address of your local account.
• Enter the received verification code, and then click Next to proceed with the verification step. You're now allowed to choose a new password.

• Enter a new password and confirm it. The password will be validated based on the password policy of the tenant, and a strength validator appears to indicate to the user whether the password entered meets that policy.

• Click Finish. Once you provide matching passwords that meet the organizational policy, your password is reset and you can log in with your new password immediately.

A password rest notification mail is sent in parallel to the verified email account.

• Click click here to sign in. You're redirected to the local account sign-in page.

• Enter your new credentials and click Sign in. You should now be able to sign in.

Collecting additional information during sign-up

As mentioned before, you can collect additional information from the user during sign-up in addition to standard built-in B2C tenant attributes.

To do that you first have to create custom attributes and then use them in your policies.

Note    Custom attributes use Azure AD Graph API Directory schema extensions under the hood. For more information, see article Azure AD Graph API Directory Schema Extensions.

Note    For more information, see article Azure Active Directory B2C: Use custom attributes to collect information about your consumers.

Adding a custom user attribute to the B2C tenant

To create a custom user attribute, proceed with the following steps:

1. Switch back to the B2C features blade or navigate to the related URL (see above).
2. On the B2C features blade, click User attributes.

1. Click +Add at the top of the blade. An Add an attribute blade opens.

1. In Name, provide a name (without any space and special character) for the custom user attribute. For example, in our illustration, type in "LoyaltyNumber".
2. Leave Data type as String. This is the only supported type at this writing.
3. Click Create.

1. Close the blade just opened, and leave the B2C features blade open.

Using the custom user attribute in a sign-up policy

To use the newly created custom user attribute, proceed with the following steps:

1. Switch back to the B2C features blade or navigate to the related URL (see above).
2. On the B2C features blade, click Sign-up policies.
3. Open the B2C_1_B2CSignUp sign-up policy and click Edit at the top of the blade.
4. Click Sign-up attributes and select the above LoyaltyNumber custom attribute. Click OK.
5. Click Application claims and select the above LoyaltyNumber custom attribute. Click OK.
6. Click Save at the top of the blade.

You should now see LoyaltyNumber in the list of attributes being collected during consumer sign-up and see it in the token sent back to your application.

This concludes our walkthrough on Azure AD B2C. We hope that this gives you an idea of the power of Azure AD B2C whilst for the sake of brevity, it only scratches the surface of the possibilities.

A sneak peak of what's coming next

As previously outlined, Microsoft has already worked with a number of developers to build consumer-facing applications using Azure AD B2C as part of the private and public preview programs before the GA.

This has enable to gather a backlog of features:

1. Support for custom identity providers. This would be the ability to, say, add an arbitrary OpenID Connect 1.0 or SAML 2.0 identity provider to the B2C tenant.
2. Full UI customization for the for user experiences and not just the aforementioned HTML5/CSS customization (see section § Customizing the overall user experience), but also the ability to have your URL appear in the browser for every page rendered by Azure AD B2C. That will remove the last visible remnant of Microsoft from the user experiences.
3. Localization. If you have users all over the world speaking many languages, sign-up, sign-in, and other pages need to render appropriately using strings you provide in the languages you want to support.
4. A hook at the end of sign up. A number of people have said they want the ability to check a user who is signing up against a record in a different system. A little hook at the end of sign up would allow them to do this.
5. A variety of predefined reports, as the ones available in Azure AD so that you can review the activity in your B2C tenant at a glance and without having to write code to call an audit log API.
6. Etc.

The above is just a fraction of the list… Towards the path to GA, you can track the progress made by following the Azure AD B2C documentation.

One can also expect a Premium edition in the future with even more advanced capabilities. Stay tuned ;-)