Skip to content
  • There are no suggestions because the search field is empty.

How can I set up single sign-on with Microsoft Azure?

This chapter explains how to configure single sign-on with Microsoft Azure.

Create app registration (OpenID Connect client)

  • Login to azure

  • Navigate to "Azure Active Directory"

  • Navigate to "App registrations" on the left

  • Click "New registration"

    • For "Supported account types" choose (Accounts in this organizational directory only (<YOUR TENANT> only - Single tenant))

    • Platform "Web"

    • Url: "https://<your-subdomain>.<your-hintbox-domain>.<your-hintbox-toplevel-domain>/login"

  • After creation you can see the "Application (client) ID" in Overview. This is the client ID needed for SSO configuration in Hintbox 

  • Click the button "Endpoints" on the top.

  • You can see the "OpenID Connect metadata document". This is the well-known endpoint needed for SSO configuration in Hintbox

  • Navigate to "Certificates & secrets" to create a secret key

  • Click "New client secret" and give it a description and expires value

    • Important: Copy Secret value after creation, the value can not be shown again!

    • The secret is the client secret needed for SSO configuration in Hintbox

Add role

  • Navigate to "App Roles"

    • Fill display name and description

    • For "Allowed member types" use "Users/Groups"

    • For "Value" use "hintbox" ("hintbox" is the access role needed for SSO configuration in Hintbox, but "hintbox" should be default

      Click "Create app role"

Add user to client

  • Navigate to back to "Home" -> "Azure Active Directory"

  • Then navigate to "Enterprise applications" on the left and choose your application

  • Navigate to "Users and groups"

    • Click "Add user/group"

    • Select the users, that should have access to the application

    • Make sure, that your previously created app role is selected

    • -> Assign

Add name of user in token (optional)

  • We can add the name of the user in the token

    • This name is used in Hintbox for the user

    • Navigate to "Azure Active Directory"

    • Navigate to "App registrations" on the left and select your application

    • Navigate to "Token configuration"

      • Click on "Add optional claim"

      • Choose "Access"

      • The choose "family_name" and "given_name"

      • Click on "Add"

      • An info dialog will show up asking, if permissions for OpenID Connect should be configured

      • Check the checkbox and then click "Add"

Additional Scopes

By default Azure Active Directory does not send refresh tokens if offline_access Scope is not requested. Therefore, we need to add this scope in the Hintbox under Step 4: Configure additional scopes.

Workaround (wrong issuer value)

Because for some reason the "iss" value is not correct in the access token. This should be "https://login.microsoftonline.com/<my_tenant_id>/v2.0" and not "https://sts.windows.net/<my_tenant_id>". Microsoft uses the v1 api version by default, even if we specify v2 in the url. To fix this we need to do a workaround!

  • Navigate to back to "Home" -> "Azure Active Directory"

  • Navigate to "App registrations" on the left

  • Choose your application

  • Navigate to "Manifest"

    • Change value of "requestedAccessTokenVersion" from null to 2 in “Microsoft Graph App Manifest”

    • (Before it was "accessTokenAcceptedVersion" in old manifest format “AAD Graph App Manifest”)

    • Warning – Azure may take about an hour to change this setting

  • Navigate to "Expose an API"

    • Click on "Add a scope"

    • Add any scope e.g. "hintbox-api-v2-scope"

    • Which name you choose does not matter

    • When we have at least one exposed endpoint, the token will be in version v2

    • The scope name is a additional scope and needed for SSO configuration in Hintbox.

    • The scope looks something like: api://<client_id>/hintbox-api-v2-scope