Single sign-on with Microsoft Entra ID (Azure AD)
Let your team sign in to OGDESK with their Microsoft work account: register OGDESK in Microsoft Entra ID, then connect it here.
Who can do this:Tenant AdministratorEntra Application Administrator
Microsoft Entra ID is the new name for Azure Active Directory. This guide connects it to OGDESK over OpenID Connect, which is the simpler of the two ways and the one we recommend. If your organisation standardises on SAML, see Using SAML instead at the end.
| Part | Where | What you do |
|---|---|---|
| A | OGDESK | Verify your email domain. |
| B | Microsoft Entra | Register OGDESK as an app, create a client secret, and send the email claim. |
| C | OGDESK | Enter the app’s details. |
| D | Both | Test it, then require it if you want to. |
Before you start
- In Microsoft Entra: the Application Administrator or Cloud Application Administrator role.
- In OGDESK: the Tenant Administrator role.
- Permission to add a TXT record to your domain’s DNS.
- Your own OGDESK account on the domain you will verify, so you can test it yourself.
- Everybody who will sign in needs an email address on their Entra account, on that domain, and must already be a member of your OGDESK workspace. Invite them first.
Part A — Verify your email domain in OGDESK
Step 1: In OGDESK, go to Administration → App settings → Single sign-on.
Step 2: Under Email domains, type your domain (for example
brightwater.com) and choose Claim.
Step 3: Publish the TXT record shown at your DNS provider, using the Host and Value exactly as they appear.
Step 4: Choose Check DNS until the domain shows Verified. DNS changes can take a few minutes.
Part B — Register OGDESK in Microsoft Entra
Sign in to the Microsoft Entra admin center at entra.microsoft.com. If a menu has moved, use the search box at the top of the admin center to find it by name.
Step 1: Open App registrations and choose New registration. Fill it in like this, then choose Register:
| Field | What to enter |
|---|---|
| Name | OGDESK (anything your colleagues will recognise) |
| Supported account types | Accounts in this organizational directory only (Single tenant) |
| Redirect URI | Platform Web, and https://www.ogdesk.com/api/v1/auth/sso/callback/oidc. Copy it from Redirect / ACS URL in OGDESK if your address is different. |
Step 1: On the app’s Overview page, copy the Application (client) ID and the Directory (tenant) ID. You need both in Part C.
Step 2: Open Certificates & secrets → Client secrets → New client secret. Give it a description and an expiry, and choose Add.
Copy the secret’s Value straight away: Entra shows it only once. Do not copy the Secret ID. Microsoft recommends an expiry of 12 months or less, and allows 24 months at most.
Step 3: Open Token configuration → Add optional claim. Choose token type ID, tick email, and choose Add. If asked, accept turning on the Microsoft Graph email permission.
Without this, Entra does not put people’s email address in the sign-in, and OGDESK cannot tell who they are.
Step 4: Optional: under API permissions, choose Grant admin consent so nobody is asked to approve OGDESK the first time they sign in. Do this if your organisation does not let people consent to apps themselves.
Part C — Enter the app’s details in OGDESK
Back on the Single sign-on tab, under Identity provider:
| Field | What to enter |
|---|---|
| Protocol | OpenID Connect |
| Button label | Microsoft, so the sign-in button reads “Sign in with Microsoft” |
| Issuer URL | https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0 |
| Client ID | The Application (client) ID |
| Client secret | The secret’s Value |
| Scopes | Leave as openid email profile |
| Email claim | Leave blank |
| Accept addresses the provider does not mark as verified | Tick it. Entra never says whether an address is verified, so without it every sign-in is refused. |
Choose Enable single sign-on to save.
Part D — Test it, then require it
Step 1: Under How people sign in, tick Offer single sign-on and save.
Step 2: In a private browser window, open the OGDESK sign-in page, type your work email, choose Continue, then Sign in with Microsoft. Sign in with Microsoft and you land back in OGDESK.
Step 3: On the Single sign-on tab, Last successful sign-in confirms it worked. If not, Last attempt says why. Passwords keep working while you test.
Step 4: Once it works, you can tick Require it, and turn passwords off. See Set up single sign-on for what that changes.
Common problems
| What you see | What to do |
|---|---|
| AADSTS50011 at Microsoft | The redirect URI in Entra does not match. Copy Redirect / ACS URL from OGDESK again and paste it under the app’s Authentication settings, platform Web. |
| AADSTS7000215 (invalid client secret) | The Secret ID was copied instead of the Value, or the secret has expired. Create a new secret and paste its value. |
| AADSTS65001 or a consent prompt | Nobody has consented to the app. Choose Grant admin consent under API permissions. |
| “Your identity provider did not send an email address.” | Add the email optional claim (Part B), and check the person has an email address in Entra. |
| “Your identity provider did not say whether it has verified your email address…” | Tick Accept addresses the provider does not mark as verified (Part C). |
| “…an address this workspace has not verified.” | The person’s address is on a domain you have not verified, often onmicrosoft.com. Verify their domain, or give them an address on yours. |
| “That account is not a member of this workspace.” | Invite them to OGDESK first. |
Using SAML instead
OpenID Connect is simpler, but Entra can also connect over SAML 2.0. In Entra, SAML is set up as an enterprise application rather than an app registration:
Step 1: Open Enterprise applications → New application → Create your own application. Name it
OGDESK, choose Integrate any other application you don’t find in the gallery (Non-gallery), and choose Create.Step 2: Open Single sign-on → SAML. Under Basic SAML Configuration, set Identifier (Entity ID) to OGDESK’s Our entity ID and Reply URL (Assertion Consumer Service URL) to OGDESK’s Redirect / ACS URL.
Save the provider in OGDESK with protocol SAML 2.0 first; the two addresses appear once it is saved.
Step 3: Under SAML Certificates, choose Edit and set Signing Option to Sign SAML response and assertion.
Entra signs only the assertion by default, and OGDESK refuses anything that is not signed in both places.
Step 4: Download Certificate (Base64), open it in a text editor, and paste it into OGDESK’s Signing certificate. Copy Entra’s Login URL into Sign-on URL, and Microsoft Entra Identifier into IdP entity ID.
Step 5: Set NameID format to
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.Step 6: Under Users and groups, assign the people or groups who may sign in. Otherwise Entra refuses them with AADSTS50105.