# Set up your Microsoft Entra app

> Register an app in Microsoft Entra, step by step, so your people can sign in to Bifröst Orbit with their work accounts.

Source: https://docs.bifrostorbit.com/orbit/admins/set-up-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.

## 1. Copy 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.

## 2. Register the app

1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com).
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:

| In Entra | Goes into Orbit as |
| --- | --- |
| **Directory (tenant) ID** | **Tenant ID** |
| **Application (client) ID** | **Client ID** |

## 3. Create 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.

> **Important:** Copy the secret's **Value**, not its **Secret ID**. The Secret ID looks similar but does not work.

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.

## 4. Add 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:

| Permission | Why Orbit needs it |
| --- | --- |
| **Application.Read.All** | Reads the app roles your app offers, and who is assigned to them. |
| **User.Read.All** | Shows names, email addresses and job titles when you add members. |
| **GroupMember.Read.All** | Only if you assign groups to the app: finds the people in those groups. |

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

## 5. Create 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.

## 6. Choose 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.

## 7. Optional: 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.

## 8. Enter 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](https://docs.bifrostorbit.com/orbit/admins/connect-microsoft-sso/) to choose who gets in and what each role gives.

## 9. Try 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

| What you see | What it means | What to do |
| --- | --- | --- |
| *Your organisation has not set up Microsoft sign-in for this address* | The email's domain is not on your connection. | Add the domain under **Work email domains**, and check Microsoft SSO is switched on. |
| AADSTS50011: the redirect URI does not match | The redirect URI in Entra is missing or different. | Copy it again from Orbit and add it as a **Web** redirect URI under **Authentication**. |
| AADSTS700016: application not found | The client ID does not belong to this tenant. | Check the tenant ID and client ID both come from the same app's Overview. |
| AADSTS7000215: invalid client secret | The secret is wrong or expired, or the Secret ID was used. | Create a new secret and paste its **Value**. |
| AADSTS50105: the user is not assigned to a role | Assignment is required and this person is not assigned. | Assign them, or a group they are in, under **Users and groups**. |
| *Microsoft refused your app's credentials* in Orbit | Orbit could not get a token with the saved details. | Check the tenant ID, client ID and secret, and whether the secret has expired. |
| *Microsoft refused to list the app roles* | **Application.Read.All** is missing or not consented. | Add it and choose **Grant admin consent**. |
| Nobody appears when adding members | **User.Read.All** is missing, or nobody has an app role. | Add and consent the permission, and assign app roles to people. |
| Signed in, but no satellites | Microsoft let them in, but no rule or default access gave them anything. | Under **Who gets in**, give everyone default access, or map their app role. |

## 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.