> For the complete documentation index, see [llms.txt](https://docs.onelens.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onelens.cloud/getting-started/single-sign-on-sso-setup/azure-entraid-saml-sso-setup.md).
# Azure EntraID SAML SSO Setup
Configure SAML single sign-on between Microsoft Entra ID (formerly Azure AD) and OneLens.
## TL;DR
* **What it does** — Lets your users sign in to OneLens with their existing Entra ID credentials, so OneLens stops being a separate username and password.
* **How long** — 20–30 minutes end to end, assuming you already have the Entra ID permissions.
* **Who does it** — Someone who can create enterprise applications in Entra ID (Application Administrator or Global Administrator) plus a OneLens `ROOT` or `ADMIN` user.
* **What you need open** — Two browser tabs: the Entra ID portal, and the OneLens SSO wizard at **Settings → SSO → Configure**.
## What You'll Get Once Connected
| Capability | What it means |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Single sign-on | Users click through to OneLens from Entra ID or from the OneLens login page, with no separate password. |
| Central deprovisioning | Removing a user in Entra ID removes their access to OneLens. |
| Role assignment from Entra ID | Optionally map Entra ID app roles to OneLens `ROOT`, `ADMIN` and `MEMBER` roles. |
| Persistent user identity | Users are keyed on their Entra ID object ID, so a name or email change doesn't create a duplicate account. |
| MFA and conditional access | Whatever policies you already enforce in Entra ID apply to OneLens logins too. |
| Auditability | Sign-in events appear in the Entra ID sign-in logs alongside your other apps. |
## Security at a Glance
| Question | Answer |
| -------------------------------- | ------------------------------------------------------------------------------------------------- |
| What protocol is used? | SAML 2.0. OneLens also supports OIDC, configured separately. |
| Where do credentials live? | Only in Entra ID. OneLens never sees or stores the user's password. |
| What identifies a user? | The Entra ID object ID (`user.objectid`), sent as a persistent Name ID. |
| What attributes are read? | Name ID, `emailaddress`, `metadata`, and optionally `role`. Nothing else. |
| How is the assertion verified? | Against the signing certificate in the federation metadata you upload in step 5. |
| Does this change existing users? | Existing OneLens users are matched on email. Set SSO as the only login method once you've tested. |
| Can it be reversed? | Yes. Disable SSO in **Settings → SSO** and password login resumes. |
## How It Works
Entra ID is the identity provider (IdP) and OneLens is the service provider (SP). When a user tries to reach OneLens, OneLens redirects the browser to Entra ID; Entra ID authenticates the user and posts a signed SAML assertion back to the OneLens assertion consumer service (ACS) URL. OneLens validates the signature, reads the user's identity and role out of the assertion, and starts a session.
The setup is therefore a two-sided exchange. You give Entra ID two OneLens URLs (the entity ID and the reply URL), and you give OneLens the Entra ID federation metadata. Everything else is attribute plumbing.
{% hint style="info" %}
Both sides of the exchange are tenant-specific. The URLs and metadata shown in the OneLens wizard belong to your organization only — don't reuse values from another tenant's guide.
{% endhint %}
## Prerequisites
* An Entra ID account with permission to create and configure enterprise applications.
* A OneLens account with the `ROOT` or `ADMIN` role.
* The OneLens SAML wizard open: sign in to OneLens, go to **Settings → SSO**, and click **Configure**. This opens the wizard at `auth.onelens.cloud` with your organization's values already filled in.
{% stepper %}
{% step %}
## Create a new SAML enterprise app
In the Entra ID portal, search for **Enterprise Applications**.
In the Enterprise Applications menu, click **New application**.
On the next page click **Create your own application**.
Name your app — "OneLens" is the obvious choice — and select **Integrate any other application you don't find in the gallery (Non-gallery)**. Click **Create**.
Once the application has been created, open **Single sign-on** in the sidebar and choose **SAML**.
{% endstep %}
{% step %}
## Enter the OneLens details into Entra ID
Edit the **Basic SAML Configuration** section and add the two service provider values from the OneLens wizard.
| Entra ID field | Value from the OneLens wizard |
| ------------------------------------------ | ------------------------------------------- |
| Identifier (Entity ID) | The `.../saml//metadata` URL |
| Reply URL (Assertion Consumer Service URL) | The `.../saml//acs` URL |
{% hint style="info" %}
Copy both values straight from your own wizard screen rather than typing them. The connection ID in the middle of each URL is unique to your organization, and a single wrong character produces an assertion Entra ID will refuse to send.
{% endhint %}
{% endstep %}
{% step %}
## Map user attributes
In the **Attributes & Claims** section, click the pencil icon to edit the claims Entra ID sends.
Select the **Unique User Identifier (Name ID)** claim. Set **Name identifier format** to `Persistent` and **Source attribute** to `user.objectid`. Click **Save**.
Some claims, such as `emailaddress`, are added for you. To add the rest, use **Add new claim** and set the **Namespace** to `http://schemas.xmlsoap.org/ws/2005/05/identity/claims`.
| Attribute | Claim name |
| ------------- | -------------- |
| Email | `emailaddress` |
| Metadata | `metadata` |
| {% endstep %} | |
{% step %}
## Map user roles (optional)
Without this step every user who signs in through SSO lands on the `MEMBER` role. To have Entra ID decide the role instead, send a `role` claim.
### Add the role claim
Create a new claim with these fields:
| Field | Value |
| ---------------- | ------------------------------------------------------- |
| Name | `role` |
| Namespace | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims` |
| Source attribute | `user.assignedroles` |
### Create the app roles
* In Entra ID, go to **App registrations** and select your app.
* Open **App roles**. You'll add three roles: `ROOT`, `ADMIN` and `MEMBER`.
* Click **Create app role**.
* Set **Display name** and **Value** to the role name exactly as written above.
* Set **Allowed member types** to **Users/groups**.
* Add a description and leave **Do you want to enable this app role?** checked.
* Click **Save**, then repeat for the remaining roles.
Once all three exist, you assign a role to a user or group at the point you add them to the application.
{% hint style="warning" %}
The role **Value** is the string OneLens matches on, and it is case-sensitive. `Admin` will not be recognised as `ADMIN`.
{% endhint %}
{% endstep %}
{% step %}
## Finish the connection in OneLens
Back in Entra ID's SAML single sign-on page, download the **Federation Metadata XML** file.
Upload that file in the final step of the OneLens wizard and click **Finish**.
If you'd rather not use the metadata file, the wizard accepts the three values individually: **Login URL**, **Entra ID Identifier**, and the Base64 **Certificate**. All three are on the same Entra ID page.
{% endstep %}
{% endstepper %}
## Verify It Works
{% stepper %}
{% step %}
## Assign a test user
In Entra ID, assign at least one test user (yourself) to the application under **Users and groups**.
{% endstep %}
{% step %}
## Test sign-in
Open a private browser window and go to the OneLens login page.
Sign in with the test account and confirm you land in OneLens without being asked for a OneLens password.
{% endstep %}
{% step %}
## Confirm the assigned role
Check the user's role in **Settings → Users** matches the app role you assigned.
{% endstep %}
{% step %}
## Enable SSO-only login
Only once that passes, enable **SSO as the only login method** in **Settings → SSO**.
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
Keep one OneLens `ROOT` user with password login until you have confirmed SSO works for a real user. Turning on SSO-only while the connection is misconfigured locks everyone out, including you.
{% endhint %}
## Troubleshooting
| Symptom | Likely cause | Fix |
| ------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| "AADSTS50011: reply URL does not match" | The Reply URL in Entra ID doesn't exactly match the OneLens ACS URL | Re-copy the ACS URL from the wizard; check for a trailing slash |
| Signature validation fails | Metadata uploaded from a different app, or the certificate has rolled over | Download fresh federation metadata and re-upload it in the wizard |
| A returning user shows up as a new account | Name ID is not persistent, or is sourced from email instead of object ID | Set Name ID format to `Persistent` and source to `user.objectid` |
| Everyone lands on `MEMBER` | The `role` claim is missing, or the app role Value doesn't match | Confirm the claim name, namespace and `user.assignedroles` source; check role Values are uppercase |
| "User not assigned to a role for the application" | The user isn't assigned to the enterprise app | Add them under **Users and groups** in Entra ID |
| Login loops back to the OneLens login page | Assertion is valid but the email claim is missing | Confirm the `emailaddress` claim is present in Attributes & Claims |
## FAQ
Can we use OIDC instead of SAML?
Yes. The same **Settings → SSO → Configure** flow supports OIDC; choose it at the start instead of SAML.
Do we need to re-run this when our Entra ID certificate rolls over?
Yes — upload the new federation metadata in the wizard before the old certificate expires. Entra ID emails a reminder to the notification address on the app.
What happens to users who already have OneLens passwords?
They are matched on email address and keep their existing account and data. Once you enable SSO as the only login method, their password stops working.
Can we restrict OneLens to a subset of employees?
Yes. Assign only the relevant users or groups to the enterprise application in Entra ID.
How do we disconnect SSO?
Turn off SSO in **Settings → SSO** in OneLens, then delete the enterprise application in Entra ID. Password login resumes immediately.
Does OneLens support SCIM user provisioning?
Not through this wizard. Users are created on first SSO login. Ask OneLens support if you need automated provisioning.
Can a user be `ADMIN` in one OneLens organization and `MEMBER` in another?
Roles are per-organization, and the SAML connection is per-organization, so yes — each has its own enterprise app and its own role assignment.
## Need Help?
* **Microsoft docs** — "Configure SAML-based single sign-on" and "Configure app roles" in the Entra ID documentation.
* **OneLens support** — Use **Get Help → Submit a Ticket** in the OneLens app, or reach out to your OneLens contact. Include your organization name and the connection ID from the wizard URL.
*Reference sources: OneLens Enterprise SSO setup wizard (auth.onelens.cloud), Microsoft Entra ID documentation on SAML-based single sign-on and app roles.*
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.onelens.cloud/getting-started/single-sign-on-sso-setup/azure-entraid-saml-sso-setup.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.
