DEV Community: Michał Silski

Auth0: using system browser to authenticate in .NET desktop application

Michał Silski — Sat, 04 Mar 2023 00:00:00 +0000

In previous article I described general ideas on how to integrate OAuth 2.0 authorization and authentication with desktop applications. In this article I will describe how to implement authentication in .NET desktop application with Auth0, using default system browser to perform user’s login and logout actions.

Auth0 nuget packages
- Default implementation.
Display auth0 login form in system browser
- Desired architecture
- Custom IBrowser implementation
- Implementation considerations
- Redirect URI
- HttpListener instance
- Timeout

Auth0 nuget packages

Auth0 provides Auth0.OidcClient.WPF and Auth0.OidcClient.WinForms nuget packages, which enable developers to integrate Auth0 authorization and authentication with WPF and WinForms-based applications. Example below presents minimal code, needed to authenticate user and acquire id_token using Auth0.OidcClient.WPF library.

string domain = ;//application domain
string clientId = ;//application clientId
client = new Auth0Client(new Auth0ClientOptions
{
    Domain = domain,
    ClientId = clientId
});
var loginResult = await client.LoginAsync();
var id_token = loginResult.IdentityToken;
var userClaims = loginResult.User.Claims;

Authorization code flow with PKCE is used to obtain a token

Auth0ClientOptionsclass includes IBrowser Browser {get; set;} property. IBrowser implementation takes responsibility of displaying login screen to the user. Additionally, it is used to perform user logout process.

Default implementation.

By default, Auth0 nuget package uses WebViewBrowser implementation of IBrowser interface. It makes use of WebViewCompatible framework component, to display login form to the user.WebViewBrowser renders html login page in new application window

Display Auth0 login form in system browser

In this section presents custom implementation of IBrowser interface, which displays login form using system browser.

Desired architecture

In order to display login form, system browser should be launched by desktop application, with authorization request configured as startup URL. In response, authorization server returns login page.

Once user is authenticated, application has to capture redirect URI, with authorization code provided as parameter. Since system browser is running on client machine, it can successfully resolve localhost loopback address. Application can host http server on one of the localhost ports e.g. http://localhost:8888. Once localhost address is set as redirect URI on authorization server and specified in initial authorization request, authorization code can be captured by the server.

Custom IBrowser implementation

IBrowser interface includes a single method signature:

public interface IBrowser
{
    Task<BrowserResult> InvokeAsync(BrowserOptions options, CancellationToken cancellationToken = default(CancellationToken));
}

BrowserOptions, passed as an argument, specifies StartUrl and EndUrl properties

StartUrl - URL to initiate OAuth action. In case of authentication or authorization it is set to authorize request. (In the context of logout it represents /logout endpoint request.)
EndUrl - Redirect URL. (In case of logout it represents post logout redirect url.)

Below, custom, IBrowser implementation utilizes system browser to perform login and logout actions

internal class SystemBrowser : IBrowser
{
    const string ERROR_MESSAGE = "Error ocurred.";
    const string SUCCESSFUL_AUTHENTICATION_MESSAGE = "You have been successfully authenticated. You can now continue to use desktop application.";
    const string SUCCESSFUL_LOGOUT_MESSAGE = "You have been successfully logged out.";
    private HttpListener _httpListener;
    private void StartSystemBrowser(string startUrl)
    {
        Process.Start(new ProcessStartInfo(startUrl) { UseShellExecute = true });
    }
    public async Task<BrowserResult> InvokeAsync(BrowserOptions options, CancellationToken cancellationToken = default)
    {
        StartSystemBrowser(options.StartUrl);
        var result = new BrowserResult();

        //abort _httpListener if exists
        _httpListener?.Abort();
        using (_httpListener = new HttpListener())
        {
            var listenUrl = options.EndUrl;

            //HttpListenerContext require uri ends with /
            if (!listenUrl.EndsWith("/"))
                listenUrl += "/";

            _httpListener.Prefixes.Add(listenUrl);
            _httpListener.Start();
            using (cancellationToken.Register(() =>
            {
                _httpListener?.Abort();
            }))
            {
                HttpListenerContext context;
                try
                {
                    context = await _httpListener.GetContextAsync();
                }
                //if _httpListener is aborted while waiting for response it throws HttpListenerException exception
                catch (HttpListenerException)
                {
                    result.ResultType = BrowserResultType.UnknownError;
                    return result;
                }

                //set result response url
                result.Response = context.Request.Url.AbsoluteUri;

                //generate message displayed in the browser, and set resultType based on request
                string displayMessage;
                if (context.Request.QueryString.Get("code") != null)
                {
                    displayMessage = SUCCESSFUL_AUTHENTICATION_MESSAGE;
                    result.ResultType = BrowserResultType.Success;
                }
                else if(options.StartUrl.Contains("/logout") && context.Request.Url.AbsoluteUri == options.EndUrl)
                {
                    displayMessage = SUCCESSFUL_LOGOUT_MESSAGE;
                    result.ResultType = BrowserResultType.Success;
                }
                else
                {
                    displayMessage = ERROR_MESSAGE;
                    result.ResultType = BrowserResultType.UnknownError;
                }

                //return message to be displayed in the browser
                Byte[] buffer = System.Text.Encoding.UTF8.GetBytes(displayMessage);
                context.Response.ContentLength64 = buffer.Length;
                context.Response.OutputStream.Write(buffer, 0, buffer.Length);
                context.Response.OutputStream.Close();
                context.Response.Close();
                _httpListener.Stop();
            }
        }
        return result;
    }
}

Once authorization code is captured, system browser displays

After successful logout, system browser displays

SystemBrowser class can be used to instantiate Auth0ClientOptions as below

private Auth0Client _client = new Auth0Client(new Auth0ClientOptions
{
    Domain = ;//application domain
    ClientId = ;//application clientId
    Browser = new SystemBrowser(),
    RedirectUri = "http://localhost:8888",
    PostLogoutRedirectUri = "http://localhost:8888/logout"
});

public void Login
{
    var loginResult = await _client.LoginAsync();
    var id_token = loginResult.IdentityToken;
    var userClaims = loginResult.User.Claims;
}

Note that given RedirectUri and PostLogoutRedirectUri need to be registered in Auth0 application settings.

Implementation considerations

Redirect URI

Proposed implementation arbitrary specifies redirect URI as http://localhost:8888. It can be considered risky to assume port 8888 is not occupied by other process in application’s target environment. In case port is already in use, authentication could not be performed.

To mitigate this risk, implementation could verify, if desired port is not occupied. In case it is occupied, other port can be verified and eventually used i.e. 8889.

