{ "componentChunkName": "component---src-pages-blog-markdown-remark-fields-slug-js", "path": "/blog/how-to-implement-oidc-with-microsoft-entra-id", "result": {"data":{"markdownRemark":{"html":"

Table of Contents

\n\n \n \n \n \n
\n\n
\n

How to implement OIDC with Microsoft Entra ID

\n

Microsoft Entra ID - previously known as Azure AD - is a popular cloud-based version of Active Directory. Many companies love using Active Directory to organise their company and manage user permissions and roles. This makes Active Directory a great candidate for being an Identity Provider for applications that support SSO.

\n

This guide will both show you how to make your own Oauth/OIDC implementation in express as well as how to integrate Entra ID SSO with SuperTokens. SuperTokens is our authentication platform that you can integrate in your web applications to handle user sessions.

\n

How the Oauth/OIDC Flow works

\n

The user is redirected to the identity provider’s website in order to give their credentials and verify themselves. After the user has been verified, the provider sends us back an authorization code that we can trade for an id token that contains the user’s basic information, like name and email. The information we can read is set in the scope, which is shown to the user when they log in to their identity provider.

\n

Create an application in Microsoft Entra ID

\n

In order to set up Oauth, we have to register our application with Microsoft so it knows what application is asking for user information. When we register, we are given a Client ID that we give back to Microsoft during the Oauth process so it knows it’s us.

\n

Head to the Microsoft Entra homepage. On the left sidebar, click Applications -> App Registration -> Create a New Registration. This page will ask you for a Redirect URI and a platform. The platform will be web. The Redirect URI is where Microsoft will send the access code to during the Oauth flow. This endpoint will need to be created later in your app, but we can tell Microsoft what it will be now.

\n

Express redirect URI: http://localhost:3000/auth/callback

\n

SuperTokens redirect URI: http://localhost:3000/auth/callback/entra

\n

Under supported account types, you’ll be asked if you want to handle single tenant, multi-tenant, or personal accounts. This will depend on your use case:

\n

Single tenant - making an internal tool and only want people in your organisation to be able to use this application.

\n

Multi-tenant - making a tool for corporate users that allows others to login with their Entra ID account.

\n

Common - allows anyone with any microsoft account to log in (xbox, skype, etc)

\n

Select whichever use case is right for you.

\n

After saving, you should be redirected to the overview page containing your Client ID (also referred to as an Application ID). If you aren’t redirected to this page, then you can click security -> permissions -> app registration -> overview in the new left hand tab. Save the Client ID to add to your application later.

\n

\n \n \n \n \n

\n

Click on Authentication on the left hand side. Under the section “Implicit grant and hybrid flows”, select the option:

\n

ID tokens (used for implicit and hybrid flows)

\n

And then save at the bottom.

\n

Click “Certificates and Secrets” on the left side of the screen and create a new Client Secret. The Client Secret is used to verify that the Oauth flow was started by the owner of the registered app, as this key is meant to be kept private. Copy the Client Secret Value - and not the Client Secret ID - for use later in the application.

\n

\n \n \n \n \n

\n

Finally, click Overview -> endpoints at the top of the page. Copy the OpenID Connect metadata document url for later.

\n

Configure your application for Microsoft Entra ID Oauth

\n

If following the supertoken steps, you can scroll to the next section. If you’re doing a custom integration, follow these steps.

\n

Let’s create our express server and handle the Oauth flow.\nGenerate a new project:

\n\n \n \n \n \n
npm init
\n

Then add the needed dependencies:

\n\n \n \n \n \n
npm install --save express express-session axios dotenv cookie-parser
\n

Create a file named .env in the root of your project and add the following values:

\n\nCLIENT_SECRET_VALUE=\nCOOKIE_SECRET=\nSECRET=`, `56057654708647100000`)\"\n >\n \n \n \n \n
CLIENT_ID=<YOUR_CLIENT_ID>\nCLIENT_SECRET_VALUE=<YOUR_CLIENT_SECRET_VALUE>\nCOOKIE_SECRET=<SECRET_FOR_COOKIES>\nSECRET=<SECRET_FOR_EXPRESS_SESSION>
\n

Now we can start making our express app.

\n

We’ll create an index.js file to write our express server in. After that, we’ll make an auth endpoint that sends the user to Microsoft with our Client ID so Microsoft knows it’s our application starting the process. We’ll also add some code to initialise an express session for after the user has authenticated themselves, generate state to mitigate CSRF attacks, and a configuration object that has the Oauth information needed for Microsoft.

\n {\n res.send('Login with Microsoft Entra ID');\n});\n\n// The auth endpoint generates our oauth url for Microsoft Entra ID\napp.get('/auth', (req, res) => {\n\n require('crypto').randomBytes(24, function(err, buffer) {\n let stateParam = buffer.toString('hex');\n res.cookie("stateParam", stateParam, { maxAge: 1000 * 60 * 5, signed: true });\n\n const authUrl = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?" + qs.stringify({\n client_id: config.clientId,\n response_type: 'code',\n redirect_uri: config.redirectUri,\n response_mode: 'query',\n scope: config.scope.join(" "),\n state: stateParam\n });\n\n res.redirect(authUrl);\n });\n\n \n});\n\napp.listen(3000, () => {\n console.log(\\`Server is running on port 3000\\`);\n});`, `39331368264399560000`)\"\n >\n \n \n \n \n
require('dotenv').config()\n\nconst express = require('express');\nconst session = require('express-session');\nconst axios = require('axios');\nconst qs = require('querystring');\nconst crypto = require('crypto');\nconst cookieParser = require('cookie-parser');\n\n\nconst app = express();\n\n// Configuration settings for Microsoft Entra ID\nconst config = {\n  clientId: process.env.CLIENT_ID,\n  clientSecret: process.env.CLIENT_SECRET_VALUE,\n  redirectUri: \"http://localhost:3000/auth/callback\",\n  scope: [\"openid\", \"email\", \"profile\"]\n};\n\n// Add session middleware\napp.use(session({\n  secret: process.env.SECRET,\n  resave: false,\n  saveUninitialized: true\n}));\n\napp.use(cookieParser(process.env.COOKIE_SECRET));\n\n// The root path links us to the /auth endpoint, which generates\n// the url to start oauth flow\napp.get('/', (req, res) => {\n  res.send('<a href=\"/auth\">Login with Microsoft Entra ID</a>');\n});\n\n// The auth endpoint generates our oauth url for Microsoft Entra ID\napp.get('/auth', (req, res) => {\n\n  require('crypto').randomBytes(24, function(err, buffer) {\n    let stateParam = buffer.toString('hex');\n    res.cookie(\"stateParam\", stateParam, { maxAge: 1000 * 60 * 5, signed: true });\n\n    const authUrl = \"https://login.microsoftonline.com/common/oauth2/v2.0/authorize?\" + qs.stringify({\n      client_id: config.clientId,\n      response_type: 'code',\n      redirect_uri: config.redirectUri,\n      response_mode: 'query',\n      scope: config.scope.join(\" \"),\n      state: stateParam\n    });\n\n    res.redirect(authUrl);\n  });\n\n  \n});\n\napp.listen(3000, () => {\n  console.log(`Server is running on port 3000`);\n});
\n

Now let’s build the callback endpoint that Microsoft will send the Authorization Code to after the user has verified themselves. On this endpoint, we’ll trade the Authorization Code for an Access Token and Refresh Token and save it in our express session. This endpoint needs to listen on the same path that we gave Microsoft for our Callback URI. We’ll also tell this endpoint to redirect to a profile endpoint that we’ll define in the next step.

\n {\n const { code, state } = req.query;\n const { stateParam } = req.signedCookies;\n\n if (stateParam !== state) {\n res.status(422).send("Invalid State");\n return;\n }\n\n const tokenUrl = "https://login.microsoftonline.com/common/oauth2/v2.0/token?";\n\n const tokenParams = {\n client_id: config.clientId,\n scope: config.scope.join(" "),\n code,\n redirect_uri: config.redirectUri,\n grant_type: 'authorization_code',\n client_secret: config.clientSecret\n };\n\n try {\n const response = await axios.post(tokenUrl, qs.stringify(tokenParams), {\n headers: {\n 'Content-Type': 'application/x-www-form-urlencoded'\n }\n });\n\n // save the token data in the user session in express\n req.session.tokenSet = response.data;\n res.redirect('/profile');\n } catch (error) {\n console.error('Token exchange error:', error);\n res.redirect('/');\n }\n});\n`, `21794448652239450000`)\"\n >\n \n \n \n \n
// This is our Redirect URI\n// After the flow has started, Microsoft sends us back\n// an authorization code, authorizing us to get access and refresh tokens\n// on behalf of the user\napp.get('/auth/callback', async (req, res) => {\n  const { code, state } = req.query;\n  const { stateParam } = req.signedCookies;\n\n  if (stateParam !== state) {\n    res.status(422).send(\"Invalid State\");\n    return;\n  }\n\n  const tokenUrl = \"https://login.microsoftonline.com/common/oauth2/v2.0/token?\";\n\n  const tokenParams = {\n    client_id: config.clientId,\n    scope: config.scope.join(\" \"),\n    code,\n    redirect_uri: config.redirectUri,\n    grant_type: 'authorization_code',\n    client_secret: config.clientSecret\n  };\n\n  try {\n    const response = await axios.post(tokenUrl, qs.stringify(tokenParams), {\n      headers: {\n        'Content-Type': 'application/x-www-form-urlencoded'\n      }\n    });\n\n    // save the token data in the user session in express\n    req.session.tokenSet = response.data;\n    res.redirect('/profile');\n  } catch (error) {\n    console.error('Token exchange error:', error);\n    res.redirect('/');\n  }\n});\n
\n

Now we’ll define our profile endpoint and logout endpoint. The Profile endpoint will use the token we received, call to Microsoft for the user’s information, and display it on the screen. And the logout endpoint will destroy the express session.

\n {\n if (!req.session.tokenSet) {\n return res.redirect('/');\n }\n\n const { id_token } = req.session.tokenSet;\n\n // the main profile information is in the body\n // of the JWT\n const body = id_token.split(".")[1];\n\n // convert it from base64 to utf8\n let bufferObj = Buffer.from(body, "base64");\n let string = bufferObj.toString("utf8");\n\n res.send(\\`

Profile

\\${string}

logout\\`);\n});\n\napp.get('/logout', (req, res) => {\n req.session.destroy((err) => {\n if (err) {\n console.error(err);\n }\n res.redirect('/');\n });\n});`, `4173008810535439000`)\"\n >\n \n \n \n \n
// grab token data from express session\n// and get user info from microsoft\napp.get('/profile', async (req, res) => {\n  if (!req.session.tokenSet) {\n    return res.redirect('/');\n  }\n\n  const { id_token } = req.session.tokenSet;\n\n  // the main profile information is in the body\n  // of the JWT\n  const body = id_token.split(\".\")[1];\n\n  // convert it from base64 to utf8\n  let bufferObj = Buffer.from(body, \"base64\");\n  let string = bufferObj.toString(\"utf8\");\n\n  res.send(`<h1>Profile</h1><span>${string}</span><br><br><a href=\"/logout\">logout</a>`);\n});\n\napp.get('/logout', (req, res) => {\n  req.session.destroy((err) => {\n    if (err) {\n      console.error(err);\n    }\n    res.redirect('/');\n  });\n});
\n

Now when we run our app, we can log into our Microsoft account and see our account information. Nice! Full Oauth flow finished for Microsoft Entra ID.

\n

Configure SuperTokens for Microsoft Entra ID Oauth

\n

Run to make a new SuperTokens project:

\n\n \n \n \n \n
npx create-supertokens-app@latest --recipe=thirdparty
\n

We need to configure the front-end to generate a “Login with Entra” button, so add the following to your front-end config.tsx.

\n
{"Login with " + props.name}
\n }\n ],\n },\n }),\n`, `57863494644765880000`)\"\n >\n \n \n \n \n
ThirdParty.init({\n            signInAndUpFeature: {\n                providers: [\n                    {\n                        // The ID sets your callback url\n                        // ie http://localhost:3000/auth/callback/entra\n                        id: \"entra\",\n                        name: \"Entra ID\", // Will display \"Continue with X\"\n\n                        // optional\n                        // you do not need to add a click handler to this as\n                        // we add it for you automatically.\n                        buttonComponent: (props: {name: string}) => <div style={{\n                            cursor: \"pointer\",\n                            border: \"1\",\n                            paddingTop: \"5px\",\n                            paddingBottom: \"5px\",\n                            borderRadius: \"5px\",\n                            borderStyle: \"solid\"\n                        }}>{\"Login with \" + props.name}</div>\n                    }\n                ],\n            },\n        }),\n
\n

Now we need to configure the back-end to handle the OIDC calls. We’ll set our scopes to [“openid”, “email”, “profile”], and our oidcDiscoveryEndpoint to the OpenID Connect metadata document we got in our application overview.

\n

Add the following to your config.ts

\n",\n clientSecret: "",\n scope: ["openid", "email", "profile"]\n }],\n oidcDiscoveryEndpoint: "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration",\n userInfoMap: {\n fromUserInfoAPI: {\n userId: "sub",\n email: "email",\n }\n }\n }\n },\n ],\n },\n })\n`, `9591313430247594000`)\"\n >\n \n \n \n \n
ThirdParty.init({\n            signInAndUpFeature: {\n                providers: [\n                    {\n                        config: {\n\t\t                        // The thirdPartyId connects to the front-end id\n                            thirdPartyId: \"entra\",\n                            name: \"Entra ID\",\n                            clients: [{\n                                clientId: \"<CLIENT_ID>\",\n                                clientSecret: \"<CLIENT_SECRET_VALUE>\",\n                                scope: [\"openid\", \"email\", \"profile\"]\n                            }],\n                            oidcDiscoveryEndpoint: \"https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration\",\n                            userInfoMap: {\n                                fromUserInfoAPI: {\n                                    userId: \"sub\",\n                                    email: \"email\",\n                                }\n                            }\n                        }\n                    },\n                ],\n            },\n        })\n
\n

Run npm run start and head to localhost:3000 in the browser. You’ll see the option Sign in with Entra. Click it and you’ll get a session signed in from Entra ID. How easy was that?

\n

\"Entra

\n

Conclusion

\n

Active Directory is a time tested way to store users and permissions. Its ability to integrate as an Identity Provider makes it valuable, especially to large organisations that have lots of users and permissions to manage. If you found the usual way of integrating Entra ID to be cumbersome, then try simplifying your SSO logins with SuperTokens.

\n

Github repo for express instance

\n

Github repo for SuperTokens project

","frontmatter":{"date":"January 07, 2025","title":"How to implement OIDC with Microsoft Entra ID","cover":"entra-id.png","author":"Connor Peshek","description":"Implementing OIDC with Microsoft Entra ID can be confusing. We're gonna help you implement it two different ways — in your own ExpressJS server or in SuperTokens."},"fields":{"slug":"/how-to-implement-oidc-with-microsoft-entra-id/"}},"site":{"siteMetadata":{"title":"SuperTokens Blog"}}},"pageContext":{"id":"c2a7768c-4077-5816-9c4b-5fe393bec295","fields__slug":"/how-to-implement-oidc-with-microsoft-entra-id/","__params":{"fields__slug":"how-to-implement-oidc-with-microsoft-entra-id"}}}, "staticQueryHashes": []}