Set up your Microsoft Entra app

Bifröst Orbit signs your people in through an app registration that lives in your own Microsoft Entra tenant. You create it once, and Orbit uses it for sign-in, for reading your app roles and for listing your people when you add members.

You need to be able to create app registrations and grant admin consent in your tenant, for example as a Cloud Application Administrator or Global Administrator. Keep Orbit open on your organisation's Sign-in tab in another window, because you copy values back and forth.

1Copy your redirect URI from Orbit

1. In Orbit, open Organisations, choose your organisation, then the Sign-in tab.
2. Switch on Microsoft SSO.
3. Copy the Redirect URI shown in the Microsoft SSO section. It ends in your organisation's ID, such as https://app.bifrostorbit.com/api/auth/callback/entra-….

Each organisation has its own redirect URI, so copy it from your organisation rather than from someone else's.

2Register the app

1. Sign in to the Microsoft Entra admin center.
2. Type App registrations in the search box at the top, open it, and choose New registration.
3. Fill in:
   • Name: something your people will recognise on the Microsoft sign-in page, such as Bifröst Orbit.
   • Supported account types: Accounts in this organizational directory only (single tenant).
   • Redirect URI: choose Web and paste the redirect URI from step 1.
4. Choose Register.

On the app's Overview page, note two values for later:

3Create a client secret

1. Open Certificates & secrets and choose New client secret.
2. Add a description, such as Bifröst Orbit, and choose when it expires. Microsoft allows up to 24 months.
3. Choose Add, then copy the Value straight away. Microsoft shows it only once.

Put a reminder in your calendar a few weeks before the secret expires. When it does, nobody can sign in with Microsoft until a new secret is saved in Orbit.

4Add API permissions

Orbit reads your app roles and your people as the app itself, so it needs a few application permissions.

1. Open API permissions and choose Add a permission › Microsoft Graph › Application permissions.
2. Add:

1. Check that the delegated permission User.Read is listed. New registrations have it already; Orbit uses it to show each person's profile photo.
2. Choose Grant admin consent for your organisation, and confirm. Every permission should show a green tick under Status.

5Create app roles

App roles decide who gets which role in Orbit. Skip this step if everyone who signs in should get the same access.

1. Open App roles and choose Create app role.
2. Fill in:
   • Display name: what admins see, such as Admin.
   • Allowed member types: Users/Groups.
   • Value: the key sent at sign-in, such as Admin. No spaces.
   • Description: shown in Orbit next to the role, such as Manages members and settings.
3. Make sure Do you want to enable this app role? is ticked, and choose Apply.
4. Repeat for each role you need, for example Member or Viewer.

Orbit reads these roles automatically. On the Sign-in tab, under Role mapping, you then choose what each one gives in Orbit.

6Choose who can sign in

By default, anyone in your tenant can sign in to the app. To let in only the people you choose:

1. Type Enterprise applications in the search box at the top, open it, and open your app. It has the same name as the registration.
2. Open Properties, set Assignment required? to Yes, and choose Save.
3. Open Users and groups, choose Add user/group, pick people or groups, select the app role they get, and choose Assign.

Only assigned people can then sign in, and only people with an app role appear when you add members in Orbit. Assigning groups needs a Microsoft Entra ID P1 licence or higher.

7Optional: send groups at sign-in

Only needed if you want Orbit rules that match a Microsoft group instead of an app role.

1. In your app registration, open Token configuration and choose Add groups claim.
2. Choose Security groups, or Groups assigned to the application if you assign groups in step 6, and choose Add.
3. In Orbit, add a group rule with the group's Object ID, found on the group's Overview page in Entra.

8Enter your app in Orbit

Back on your organisation's Sign-in tab, under Microsoft SSO:

1. Paste the Tenant ID and Client ID from step 2.
2. Paste the secret Value from step 3 into Client secret.
3. Under Work email domains, type the domains your people's addresses use, such as example.com. Separate several with commas.
4. Choose Save changes.

If everything is right, Role mapping lists your app roles, saying how many it read and whether user assignment is required. Then follow Connect Microsoft SSO to choose who gets in and what each role gives.

9Try it

1. Open Your sign-in address from the top of the Sign-in tab in a private browser window, and choose Sign in with Microsoft. Or open the usual sign-in page, enter a work email on one of your domains and choose Continue.
2. Sign in on Microsoft's page. The first time, Microsoft may ask you to accept the app's permissions.

You land on Home with the satellites your role gives. If not, see the next section.

When something goes wrong

Keeping it working

• Secrets expire. Create the new secret in Entra before the old one runs out, paste it into Client secret in Orbit and save. Leaving the field blank keeps the saved secret.
• Roles follow Microsoft. Adding, renaming or disabling an app role in Entra shows in Orbit the next time you open the Sign-in tab. Taking a role away from someone takes the access away at their next sign-in.
• Pausing. Switching Connection off in Orbit stops Microsoft sign-in without losing anything. People with an address on a domain that requires SSO cannot sign in at all while it is off.