This manual page is mainly for area owners, key customer contacts, but also for end-users so that they can be aware of such solution and can ask management or proper ICT contacts to implement it also in their environment.
TDS platform does not need any external users source as it has it own identity with users database. Every TDS user has account in TDS with his own password and can enable MFA/2FA for better security.
However if organisations would like to make life easier for users by allowing them to be singned-in/authenticated seamlessly just by clicking "OrganisationX AzureAD" button instead of entering credentials, they can decide to integrate TDS platform into AzureAD or similar kind of identity provider.
OpenID Connect (OIDC) is quite straightforward and modern solution for adding support for centralised authentication. We usually meet together with customer organisation representatives and their identity provider administrators and settle down procedure details and requirements. Then AzureAD adminstrators need to follow steps how to integrate TDS Keycloak using OIDC as defined in this chapter.
Azure portal is expected to be used: https://portal.azure.com/#home
Set Redirect URI to callback URL:
https://identity.core.tds.CUSTOMERX.com/auth/realms/tds/broker/main-oidc/endpoint |
It says that it is optional, but it is mandatory in our case. |
First we add new policy for TDS Keycloak in Azure AD, for example "Tietoevry-TDS-Keycloak-Policy" in this case:
New-AzureADPolicy -Definition @('{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"true", "ClaimsSchema": [{"Source":"user","ID":"givenname","JwtClaimType":"given_name"},{"Source":"user","ID":"surname","JwtClaimType":"family_name"},{"Source":"user","ID":"mail","JwtClaimType":"mail"},{"Source":"user","ID":"onpremisessamaccountname","JwtClaimType":"samaccountname"}]}}') -DisplayName "Tietoevry-TDS-Keycloak-Policy" -Type "ClaimsMappingPolicy" |
Then we link service principal policy to Enterprise application (always remember to use correct ID):
Add-AzureADServicePrincipalPolicy -Id "<Enterprise-Application-UUID>" -RefObjectId "9cb83e39-8b0b-40da-8e2c-e49b8d2522b7" #'Tietoevry DevOps Space (TDS) Keycloak' & 'Tietoevry-TDS-Keycloak-Policy' |
Then go to application permissions and grant "Admin" consent (on behalf of all users in this tenant) as following:
| Microsoft Graph | Claim value | Permission | Type | Granted through | Granted by |
|---|---|---|---|---|---|
| Microsoft Graph | User.Read | Sign in and read user profile | Delegated | Admin consent | An administrator |
Find line with "acceptMappedClaims" and change it from "null" to "true"
Click "Save"
TDS team needs following details in order to finish integration:
| Attribute | Example/template value |
|---|---|
| Authorization URL | https://login.microsoftonline.com/<TENANT-ID>/oauth2/v2.0/authorize |
| Token URL | https://login.microsoftonline.com/<TENANT-ID>/oauth2/v2.0/token |
| Client ID | b1a10f18-5456-47c3-9843-d90cd58c5278 |
| Client Secret | m4yg87DR-_juvp~Tv4U9w-q9x8Mzmo~1Lp |
TDS team then takes over and finishes setup according to internal documentation Identity broker Azure AD OpenID Connect setup#Keycloakpart.
Details need to be discussed on meeting with customer representatives and AzureAD administrators.
TDS team recommends OIDC option as its setup and maintenance is generally easier and more flexible than SAML. For example SAML requires proper timing of certificates exchanges when multiple teams/parties must organise themselves in corporate environments - this makes even regular changes more complicated. OIDC requires regular exchanging of secrets, however thanks to possibility to have multiple secrets at the very same time, changes are easier and do not require strict timing like in SAML case when certificates are being exchanged. SAML setup is less straightforward than in OIDC case.
This solution is getting less and less popular in favour of AzureAD, but it is still possible to integrate using ADFS if there is no other way.