Umbraco and Okta Integration

With the increasing number of browser based business tools, people working from home and the ongoing drive for enhanced security it is no wonder more and more organisations are looking to Okta to assist with their identity management.

Fortunately for us as Umbraco CMS developers integrating the two systems is relatively straight forward and we have now successfully integrated the two applications successfully for several Umbraco instances.

Instructions on how to integrate Umbraco CMS and Okta

These instructions assume that you already have an Okta account, if you don’t, create a free account first.

Step 1: Add an App into Okta

In the Okta Admin console:

Navigate to Applications → Applications
Click Create Add Integration button

Choose Sign on method = OIDC - OpenID Connect
Choose Platform = Web Application
Click Next

Give the Application an appropriate name
Add a Login and Logout redirect URI to https://{site-domain}/umbraco replacing {site-domain} with your Umbraco site domain (ie https://mysite.com/umbraco)
NOTE: you will need to add and entry for all domains that intend to use this app (ie your production and test site URLs)

Choose the appropriate Controlled access
Click Save
On the General tab, in the General Settings section, click Edit
In the Allowed Grant Types select Implict (hybrid) and Allow ID Token

Click Save at the bottom of the form
Take a note of the Client Id, Client Secret, and Okta domain values, these will be needed for the website.

Click the Assignments tab
Add the groups or people who will be able to authenticate using this app.

Step 2: Add the Okta Middleware to the Umbraco solution

First off, install the Okta.AspNet package from nuget


1PM>Install-Package Okta.AspNet

Create a new class which inherits from UmbracoDefaultOwinStartup, I named my class OktaOwinStartup but you can call it whatever you want.

                    
1[assembly: OwinStartup("OktaOwinStartup", typeof(OktaOwinStartup))]
2namespace UmbracoOkta
3{
4    class OktaOwinStartup: UmbracoDefaultOwinStartup
5    {
6    }
7}
                
            

I have used the OwinStartup attribute to name my start up class, this is the name we will use in the app settings later on.

Override and place your code the ConfigureUmbracoAuthentication method.

                    
1protected override void ConfigureUmbracoAuthentication(IAppBuilder app)
2{
  // Must call the base implementation to configure the default back  office authentication config.
  base.ConfigureUmbracoAuthentication(app);
  var oktaOptions = new OktaMvcOptions
  {
      OktaDomain = domain,
      ClientId = clientId,
      ClientSecret = clientSecret,
      AuthorizationServerId = AuthServerId,
      RedirectUri = redirectUri,
      PostLogoutRedirectUri = postLogoutRedirectUri,
      Scope = new string[] { "openid", "profile", "email" }
  };
  var issuer = UrlHelper.CreateIssuerUrl(.OktaDomain, oktaOptions.AuthorizationServerId);
  var options = new OpenIdConnectAuthenticationOptionsBuilder(oktaOptions).BuildOpenIdConnectAuthenticationOptions();
  var autoLinkOptions = new ExternalSignInAutoLinkOptions(enableAutoLinking, new[] { Constants.Security.WriterGroupAlias })
  {
      AllowManualLinking = false
  };
21
  options.Caption = "Okta";
  options.ForUmbracoBackOffice("btn-microsoft", "fa-openid");
  options.SignInAsAuthenticationType = Constants.Security.BackOfficeExternalAuthenticationType;
  options.AuthenticationType = issuer;
  options.SetBackOfficeExternalLoginProviderOptions(new 
  BackOfficeExternalLoginProviderOptions
  {
      AutoRedirectLoginToExternalProvider = false,
      DenyLocalLogin = true,
      AutoLinkOptions = autoLinkOptions,
  });
33
  app.UseOpenIdConnectAuthentication(options);
35}
                
            

The code should be easy to follow, it's mostly boilerplate but some things to note:

I am setting up the AutoLink option, this will automatically create an Umbraco user if they do not exist and assign them to the Writer group.

The FromUmbracoBackoffice() call incorrectly sets the AuthenticationType, so this is set to the correct value on line 25.

I have set the DenyLocalLogin to true, setting this to false will allow a user to login with either Okta or their Umbraco password.

I am using app settings in the web config file to pass through some variables.

                    
1private readonly string clientId = ConfigurationManager.AppSettings["okta:ClientId"];
2private readonly string clientSecret = ConfigurationManager.AppSettings["okta:ClientSecret"];
3private readonly string domain = ConfigurationManager.AppSettings["okta:oktaDomain"];
4private readonly string redirectUri = ConfigurationManager.AppSettings["okta:RedirectUri"];
5private readonly string postLogoutRedirectUri = ConfigurationManager.AppSettings["okta:PostLogoutRedirectUri"];
6private readonly bool enableAutoLinking = bool.Parse(ConfigurationManager.AppSettings["okta:EnableUmbracoAutoLinking"] ?? "false");
7private readonly string AuthServerId = ConfigurationManager.AppSettings["okta:AuthorizationServerId"] ?? "default";
                
            

Step 3: Update the Web.Config

With the code setup, you can now update the web.config in the Umbraco website solution, replace the tokens in {}

                    
1<!-- 1. Update this value -->
  <add key="owin:appStartup" value="OktaOwinStartup" />
3
  <!-- 2. Replace these values with your Okta configuration -->
  <add key="okta:ClientId" value="{Your-Client-ID}" />
  <add key="okta:ClientSecret" value="{Your-Client-Secret}" />
  <add key="okta:OktaDomain" value="https://{Your-Okta-Domain}" />
8
  <!-- 3. Update these values -->
  <add key="okta:RedirectUri" value="{Website-Umbraco-Path}" />
  <add key="okta:PostLogoutRedirectUri" value="{Website-Umbraco-Path}" />  
    
  <!-- 4. When Autolinking is true, Okta Authenticated users will be created in the 
          CMS Database with the permission of writer if they don't already exist -->
  <add key="okta:EnableUmbracoAutoLinking" value="true"/>
                
            

Okta requires the site to be running in HTTPS, even when testing locally.

Step 4: Enabling Multifactor Authentication

Multifactor authentication (MFA) is handled by Okta and does not require any further Umbraco configuration. These instructions will be very brief as they may differ for various organizations depending on whether or not they have already setup MFA in the past.

In the developer console, select Security → Multifactor and create an policy if you don’t have one, make sure you have applied this policy to the group or people that login to the app. This part of the process also controls what happens the first time a user logins in or registers.
Choose your application of the Applications → Applications
On the Sign-On tab, create a policy to determine what happens when a user signs in. Here you control what happens every time a user logins in, such as force MFA, or only request MFA one a day.

That’s it! Umbraco and Okta will be working as one to keep your CMS back office safe and secure.

Integrating Okta SSO with Umbraco CMS

Instructions on how to integrate Umbraco CMS and Okta

Step 1: Add an App into Okta

Step 2: Add the Okta Middleware to the Umbraco solution

Step 3: Update the Web.Config

Step 4: Enabling Multifactor Authentication

Latest

Categories

Archive

Integrating Okta SSO with Umbraco CMS

Instructions on how to integrate Umbraco CMS and Okta

Step 1: Add an App into Okta

Step 2: Add the Okta Middleware to the Umbraco solution

Step 3: Update the Web.Config

Step 4: Enabling Multifactor Authentication

Latest

Categories

Archive

Newsletter