Using OpenID Connect with Microsoft Azure AD

A step by step guide to achieve single sign on

OpenID Connect SSO walkthrough

So you have heard that SAML 2.0 is a lot more expensive than OpenID Connect when using Microsoft Azure AD as identity provider? OpenID Connect is an authentication protocol built upon the authorization framework OAuth 2.0. The JSON structure of OpenID Connect is more efficient than the XML format used by SAML 2.0 and consumes less bandwidth. Here's the guide to get you started.

Prerequisites

  • An active subscription to Microsoft Azure

App registration

First of all you need to register your Sitevision web site as an "app" in Microsoft Azure. Head over to https://portal.azure.com and login with your admin credentials.

Azure app registration
  • Click on "Azure Active Directory" in the left side menu.
  • Click on "App registrations" and then on "New registration"
Azure register an application


  • Give the app a friendly name. Example: The Bulletin
  • Select who can login through this app
  • Select "Web" in the dropdown for Redirect URI. The redirect URI to be entered must follow a very specific format. The format is https://<YOUR_DOMAIN>/openidconnect/login. Replace <YOUR_DOMAIN> with your domain. Example: https://thebulletin.sitevision.net/openidconnect/login
  • Click "Register"

Choose your friendly name wisely. This name will be presented to the user when the app ask for permission to login as the user

App configuration

Now that your app has been registered you need to customize it and collect some data. Remember to save your settings as we go along.

Azure collect IDs
  • Copy and store Application ID for later use
  • Copy and store Directory ID for later use

Next, go to "Authentication"

Azure Redirect URIs
  • Make sure that your previously registered Redirect URI is listed here
  • If you have any secondary domain names on your Sitevision web site, add them here as well. It must follow the same format as specified earlier. Example: https://anotherbulletin.sitevision.net/openidconnect/login

Go on and click "Certificates & secrets"

Azure Generate secret
  • Click the button "New Client secret"
  • Give the key a description
  • Set the expire time for the key
  • Click "Add"
  • Copy and store the Client secret for later use

If you choose to select any other expire time than "Never", make sure to set a calendar event to remind you to renew the secret before it expires. Maybe 10-20 colleagues need to set a reminder as well? Ask yourself what happens if none of your users can login because of an expired secret.

The secret will only be viewable until you leave the page. Copy the client secret before leaving the page. If you missed this step, just generate another secret and remove the previous one.

All the basic settings in Microsoft Azure are done.

Advanced configuration

There's a few advanced settings that might be interesting.

Azure Manifest

Include group claims in the id token

Just as in SAML2 it's possible to include group claims in the token during login. The group claims can be used to assign the user to a virtual group in Sitevision. The group claims are not included as default but can be easily added.

Click "Manifest" to view a JSON document defining the configuration of the app.

Change the value groupMembershipClaims from null to "SecurityGroup" or "All". See groupMembershipClaims in Azure Active Directory app manifest

  • "SecurityGroup" is for security groups and Azure AD roles
  • "All" will get all of the security groups, distribution groups, and Azure AD directory roles that the signed-in user is a member of.

Include extra claims in the id token

Some usable claims are omitted as default in the id token. family_name & given_name are nice-to-have claims.

Add a idToken definition to the manifest:

...
"optionalClaims": {
   "idToken": [
      {
         "name": "family_name", 
         "essential": false
      },
      {
         "name": "given_name", 
         "essential": false
      },
      {
         "name": "nickname", 
         "essential": false
      }
   ]
},
...

Sitevision settings

Filter configuration

Add an OpenID Connect authentication filter to your web site.


Azure authorization filter

Add the following properties:

  • OpenID Connect issuer URL: https://login.microsoftonline.com/<TENANT_ID>/v2.0. Replace <TENANT_ID> with the Directory ID from previous steps
  • Application ID: Paste the Application ID from previous steps
  • Client Secret: Use the client secret created in previous steps

Login module

Add an OpenID Connect login module to your web site.

  • Set the control flag to 'Sufficient'.
  • Make sure the module precedes the 'LDAP login module'

No further settings is needed. Now it's time to visit your web site.

Test the login flow

Azure login consent

When visiting a page that is not public, the user is redirected to Microsoft Azure. The user is asked to login, if not logged in already. The user is presented with a consent screen at the very first login. Permissions is requested for the app with the name as specified earlier. Example: The Bulletin.

After consenting, the user is redirected back to Sitevision.

Everything is done, enjoy the single sign on experience!

Do you want to subscribe to News from Sitevision Developer team? Subscribe here!