markyardExplore the docs

Single sign-on

Set up Microsoft Entra ID SSO for Markyard

This guide is for Microsoft Entra administrators who are connecting their organization to Markyard.

Customer guideIdentity administrator

Each Markyard hosting uses one identity provider. Follow this guide when Microsoft Entra ID is the identity provider selected for your hosting.

Before you begin

Ask your Markyard administrator for:

  • your Markyard URL, such as https://markyard.example.com;
  • the callback URL for your hosting; and
  • the logout return URL for your hosting.

For a hosting at https://markyard.example.com, the values are:

Purpose URL
Callback https://markyard.example.com/api/auth/callback/entra
Logout return https://markyard.example.com/login

You also need:

  • permission to create an app registration in your Entra tenant;
  • permission to manage the resulting Enterprise application; and
  • a security group whose members should receive Markyard access.

1. Register the application

  1. Sign in to the Microsoft Entra admin center.
  2. Switch to the directory that will authenticate Markyard users.
  3. Go to Entra ID > App registrations.
  4. Select New registration.
  5. Enter Markyard as the application name.
  6. Under Supported account types, select Accounts in this organizational directory only.
  7. Select Register.

From the application's Overview page, record:

  • Application (client) ID; and
  • Directory (tenant) ID.

2. Add the Markyard URLs

  1. In the app registration, go to Authentication.
  2. Select Add a platform.
  3. Select Web.
  4. Add the callback URL supplied by your Markyard administrator.
  5. Add the logout return URL to the Web redirect URI list.
  6. Save the configuration.

Do not configure Markyard as a Single-page application and do not enable implicit grant flows.

3. Create a client secret

  1. In the app registration, go to Certificates & secrets.
  2. Select Client secrets > New client secret.
  3. Enter a description and choose an expiration that follows your credential policy.
  4. Create the secret.
  5. Copy the secret Value immediately.

The secret Value is the credential. The Secret ID is not the credential.

  1. In the app registration, go to API permissions.
  2. Select Add a permission > Microsoft Graph > Delegated permissions.
  3. Add User.ReadBasic.All.
  4. Grant consent according to your organization's consent policy.

Do not grant User.Read.All, application-level directory permissions, or group permissions for Markyard people sharing.

This one permission also covers profile pictures. Markyard reads each person's Entra photo with the signed-in user's own delegated token, so people only ever see pictures they could already find in your directory, and an account with no picture falls back to that person's initials. No additional permission or consent step is required.

5. Restrict access to your Markyard group

  1. Go to Entra ID > Enterprise applications.
  2. Open the Enterprise application created for Markyard.
  3. Go to Properties.
  4. Set Assignment required? to Yes and save.
  5. Go to Users and groups.
  6. Select Add user/group.
  7. Assign the security group that grants Markyard access.

Entra now blocks unassigned users before they reach Markyard. You do not need to add group claims or app roles for this access check.

6. Send the application details to your Markyard administrator

Send these values through your approved secure channel:

  • Directory (tenant) ID;
  • Application (client) ID; and
  • the client secret Value.

Do not send the client secret through ordinary email or chat, and do not place it in a ticket visible to unauthorized people.

If you operate the AWS hosting, continue with Create the Microsoft Entra ID application secret for AWS before deploying Markyard.

7. Verify sign-in

After your Markyard administrator confirms that the connection is ready:

  1. Open your Markyard URL.
  2. Select Continue with Microsoft Entra ID.
  3. Sign in with a member of the assigned Markyard access group.
  4. Confirm that Markyard opens after authentication.
  5. Sign out and confirm that Entra returns you to the Markyard login page.
  6. In a private browser session, confirm that an unassigned account is rejected.

Manage access

  • Add and remove users through the security group assigned to the Markyard Enterprise application.
  • Assigned guest users can sign in when your organization permits them.
  • Removing a user from the assigned group prevents their next Entra sign-in. Ask your Markyard administrator to end an existing Markyard session when immediate removal is required.
  • Track the client secret expiration and rotate it before it expires.

Rotate the client secret

  1. Create a new client secret before the current secret expires.
  2. Copy the new secret Value immediately.
  3. Transfer the new value to your Markyard administrator through your approved secure channel.
  4. Ask your Markyard administrator to confirm browser sign-in.
  5. Delete the old secret after the new connection is verified.

Troubleshooting

AADSTS50011: reply URL mismatch

Compare the app registration's Web redirect URIs with the callback supplied by your Markyard administrator. The scheme, hostname, port, and path must match exactly.

AADSTS50105: user is not assigned

This is expected for users outside the approved access group. For an authorized user, confirm that:

  • Assignment required? is set to Yes on the correct Enterprise application;
  • the user is a member of the assigned security group; and
  • the assignment and app registration belong to the same Entra tenant.

The client secret is rejected

Confirm that you supplied the client secret Value, not its Secret ID, and that the secret has not expired.

Logout does not return to Markyard

Confirm that the exact logout return URL is registered as a Web redirect URI.

Microsoft references