> For the complete documentation index, see [llms.txt](https://academy.pentaho.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://academy.pentaho.com/administrator-path-sandbox/speciality-courses/integrating-authentication-mechanisms.md).

# Integrating Authentication Mechanisms

Speciality course on Pentaho 11 sign-on: LDAP and Active Directory, OpenID Connect with Keycloak and Entra ID, and Kerberos/IWA. 17 lessons across 6 modules, about 6h 45m.

{% hint style="warning" icon="eye" %}
**SANDBOX — draft page.** Built from `admin-auth-specialty` in Pentaho Content Manager; the labs have not yet been tested on a lab server. Items marked REPLACE-ME need an owner's confirmation.
{% endhint %}

Sign-on for Pentaho 11 beyond the login page. You start with the two directory providers Pentaho ships, LDAP and Active Directory. Then you add OpenID Connect sign-on, first with Keycloak and then with Microsoft Entra ID, and finally Kerberos silent login (Integrated Windows Authentication, or IWA) for users on domain-joined desktops. The course ends with a capstone that combines all three for one client.

{% columns %}
{% column %}

<p align="center"><i class="fa-file-lines" style="color:green;">:file-lines:</i><br><strong>17 lessons</strong><br><em>across 6 modules</em></p>
{% endcolumn %}

{% column %}

<p align="center"><i class="fa-flask" style="color:orange;">:flask:</i><br><strong>10 workshops</strong><br><em>hands-on labs</em></p>
{% endcolumn %}

{% column %}

<p align="center"><i class="fa-clock" style="color:cyan;">:clock:</i><br><strong>~6h 45m</strong><br><em>estimated</em></p>
{% endcolumn %}
{% endcolumns %}

{% hint style="success" icon="cloud-arrow-up" %}
Every workshop is hands-on and runs on Pentaho's hosting platform, with the Lab Guide embedded in each lab. The lab is an Ubuntu server running Pentaho Server 11, an OpenLDAP directory, a Samba Active Directory domain controller for the domain `PENTAHO.LAB`, and Keycloak. The Entra ID workshops use a Microsoft Entra tenant of your own.
{% endhint %}

***

<h3 align="center">Before you start</h3>

{% columns %}
{% column %}
{% hint style="success" icon="circle-check" %}
**What you'll need**

Comfort with the Linux command line and with editing Pentaho's configuration files. Level 1 course accreditation, or equivalent experience running a Pentaho Server, is the natural lead-in. This Speciality stands alone: it teaches LDAP and Active Directory from the start.
{% endhint %}
{% endcolumn %}

{% column %}
{% hint style="info" icon="tag" %}
**Built against**

Pentaho Enterprise Edition **11.0.0.0-237**, the build every course on the Academy runs. The hosted labs run this exact release, so every screen, menu and dialog matches the guide step for step.
{% endhint %}
{% endcolumn %}
{% endcolumns %}

***

## How sign-in works in Pentaho

Every sign-in answers two questions, and in Pentaho 11 two different parts answer them.

* **Who is this?** An **authentication mechanism** answers this one. It might be Pentaho's own login form, an identity provider through OpenID Connect (OIDC), or a Kerberos ticket from the Windows domain.
* **What may they do?** A **security provider** answers this one. It holds users and their roles: Jackrabbit (Pentaho's own repository), an LDAP directory, or Active Directory.

The mechanism passes Pentaho only a username. Pentaho then asks the security provider for that username's roles.

<figure><img src="https://4085791867-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fi1iLuqU8CtNkHG0ddYxc%2Fuploads%2FyZuddZ47XpR9NvP01bjE%2Fsign-in-two-halves.svg?alt=media" alt="Two halves of a sign-in: on the left, who is this, answered by the login form, OpenID Connect through Keycloak or Entra ID, or a Kerberos ticket from the Windows domain, all of which hand Pentaho a username; on the right, what may they do, answered by the security provider, Jackrabbit or LDAP for OpenLDAP and Active Directory, which supplies the roles Pentaho Server signs the user in with; roles never come from the identity provider"><figcaption><p>The two halves of every sign-in: a mechanism proves who, a security provider says what.</p></figcaption></figure>

With the login form, the security provider answers both questions: it checks the password and supplies the roles. With OpenID Connect or Kerberos, someone else checks who the user is. The roles still come from the security provider, never from the identity provider. That is why the same username has to exist in both places: a user whose name the security provider does not know signs in with no roles.

### OpenID Connect: signing in at an identity provider

With OpenID Connect, Pentaho shows no password box of its own. It sends the browser to an identity provider, such as Keycloak or Microsoft Entra ID, and trusts the identity provider's answer about who the user is. The user's password never reaches the Pentaho Server.

<figure><img src="https://4085791867-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fi1iLuqU8CtNkHG0ddYxc%2Fuploads%2FC4pG4u59Bnc4YvqQV2IY%2Foidc-code-flow.svg?alt=media" alt="The OpenID Connect authorization code flow across Browser, Pentaho Server and Keycloak: Pentaho redirects the browser to Keycloak, suzy signs in there, Keycloak redirects back to /pentaho/login/oauth2/code/keycloak with a code, Pentaho exchanges the code for an ID token on the back channel and checks its signature, takes the username from the preferred_username claim, and gets suzy&#x27;s roles from the security provider"><figcaption><p>The OpenID Connect authorization code flow in Pentaho 11: steps 5 to 7 run server to server, and the roles come from the security provider.</p></figcaption></figure>

{% hint style="info" icon="gears" %}
**Under the hood**

* Switch OIDC on with `enable-oauth-authentication=true` in `security.properties`.
* Each identity provider gets one **registration** in `applicationContext-spring-security-oauth.properties`: a block of keys whose prefix matches the registration's `registration-id`, such as `keycloak.`. Each registration adds a button to the login page.
* The identity provider sends the browser back to the **callback** `http://<host>:8080/pentaho/login/oauth2/code/<registration-id>`, so that address must be registered with the provider as a redirect URI.
* `user-name-attribute-name` picks the token **claim** used as the Pentaho username. The course uses `preferred_username`.
* `enable-global-logout=true`, in the same file, makes signing out of Pentaho also end the session at the identity provider. Without it, the identity provider can sign the user straight back in.
  {% endhint %}

### Kerberos: signing in with a domain ticket

With Kerberos, users who have already signed in to the Windows domain open Pentaho and are simply in, with no login page. Their browser proves who they are with a ticket from the domain, through a protocol called SPNEGO.

<figure><img src="https://4085791867-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fi1iLuqU8CtNkHG0ddYxc%2Fuploads%2Ft5X3vJQKBGsqGuy8zvjS%2Fspnego-flow.svg?alt=media" alt="Kerberos SPNEGO silent sign-in across a domain-joined browser, the domain controller and Pentaho Server: Pentaho answers 401 Negotiate, the browser gets a service ticket for HTTP/pentaho.pentaho.lab from the KDC and sends it, Pentaho decrypts it with the keytab, looks up suzy&#x27;s groups in Active Directory and signs her in; with no ticket the login form appears"><figcaption><p>Kerberos/SPNEGO silent sign-in, with the login form as the fallback.</p></figcaption></figure>

{% hint style="info" icon="gears" %}
**Under the hood**

* **The SPN.** Tickets are issued for a service principal name, `HTTP/pentaho.pentaho.lab`, which must match the address in the browser. So you open `http://pentaho.pentaho.lab:8080/pentaho`, never `localhost`.
* **The keytab.** A file holding the key of the Active Directory service account behind that SPN. Pentaho uses it to check tickets without needing a password.
* **The added jars.** Pentaho 11 ships no Kerberos libraries. The course adds Spring Security Kerberos 2.2.0 (`core` and `web`) to the Pentaho webapp, and wires the SPNEGO beans into `applicationContext-spring-security.xml`.
* **Browser trust.** A browser sends tickets only to sites it trusts. In Firefox that is `network.negotiate-auth.trusted-uris`, set to `.pentaho.lab`.
* **Clocks.** Kerberos refuses tickets when clocks differ by more than five minutes.
  {% endhint %}

### Choosing for a customer

Pick the security provider from where the customer's users already live, and the authentication mechanism from how those users already sign in to everything else.

<table data-search="false"><thead><tr><th>The customer has</th><th>Security provider</th><th>Authentication mechanism</th></tr></thead><tbody><tr><td>A small team, and no directory</td><td>Jackrabbit</td><td>The login form</td></tr><tr><td>An LDAP directory such as OpenLDAP</td><td>LDAP</td><td>The login form</td></tr><tr><td>Active Directory</td><td>LDAP, with Active Directory settings</td><td>The login form</td></tr><tr><td>A cloud identity provider, or contractors outside the domain</td><td>LDAP or Active Directory, for roles</td><td>OpenID Connect</td></tr><tr><td>Domain-joined desktops, and users who expect no login page</td><td>Active Directory</td><td>Kerberos, with the login form as fallback</td></tr></tbody></table>

The mechanisms combine: one Pentaho Server can offer a Kerberos ticket, several identity provider buttons and the login form at once. The security provider does not: roles always come from one place.

**Where SAML and CAS stand.** Earlier Pentaho releases offered SAML and CAS for single sign-on. This course does not teach either; one reading explains where they stand in Pentaho 11, and points to OpenID Connect as the way forward. REPLACE-ME: confirm with Pentaho support whether SAML is supported on Pentaho 11 at all.

***

{% hint style="info" icon="trophy" %}

#### What you'll build

The course ends in a capstone project for Meridian Freight, a logistics company whose security team allows nobody a Pentaho password. Office staff on domain-joined desktops sign in silently with Kerberos, contractors sign in through Meridian's own Keycloak realm, and one break-glass administrator keeps the login form. Every role comes from Meridian's Active Directory groups.
{% endhint %}

<figure><img src="https://4085791867-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fi1iLuqU8CtNkHG0ddYxc%2Fuploads%2FapFolAriVdWGpha03FPC%2Fcapstone-three-ways-in.svg?alt=media" alt="Meridian Freight&#x27;s three ways in: office staff with a Kerberos ticket, contractors through the meridian Keycloak realm, and the break-glass administrator through the login form all reach Pentaho Server, which takes every role from Active Directory groups nested inside the Pentaho role groups"><figcaption><p>Meridian Freight's sign-on: three ways in, one source of roles.</p></figcaption></figure>

***

<h3 align="center">Course outline</h3>

<p align="center"><i class="fa-file-lines" style="color:green;">:file-lines:</i> reading · <i class="fa-flask" style="color:orange;">:flask:</i> hands-on workshop</p>

{% hint style="info" icon="circle-info" %}
Full lessons unlock once you're enrolled — this is the outline only. Times are the lab guides' own estimates.
{% endhint %}

<table data-search="false"><thead><tr><th width="382">Module</th><th width="115" align="center">Reading</th><th width="132" align="center">Workshops</th><th width="100" align="right">Time</th></tr></thead><tbody><tr><td>Getting Started</td><td align="center">2</td><td align="center">—</td><td align="right">~30m</td></tr><tr><td>Directory Sign-On: LDAP and Active Directory</td><td align="center">1</td><td align="center">2</td><td align="right">~55m</td></tr><tr><td>OpenID Connect with Keycloak</td><td align="center">1</td><td align="center">3</td><td align="right">~1h 15m</td></tr><tr><td>OpenID Connect with Microsoft Entra ID</td><td align="center">1</td><td align="center">2</td><td align="right">~55m</td></tr><tr><td>Kerberos and IWA</td><td align="center">2</td><td align="center">2</td><td align="right">~1h 10m</td></tr><tr><td>Capstone Project</td><td align="center">—</td><td align="center">1</td><td align="right">~2h</td></tr><tr><td><strong>Total</strong></td><td align="center"><strong>7</strong></td><td align="center"><strong>10</strong></td><td align="right"><strong>~6h 45m</strong></td></tr></tbody></table>

{% stepper %}
{% step %}

### <i class="fa-rocket" style="color:blue;">:rocket:</i> Getting Started

`2 readings · ~30m`

How to get the most out of this guide, and the authentication options Pentaho 11 offers: where each one fits, and where SAML and CAS now stand.

<details>

<summary>See the full breakdown</summary>

<table data-search="false"><thead><tr><th width="79"></th><th>Lesson</th><th width="90">Time</th></tr></thead><tbody><tr><td><i class="fa-file-lines" style="color:green;">:file-lines:</i></td><td>Before You Start</td><td>~15m</td></tr><tr><td><i class="fa-file-lines" style="color:green;">:file-lines:</i></td><td>Authentication in Pentaho 11</td><td>~15m</td></tr></tbody></table>

</details>
{% endstep %}

{% step %}

### <i class="fa-address-book" style="color:blue;">:address-book:</i> Directory Sign-On: LDAP and Active Directory

`1 reading · 2 workshops · ~55m`

Pentaho's two out-of-the-box directory providers. You point the Pentaho Server at an OpenLDAP directory, then at a simulated Active Directory domain, with users and roles coming from the directory.

<details>

<summary>See the full breakdown</summary>

<table data-search="false"><thead><tr><th width="79"></th><th>Lesson</th><th width="90">Time</th></tr></thead><tbody><tr><td><i class="fa-file-lines" style="color:green;">:file-lines:</i></td><td>Overview of Directory Sign-On</td><td>~15m</td></tr><tr><td><i class="fa-flask" style="color:orange;">:flask:</i></td><td>LDAP with OpenLDAP</td><td>~20m</td></tr><tr><td><i class="fa-flask" style="color:orange;">:flask:</i></td><td>Active Directory with a Simulated Domain</td><td>~20m</td></tr></tbody></table>

</details>
{% endstep %}

{% step %}

### <i class="fa-id-badge" style="color:blue;">:id-badge:</i> OpenID Connect with Keycloak

`1 reading · 3 workshops · ~1h 15m`

The single sign-on Pentaho 11 ships out of the box, worked end to end against a Keycloak realm in the lab: the authorization code flow, the Pentaho client, and signed-in users matched to Jackrabbit or LDAP roles.

<details>

<summary>See the full breakdown</summary>

<table data-search="false"><thead><tr><th width="79"></th><th>Lesson</th><th width="90">Time</th></tr></thead><tbody><tr><td><i class="fa-file-lines" style="color:green;">:file-lines:</i></td><td>How OIDC Sign-On Works in Pentaho 11</td><td>~15m</td></tr><tr><td><i class="fa-flask" style="color:orange;">:flask:</i></td><td>Keycloak as the Identity Provider</td><td>~20m</td></tr><tr><td><i class="fa-flask" style="color:orange;">:flask:</i></td><td>Enable OAuth and Register the Pentaho Client</td><td>~20m</td></tr><tr><td><i class="fa-flask" style="color:orange;">:flask:</i></td><td>Match OIDC Users to Jackrabbit or LDAP Roles</td><td>~20m</td></tr></tbody></table>

</details>
{% endstep %}

{% step %}

### <i class="fa-cloud" style="color:blue;">:cloud:</i> OpenID Connect with Microsoft Entra ID

`1 reading · 2 workshops · ~55m`

The same flow against the cloud identity provider most customers run, enabled alongside Keycloak. Okta and other OIDC providers are configured the same way. You work in a Microsoft Entra tenant of your own.

<details>

<summary>See the full breakdown</summary>

<table data-search="false"><thead><tr><th width="79"></th><th>Lesson</th><th width="90">Time</th></tr></thead><tbody><tr><td><i class="fa-file-lines" style="color:green;">:file-lines:</i></td><td>Overview of Entra ID Sign-On</td><td>~15m</td></tr><tr><td><i class="fa-flask" style="color:orange;">:flask:</i></td><td>Register Pentaho in Microsoft Entra ID</td><td>~20m</td></tr><tr><td><i class="fa-flask" style="color:orange;">:flask:</i></td><td>Entra ID as a Second Provider</td><td>~20m</td></tr></tbody></table>

</details>
{% endstep %}

{% step %}

### <i class="fa-windows" style="color:blue;">:windows:</i> Kerberos and IWA

`2 readings · 2 workshops · ~1h 10m`

Integrated Windows Authentication: Kerberos/SPNEGO silent login for domain-joined users, and how to troubleshoot it. This is platform sign-on, separate from the Kerberos Pentaho uses to reach secured big-data clusters.

<details>

<summary>See the full breakdown</summary>

<table data-search="false"><thead><tr><th width="79"></th><th>Lesson</th><th width="90">Time</th></tr></thead><tbody><tr><td><i class="fa-file-lines" style="color:green;">:file-lines:</i></td><td>Overview of Kerberos and IWA</td><td>~15m</td></tr><tr><td><i class="fa-flask" style="color:orange;">:flask:</i></td><td>Configure IWA Prerequisites</td><td>~20m</td></tr><tr><td><i class="fa-flask" style="color:orange;">:flask:</i></td><td>Enable Kerberos SPNEGO Silent Login</td><td>~20m</td></tr><tr><td><i class="fa-file-lines" style="color:green;">:file-lines:</i></td><td>Troubleshooting IWA Login Failures</td><td>~15m</td></tr></tbody></table>

</details>
{% endstep %}

{% step %}

### <i class="fa-trophy" style="color:blue;">:trophy:</i> Capstone Project

`1 workshop · ~2h`

Single sign-on for a client end to end: an identity provider, role matching, and silent login where the scenario needs it. For Meridian Freight, that means Kerberos for office staff, a Keycloak realm for contractors, and roles from Active Directory.

<details>

<summary>See the full breakdown</summary>

<table data-search="false"><thead><tr><th width="79"></th><th>Lesson</th><th width="90">Time</th></tr></thead><tbody><tr><td><i class="fa-flask" style="color:orange;">:flask:</i></td><td>Capstone: Single Sign-On for a Client</td><td>~2h</td></tr></tbody></table>

</details>
{% endstep %}
{% endstepper %}

***

{% columns %}
{% column %}
{% hint style="warning" icon="file-certificate" %}
**Course exam**

The course ends with an open-book exam in the Lab Guide: 30 questions drawn at random from a pool of 35, across directory sign-on, OpenID Connect and Kerberos, with an 80% pass mark. It is not proctored. REPLACE-ME — confirm whether passing it issues a course accreditation of its own.
{% endhint %}
{% endcolumn %}

{% column %}
{% hint style="info" icon="award" %}
**Counts towards Level 3 — Certified**

This Speciality forms part of the **Level 3 — Certified** credential, since it covers the same authentication ground — SSO and enterprise identity — in more depth.
{% endhint %}
{% endcolumn %}
{% endcolumns %}

***

<p align="center"><a href="https://academy.pentaho.com/administrator-path-sandbox/speciality-courses.md" class="button secondary" data-icon="arrow-left">Back to Speciality Courses</a></p>


---

# 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://academy.pentaho.com/administrator-path-sandbox/speciality-courses/integrating-authentication-mechanisms.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.
