<style>p { margin: 0; }span.fr-emoticon.fr-emoticon-img { background-repeat: no-repeat !important; font-size: inherit; height: 1em; width: 1em; min-height: 20px; min-width: 20px; display: inline-block; margin: -0.1em 0.1em 0.1em; line-height: 1; vertical-align: middle; } span.fr-emoticon { font-weight: normal; font-family: "Apple Color Emoji", "Segoe UI Emoji", "NotoColorEmoji", "Segoe UI Symbol", "Android Emoji", "EmojiSymbols"; display: inline; line-height: 0; } blockquote { border-left: solid 2px #5e35b1; color: #5e35b1; margin-left:0; padding-left:5px;}blockquote blockquote{ border-color: #00bcd4; color: #00bcd4;}blockquote blockquote blockquote{ border-color: #43a047; color: #43a047;} table.grid{ border-collapse: collapse;} table.grid td, table.grid th { border: 1px solid #ddd;} .fr-fic.fr-dib{ display: block; margin: 5px auto;}.fr-fic.fr-dib.fr-fir{ text-align: right; margin: 5px 0 5px auto;}.fr-fic.fr-dib.fr-fil{ text-align: left; margin: 5px auto 5px 0;}.fr-fic.fr-dii{ float: none; margin: 5px auto;}.fr-fic.fr-dii.fr-fil{ float: left; margin: 5px auto;}.fr-fic.fr-dii.fr-fir{ float: right; margin: 5px auto;}img.fr-dib.fr-fir { margin-right: 0; text-align: right;}img.fr-dib.fr-fil { margin-left: 0; text-align: left;}img.fr-dib { margin: 5px auto; display: block; float: none;}img.fr-bordered { box-sizing: content-box; border: solid 5px #CCC;}img.fr-shadow { box-shadow: 10px 10px 5px 0px #cccccc;}img.fr-rounded { border-radius: 10px; -moz-border-radius: 10px; -webkit-border-radius: 10px; -moz-background-clip: padding; -webkit-background-clip: padding-box; background-clip: padding-box;}</style><style>
p {
margin: 0;
}
span.fr-emoticon.fr-emoticon-img {
background-repeat: no-repeat !important; font-size: inherit; height: 1em; width: 1em; min-height: 20px; min-width: 20px; display: inline-block; margin: -0.1em 0.1em 0.1em; line-height: 1; vertical-align: middle;
}
span.fr-emoticon {
font-weight: normal; font-family: "Apple Color Emoji", "Segoe UI Emoji", "NotoColorEmoji", "Segoe UI Symbol", "Android Emoji", "EmojiSymbols"; display: inline; line-height: 0;
}
blockquote {
border-left: solid 2px #5e35b1; color: #5e35b1; margin-left: 0; padding-left: 5px;
}
blockquote blockquote {
border-color: #00bcd4; color: #00bcd4;
}
blockquote blockquote blockquote {
border-color: #43a047; color: #43a047;
}
table.grid {
border-collapse: collapse;
}
table.grid td,
table.grid th {
border: 1px solid #ddd;
}
.fr-fic.fr-dib {
display: block; margin: 5px auto;
}
.fr-fic.fr-dib.fr-fir {
text-align: right; margin: 5px 0 5px auto;
}
.fr-fic.fr-dib.fr-fil {
text-align: left; margin: 5px auto 5px 0;
}
.fr-fic.fr-dii {
float: none; margin: 5px auto;
}
.fr-fic.fr-dii.fr-fil {
float: left; margin: 5px auto;
}
.fr-fic.fr-dii.fr-fir {
float: right; margin: 5px auto;
}
img.fr-dib.fr-fir {
margin-right: 0; text-align: right;
}
img.fr-dib.fr-fil {
margin-left: 0; text-align: left;
}
img.fr-dib {
margin: 5px auto; display: block; float: none;
}
img.fr-bordered {
box-sizing: content-box; border: solid 5px #CCC;
}
img.fr-shadow {
box-shadow: 10px 10px 5px 0px #cccccc;
}
img.fr-rounded {
border-radius: 10px; -moz-border-radius: 10px; -webkit-border-radius: 10px; -moz-background-clip: padding; -webkit-background-clip: padding-box; background-clip: padding-box;
}
</style><p id="isPasted"><strong>In this guide we will cover:</strong></p><p id="isPasted"><strong>- What is the KeyCloak Integration?</strong></p><p><strong>- Connecting to KeyCloak</strong></p><p><strong>- User and Agent Mapping</strong></p><p><br></p><p><br></p><p><strong>Related Guides:</strong></p><ul><li style="font-weight: bold;"><a href="https://usehalo.com/haloitsm/guides/2285" target="_blank" rel="noopener noreferrer"><strong>SAML 2.0</strong></a></li></ul><p><br></p><p><strong><span style="font-size: 14pt;">What is the KeyCloak Integration?</span></strong></p><p>The KeyCloak integration allows use of SAML to authenticate users and agents.</p><p><br></p><p><strong><span style="font-size: 14pt;">Connecting to KeyCloak</span></strong></p><p>Go to the SAML (AD FS) integration within Halo and ensure it is enabled.</p><p><br></p><p>Click into the module and then click this button to download the Metadata.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjJkMmY2YmRlLWY1YzEtNDdkMy05NTRjLTg2ZjYwNjgxN2E4YSJ9.w5YcwtF0dkkS-nsWxTuugoiiK5tXxQp5LM1mqG564Hk" class="fr-fic fr-fil fr-dib" width="557" style="width: 559px; height: 132.706px;" height="133"></p><p><strong><span style="font-size: 10pt;">Fig 1. Download Metadata button.</span></strong></p><p><br></p><p>Once downloaded, you will need to add 'contactType="technical"' to the <md:ContactPerson> tag, such as below.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ijk1ZGZjZTVlLWVjN2MtNGM4NS1hODFlLWQ1ODM5ZDYzMTBkNCJ9.eZip-xIaSVaKOumooTLckAZoPybWxbpFgHQSKxjZLbE" class="fr-fic fr-fil fr-dib" width="701" style="width: 703px; height: 173.134px;" height="173"></p><p><strong><span style="font-size: 10pt;">Fig 2. Adding contact type in.</span></strong></p><p><br></p><p>This is because KeyCloak uses this as a validator.</p><p><br></p><p>Next, go to KeyCloak admin portal, select the realm you are wanting to use with Halo and select 'Clients'. Then, select "Import client".</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjA3MmFkMjNjLTZiNzktNDUwNC05YzRkLTU3ZGM4MmZmMjg4OCJ9._c41bYoqZiO-KVveU2KKy8snp1iq4HXy0xPTsfp246w" class="fr-fic fr-fil fr-dib" width="767" style="width: 769px; height: 242.093px;" height="242"></p><p><strong><span style="font-size: 10pt;">Fig 3. Import client button.</span></strong></p><p><br></p><p>From there, upload the metadata we downloaded and edited from Halo and click 'Save'.</p><p><br></p><p>Now, head over to 'Realm settings' and select 'SAML 2.0 Identity Provider Metadata'.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjgzZjhkZjdkLTJiZTMtNDAzYS1iMTRjLTEzNjQyYzU5MzZiYSJ9.35NUsotJrBD6eo5rDKtfLAUtPTM43CLKcQmiW53CjUA" class="fr-fic fr-fil fr-dib" width="878" style="width: 880px; height: 788.435px;" height="788"></p><p><strong><span style="font-size: 10pt;">Fig 4. Selecting the endpoint.</span></strong></p><p><br></p><p>This will either pop out or download an XML file, you want to open this and take a note of the below two values:</p><p><br></p><ul><li>Single Sign On Service Location where the binding is for HTTP-POST: <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="<a data-fr-linked="true" href="http://localhost:8080/realms/master/protocol/saml" id="isPasted"><strong>http://localhost:8080/realms/master/protocol/saml</strong></a>"/></li><li>X509Certificate value</li></ul><p>You then need to head over to Halo and add the Location URL to the 'Login URL' section and copy the certificate value in the 'X509 Certificate for signature validation' section, ensuring to have -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- and the start and end respectively:</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImUwYzQ3ZGU3LTVmMWEtNDZlMy05MTNmLTExYmQ5M2RlZGUwYiJ9.FdSjDBZydAB1nf3CQCxJ2vGsQz_-uxPhAfqSH4PvmBk" class="fr-fic fr-fil fr-dib" width="1120" style="width: 1122px; height: 669.815px;" height="670"></p><p><strong><span style="font-size: 10pt;">Fig 5. SAML configuration.</span></strong></p><p><br></p><p>You also need to ensure that 'Sign all AuthnRequests sent to the identity provider' is selected.</p><p><br></p><p><br><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImQzZTU0NDdhLWMzZmEtNDkwNC05YzhiLWJmMzE1MjcxMDc5YiJ9.xdhTYjZoqDSPShNTho_UFrboJ96FQNaCkR5WzZdOT30" class="fr-fic fr-fil fr-dib" width="763" style="width: 765px; height: 943.175px;" height="943"></p><p><strong><span style="font-size: 10pt;">Fig 6. Enabling signing of AuthnRequests.</span></strong></p><p><br></p><p><strong><span style="font-size: 14pt;">User and Agent Mapping</span></strong></p><p>You now need to configure the mappings to ensure the users within KeyCloak match the users within Halo. You can do this with either email address or a custom value stored in any other the other fields. To do this using email, you need to ensure that email is set for the Name ID format in KeyCloak, which is done by going to the client configuration.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImMwODRhMTNkLTQ2NTktNDFhYS05ZmNmLWU1ZTIwYWFhOWJhMyJ9.XC4-AlZ2iepNAEYtX1U_BIFhtakZyNKRDTW0t1WcHTc" class="fr-fic fr-fil fr-dib" width="1206" style="width: 1208px; height: 422.14px;" height="422"></p><p><strong><span style="font-size: 10pt;">Fig 7. Setting format to email.</span></strong></p><p><br></p><p>And that the 'User Matching Field' within Halo is set to email.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImUyYzJmZTg2LTgwMmEtNDI0MS1hZDZjLWUwODY1MDFmOTA4MyJ9.fm6DpDLpJ3KDXps5ScaRkeB9eGL1JFfKZwYY85nQ3pk" class="fr-fic fr-fil fr-dib" width="613" height="700"></p><p><strong><span style="font-size: 10pt;">Fig 8. Setting the user matching field to email.</span></strong></p><p><br></p>
