Overview
A Service Provider (SP) such as the F5 APM can integrate with Azure AD (AAD) as an Identity Provider (IDP) for federated authentication using OpenID Connect (OIDC).
Through this process, a user visiting APM (e.g., https://myapps.acme.corp ) is immediately redirected to AAD for authentication, once authenticated, AAD returns a code to the APM via the user browser. The APM grabs that code, adds additional information, sends them together to AAD, and finally receives an ‘access_token’ and ‘id_token’.
This article takes a special focus around what is included in ‘id_token’ that AAD returns, as it is used by APM, and broadly speaking by any relying party SP, for the purpose of session creation.
‘id_token’ (part of OIDC) contains user identity information and is highly customizable.
The customization of ‘id_token’ is completely done within AAD. The concept is simple, but not until it is well understood in my experience; especially with the AAD having a bunch of configuration items in the mix, such as ‘Token configuration’, ‘API permissions’ and ‘Expose an API’.
This article hopes to cut all the clutter and un-muddy the water so to speak, around this topic.
OIDC
As a refresher, the difference between oAuth and OIDC lies in that OIDC is an identity piece laying on top of oAuth.
Specifically, with oAuth, ‘access_token’ alone is returned, whereas with OIDC, ‘id_token’ is returned in addition to ‘access_token’.
Scope
To tell AAD we are using OIDC, the APM needs to include a scope named ‘openid’ in its outbound request to the AAD. This is achieved via the following setting.
Within AAD, your application must include ‘openid’, as shown below.
By default, the ‘openid’ scope comes with a list of claims that will be included in ‘id_token’. However, for certain claims to be available, additional scopes are also required.
For example, if you want to have ‘preferred_username’and ‘name’ claims included, ‘profile’ scope needs to be added as well, as is depicted in the following.
AAD also lets you add optional claims via ‘Token configuration’ as shown below.
If these optional claims need additional scopes, AAD will add those scopes in for you under ‘API permissions’.
On the APM ‘OAuth Client’ configuration, make sure to add those scopes in as highlighted below.
Once the APM matches scope with AAD, AAD will include all claims in ‘id_token’ it sends back to the APM. The APM is then able to consume those claims based on the use case (e.g., create a session using email)
I am hoping that this short article sheds some light around your integration work around this space.