Note that all possible redirect URIs needs to be registered in Auth0 application settings. As for now Auth0 does not provide an option to specify redirect URI port using wildcard (i.e. http://localhost:*). However, it is possible to register multiple localhost redirect URIs with a certain port range. Application can try to find a free port within the registered range.

HttpListener instance

In presented example, SystemBrowser holds an instance of HttpListener. Before the instance is initialized, there is _httpListener?.Abort(); executed, to close and dispose existing HttpListener instance (if there is any). This mechanism is intended for scenarios, where user initiates login, but does not complete it. In subsequent login attempt existing listener will be aborted first, before initializing new instance. Abort() causes HttpListenerException in original thread, so it needs to be handled properly.

Timeout

Presented example, for sake of simplicity, does not consider timeout. BrowserOptions, passed as input parameter, contains public TimeSpan Timeout { get; set; } property. If needed, HttpListener can be closed, if no request was captured within given timeout.

OAuth 2.0 authorization with desktop application

Michał Silski — Mon, 13 Feb 2023 00:00:00 +0000

This article presents challenges and solutions for integration of OAuth 2.0 authorization with desktop applications. Vast majority of OAuth 2.0 compliant authorization servers lead user through authentication and consent process using html-based web form. This article shows how to seamlessly integrate this process into desktop application, to obtain id or/and access token.

Desktop application
- Challenges
Solution 1: Native web browser component
- Redirect URI
- Security Consideration
Solution 2. System Web Browser
- Http or Https
- Redirect URI
- User experience
- SSO
- Security Consideration
Dedicated libraries
Summary

Desktop application

Desktop application should be considered as public (non-confidential) client. During installation, all application’s binaries and files are copied into local file system. Since they can be easily decompiled and inspected by anyone having an access to file system, application should not contain any secrets. In this context, desktop application is similar to SPA web application, where JavaScript code can be entirely inspected.

It is highly recommended to use Authorization Code grant flow with PKCE extension, to authorize user with Desktop application. PKCE is designed for public clients and doesn’t require storing any secrets on user’s device.

While performing on user’s behalf authorization, authorization server displays a form, where users can enter their credentials. Authorization servers return html-based form in response to /authorize request, which initiated OAuth grant flow.

Desktop application has to display html-based form to the user. Once user is authenticated, application gathers authorization code. Authorization code is needed to obtain access/id token from /token endpoint.

Authorization server returns authorization code, as a parameter, within a front channel call to redirect URI. Redirect URI is specified in initial /authorize request as parameter. To prevent open redirector attack, redirect URI needs to be first configured on authorization server in application registration settings.

Gathering authorization code from redirect URI, becomes a challenge for desktop application, since normally it doesn’t operate in web domain and can’t be reached by URI.

Challenges

There are two main challenges that needs to be addressed to integrate desktop application with OAuth 2.0 authorization server.

How to display html-based authorize form
How to gather authorization code, sent to redirect URI

Solution 1. Native web browser component

Many desktop frameworks provide a dedicated web browser component. It can be embedded in another control or displayed in separate application window. Application code can control browser component behavior and react to its events.

Application can subscribe to web browser component event, which is raised after address in navigation bar is changed. For instance, .NET WebView2 control provides NavigationStarting event, triggered when

WebView2 starts to navigate and the navigation results in a network request. The host may disallow the request during the event.

By subscribing to this event, application can intercept each change of browser navigation URI. Once URI matches redirect URI, application can capture authorization code provided as parameter.

Below C# demo code presents how WebView2 control can be used to handle OAuth 2.0 authorization, using Authorization code flow with PKCE.

void Authorize() 
{ 
  var authorizeRequest = CreateAuthorizeRequest(); 
  webView2.CoreWebView2.Navigate(authorizeRequest); 

  //subscribe NavigationStarting event 
  webView2.NavigationStarting += (sender, e) => 
  { 
    if (!e.Uri.StartsWith(_redirectUri)) 
      return; 

    //get code parameter from redirect uri  
    var uri = new Uri(e.Uri); 
    var code = HttpUtility.ParseQueryString(uri.Query).Get("code"); 

    //request token using authorization code 
    var token = GetToken(code);
    //use token to access resources
  }; 
}

CreateAuthorizeRequest() and GetToken(string token) methods implementation is not shown for simplicity.

Redirect URI

Application doesn't require redirect URI to be reached. It takes advantage from browser just trying to navigate to it. Since it is not required to be reachable, it can be any, even not existing, URI. It only needs to be configured as allowed redirect URI on authorization server.

Authorization server providers usually add default redirect URI, when developer registers desktop application. It is usually a neutral domain, which belongs to provider. It most likely returns empty html page with 200 status code.

Security Consideration

Native browser component, usually doesn't display address bar. Even it is displayed, its content is entirely controlled by desktop application. It makes users unable to verify if they are signing-in to legitimate authorization server. Authorization server address and its https certificate, should be always verified by the user to mitigate phishing attacks. Even if your application is trusted, it is not good practice to make users used to such design.

Embedding sing-in form in desktop application, violates the principle of least privilege. Since application entirely controls browser component, it can get an access to user credentials. For instance, it can be achieved, by capturing keystrokes while sign-in form is displayed. Username and password can be used by application to obtain more privileged accesses to resources, without user consent. Again, even if your application is trusted, it is not good practice to make users used to design, which can be harmful in case of dealing with malicious application.

Solution 2. System Web Browser

Alternatively, default system browser (like chrome, firefox, edge) can be used.

In order to display login form, system browser can be launched by desktop application, with /authorize request configured as startup URI. Unfortunately, application logic is not able to react on system browser's navigation events, like in Solution 1.

Though application can host its own http server endpoint available at redirect URI address. Since system web browser is running on client machine, it can successfully resolve localhost loopback address. Considering that, application can host http server on one of the localhost ports e.g. http://localhost:8888. Once localhost address is set as redirect URI on authorization server and specified in /authorize request, authorization response containing code can be captured by localhost server.

Below C# demo code shows how authorization code can be captured by local server.

string Authorize() 
{ 
   var redirectUri = "http://localhost:8888/"; 
   var authorizeRequest = CreateAuthorizeRequest(redirectUri); 

   //start system browser 
   Process.Start(new ProcessStartInfo(authorizeRequest) { UseShellExecute = true }); 

   using var listener = new HttpListener(); 
   listener.Prefixes.Add(redirectUri); 
   listener.Start(); 

   //wait for server captures redirect_uri  
   HttpListenerContext context = listener.GetContext(); 
   HttpListenerRequest request = context.Request; 

   var code = request.QueryString.Get("code"); 

   context.Response.Close(); 
   listener.Stop(); 

   var token = GetToken(code); 
   return token; 
   //use token to access resources
}

CreateAuthorizeRequest() and GetToken(string token) methods are not shown for simplicity.

Http or Https

Since the redirect never leaves the user’s PC it is acceptable to use http://localhost:8888 instead of https://localhost:8888.

Redirect URI

Some authorization servers allow to register localhost redirect URIs with the port wildcard (like http://localhost:*) or accepts all different ports if only http://localhost is register. It is very useful for desktop applications running inside user’s operating systems. Some ports can be already taken by other processes. If intended port is taken, application is able to host http server on different port.

User experience

It is recommended to avoid closing web browser after token is obtained. If system browser is already opened on user’s device, an attempt to launch specific URL, results in opening new tab in existing window. Termination of entire browser process, closes all tabs, which leads to rather poor user experience. Instead, localhost server can return html page, with a text confirming successful authorization. For instance:

You have been successfully authorized. You can now continue to use desktop application.

SSO

System browser usage can leverage SSO experience. Single sign-on (SSO) mechanism allows the same user session to be used by multiple applications. It provides great user experience, since user can be automatically signed-in to multiple applications, registered in authorization server, after single authentication. It is possible, thanks to user session cookie, which is stored in user browser after successful login. Session cookie is then sent to authorization server with subsequent requests. It can be then recognized and validated. Once it is valid, authorization server assumes user session is active. In result login form is not displayed again.

System browser enables desktop applications to share user session with web applications, registered under the same authorization server. (Authorization servers often allow to configure group of applications allowed to share the same user session).

Security Consideration

Using system browser, to authorize desktop application’s user, involves a localhost server endpoint. In case loopback interface is accessible by other application, authorization code can be intercepted. To prevent it, applications should implement PKCE. It protects the intercepted authorization code from being used to obtain a token.

System browser, is OAuth 2.0 recommended solution for authorizing users in desktop applications.

Dedicated libraries

Authorization server providers often distribute code libraries dedicated to their products. If dedicated library is available, it is highly recommended to use it. It makes implementation easier and ensures it is compatible with specific authorization server.

Summary

Table below compares key features of presented solution

	Native browser component	System browser
User experience	Good. Authorization is entirely performed in desktop application.	Medium. User is navigated to system browser to authorize. After process in finished user needs to navigate back to desktop application.
Security	User is not able to verify authorization server address and certificate.	OAuth 2.0 recommendation
SSO	No, partially depends on framework and component	Yes
Support in popular Authorization server providers libraries	Yes	Yes

In next article I will present how to implement system browser login in WPF and WinForms with Auth0.

Azure AD B2C session management with MSAL and React.js - Part 2.

Michał Silski — Wed, 01 Feb 2023 00:00:00 +0000

This article continues the series, related with session management solutions in Azure AD B2C. Previous post outlined polling-based approach to determine session status in SSO scope. Today I will focus on front-channel logout.

As the article goal is to inspect session management from application perspective, I will refer to the code samples. Code samples originate from to React.js SPA application, supported by MSAL.js library.

Full application code is available on my GitHub.

Front-channel logout
Configuration of Azure AD B2C
MSAL and React.js configuration
Third party LocalStorage access

Front-channel logout

Front-channel logout idea is based on user logout notification, broadcasted by Azure AD B2C to all applications sharing the same user session. Usually, in response to the notification, application drops current user context and redirect user to login page (to indicate reauthentication is required).

Front-channel logout procedure starts after one application in SSO scope initiates OpenId Connect logout procedure, by sending a request to Azure AD B2C /logout endpoint.

GET <tenantname.b2clogin.co/<tenantname>.onmicrosoft.com/<policy_name>/oauth2/v2.0/logout 
?post_logout_redirect_uri=<redirect uri, application will be redirected to this uri after logout once finishes> 
&id_token_hint=<id_token_hint>

Below diagram shows the procedure of front-channel logout in SSO environment.

After /logout request, Azure AD B2C recognizes all applications, which use the same session as one passed as a cookie within the request. Next, it creates a list of their front-channel logout URLs.

In response to /logout request, B2C returns a page, which loads an iframe. Iframe includes JavaScript logic calling all URLs listed by Azure AD B2C.

Finally, user is redirected to post_logout_redirect_uri specified in the original request.

Configuration of Azure AD B2C

To enable front-channel logout in Azure AD B2C, following steps needs to be done

Front-channel logout URL has to be configured for applications registrations. Given application URL will be called by Azure AD B2C, when any other application in SSO domain initializes logout for the user, who utilizes the same session. Setting is available under App registration->authentication. URL needs to be HTTPS for security reasons. Additionally, URL cannot contain fragment component (like example.com#logout).
Custom Policy Configuration

Note that front-channel logout is supported with Custom Policies only.

Custom policy UserJourney needs to be decorated with UserJourneyBehaviors.
- Scope of SingleSignOn can be set to Tenant, Application or Policy.
- EnforceIdTokenHint option is required, so the current user context is always passed within /logout request to Azure AD B2C. Note that front-channel logout is supported only with Custom Policies.
```
<UserJourneyBehaviors> 
    <SingleSignOn Scope="Tenant" EnforceIdTokenHintOnLogout="true"/> 
</UserJourneyBehaviors> 
```

MSAL and React.js configuration

React.js & MASL application requires following configuration

MSAL configuration – MSAL configuration is expressed in JSON format. It is used to instantiate MASL application instance.
- allowRedirectInIframe: true – application needs to be reached from iframe, rendered in Azure AD B2C tenant domain. This property ensures X-Frame-Options: DENY is not added in http header.
- cacheLocation: "localStorage" - MSAL stores user related information in browser storage.
```
const msalInstance = new PublicClientApplication({  
auth: {  
     //auth config  
}, cache: {  
     cacheLocation: "localStorage",   
}, system: {  
     allowRedirectInIframe: true  
}})
```
Logout endpoint – application needs to provide a logout endpoint, at the URL corresponding with Azure AD B2C registration. React.js framework is not natively prepared for handleing routing, however uisng React-router, it is possible to serve specific content on /logout endpoint. Using BrowserRouter component, /logout request can be routed to specific application component.
```
<BrowserRouter>
    <Routes>
        <Route path="/logout" element={<Logout />} />
        <Route path="/" element={<Home />} />
    </Routes>
</BrowserRouter>
```
Logout component should not contain much logic. It needs to perform well. Note that once user logs out from other application in SSO domain, component is loaded using front-channel request. The longer it takes to load, the longer user waits for Azure AD B2C to complete original logout request. Logout component can be designed as follows:
```
import { React } from "react"; 
import { useMsal } from "@azure/msal-react"; 

export function Logout() { 
    const { instance } = useMsal(); 

    instance.logoutRedirect({ 
        account: instance.getActiveAccount(), 
        onRedirectNavigate: false 
    }); 

    return ( 
        <div>Logout</div> 
    ) 
}    
```
Setting onRedirectNavigate: false ensures that only local logout will be performed. Once onRedirectNavigate is set to true, local logout is followed by calling /logout endpoint of Azure AD B2C.
Handle account storage events – MSAL stores its internal status, including current user related data, in browser storage (localStorage – according to configured). Since the same application can be opened in many browser tabs/windows, MSAL has to react on changes in localStorage entries. In result all tabs/windows with the same application opened, can synchronize current user context. To enable this mechanism, following function needs to be executed on PublicClientApplication.
```
msalInstance.enableAccountStorageEvents(); 
```
Handling storage events is also critical in the context of front-channel logout. After application’s /logout endpoint is called by Azure AD B2C iframe, user context is removed from localStorage. If application is opened in different browser tab or window, it can to be notified about this change.

Third party LocalStorage access

Application logout endpoint, loaded from Azure AD B2C iframe, needs to access localStorage. Unless Azure AD B2C is configured using Azure Front Door, to be available from the same domain as application, it can lead to some difficulties.

Some browsers, controls localStorage access using the third-party cookies settings. Once it is disabled, localStorage cannot be accessed from website iframed in a different domain. Since more and more browsers restricts cross domain access to storage, it needs to be considered.

Azure AD B2C session management with MSAL and React.js - Part 1.

Michał Silski — Tue, 31 Jan 2023 00:00:00 +0000

Previous article describes session management possibilities provided by OpenId Connect. OpenId-Connect session represents the authenticated user context, maintained between Applications, running on users device, and Identity Provider Server. Vast majority of modern web application works in the context of logged-in user. OAuth-based solutions delegate identity management to external Identity Provider Server. From application perspective it is important to be synchronized with Identity Provider and be able to react on user session state changes. It becomes even more relevant, if multiple applications operate in the context of the same user session (SSO solutions).

In this article I will describe Azure AD B2C-specific approach to session management in SSO environment. As the article goal is to inspect session management from developer perspective, I will refer to the code samples. Code samples originate from React.js SPA application, supported by MSAL.js library.

Full application code is available on my GitHub.

MSAL
SSO- Single sign-on and Single sign-out
Azure AD B2C supported session management methods
/authorize endpoint polling
- User Experience
- React to session expiration
- Third party cookies
- Azure AD B2C API rate limits
To be continued

MSAL

MSAL (Microsoft Authentication Library) is an open-source library, which enables developers to utilize OAuth 2.0 based services like Azure AD or Azure AD B2C. MSAL provides number of functions designed to execute OAuth 2.0 flows and acquire tokens. MSAL helps application developers with user management, by supporting login, logout, edit profile or change password user flows. MASL introduces the user context to the application. User context is stored in browser storage. It enables applications to maintain their own user-related cookies layer.

MSAL is available on many platforms (MSAL.js, MSAL for Java, MSAL.NET and more)

SSO- Single sign-on and Single sign-out

Single sign-on and single sign-out functionalities are important in the context of user session management. They allow to synchronize user session status across many applications launched in the context of the same browser. SSO improves user experience by bypassing frequent re-authentications.

Single sign-on

Azure AD B2C single sign-on (SSO) mechanism allows the same user session to be used by multiple applications. It provides great user experience, since user can be automatically signed in to multiple applications, after single authentication. It is possible, thanks to user session cookie, which is stored in user browser after successful login. Session cookie is sent to Azure AD B2C with subsequent requests, where can be recognized and validated. Once it is valid, Azure AD B2C assumes user session is active. In result login form is not displayed again.

SSO scope

Azure AD B2C allows to configure applications that are allowed to share the same user session. More information on how to configure Azure AD B2C can be found in Microsoft docs.

Single sign-out

Single sign-out mechanism ensures that after user logs out from single application, other applications in SSO scope, which use the same user session, are notified. In response to notification, applications can drop the context of current user and redirect to login page, indicating current user is logged out and authentication is required.

Azure AD B2C supported session management methods

Below table shows which OpenId Session management solutions, described in previous article, are supported by Azure AD B2C:

Solution Type	Solution	Azure AD B2C support
polling based	check_session_iframe endpoint	No
polling based	/authorize endpoint polling	Yes
Logout based	Front-channel logout	Yes
Logout based	Back-channel logout	No

/authorize endpoint polling

In order to determine user session status, application can cyclically call Azure AD B2C /authorize endpoint. /authorize endpoint is used to initialize OAuth flow. In the context authentication it is called with scope=openid parameter. As the result of the flow id_token is passed to the application.

MSAL.js always initializes PKCE grant flow to obtain id_token.

Once user authenticates with Azure AD B2C, session cookie is created in user’s browser. Azure AD B2C creates x-ms-cpim-sso:{tenantId} cookie with the value of user’s session id. Cookie is encrypted and can be interpreted solely by Azure AD B2C.

If Azure AD B2C user session cookie exists in user’s browser, it is automatically attached to every call to its origin, including subsequent /authorize endpoint calls. In case attached session cookie is valid (not expired, not malformed, not revoked) PKCE flow is completed, without user being asked to enter credentials.

*Note that each flow, results in fresh id_token being passed to the application. Application is always updated with latest user data.

To take advantage from /authorize endpoint pooling, prompt=none parameter should be included in /authorize request. Otherwise, login form will always be displayed, regardless the active session.

Following diagram present initial authentication flow. During initial authentication user is asked to enter credentials. Next, session cookie is settled in user’s browser.

After initial authentication, application can start polling /authorize endpoint (diagram presents behavior, when there is a valid session cookie available in the user browser)

User Experience

The common practice to improve user experience, is to embed /authorize request in the iframe. Instead of redirecting the user to IdP site and back, iframe gives a feeling of a background call, which doesn’t interrupt user interaction with application. MSAL.js provides ssoSilent function to acquire id_token using iframe.

Below there is a fragment of MSAL.js core implementation related with ssoSilent function

async ssoSilent(request: SsoSilentRequest): Promise<AuthenticationResult> { 
 const correlationId = this.getRequestCorrelationId(request); 
   //... 
 const silentIframeClient = this.createSilentIframeClient(validRequest.correlationId); 
 result = silentIframeClient.acquireToken(validRequest); 
 //... 
}

React to session expiration

So far, we focused on happy path, assuming there is a valid user session cookie available in the browser. Once there is no active user session provided to Azure AD B2C, ssoSilent function call fails.

In case session cookie is missing, expired or not valid, Azure AD B2C displays login form. In order to prevent clickjacking attack, Azure AD B2C doesn’t allow to display login form in iframe. It is indicated by X-Frame-Options: DENY http header, added by Azure AD B2C to login page. Clickjacking is very well described in OWASP and Auth0 articles.

Attempt to display login form in iframe using ssoSilent method ends with:

InteractionRequiredAuthError: interaction_required: AADB2C90077: 
User does not have an existing session and request prompt parameter has a value of 'None'.

This exception can be used as an indication of user session expiration. Exception handling block can redirect user to custom logout page or force to reauthenticate by redirecting to /authorize endpoint (without iframe). Following example shows how to logout user from application when session no longer valid:

const callSsoSilent = async () => { 
  try { 
    await instance.ssoSilent(silentRequest);
  } catch (e) { 
    if (e instanceof InteractionRequiredAuthError) { 
      instance.logoutRedirect({ 
        account: instance.getActiveAccount(), 
        //prevents from notifying a server about logout, logout is performed only locally - in applicaiton scpoe 
        onRedirectNavigate: false 
      }); 
    } 
    else{ 
      //handling of other error 
    } 
  } 
}

Third party cookies

/autorize endpoint polling solution is dependent on third-party cookie access. Azure AD B2C, requested in iframe from application domain, needs to access session cookie. In this context, it is considered as third party cookies.

For security reasons, some browsers implement strict policies related with third-party cookies access. To ensure access to session cookie is possible, Azure AD B2C tenant can be configure to be available in the same domain as application. For example https://login.example.com while app is hosted on https://example.com. Now, session cookie is not considered as third party, since it originates from the same domain. It can be achieved using Azure Front Door.

Azure AD B2C API rate limits

It is important to consider increased network traffic and possible latency in polling implementation. Every polling-based strategy should consider API rate limits, to ensure they are not exceeded. Azure AD B2C limits requests in contexts of tenant and IP.

Measure	Limit
Maximum requests per IP per Azure AD B2C tenant	6,000/5min
Maximum requests per Azure AD B2C tenant	200/sec

To be continued

In next article I will focus on front-channel logout.

OpenId Connect Session Management

Michał Silski — Mon, 30 Jan 2023 00:00:00 +0000

OpenId-Connect session represents the authenticated user context, maintained between Applications and Identity Provider Server. Session enables applications to provide seamless authentication experience by:

Avoiding frequent authentication – As long as there is an active session available, application can acquire new access/id tokens from Identity Provider Server, without user being asked to re-authenticate.
Enabling Single sign-on (SSO) - SSO enables multiple applications launched in the same web browser and working under the same Identity Provider Server to share the same user session. Once user logs-in into single application, other applications, can be used, without user being asked to re-authenticate.
Synchronizing user context across applications - From application perspective, it is important to know if it works in the context of logged-in user or not. Since identity management is delegated to Identity Provider Server, application needs to be synchronized with Identity Provider. Moreover, it needs to react on user session events. It becomes challenging, in SSO scenarios, where multiple applications, use the same user session. Some actions like user logout, password reset or users account deletion requires all other applications using current session to be informed.

Additionally, Identity Provider servers usually provides administrator option to revoke all user’s sessions. It can be used if user device was lost or stolen to protect against unauthorized access and malicious usage.

In this article I will describe how applications determine user session status, considering SSO scenarios. I will focus on methods provided by OpenId Connect. For applications requiring custom solutions, described methods can be used as a foundation.

Terminology
Determining session status
Polling Based Solutions
- Solution 1 - check_session_iframe endpoint
- Solution 2 - /authorize endpoint polling
Logout Based Solutions
- Solution 3 - Front-Channel Logout
- Solution 4 - Back-Channel Logout

Terminology

To keep this article consistent, I will use following naming for OpenId Connect parties

RP – Relaying Party, Client Application

IdP - Authorization Server, Identity Provider Server

additionally

SSO scope – RP’s registered under common IdP, able to utilize the same user session.

Determining session status

Applications usually provide different functionalities depending if running in the context of logged-in user or not. Below solutions enables RPs to determine current session status.

Polling Based Solutions

Polling, in general, is a way to determine a status of an asset, by actively, cyclically, checking its value. In the context of OpenId Connect and session management, polling solutions are based on cyclic requests to IdP to gather latest user session status.

Solution 1 - check_session_iframe endpoint

check_session_iframe endpoint is described in OpenId Connect Session-related specs. It requires RP to load JavaScript code from IdP. Loaded code validates current session state.

session_state

In response to initial /authorize endpoint request, IdP returns session_state parameter. Additionally, after successful authentication, IdP stores a session cookie in user’s browser.

loading IdP code

RP application, launched in the browser, should include an iframe element that loads content from IdP’s /check_session_iframe endpoint. Loaded content is a JavaScript function, which validates if user session is active or not. Validation is based on session_state and clientId provided by RP as arguments. Function calculates expected session cookie value and compares it with actual session cookie, stored in the browser. Once expected and actual session cookies are equal, function returns unchanged (which indicates active session), or changed. This logic can be expressed by following condition:f(session_state, client_id) == session_cookie ? unchanged : changed

Cyclic execution

IdP validation function can be executed periodically by RP, to achieve polling mechanism. OpenId Connect documentation recommends to load anther iframe directly from RP, that will be solely responsible for cyclically triggering validation.

Network traffic

Network traffic needed to check session status is very limited. Once IdP iframe is loaded, session can be validated using loaded JavaScript code only - with no IdP interaction. That can be considered as main advantage of check_session_iframe-based solution.

Limitation: Iframe and 3rd Party Cookies

Iframe based has a serious limitation in modern, security-oriented browsers. OpenId Connect documentation stands:

Note that at the time of this writing, some User Agents (browsers) are starting to block access to third-party content by default to block some mechanisms used to track the End-User’s activity across sites. Specifically, the third-party content being blocked is website content with an origin different that the origin of the focused User Agent window. Site data includes cookies and any web storage APIs (sessionStorage, localStorage, etc.).

For security reasons more and more browsers don’t allow cross domain cookies access. Since RP loads IdP iframe, it requires an access to the session cookie, which belongs to IdP.

Following list presents popular browser support for 3rd party cookies.

Safari – not supported
Google Chrome– planning to finish support in 2024
Firefox – third party cookies are blocked by default

Some IdPs allows to configure a custom domain, common for RP and IdP. Having IdP and RP in the same domain makes cookie access possible, regardless 3-rd party cookies restrictions. For instance, IdP can be accessed at https://login.example.com while app is hosted on https://example.com.

Solution 2 - /authorize endpoint polling

OpenId Connect specification describes /authorize endpoint. It is used to initiate authentication flow. /authorize endpoint accepts prompt parameter. In case prompt parameter set to none, IdP checks session cookie, provided within the request. If attached cookie represents an active session, user will not be asked to enter credentials. If provided session cookie is invalid or associated user session is no longer active, user will be asked to enter login credentials.

In the context of authentication /authorize endpoint call initiates grant flow, which eventually returns id_token to the application. By calling /authorize endpoint cyclically, application is updated with latest user-related claims, stored in id_token. It can be an advantage, when other application modifies user claims in the meantime.

Some IdPs providers, supports rolling session. Session expiration can be postponed every time, when corresponding session cookie is used to acquire new id_token. It allows to keep the session alive longer, when it is actively used by RP.

Iframe for seamless experience

To provide seamless user experience /authorize endpoint can be called using iframe. Thanks to iframe, user is not redirected to /authorize page and back on every call. Instead, call can be done “in the background”- without users notice.

Limitation 1: Iframe and 3rd Party Cookies

In order to validate user session IdP requires an access to session cookie stored in browser. Considering strict 3-rd party policy, it might not be possible, when IdP was called from other domain’s iframe.

Limitation 2: Iframe and Clickjacking protection

Iframe usage leads to some more security concerns than just 3rd party cookies, especially in the context of authentication and authorization. Iframe element can be used to perform clickjacking attack. Clickjacking is very well described in OWASP and Auth0 articles. To prevent the attack, a X-Frame-Options: DENY header can be added to http header, to make sure, browser will not allow to load th login page inside iframe.

As long as there is active user session, /authorize endpoint can be successfully called from iframe. Once user session expires, IdP tries to redirect next /authorize call to the login page. Since login page likely includes X-Frame-Options: DENY header and it is called from iframe, redirect will fail.

As a workaround some IdP providers recommend following solution expressed in pseudo-code

try 
{ 
    CallAutorizeUsingIFrame(); 
} 
catch 
{ 
    CallAuthorizeUsingRedirect();
}

In example above /authorize endpoint is called using redirect, only when iframe call fails. Assuming failure is caused by expired session and attempt to display login page in iframe, user will be redirected to login page outside the iframe in catch block. After successful login new session is established and /authorize can be called from iframe again.

Besides that, some IdPs allows to configure X-Frame-Options header value if needed, however it should be considered as “unsafe mode”.

Limitation 3: API Rate Limits

/authorize endpoint polling should be considered in the context of IdP API rate limits. If polling interval is too short, API call limit can be reached.

Logout Based Solutions

RPs use logout-based solutions to track active user session by listening on logout event. RP provides an endpoint that can be called by IdP, in case logout event occurred in other application, which uses the same user session.

RP logout is initiated by calling IdP’s /logout endpoint.

IdP clears session cookie on logout request. Moreover, IdP can spread logout information to other RPs using

Front-Channel Logout
Back-Channel Logout

Solution 3 - Front-Channel Logout

Front-Channel Logout is described in OpenId Connect documentation. Front-Channel Logout procedure is initiated by calling IdP’s /logout endpoint. IdP tracks RPs and their active sessions. Based on session cookie, provided within /logout request IdP finds all applications using corresponding session. Once IdP receives logout request from RP, logout event is spread to other RPs (which uses the same session), by calling their frontchannel_logout_uri endpoints via front channel. (All RPs need to be configured with frontchannel_logout_uri in IdP client registration properties).

RPs can adjust their internal state and clean information associated with logged-in user, after receiving front-channel logout request.

Front-channel logout mechanism utilizes iframes. IdP loads a website containing iframes in response to /logout request. Each iframe src corresponds with single frontchannel_logout_uri. Once all RPs are notified IdP redirects user to post_logout_redirect_uri specified in initial /logout request parameters.

Limitation 1: Iframe and 3rd Party Cookies

Main limitation of frontend logout solutions is, again, related with third-party cookies. Since frontchannel_logout_uri is iframed and called on IdP, there might be some limitations with access to RP’s cookies.

Limitation 2: URI fragment component

Additionally, frontchannel_logout_uri must not contains fragment component (like example.com#logout). Many SPA frameworks uses fragment components for routing.

Solution 4 - Back-Channel Logout

Back-Channel Logout is described in OpenId Connect documentation. Logout information is sent to all RPs using current browser session via back-channel. In response to /logout request IdP creates a logout_token and sends it via back-channel POST call to RP’s /backchannel_logout_uri. backchannel_logout_uri is associated with RP in IdP client registration properties.

logout_token should be validated by RP. It is critical to compare logout_token properties (like sub) with current id_token and verify if logout request corresponds with currently logged in user.

Once all RPs are notified IdP redirects user to post_logout_redirect_uri specified in initial /logout request parameters.

Not all IdPs supports Back-Channel logout. If Back-Channel is supported, backchannel_logout_supported property is visible in IdP discovery endpoint.

OAuth 2.0 refresh tokens with Azure AD B2C

Michał Silski — Sun, 29 Jan 2023 00:00:00 +0000

Refresh tokens are commonly used in OAuth based authorization scenarios. The purpose of refresh token is to retrieve new id/access token from authorization server, without user interaction. In simple scenarios, once access token expires, user is forced to reauthenticate in order to get new token. With refresh tokens, expired access token can be replaced with fresh one in the background, without user interaction.

Using refresh tokens improves application security. One might think it would be just enough to extend an expiration time of id/access token. By making it long lived, user avoids often re-authentication. This approach may put your application at greater risk of token being intercepted and used by attacker.

Once id/access token is retrieved from Auth server, it can be used until it expires against resource server (e.g. personal calendar service). Risk of token interception and malicious usage increases as the same long-lived id/access token is used over and over again.

With short-lived access token, risk of its interception still exists, however their malicious usage can be minimized as they shortly expire and cannot be used against resource server anymore. In Azure AD B2C default access token lifetime is 60 minutes and can be configured in a range of 5 minutes to 24 hours.

Besides external risks long-lived access tokens, expose resources to internal risks. Once user access to specific resource is changed or revoked, it will be reflected only in access token generated after this change. With long lived access tokens user might keep the access to the resource for long time, even if it was changed or revoked in the meantime.

Refreshing tokens by the book
Refresh tokens settings in Azure AD B2C
- User Flows
- Custom Policies
Refresh token revocation
- Revocation and access tokens
- Azure AD B2C revocation scenarios
- One time use refresh token
Customizing refresh token flow

Refreshing tokens by the book

Below diagram presents how refresh token can be used in Authorization Code Grant flow.

In order to get refresh token from Azure AD B2C authorization server following request needs to be sent to /token endpoint

POST https://{tenant_id}.b2clogin.com/{tenant_id}.onmicrosoft.com/{policy}oauth2/v2.0/token 
?grant_type=refresh_token 
&client_secret={client_secret} 
&client_id={client_id} 
&scope=offline_access //in addition, openid or specific access can be specified 
&refresh_token={refresh_token}

Auth server response includes new refresh token plus access or id token (depending of specified request scope).

Note 1

Authorization code grant flow is presented as example. Note that refresh token can be used in OAuth flows other than that, except implicit grant flow.

Note 2

Refresh token is encrypted during generation, and decrypted by Auth server once it is used. Its payload is transparent for client application and can be understood solely by Auth server.

Refresh tokens settings in Azure AD B2C

Azure AD B2C governs refresh tokens and controls their behavior. Refresh token can be configured using 3 properties

refresh_token_lifetime_secs – describes how long single refresh token is valid. Once refresh token lifetime expires, it cannot be used to gather new refresh token and will be refused by Auth server. Minimum value is 24h, maximum is 90 days.
rolling_refresh_token_lifetime_secs – describes time frame in which token refreshing can be continued. Refresh token can be used to get new refresh token. New refresh token can be used to get another refresh token etc. It creates a chain. This property specifies maximum length of refresh token chain. Minimum value is 24h, maximum is 365 days.
allow_infinite_rolling_refresh_token – once this property is set to true, refresh token chain is not time limited.

These properties can be configured for both User Flows and Custom Policies (Identity Experience Framework).

User Flows

User Flows allows to configure refresh token properties under Settings/Token Lifetime

Custom Policies

Custom Policies takes advantage of extending OpenId Connect TechnicalProfile. Azure AD B2C custom policies starter pack implements TrustFrameworkBase custom policy, which defines JwtIssuer - OpenId Connect TechnicalProfile. It can be inherited and extended with refresh token settings like below

<ClaimsProvider>
    <DisplayName>Token Issuer</DisplayName>
    <TechnicalProfiles>
        <TechnicalProfile Id="JwtIssuer">
            <Metadata>
                <!-- 86400s = 24h -->
                <Item Key="refresh_token_lifetime_secs">86400</Item>
                <!-- 172800s = 48h -->
                <Item Key="rolling_refresh_token_lifetime_secs">172800</Item>
                <Item Key="allow_infinite_rolling_refresh_token">false</Item>
            </Metadata>
        </TechnicalProfile>
    </TechnicalProfiles>
</ClaimsProvider>

Refresh token lifetime configuration is reflected in response from /token endpoint. Response includes refresh_token_expires_in property that corresponds with refresh_token_lifetime_secs setting. Thanks to that application can request new refresh token before current expires.

Refresh token revocation

Azure AD B2C does not provide OAuth /revocation endpoint which is normally used to inform the Auth server specific token should not be accepted anymore.

Token revocation can be achieved in three different ways using

1. Using Powershell

Revoke-AzureADUserAllRefreshToken -ObjectId <String>

2. Using Graph API

POST https://graph.windows.net/myorganization/users/{user_id}/invalidateAllRefreshTokens?api-version

3. Using Azure portal

Revoke session button is available in B2C tenant user settings

This solution doesn’t invalidate refresh token directly. It is designed to revoke user session, not refresh tokens. Though it is possible to implement a custom logic which stops refresh token from being used, after user session is revoked. Specific implementation is described in customizing refresh token flow section.

Azure AD B2C revocation scenarios

Azure AD B2C token revocation possibilities seem to be designed for administrator usage scenarios. For example, when user loss device, administrator can revoke tokens, so reauthentication will be required.

This approach doesn’t work well with scenarios, where users need to revoke their own tokens. However, it is valid requirement considering security reasons. After user logs out from application, refresh tokens are usually removed from application memory but they are not invalidated on Auth Server and still can be used. It creates a risk of malicious usage of intercepted refresh tokens.

Revocation and access tokens

Refresh token revocation does not invalidate the access token. User does not lose the access immediately. Access tokens are valid until they expire. Once application gets an access token, there is no way to prevent application from accessing resource with this access token. Refresh token revocation prevents from acquiring new id/access tokens without reauthentication.

One time use refresh token

Staying in the context of security, there are recommendation for Auth servers to generate one time use refresh tokens. Refresh token should be used only once to request new access and refresh tokens. New refresh token, can be used only once as well. This approach mitigates refresh token usage risk, even if it is intercepted by attacker. Though Azure AD B2C by default allows to use the same refresh token multiple times.

Customizing refresh token flow

Customization of token claims can be implemented using Azure AD B2C custom policies. Claims generation process can be customized, when the tokens are requested specifically using refresh token.

This functionality gives variety of possibilities, for example

Refresh user claims in returned id token. Some claims might have changed after they were initially generated during sign in process.
Call external API to check if user, who is trying to refresh the token, is on some blacklist. Interrupt token generation if that is the case.
Check if user’s refresh token was revoked.

Example below, presents how to check if user session was revoked, before refreshing the token.

After /token endpoint is requested with with grant_type=refresh_token, Azure AD B2C triggers UserJourney, referenced in RelyingParty as an Endpoint with Id=Token.

<RelyingParty>
    <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
    <Endpoints>
        <Endpoint Id="Token" UserJourneyReferenceId="RedeemRefreshToken" />
    </Endpoints> 
... 
</RelyingParty>

RedeemRefreshToken Journey is implemented in Azure AD B2C starter pack in TrustFrameworkBase.xml policy file. (Starter pack is recommended by Azure as a foundation for Custom Policies) Of course, you can extend, customize or use different UserJourney instead.

RedeemRefreshToken UserJourney includes three steps,

<UserJourney Id="RedeemRefreshToken">
    <PreserveOriginalAssertion>false</PreserveOriginalAssertion>
    <OrchestrationSteps>
        <OrchestrationStep Order="1" Type="ClaimsExchange">
            <ClaimsExchanges>
                <ClaimsExchange Id="RefreshTokenSetupExchange" TechnicalProfileReferenceId="RefreshTokenReadAndSetup" />
            </ClaimsExchanges>
        </OrchestrationStep>
        <!-- Extra steps can be added before or after this step for REST API or claims transformation calls-->
        <OrchestrationStep Order="2" Type="ClaimsExchange">
            <ClaimsExchanges>
                <ClaimsExchange Id="CheckRefreshTokenDateFromAadExchange" TechnicalProfileReferenceId="AAD-UserReadUsingObjectId-CheckRefreshTokenDate" />
            </ClaimsExchanges>
        </OrchestrationStep>
        <OrchestrationStep Order="3" Type="SendClaims" CpimIssuerTechnicalProfileReferenceId="JwtIssuer" />
    </OrchestrationSteps>
</UserJourney>

which utilize following TechnicalProfiles

RefreshTokenReadAndSetup – it just returns refresh token parameters like objectId and refreshTokenIssuedOnDateTime in output claims. Before executing refresh token UserJourney, refresh token claims seems to be already preloaded into claims bag. (It is different approach comparing to UserInfoEndpoint implementation, where dedicated technical profile loads access token claims into claims bag explicitly).

AAD-UserReadUsingObjectId-CheckRefreshTokenDate – retrieves user information stored in azure AD. Since it uses base AAD-UserReadUsingObjectId TechnicalProfile, basic user data will updated in returned id/access token. Additionally, refreshTokensValidFromDateTime property is read from AD. When user’s refresh token is revoked refreshTokensValidFromDateTime is set to time it happened.

<TechnicalProfile Id="AAD-UserReadUsingObjectId-CheckRefreshTokenDate">
    <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="refreshTokensValidFromDateTime" />
        <OutputClaim ClaimTypeReferenceId="displayName" />
    </OutputClaims>
    <OutputClaimsTransformations>
        <OutputClaimsTransformation ReferenceId="AssertRefreshTokenIssuedLaterThanValidFromDate" />
    </OutputClaimsTransformations>
    <IncludeTechnicalProfile ReferenceId="AAD-UserReadUsingObjectId" />
</TechnicalProfile>

By comparing refreshTokensValidFromDateTime property with refreshTokenIssuedOnDateTime it is possible to validate if used refresh token should be accepted by auth server. This logic is implemented by output claim transformation. Once refreshTokensValidFromDateTime is greater that refreshTokenIssuedOnDateTime, exception is thrown and UserJourney is interrupted. In that case, Auth server returns 400-Bad request http response, including body:

{ 
    "error": "invalid_grant", 
    "error_description": "AADB2C90129: The provided grant has been revoked. Please reauthenticate and try again.Correlation ID: xxxxxx-xxxx-xxxx-xxxx-xxxxxxxx\r\nTimestamp: xxxx-xx-xx xx:xx:xxx\r\n" 
}

JwtIssuer - OpenIdConnect technical profile that issues requested token and returns it to relaying party. Refresh token properties described above, in Refresh tokens properties in Azure AD B2C section, can be specified in its definition.

Progressive profiling with Azure AD B2C

Michał Silski — Sat, 28 Jan 2023 00:00:00 +0000

Azure AD B2C provides advanced tools for user identity and access management. Modern applications often delegate identity and access management to external services. At the same time authorization and authentication needs to be highly flexible, providing features as:

Integration with external identity providers like GitHub or Facebook etc.
Customization of user experience during sign-in, sign-up, profile edit etc.
Extension of user identity with application-specific information
Performing calls to external APIs during authorization or authentication

Azure AD B2C supports all these scenarios and even more. In this article I will focus on progressive profiling implementation, taking advantage of Azure AD B2C support for highly customized user experience.

Progressive Profiling is a gradual way of collecting user preferences. As application collects user’s preferences it can provide more personalized, better suited experience.

The concept of Progressive Profiling
Progressive Profiling implementation using Azure AD B2C
Progressive Profiling UserJourney - Custom Policy implementation

The concept of Progressive Profiling

Imagine user is singing-up for gym website. User is asked to fill in standard sign-up form, including email and username. Gym website added personalized training offer recently. In result, during sign-up process, user is additionally asked about favorite exercises, training preferences, age, calories eaten per day, health condition and past training record. At this point most of potential customers would probably resign from signing-up. The main reason is most likely users don’t trust the website yet to share such detailed information.

Progressive profiling is a way to ask these questions gradually, as trust to the website (and company) increases and user observes benefits of personalization. Let’s assume user signs-up with minimum information required. After several visits, during next sign-in process, user is informed about personalized training offer and asked to choose favorite exercise from the list. This question can be not answered, however after few visits on the website and maybe on the gym itself, there is a better chance this information will be shared. As users observe benefits form personalization, they become more eager to share their preferences.

Progressive Profiling implementation using Azure AD B2C

Azure AD B2C allows to incorporate progressive profiling into sign-in process. It is possible to customize sign-in process and extend it with gathering and processing additional user’s input.

Provided information can be stored in Azure AD B2C tenant and served within id_token. Having preferences as a part of user identity enables application to personalize services it provides.

id_token token can be extended with progressive profiling information as follows:

Azure AD B2C provides two ways of configuring identity related flows.

User flows - predefined, build-in policies designed to handle most common scenarios; can be configured within Azure Portal UI.
Identity Experience Framework (Custom Policies) - Configuration of identity-related processes like sign-in, sign-up, reset password or profile edit is called policy. Policies are defined in xml files. Xml-based policies are flexible and can be highly customized.

Progressive profiling scenario is not supported by user flows and needs to be implemented using Identity Experience Framework.

TrustFrameworkPolicy is top-level xml element of policy file. It defines claims schema, claims transformation, token generation steps and more. It is well described on https://learn.microsoft.com/en-us/azure/active-directory-b2c/trustframeworkpolicy.

TrustFrameworkPolicy uses concept of UserJourneys. UserJourney includes steps (Orchestration Steps), needs to be taken to perform identity related actions like sign-in or sign-up. In the context of signing-in, the result of UserJourney is generated id_token.

OrchestrationSteps process claims using TechnicalProfiles. TechnicalProfile generates output claims based on input claims by interacting with AD, calling external API, gathering data from user, etc. TechnicalProfiles are connected together in a chain by OrchestrationSteps, creating UserJourney.

UserJourney starts when OAuth 2.0 flow is initiated (in most cases by calling corresponding /authorize endpoint).

Result id_token is passed to RedirectUrl once application requests a token. RedirectedUrl can be configured in Azure AD B2C tenant for registered application.

Note: Using implicit grant flow /authorize endpoint call, which initiates authentication, is considered as the token request at the same time

Progressive Profiling UserJourney - Custom Policy implementation

The concept solution of progressive profiling policy is available on my GitHub. Repository contains following files implementing policies

TrustFrameworkBase.xml (B2C_1A_TrustFrameworkBase policy)
TrustFrameworkLocalization.xml (B2C_1A_TrustFrameworkLocalization policy)
TrustFrameworkExtensions.xml (B2C_1A_TrustFrameworkExtensions policy)

These files originate from Azure custom policy samples repository. They are recommended as a foundation for building custom policies. Additionally, my repository contains xml files, which implements custom progressive profiling policy.

ProgressiveProfileTrustFrameworkBase.xml (B2C_1A_ ProgressiveProfile_TrustFrameworkBase policy) defines base claims and technical profile to handle progressive profiling, exchange claims with AAD and handle user input.
ProgressiveProfileTrustFrameworkExtensions.xml (B2C_1A_ ProgressiveProfile_TrustFrameworkExtensions policy) defines application-specific claims which will be gathered from user in progressive profiling flow. It implements UserJourney.
ProgressiveProfileSignUpOrSignin.xml (B2C_1A_ProgressiveProfile_SignUpOrSignIn policy) defines RelyingParty which returns final token claims.

Policies can be inherited. Inheritance allows to use or extend elements defined in parent policies. Following diagram presents inheritance of policies in this implementation:

Below diagram shows the concept of UserJourney that incorporates progressive profiling into user sign-in flow.

Presented UserJourney uses several custom claims, to control progressive profiling UserJourney

PPCounter – used to count user sign-in actions. Once counter reaches specific value, progressive profiling form should be displayed to the user after signing-in. Next PPCounter is reset. It is saved in AD user attributes, so value is preserved between UserJourney executions.
PPShouldExecute – determines if PPCounter reaches specific level after which progressive profiling form should be displayed to the user. In given example PPShouldExecute is set once PPCounter equals 3. It means user is asked to fill progressive profiling form after every 3rd sign-in.
PPExecuted – indicates that progressive profiling information was already gathered from user in current UserJourney. It helps to prevent from asking user for multiple information in single UserJourney execution.

Step 1 utilizes base self-asserted technical profile which displays sign-in form in the browser. Once user fills email and password SelfAsserted-LocalAccountSignin-Email credentials are validated by executing ROPC (Resource Owner Password Credentials) flow. ROPC flow gets user access token form https://login.microsoftonline.com/{tenant}/oauth2/token endpoint. Received token indludes objectId attribute, which identifies user in AD tenant.

Step 2 is not directly related with progressive profiling and it is excluded from diagram. Step 2 guides user through sign-up action in case user account does not exist.

Step 3 reads user related data from AD tenant. It uses extended base AAD-UserReadUsingObjectId TechnicalProfile to gather user data based on objectId from Step1.

B2C_1A_ ProgressiveProfile_TrustFrameworkBase

<TechnicalProfile Id="AAD-UserReadUsingObjectId">
    <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="extension_PPCounter" DefaultValue="0"/>
    </OutputClaims>
    <OutputClaimsTransformations>
        <OutputClaimsTransformation ReferenceId="IncrementProgressiveProfileCounter" />
        <OutputClaimsTransformation ReferenceId="SetProgressiveProfilingShouldExecute" />
    </OutputClaimsTransformations>
</TechnicalProfile>

PPCounter claim is read from AD. If it does not exist its value is set to 0. Additionally, two output claims transformations are executed:

PPCounter claim is incremented

<ClaimsTransformation Id="IncrementProgressiveProfileCounter" TransformationMethod="AdjustNumber">
    <InputClaims>
        <InputClaim ClaimTypeReferenceId="extension_PPCounter" TransformationClaimType="inputClaim" />
    </InputClaims>
    <InputParameters>
        <InputParameter Id="Operator" DataType="string" Value="INCREMENT" />
    </InputParameters>
    <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="extension_PPCounter" TransformationClaimType="outputClaim" />
    </OutputClaims>
</ClaimsTransformation>

PPShouldExecute claim is added and set to true when PPCounter equals 3. It enables progressive profiling prompt on every third log-in

<ClaimsTransformation Id="SetProgressiveProfilingShouldExecute" TransformationMethod="AssertNumber">
    <InputClaims>
        <InputClaim ClaimTypeReferenceId="extension_PPCounter" TransformationClaimType="inputClaim" />
    </InputClaims>
    <InputParameters>
        <InputParameter Id="Operator" DataType="string" Value="GreaterThanOrEqual" />
        <InputParameter Id="CompareToValue" DataType="int" Value="3" />
        <InputParameter Id="throwError" DataType="boolean" Value="false" />
    </InputParameters>
    <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="PPShouldExecute" TransformationClaimType="outputClaim" />
    </OutputClaims>
</ClaimsTransformation>

ProgressiveProfile_TrustFrameworkExtensions

<TechnicalProfile Id="AAD-UserReadUsingObjectId">
    <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="extension_PreferedTraining"/>
        <OutputClaim ClaimTypeReferenceId="extension_PreferedExcercises"/>
    </OutputClaims>
</TechnicalProfile>

Progressive profiling, implementation specific, claims are read from AD as well.

Step 4 executes SubJourney which is designed to gather and store user preferences. Each Orchestration Step correspond with single progressive profiling claim. Its structure can be easily extended when new application specific claims are added. SubJourney is executed when PPShouldExecute equals true.

SubJourney Steps are skipped if corresponding claim is already set or different claim was set in current UserJourney.

<OrchestrationStep Order="1" Type="ClaimsExchange">
    <Preconditions>
        <Precondition Type="ClaimsExist" ExecuteActionsIf="true">
            <Value>extension_PreferedTraining</Value>
            <Action>SkipThisOrchestrationStep</Action>
        </Precondition>
        <Precondition Type="ClaimsExist" ExecuteActionsIf="true">
            <Value>PPExecuted</Value>
            <Action>SkipThisOrchestrationStep</Action>
        </Precondition>
    </Preconditions>
    <ClaimsExchanges>
        <ClaimsExchange Id="ProfileUpdateExchangePreferedTraining" TechnicalProfileReferenceId="SelfAsserted-ProgressiveProfiling-PreferedTraining" />
    </ClaimsExchanges>
</OrchestrationStep>

It calls SelfAsserted technical profile which displays progressive profiling form and saves selected value in output claim. Additionaly, technical profile sets PPExecuted output claim to true. It prevents from showing next progressive profiling forms during the same sign-in flow.

Step 5 writes output claims associated with user to Azure AD.

Step 6 resets (deletes) PPCounter claim from AD if progressive profiling SubJourney were executed.

<OrchestrationStep Order="6" Type="ClaimsExchange">
    <Preconditions>
        <Precondition Type="ClaimEquals" ExecuteActionsIf="true">
            <Value>PPExecuted</Value>
            <Value>false</Value>
            <Action>SkipThisOrchestrationStep</Action>
        </Precondition>
    </Preconditions>
    <ClaimsExchanges>
        <ClaimsExchange Id="DeleteClaimUpdateExchange" TechnicalProfileReferenceId="AAD-DeleteProgressiveProfilingCounter" />
    </ClaimsExchanges>
</OrchestrationStep>

Step 7 creates JWT token based on current output claims.

All policy configuration files are available on my GitHub.

DEV Community: Michał Silski

Auth0: using system browser to authenticate in .NET desktop application

Auth0 nuget packages

Default implementation.

Display Auth0 login form in system browser

Desired architecture

Custom IBrowser implementation

Implementation considerations

Redirect URI

HttpListener instance

Timeout

OAuth 2.0 authorization with desktop application

Table of contents

Desktop application

Challenges

Solution 1. Native web browser component

Redirect URI

Security Consideration

Solution 2. System Web Browser

Http or Https

Redirect URI

User experience

SSO

Security Consideration

Dedicated libraries

Summary

Azure AD B2C session management with MSAL and React.js - Part 2.

Table of contents

Front-channel logout

Configuration of Azure AD B2C

MSAL and React.js configuration

Third party LocalStorage access

Azure AD B2C session management with MSAL and React.js - Part 1.

Table of contents

MSAL

SSO- Single sign-on and Single sign-out

Single sign-on

SSO scope

Single sign-out

Azure AD B2C supported session management methods

/authorize endpoint polling

User Experience

React to session expiration

Third party cookies

Azure AD B2C API rate limits

To be continued

OpenId Connect Session Management

Table of contents

Terminology

Determining session status

Polling Based Solutions

Solution 1 - check_session_iframe endpoint

session_state

loading IdP code

Cyclic execution

Network traffic

Limitation: Iframe and 3rd Party Cookies

Solution 2 - /authorize endpoint polling

Iframe for seamless experience

Limitation 1: Iframe and 3rd Party Cookies

Limitation 2: Iframe and Clickjacking protection

Limitation 3: API Rate Limits

Logout Based Solutions

Solution 3 - Front-Channel Logout

Limitation 1: Iframe and 3rd Party Cookies

Limitation 2: URI fragment component

Solution 4 - Back-Channel Logout

OAuth 2.0 refresh tokens with Azure AD B2C

Table of contents

Refreshing tokens by the book

Refresh tokens settings in Azure AD B2C

User Flows

Custom Policies

Refresh token revocation

1. Using Powershell

2. Using Graph API

3. Using Azure portal

Azure AD B2C revocation scenarios

Revocation and access tokens

One time use refresh token