Intro

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.

Azure AD integration with TDS Keycloak using OpenID Connect

This is quite straightforward and modern solution for adding support for centralised authentication.

These are instructions for AzureAD adminstrators how to integrate TDS Keycloak using OIDC.

Registering application in Azure portal

Azure portal is expected to be used: https://portal.azure.com/#home

• Go to https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps
• Click "New registration"
• Set name "Tietoevry DevOps Space (TDS) Keycloak" or something similar
• Select who can use it, usually first option "Accounts in this organizational directory only (Tietoevry only - Single tenant)" is OK

• 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.

  
  

• Click "Register"
• On shown overview screen you shall find and copy following values that will be needed later for setup on Keycloak side:
  • Application (client) ID
  • Directory (tenant) ID
• Following claims need to enabled:
  • sAMAccountName (onpremisessamaccountname)
  • email
  • firstname
  • lastname
• AzureAD team must run following powershell commands to properly enable "sAMAccountName" claim

  • 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"

    https://docs.microsoft.com/en-us/powershell/module/azuread/new-azureadpolicy?view=azureadps-2.0-preview

  • Obtain relevant Enterprise application ID
    • Go to Enterprise Applications https://portal.azure.com/#blade/Microsoft_AAD_IAM/StartboardApplicationsMenuBlade/AppAppsPreview/menuId/
    • Search for application with name that you registered in previous step

  • 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'

    https://docs.microsoft.com/en-us/powershell/module/azuread/add-azureadserviceprincipalpolicy?view=azureadps-2.0-preview

  • 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

    
    

  • Then go to "Manifest" and enable custom claims mapping as suggested in https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-claims-mapping#security-considerations 

    • Find line with "acceptMappedClaims" and change it from "null" to "true"

    • Click "Save"

Providing information to TDS team

TDS team needs following details in order to finish integration:

We also need to setup process for replacing secret on regular basis according to validity possibilities.

ADFS integration with TDS Keycloak using SAML

This solution is not as popular as AzureAD, but it is still possible to integrate this way if there is no other way. It is less flexible than OIDC as it requires proper timing of certificates exchanges when multiple teams/parties must organise themselves in corporate environments. From this point of view OIDC integration is recommended as it is quite easy to setup and it is more flexible than ADFS with SAML. Although OIDC requires regular exchanging of secrets, thanks to possibility to have multiple secrets at the same time, changes are very easy and do not require strict timing like in SAML case when certificates are being exchanged.

Also setup is less straightforward than in OIDC case. In case of need we provide consultancy.