# Azure AD

Integrate Valohai with Azure Active Directory to centralize authentication and avoid duplicating access control settings. Users log in with their existing Azure AD credentials, and team membership updates automatically based on AD groups.

## Prerequisites

An Azure account with permission to manage applications in Azure Active Directory. Any of these roles work:

* Application Administrator
* Application Developer
* Cloud Application Administrator

## Setup Overview

1. Verify your Azure AD domain with Valohai
2. Create an Azure AD App Registration
3. Configure access grants in Valohai
4. Users log in via Azure AD

## Step 1: Verify Your Domain

Contact <support@valohai.com> with your Azure AD domain name (e.g., `yourcompany.com` or `yourcompany.onmicrosoft.com`).

Valohai will verify the domain and enable Azure AD integration for your organization.

## Step 2: Create App Registration

### Access Azure Active Directory

1. Sign in to [Azure Portal](https://portal.azure.com/)
2. Search for "Azure Active Directory" in the top search bar
3. Select Azure Active Directory from results

<figure><img src="/files/yhzpGjusHexD4Jge5jbh" alt=""><figcaption></figcaption></figure>

### Create New Registration

1. Under **Manage**, select **App registrations**
2. Click **New registration**

<figure><img src="/files/fF3XsO6SfL0Z0HCXr7yB" alt=""><figcaption></figcaption></figure>

### Configure Registration Details

**Name:** Enter a display name (e.g., "Valohai ML Platform"). This appears to users during login.

**Supported account types:** Select **Accounts in this organizational directory only** in most cases. See [Microsoft's documentation](https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) for other scenarios.

**Redirect URI:**

* Type: **Web**
* URL: `https://app.valohai.com/accounts/azure/callback/`

Click **Register** to create the app.

<figure><img src="/files/zefx8Ugz9H9Y2W0rhMTg" alt=""><figcaption></figcaption></figure>

### Note Your Application Details

After creation, note these values (you'll need them for Valohai configuration):

* **Application (client) ID:** Found on the app overview page
* **Directory (tenant) ID:** Found on the app overview page

Share these with <support@valohai.com> to complete the integration.

## Step 3: Configure Access Grants

Access grants control which Azure AD users and groups can access your Valohai organization. Users must match at least one grant to log in.

### Requirements

You must be a Valohai organization administrator.

### Add Access Grants

1. Click **Hi, \<name>** in Valohai
2. Select **Manage \<organization>**
3. Go to **Settings**
4. Click **Manage access grants** in the Access Grants section
5. Click **Add new grant**
6. Configure the grant:
   * **Grant IDs:** Azure AD user or group UUIDs (see below)
   * **Teams:** Valohai teams to automatically assign matching users
7. Click **Save**

### Find Azure AD UUIDs

#### User UUID

1. In Azure Portal, go to **Azure Active Directory** → **Users**
2. Find the user
3. Copy the **Object ID** (this is the UUID)

#### Group UUID

1. In Azure Portal, go to **Azure Active Directory** → **Groups**
2. Find the group
3. Copy the **Object ID** (this is the UUID)

### Example Access Grants

**Grant all data scientists access and auto-assign to team:**

```
Grant IDs: <data-science-group-uuid>
Teams: data-science
```

**Grant specific executive access:**

```
Grant IDs: <cto-user-uuid>, <vp-eng-user-uuid>
Teams: leadership, ml-engineering
```

**Multiple groups with different team assignments:**

```
Grant 1:
  IDs: <ml-research-group-uuid>
  Teams: research

Grant 2:
  IDs: <ml-production-group-uuid>
  Teams: production, ops
```

## Step 4: User Login

After setup completes:

1. Users navigate to [app.valohai.com](https://app.valohai.com)
2. Click **Login with Azure AD**
3. Authenticate using Azure AD credentials
4. Users are automatically added to your Valohai organization

> Tell users to use the **Azure AD login button**, not the standard email/password login. This ensures they use SSO instead of creating separate Valohai accounts.

## Automatic Team Mapping

Access grants automatically assign users to teams based on their Azure AD group membership:

**Azure AD setup:**

```
Group: "Data Scientists" (uuid: abc-123...)
Members: Alice, Bob, Charlie
```

**Valohai access grant:**

```
Grant IDs: abc-123...
Teams: data-science, ml-research
```

**Result:** When Alice logs in via Azure AD, she's automatically added to both the "data-science" and "ml-research" teams in Valohai.

**Team changes:** If you remove Alice from the Azure AD group and she logs in again, Valohai updates her team membership on the next login.

## Advanced: Attribute Mapping

You can send additional user attributes from Azure AD to Valohai for more sophisticated team mapping.

**Example attributes:**

* Department (Engineering, Research, Operations)
* Job title (Data Scientist, ML Engineer)
* Cost center codes
* Custom attributes

Contact <support@valohai.com> to configure attribute-based team mapping for your organization.

## Troubleshooting

### User Can't Log In

**Cause:** User or their group isn't in any access grant.

**Fix:**

1. Find their user or group UUID in Azure AD
2. Add it to an access grant in Valohai
3. User tries logging in again

### User Logs In But Has No Team Access

**Cause:** Access grant doesn't specify teams, or specified teams don't exist.

**Fix:**

1. Edit the access grant
2. Add appropriate teams
3. User logs out and logs in again to refresh team membership

### Redirect URI Mismatch Error

**Cause:** Redirect URI in Azure AD doesn't match Valohai's callback URL.

**Fix:**

1. Go to Azure AD App Registration
2. Select **Authentication**
3. Verify redirect URI is exactly: `https://app.valohai.com/accounts/azure/callback/`
4. Save changes

### User Accidentally Created Separate Account

**Cause:** User used email/password login instead of Azure AD button.

**Fix:**

1. User logs in via Azure AD (creates correctly-linked account)
2. Contact <support@valohai.com> to merge accounts

## Security Best Practices

**Use groups, not individual users:** Manage access by adding/removing users from Azure AD groups rather than updating Valohai grants.

**Review access grants quarterly:** Audit which groups have access and their team assignments.

**Require MFA in Azure AD:** Enforce multi-factor authentication at the Azure AD level for all users.

**Limit admin grants:** Only grant Valohai admin privileges to users who need full organizational control.

## Related Topics

* [Okta SAML SSO](/user-and-organization-management/single-sign-on/okta-saml.md) — Alternative SSO provider
* [Create Teams](/user-and-organization-management/getting-started/create-teams.md) — Set up teams for automatic assignment
* [Invite Users](/user-and-organization-management/getting-started/invite-users.md) — Manual user management (alternative to SSO)
* [FAQ](/user-and-organization-management/getting-started/faq.md) — SSO-related questions


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.valohai.com/user-and-organization-management/single-sign-on/azure-ad.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.