Today I am guiding you through OpenID Connect federation with Entra ID (Azure AD), with other words I will teach you how to configure Entra ID authentication for any web service out there.
What is Open ID and Open ID Connect?
Open ID is an open source model for IDs (identities) across Internet, a competitor to SAML. OpenID and SAML issues a token after given the correct credentials, which you can exchange for access to services.
And with Open ID Connect we build upon OpenID by separating information into three tokens. We can then encrypt these tokens individually to secure information travelling across the Internet even more.
Because tokens often bear information about you, which should be kept secure and reliable until the recieving service deciphers your token to read out information about you. To understand more about information carried through token, please read my previous post on Entra ID Provisioning API.
But what about SAML?
Most services out there still support SAML, and there is not a rush to convert from SAML to OpenID Connect (OIDC). SAML still holds hackers away, but OIDC is more simple, yet has more modern support. Especially when using mobile apps, where sign-in doesn’t happen in a browser.
Key words to understand
Identity Provider, is the service that provides the identity and primary token to access federated services. Today this is Entra ID.
Service Provider, is the service you are trying to access. Usually a web service, and there is a wast amount of services available from the Enterprise Application Gallery in Entra ID to help configuring federated authentication.
Request, is the package your service provider creates, in which you present to the identity provider.
Redirect URI, is the list of allowed URLs you can during the request, request to be forwarded to after successfull authentication by the Identity Provider.
Access token, the token issued by the identity provider as part of the OpenID flow. Depending on the service provider, you can chose to only send an ID token provided by the OIDConnect layer.
Claims, are information your service provider needs to find in the token, and we configure claims on the identity provider. This is usually information from the users profile/attributes.
Certificates, is used to cipher tokens after authentication by the identity provider. This certificate is shared in secret with the service provider, allowing the service provider to decipher the token and read your information. Some service providers doesn’t need any claims from the token, but know you are authenticated by the trusted identity provider due to simple having a token. If the identity provider doesn’t authorize you access, it will not serve you a token.
Metadata, is a common way to import necessary information about the identity provider into the service provider. There is no secrets here, it is just easier for a service provider to import the settings from a metadata URL or file, rather then typing it in manually.
Enterprise Application and Application Registration
Entra ID has to layers for applications, Enterprise Applications and Application Registrations. I have read many attempts at explaining the difference, and they all seem to come a bit short. So rather then trying again, I will just explain the differences you need to know in the context of this topic.
Enterprise Applications supports different type of authentication, among them are SAML and Password-based authentication. The last option will map the sign-in page and store the credentials, so the second time you authenticate it will happen automatically.
Application Registrations supports OpenID and OpenID Connect, so based on the context in this post, navigate to App Registrations in Entra ID when creating you identity providers application. This visually different from the Enterprise Application as the Single Sign-On blade will enable you to add additional custom claims, while in an Enterprise Application it doesn’t support this for OpenID.
However, if you configure Azure AD Application Proxy aka Entra ID Private Access on the app registration, the settings under Single Sign-On where I will show you how to use custom claims in OpenID, changes to the Enterprise Application view. So in order to have access to the custom claims configuration, make another application to configure the proxy.
Understanding the authentication flow
Here is a quick picture of the authentication flow when using OIDC, and I only want to emphasize that there is in no circumstances necessary for the identity provider and service provider to communicate directly. Part of the security built into bought SAML, OpenID and OIDC is that all communication goes through your client/device. It your device that talks to the identity service, its your device that talks to the service provider and it is your device that makes every exchange in the flow.
Thanks to Microsoft for this flow chart.
Entra ID configuration for OIDC
Here is screenshots from creating an Application Registration and configure the application to do OpenID authentication with custom claims.
Thanks to Unit4 for pictures, as I recently worked with their team to federate authentication to their ERP system.
In the screenshot below you choose who can access this application, and as long as you only need to support members of your own tenant, including invited guest accounts from other tenants, we can chose the single tenant support.
This is more secure, as all other identities will be denied access at the front door.
Remeber to add your services URLs in the above blade along with the Service Providers Identity Proxy service redirect URIs. Often they are the same, but in this example the Identity Provider is a hosted solution and the services is self-hosted. Hence they are separated and we need them all to be accepted redirect URIs.
Here you can add claims into the different type of Open ID Connect tokens, based on the default schema of attributes in Entra ID with Open ID Connect tokens.
Custom claims
The list supported by the GUI in Application Registration or what is called the default schema isn’t always enough, because there is more attributes on each user you could want to include in the token.
An example often used is the EmployeeID attribute, but we can still have it included in the token.
Head over to Enterprise Application and search for your application, here under Single Sign-On we can add custom claims like this.
However, in order for this to work we have to accept mapped claims on our app registration. This pretty straight forward if your only serving users or guest accounts in a single Entra ID tenant (included guest accounts).
Go back to the Application Registration and you will find the Manifest on your Apps menu.
Copy/paste these two lines of code to replace the values set in the default manifest at line 3 and 4, then save.
"acceptMappedClaims": true,
"accessTokenAcceptedVersion": 2,
Verification and troubleshooting
One, if not, the most common issue when configuring a federation, is the game of blaming the other side.
Is the URL correct? Is the certificate correct? Have anyone made a typo? Does the token actually have the claim? Is the claim empty?
This is a good reason to understand a bit of troubleshooting, and being able to decipher the token can help understand what attributes and values are inside the token for the service provider to collect.
Jwt.ms is site with tools to decipher the token, if you can collect it from a browser using developer tools (F12) or capturing tools like Fiddler.
Or you can allow oauth.tools access to your application registration, and it will work as client to collect the token on its own.
Other then that the error messages shown in the client will often give information about what’s going on, but sometimes you need to dive deeper hoping the service you fail on has sign-in logs to better explain what went wrong.
Thank you for reading, and I hope it was helpful. Please don’t hesitate to get in touch if something is changed/wrong or you could use some help.
