<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><strong>In this guide we will cover:</strong></p><p><strong>- API Details</strong></p><p><strong>- Application Configuration</strong></p><p><br></p><p><br></p><p><strong>Related Guides:</strong></p><ul><li><a href="https://usehalo.com/haloitsm/guides/1062/" target="_blank" rel="noopener noreferrer"><strong>Halo Integrator</strong></a></li></ul><p><br></p><p>This guide outlines the configuration of Halo applications which can be used to connect applications to your instance of Halo via the API.</p><p><br></p><p><strong><span style="font-size: 14pt;">API Details</span></strong></p><p>Navigate to Configuration > Integrations > Halo API to see the related configuration page. This area provides details about connecting to your instance of Halo via the API including resource and authorization servers as well as a link to our official API documentation.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY2NDJhOGEwLTM4N2ItNGRkMS1hZDQzLWM1OGFjODZmMDA3NiJ9.GmxQuJsby92G2txZCeoR-rhiGoOFjfW3i-L8y3auMs0" class="fr-fic fr-fil fr-dib" width="915" height="366"></p><p><strong><span style="font-size: 10pt;">Fig 1. API details</span></strong></p><p><br></p><p>Documentation about your Halo API can also be found at <Halo Web App Agent Portal URL>/api/swagger.</p><p><br></p><p>You are also able to connect to other instances of Halo utilizing the "Connected Instances" area.</p><p><br></p><p><strong><span style="font-size: 14pt;">Application Configuration</span></strong></p><p>From this page, click "View Applications" to find your list of Halo applications. Note that there are previously configured applications which are used to connect various aspects of your Halo Web App. Please do not adjust any of these existing applications as they are vital in the basic function of your instance of Halo.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjFhYzRjN2JlLWI0ZWQtNDdkZi04NjYyLTEzZWVkZmVjMmNiMiJ9.VabJ_ZYjOMJeF-l5_3slBUThgU3HFQINnPmrj-6MP8Q" class="fr-fic fr-fil fr-dib" width="1368" style="width: 1370px; height: 243.231px;" height="243"></p><p><strong><span style="font-size: 10pt;">Fig 2. List of applications</span></strong></p><p><br></p><p>To start a new application, click "New" on the top right corner of the screen. </p><p><br></p><p>From here on the "Details" tab, you will be prompted to name your application, enable it, and set its "Authentication Method". You can include a description here, and upon creation a "Creation Date" and "Created By" field will auto populate.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjUzMTM5ODU3LWMyOTgtNDg3ZS04ZGFjLWY1YjQ1OTYyZGYzMCJ9.B8508GjE0MLBKKPYu_Z6EeYjLgNmeRg3sA5kv2bCNek" class="fr-fic fr-fil fr-dib" width="1230" style="width: 1232px; height: 749.755px;" height="750"></p><p><strong><span style="font-size: 10pt;">Fig 3. Configuring the application</span></strong></p><p><br></p><p><span style="font-size: 12pt;"><strong>Authentication Methods</strong></span></p><ul><li>The following authentication methods are available for Halo API applications:</li><li>Username & Password</li><li>Implicit Flow (Single Page Application)</li><li>Authorisation Code (Native Application)</li><li>Client ID and Secret (Services)</li><li>API Key (This should only be used if the system you are integrating with does not offer one of the other OAuth flows)</li><li>JWT Assertion (Services) (v2.234.6+)<ul><li>This is similar to the Client ID & Secret flow and it offers improved security, but it is more difficult to implement. The user creates a JWT and signs it with a secret key, and sends the JWT to the token endpoint instead of the client secret. This avoids sending the secret to the token endpoint like in Client ID & Secret flow.</li></ul></li><li>Halo Automation Identity (v2.234.6+)</li></ul><p><br>For example, we can set our application to "Client ID and Secret (Services)" and we are provided a "Client ID" and "Client Secret" which we can utilize in another application to connect to your instance of Halo. We are also prompted to select a "Login Type" and setting specific to that login type.</p><p><br></p><p><strong><span style="font-size: 11pt;">Using Machine Identity</span></strong></p><p>When using a Client ID and Secret (or API Key) to authenticate you will be able to give the application a machine identity rather than having to have the application log in as (use the identity of) a specific agent. </p><p><br></p><p id="isPasted">This allows the application to not act as particular agent. This means it's access will not be tied to the access/permissions of a particular agent. Useful for auditing changes as it will be clear what changes actual agents have completed vs changes the application completes. Making it easier to restrict the application's permissions and follow the principle of least privilege. </p><p><br></p><p>To do this set the "Agent to log in as" as "Application identity". </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjJkOGZlOTA4LTE3NDItNGY4Mi05ZjUzLTQ1NzMwYzEzMWM2NyJ9.F9t6D1tRyBupLpjdqqNlOKLIzXumA1t8ljtK9cpx6Z0" class="fr-fic fr-fil fr-dib" width="1218" style="width: 1220px; height: 705.895px;" height="706"></p><p><strong><span style="font-size: 10pt;">Fig 4. Create application to authorise using a machine (application) identity</span></strong></p><p><br></p><p>Once chosen you will be able to give the application "Identity Roles". The role chosen here will determine what the application has permission to do in your instance. The roles available here will be determined by the <a data-fr-linked="true" href="https://usehalo.com/haloitsm/guides/1900" id="isPasted" target="_blank" rel="noopener noreferrer">agent roles</a> you have created in your instance, however the "sys-all-permissions" role will also be available. </p><p><br></p><p><strong>sys-all-permissions -</strong> This role grants highest levels of access, access will then be filtered down based on selected scopes.</p><p><br></p><p><strong>Require JWT Assertion - Client ID and Secret method only </strong></p><p>JWT assertions can be added as a requirement for API applications using the Client ID and Secret authentication method. This adds additional security to applications, it is not necessary most of the time but it is recommended for applications with high privileges. </p><p><br></p><p><strong><span style="color: rgb(226, 80, 65);">Important: From v2.234+ this option will be replaced with the JWT Assertion (Services) authentication method. Existing applications using this will not be affected. </span></strong></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImI0ODcyYjNmLTcwOTQtNDdlMy1hNjhmLTQxYmI5NTg4YTEwNSJ9.AMzZHxmn7ck1fTh0L2qORhHQKNrEBGgOAzIZYgOnIZM" class="fr-fic fr-fil fr-dib" width="945" style="width: 947px; height: 629.11px;" height="629"></p><p><strong><span style="font-size: 10pt;">Fig 5. Enable the requirement of JWT assertion to authenticate an application</span></strong></p><p><br></p><p>When used, you will need to generate a JWT, this will need to be signed with a RSA private key using the PS256 algorithm. The Halo server will then validate the JWT supplied the in the "client_assertion" property, using the known public key. </p><p><br></p><p>Once the application authorisation is set you can give the application scopes/permissions. </p><p><br></p><p data-pasted="true"><strong><span style="font-size: 11pt;">Halo Automation Identity (v2.234.6+)</span></strong></p><p data-pasted="true">This authentication method is used when integrating with your own Halo instance. This authenticates access to your own instance, coming from your own instance. This can only be used within the Halo runbooks engine. It cannot be used when integrating Halo with a third party tool. </p><p><br></p><p>To use applications with this authentication method assign the application to a <a href="https://usehalo.com/haloitsm/guides/2660" target="_blank" rel="noopener noreferrer">custom integration</a> which has "Connection" set to "Connect to your Halo".</p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjUwOTM4ZmJiLTZhOWQtNGQwMS04OGQ5LTg5N2I2MTUxZjk2MCJ9.wttwCGbXmpELCj_2qhNRirOwHYSUEXVuRbjLP1W2PbI" class="fr-fic fr-fil fr-dib" width="1614" style="width: 1616px; height: 630.401px;" height="630"></p><p><strong><span style="font-size: 10pt;">Fig 6. Custom Integration using Automation Identity </span></strong></p><p><br></p><p data-pasted="true">This then authenticates the integration's methods using an implementation of JWT assertion flow which automatically manages and rotates rsa keys, or utilises one-time use tokens depending on the scenario.</p><p><br></p><p><strong><span style="font-size: 12pt;">Give the Application Permissions/Scopes</span></strong></p><p>On the "Permissions" tab you are able to set exactly what services utilizing this application are able to do in Halo. If the application is authenticating access as a particular agent, or has been given it's own roles, these permissions will apply in addition to the agent/role restrictions. Permissions will further filter down what the application is able to do. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjE2MGUxMTgzLTAwOTYtNGJhZS05NDY2LTQ3NjcyNzJlNmJmYiJ9.-R5NErLKj7Lml3qezMhK2RTQgG5p6NNYhY5zNp_bI-w" class="fr-fic fr-fil fr-dib" width="1060" height="558"></p><p><br></p><p><strong><span style="font-size: 10pt;">Fig 7. Permission options.</span></strong></p><p><br></p><p>Simply check the permissions/scopes you would like the application to have. </p>
