> For the complete documentation index, see [llms.txt](https://docs.coreway.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coreway.com/coreway-hr/zh-hk/sso/entra-id.md).

# 附錄：Microsoft Entra ID 設定範例

Microsoft Entra ID（前身為 Azure AD）同時支援 SAML 2.0 與 OIDC。整體流程與 [第二步](/coreway-hr/zh-hk/sso/register.md)、[第三步](/coreway-hr/zh-hk/sso/idp-config.md) 相同，本頁只列出 Entra ID 後台的對應位置與注意事項。

操作位置：[Microsoft Entra 管理中心](https://entra.microsoft.com/)，需具備**雲端應用程式管理員**以上權限。

{% hint style="info" %}
開始前請先完成 [第一步：設定組織代碼](/coreway-hr/zh-hk/sso/login-code.md)，並從「登記到企業身份源」區塊複製所需地址。
{% endhint %}

## A. SAML 2.0

### A1. 建立企業應用程式

{% stepper %}
{% step %}

## 前往企業應用程式

前往 **身分識別 → 應用程式 → 企業應用程式**。

<figure><img src="https://1973974622-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBZneYuSUsErYNDcsI8Fx%2Fuploads%2Fujc01iKbOdSkKeD0yn7x%2Fimage.png?alt=media&amp;token=b66496bf-e943-4e08-b80c-e6f767144fad" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

## 建立自己的應用程式

點 **新增應用程式 → 建立您自己的應用程式**。

<figure><img src="https://1973974622-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBZneYuSUsErYNDcsI8Fx%2Fuploads%2FnlUaGYAZxVKYDNhdD9f0%2Fimage.png?alt=media&amp;token=e4b1200b-0708-4b77-83a5-59bce0b8852e" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

## 輸入應用程式資訊

輸入名稱（例如 `YOOV`），選擇 **整合您在資源庫中找不到的任何其他應用程式（非資源庫）**，點 **建立**。
{% endstep %}
{% endstepper %}

### A2. 設定單一登入

{% stepper %}
{% step %}

## 選擇 SAML

在該應用程式左側點 **單一登入**，選 **SAML**。

<figure><img src="https://1973974622-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBZneYuSUsErYNDcsI8Fx%2Fuploads%2FD25HbTCUohhWfdhIHIbE%2Fimage.png?alt=media&amp;token=c2d7659b-a271-4e2b-91e6-c0f7e3ae9a40" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

## 編輯基本 SAML 設定

編輯 **基本 SAML 設定**，按下表填寫：

| Entra ID 欄位           | 填入本系統的            |
| --------------------- | ----------------- |
| 識別碼（實體識別碼）            | SP Entity ID      |
| 回覆 URL（判斷提示取用者服務 URL） | 斷言消費地址（ACS）       |
| 登出 URL（選用）            | 登出回跳地址（使用統一登出時才填） |

「登入 URL」「轉送狀態」留空即可——我們使用 SP 發起的登入流程。

<figure><img src="https://1973974622-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBZneYuSUsErYNDcsI8Fx%2Fuploads%2FN0AGeKhAyPErrMtmrXOY%2Fimage.png?alt=media&amp;token=7e18de33-a322-421b-b117-b3c4b912000b" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

## 儲存設定

點 **儲存**。
{% endstep %}
{% endstepper %}

### A3. 確認屬性與宣告

展開 **屬性與宣告**，確認 **唯一使用者識別碼（名稱識別碼）** 的來源屬性：

<figure><img src="https://1973974622-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBZneYuSUsErYNDcsI8Fx%2Fuploads%2Fsmv752vGGth3BHEFVko8%2Fimage.png?alt=media&amp;token=7e0bc766-c17c-4b3f-ba15-ec4712e960a1" alt=""><figcaption></figcaption></figure>

| 來源屬性                     | 說明                                      |
| ------------------------ | --------------------------------------- |
| `user.mail`              | 建議值。Entra 中的郵件地址，與成員在系統中的電郵比對           |
| `user.userprincipalname` | 使用者沒有設定 mail 時的替代值，但 UPN 未必等於電郵，需自行確認一致 |

名稱識別碼格式建議選 **電子郵件地址**（對應系統的 NameID 格式 `emailAddress`）。

{% hint style="warning" %}
**常見坑**：部分租戶的使用者 `mail` 屬性為空，SAML 斷言會回傳空值導致配對失敗。請先在 Entra 的使用者資料中補齊郵件，或改用 UPN 並確保與系統內成員電郵一致。
{% endhint %}

若要改用屬性配對（而非 NameID），記下該宣告的**完整名稱**，Entra 預設帶命名空間，例如：

```
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
```

在系統的「配對值來源」選 **斷言中的屬性**，「屬性名稱」貼上這一整串。

### A4. 取得中繼資料網址

在 **SAML 憑證** 區塊複製 **應用程式同盟中繼資料 URL（App Federation Metadata Url）**，格式類似：

```
https://login.microsoftonline.com/<tenantId>/federationmetadata/2007-06/federationmetadata.xml?appid=<appId>
```

### A5. 指派使用者

回到應用程式的 **使用者和群組**，點 **新增使用者/群組**，加入需要使用 SSO 的人員或群組。

{% hint style="warning" %}
Entra 企業應用程式預設「需要使用者指派」。沒有被指派的人登入會被 Entra 擋下，錯誤訊息出現在 Microsoft 頁面而非本系統。
{% endhint %}

### A6. 回到本系統完成設定

{% stepper %}
{% step %}

## 選擇 SAML 2.0

**安全 → 企業登入 → 企業身份源**，協定選 **SAML 2.0**。

<figure><img src="https://1973974622-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBZneYuSUsErYNDcsI8Fx%2Fuploads%2Fgoa2qjJLo5GIecNGfjPa%2Fimage.png?alt=media&amp;token=7ed65a12-2605-4bf2-8c7c-e4a3ce2b3bf2" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

## 匯入中繼資料

在「IdP 中繼資料地址」貼上 A4 的網址，點 **匯入**。
{% endstep %}

{% step %}

## 確認設定

確認 Entity ID、單一登入地址、簽章憑證已帶入，並依 A3 設定「配對值來源」。
{% endstep %}

{% step %}

## 儲存

點 **儲存**。
{% endstep %}
{% endstepper %}

## B. OIDC

### B1. 註冊應用程式

{% stepper %}
{% step %}

## 前往新增註冊

前往 **身分識別 → 應用程式 → 應用程式註冊 → 新增註冊**。
{% endstep %}

{% step %}

## 選擇帳戶類型

輸入名稱，支援的帳戶類型一般選 **僅此組織目錄中的帳戶（單一租用戶）**。
{% endstep %}

{% step %}

## 填入重新導向 URI

**重新導向 URI** 平台選 **Web**，填入本系統的「重新導向 URI」。
{% endstep %}

{% step %}

## 註冊

點 **註冊**。
{% endstep %}
{% endstepper %}

### B2. 取得 Client ID 與 Client Secret

{% stepper %}
{% step %}

## 取得 Client ID

在 **概觀** 頁複製 **應用程式（用戶端）識別碼** → 對應系統的 **Client ID**。
{% endstep %}

{% step %}

## 建立用戶端**鑰匙**

前往 **憑證及鑰 → 新增用戶端鑰匙**，設定到期時間後建立。
{% endstep %}

{% step %}

## 複製 Client Secret

複製鑰匙的 **值** 欄（不是「鑰匙識別碼」）→ 對應系統的 **Client Secret**。

{% hint style="warning" %}
用戶端鑰匙的值**只會在建立當下完整顯示一次**，離開頁面後無法再查看，請立即複製。另外鑰匙有到期日，建議在行事曆上記下到期時間，到期前回本系統更新。
{% endhint %}
{% endstep %}
{% endstepper %}

### B3. 取得 Discovery 地址

在 **概觀 → 端點** 複製 **OpenID Connect 中繼資料文件**：

```
https://login.microsoftonline.com/<tenantId>/v2.0/.well-known/openid-configuration
```

### B4. 確認 email 宣告

Entra 的 v2.0 權杖**預設不一定包含 email**，缺少時會配對失敗。請在應用程式註冊中：

{% stepper %}
{% step %}

## 前往權杖設定

前往 **權杖設定（Token configuration）**。
{% endstep %}

{% step %}

## 新增選用宣告

點 **新增選用宣告**，權杖類型選 **ID**，勾選 **email**，儲存。
{% endstep %}

{% step %}

## 確認 Microsoft Graph 權限

若提示需要開啟對應的 Microsoft Graph 權限，依提示確認。
{% endstep %}
{% endstepper %}

另外在 **API 權限** 確認已有委派權限 `openid`、`profile`、`email`。

### B5. 設定登出（選用）

若要使用「登出時同時退出企業身份源」：在 **驗證（Authentication）** 頁的 **前端通道登出 URL** 填入本系統的「登出回跳地址」。

### B6. 回到本系統完成設定

{% stepper %}
{% step %}

## 選擇 OIDC

**安全 → 企業登入 → 企業身份源**，協定選 **OIDC**。
{% endstep %}

{% step %}

## 匯入 Discovery 地址

在「Discovery 地址」貼上 B3 的網址，點 **匯入**。
{% endstep %}

{% step %}

## 填入用戶端資訊

填入 B2 的 **Client ID** 與 **Client Secret**（匯入不會覆蓋這兩項）。
{% endstep %}

{% step %}

## 儲存

點 **儲存**。
{% endstep %}
{% endstepper %}

## C. Entra ID 常見問題

<details>

<summary>Entra 顯示「需要系統管理員同意」</summary>

請全域管理員在 **企業應用程式 → 權限** 授與租戶同意。

</details>

<details>

<summary>Entra 顯示使用者未被指派</summary>

在應用程式的 **使用者和群組** 加入該使用者或其群組。

</details>

<details>

<summary>登入成功但系統提示配對失敗</summary>

回傳的 email 為空或與成員不符，見 A3／B4，必要時到 [第四步](/coreway-hr/zh-hk/sso/member-account.md) 單獨設定成員企業帳號。

</details>

<details>

<summary>一段時間後 OIDC 登入突然失效</summary>

用戶端祕密過期，在 Entra 重新建立後回本系統更新 Client Secret。

</details>

<details>

<summary>SAML 憑證輪替後登入失敗</summary>

回本系統重新匯入一次同盟中繼資料 URL 並儲存。

</details>

其餘問題請見 [常見問題](/coreway-hr/zh-hk/sso/faq.md)。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coreway.com/coreway-hr/zh-hk/sso/entra-id.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.