Microsoft Authentication (SSO) Guide

Microsoft OAuth allows Agents and Users to sign into the helpdesk with their Microsoft account.

Configuration

Choose ‘Microsoft’ in the ‘Add New Instance’ menu

oauth44_microsoft_inst


Give the instance a name that lets you know which provider is selected and select ‘Enabled’ for the status.

oauth12_enable_inst


Go to the ‘Config’ tab to set up this provider. Some of the default information will be autofilled.

Note: The ‘Authentication Label’ field is the text that will be displayed to the User or Agent when they sign into the helpdesk.

oauth13_inst_empty


Choose an Authentication Target to specify who should be able to use this provider.

oauth35_audience


Now you need to set up an application using your Microsoft account. The first thing you need to do is log in to the Azure Portal. which brings you to your Dashboard.

oauth1_azure_dashboard


Note: if you see an authentication issue, it means you are a standard user with restricted access.

oauth2_tenant_error


In order to use OAuth, you must have an account with administrative access to a tenant or you must be added to a tenant by an administrator.

Next, you’ll need to go to ‘Azure Active Directory’ and click ‘App Registrations’.

oauth85_app_regis


Click ‘New Registration’

oauth86_new_regis


oauth87_registration_page


Name the application and choose the supported account types:

Note: The supported account type will determine the ‘Authorization Endpoint’ and ‘Token Endpoint’ in your osTicket instance.

oauth41_act_type


The Redirect URI can be found in the plugin instance created in osTicket.

oauth15_blank_redir_uri


oauth14_ost_redir_uri


Choose Web for the Platform, paste in the Redirect URI, and click Register.

oauth16_filled_redir_uri


Once you click Register, it will take you to the Overview for your new Application.

oauth19_overview


Copy the ‘Application (client) ID and paste it into the Client ID field in your osTicket plugin instance:

oauth20_azure_cid


oauth21_ost_cid


Go back to Azure and click ‘Add a certificate or secret’

oauth22_add_secret


Click ‘New Client Secret’ to generate a new Client Secret

oauth23_new_secret


Add a secret description and click ‘Add’

oauth24_secret_desc

Important: The secret ‘Value’ will only be shown once. If you lose this value, you will have to generate a new one.

oauth25_secret_val


Copy the value and paste it into the ‘Client Secret’ field on the osTicket instance:

oauth26_ost_secret


Now you will need to get the Endpoint values from Azure. Go back to the ‘Overview’ tab and click the ‘Endpoints’ option.

oauth27_overview_endpoint

The supported account type chosen will determine the values for the ‘Authorization Endpoint’ and ‘Token Endpoint’ in your osTicket instance.


Single Tenant Endpoints:

oauth91_single


Multitenant Endpoints:

oauth89_multi1


Multitenant and Personal Accounts Endpoints:

oauth90_multi2


Personal Microsoft Account Endpoints:

oauth88_personal_only


Copy the ‘OAuth 2.0 authorization endpoint (v2)’ and paste it into the ‘Authorization Endpoint’ field in the osTicket instance.

oauth92_azure_auth_end


oauth93_ost_auth_end


Copy the ‘OAuth 2.0 token endpoint (v2)’ and paste it into the ‘Token Endpoint’ field in the osTicket instance.

oauth94_azure_token_end


oauth95_ost_token_end


The rest of the information should be autofilled in the osTicket instance for you.

oauth96_ost_autofilled


Click ‘Add Instance’ and make sure you see a confirmation message.

oauth34_added_inst


Now that the setup is complete, you should be able to use your Microsoft account to log into the helpdesk.

Agent Login

To test the functionality for Agents, go to:

Admin Panel | Agents

oauth36_backend


Ensure that you see the provider that was just set up in the list. It is important, however, to make sure you choose ‘Use any available backend’ so that you can still log into your helpdesk in the event that OAuth has an error.

Note: You must also ensure that the email for the Agent exists in the organization you are setting up OAuth for. You can see your users by going to Azure and clicking the ‘Users’ tab.

oauth40_azure_users


Log out of the helpdesk and go to the login screen.

oauth37_login_screen


Click the ‘Sign in with Azure’ button to test the OAuth set up.

Note: The sign in button text can be configured by changing the Authentication Label in the osTicket instance setup.

Now you will be prompted to enter your Microsoft account password.

oauth38_microsoft_pw


You may see a screen to allow osTicket to use your Microsoft login for the helpdesk.

oauth39_permission


Click Yes and you should be signed into your helpdesk as an Agent.

User Login

For users, logging in with a Microsoft account should create a new User if one does not exist, otherwise, it will log in as an existing User.

oauth80_user_portal


Click ‘Sign In’

oauth83_user_login


Click ‘Sign in with Azure’. Now you will be prompted to enter your Microsoft account password.

oauth84_choose_outlook


Choose your account and you should be logged in as a User.

oauth97_user_logged_in