...

Azure AD integration with TDS Keycloak using OpenID Connect

This OpenID Connect (OIDC) is quite straightforward and modern solution for adding support for centralised authentication.These are instructions for AzureAD adminstrators . 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.

Registering application in Azure portal

...

• 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 (for example Tietoevry only - Single tenant)" is OK

• Set Redirect URI to callback URL:

  Code Block
  https://identity.core.tds.CUSTOMERX.com/auth/realms/tds/broker/main-oidc/endpoint

  
  

  Note
  It says that it is optional, but it is mandatory in our case.

  
  

• Click "Register"
• On shown overview displayed "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
• Generate Client Secret
  • Go to "Certificates & secrets"
  • Click "New client secret"
    • Provide some description like "keycloak" or "CustomerX Keycloak"
    • Make secret valid for as long period as applicable or possible - usually maximum number of months that organisation allows or even infinity.
      • Remember to generate new secrets on regular basis as security measure. Implementing process for replacing secret on regular basis according to validity possibilities is highly recommended.
    • Click "Add"
    • Now you MUST copy "Value" of new secret otherwise it will disappear soon. It will be needed later for setup on Keycloak side.
• 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:

    Code Block

    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):

    Code Block
    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"

...

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

...

TDS team then takes over and finishes setup according to internal documentation Identity broker Azure AD OpenID Connect setup#Keycloakpart.

Google integration with TDS Keycloak using SAML

• Follow official instructions to set up custom SAML

...

• application - https://support.google.com/a/answer/6087519?hl=en
  • Metadata will be provided by TDS team, but usually it is at Keycloak URL like https://identity.core.tds.CUSTOMERX.com/auth/realms/tds/broker/google-saml/endpoint/descriptor
• Make sure to set up following attribute mapping:
  • E-mail >> email
  • Windows Login >> sAMAccountName
  • First Name >> FirstName
  • Last Name >> LastName
• Define custom initial page to portal URL, like https://tds.CUSTOMERX.com
• Provide GoogleIDPMetadata.xml metadata file to TDS team.

Azure AD integration with TDS Keycloak using SAML

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 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 - 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 very easy easier and do not require strict timing like in SAML case when certificates are being exchanged.Also  SAML setup is less straightforward than in OIDC case. In case of need we provide consultancy

ADFS integration with TDS Keycloak using SAML

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.