Set up OAuth 2.0 and Azure AD#
You can set up EclecticIQ Intelligence Center to act as a web service in Microsoft identity platform OAuth 2.0 flows
This allows you to:
Set up a third-party application to authenticate with and make API calls to EclecticIQ Intelligence Center instance.
Manage credentials used by that third-party application on Azure AD, instead of on EclecticIQ Intelligence Center.
But does not allow you to sign in to EclecticIQ Intelligence Center using Azure AD credentials.
To allow users to sign in using Azure AD credentials, see Set up SAML with Azure AD instead.
Set up OAuth 2.0 with EclecticIQ Intelligence Center#
You must have:
Root access to EclecticIQ Intelligence Center host.
Permissions to register applications on the target Azure AD tenant.
Steps:
Register an Azure AD application for EclecticIQ Intelligence Center#
Register application on your Azure AD tenant for EclecticIQ Intelligence Center. Follow the instructions in Azure AD documentation to do so.
Once done, select your registered app to configure it.
Go to Expose an API and select Add a scope.
In Add a scope, fill out the following fields:
Field name
Description
Scope name
Set to:
platform.read-write
Who can consent?
Depends on how your Azure AD tenant is managed.
Admin consent display name
Set to:
Platform read and write access
Admin consent description
Set to:
This API scope allows read and write access to EclecticIQ Intelligence Center.
State
Set to Enabled.
Select Add scope to save your changes.
Configure platform_settings.py#
Set the following parameters in /etc/eclecticiq/platform_settings.py
:
Parameter |
Required |
Description |
---|---|---|
|
Yes |
Set to |
|
Yes |
Azure AD Directory (tenant) ID The ID of the Azure AD tenant you want your EclecticIQ Intelligence Center instance and third party application to interact with. |
|
Yes |
Application (client) ID registered for your Intelligence Center instance The ID of the application object registered for your EclecticIQ Intelligence Center instance. |
|
Yes |
Application (client) ID registered for the connecting third-party application The ID(s) for one or more registered application objects, for each third party application used to make API calls to EclecticIQ Intelligence Center after authenticating with Azure AD. |
|
Yes |
When an Azure AD user signs in on EclecticIQ Intelligence Center through OAuth 2.0, EclecticIQ Intelligence Center creates an external user named after the Azure AD user’s OID (Azure AD object identifier). The user will still be able to use their username to sign in using Microsoft identity platform OAuth 2.0 flows. |
|
Yes |
This is used to set the email address of external users. |
|
Yes |
Set this to the Azure AD claim that contains role names to assign an Azure AD user. EclecticIQ Intelligence Center assigns users to the groups contained in this claim. The claim should contain one or more Azure AD groups. Groups emitted with this claim must match the names of existing groups on EclecticIQ Intelligence Center exactly. See Map Azure AD groups and roles to EclecticIQ Intelligence Center below. You can also set this to a custom claim. See Assign groups and roles to users using custom claims. |
|
Yes |
Set this to the Azure AD claim that contains role names to assign an Azure AD user. EclecticIQ Intelligence Center assigns users to the roles contained in this claim. By default, this parameter is set to Set this to Roles emitted with this claim must match the names of existing roles on EclecticIQ Intelligence Center exactly. See Map Azure AD groups and roles to EclecticIQ Intelligence Center below. You can also set this to a custom claim. See Assign groups and roles to users using custom claims. |
|
No |
A list of groups that are assigned to external users who sign in on EclecticIQ Intelligence Center using OAuth 2.0.
|
|
No |
A list of roles that are assigned to external users who sign in on EclecticIQ Intelligence Center using OAuth 2.0.
|
|
No |
Do not change this value. Tells EclecticIQ Intelligence Center to use case-sensitive matching when matching groups and roles names from your external authentication system to EclecticIQ Intelligence Center’s groups and roles. |
|
No |
Set this to |
|
No |
This is used to set the First name of external users. |
|
No |
This is used to set the Last name of external users. |
|
No |
When this parameter is set,
you can assign a user administrator rights
by setting the value of this claim to |
|
No |
When this parameter is set, all users assigned to this group on the tenant are assigned administrator rights on EclecticIQ Intelligence Center. |
Sample of OAuth 2.0 parameters in platform_settings.py
:
OAUTH_ENABLED = True
OAUTH_TENANT_ID = "d86ca749-105f-4f0a-a4f2-89c5ef275c2e"
OAUTH_APPLICATION_ID = "17e1e12b-3908-4782-b7ca-f01bec2bd750"
OAUTH_CLIENT_APPLICATION_IDS = ["36a0427c-4ca6-4bb6-afe2-804a729f14a1"]
OAUTH_DEBUG = False
# Required attributes
OAUTH_USER_USERID_CLAIM: str = "oid"
OAUTH_USER_EMAIL_CLAIM: str = "email"
OAUTH_USER_GROUPS_CLAIM: str = "groups"
OAUTH_USER_ROLES_CLAIM: str = "groups"
# Optional attributes
OAUTH_USER_FIRSTNAME_CLAIM: Optional[str] = "given_name"
OAUTH_USER_LASTNAME_CLAIM: Optional[str] = "family_name"
OAUTH_USER_IS_ADMIN_CLAIM: Optional[str] = "isEclecticIQAdmin"
OAUTH_ADMIN_ROLE_NAME: Optional[str] = "EclecticIQAdminsGroup"
EXTERNAL_USER_DEFAULT_GROUPS = ["Testing Group"]
Once set, restart Intelligence Center services.
Run as root:
systemctl restart eclecticiq-platform-backend-services
Map Azure AD groups and roles to EclecticIQ Intelligence Center#
EclecticIQ Intelligence Center synchronizes group and role assignments
for Azure AD users by checking the claims specified
for the OAUTH_USER_GROUPS_CLAIM
and OAUTH_USER_ROLES_CLAIM
parameters in /etc/eclecticiq/platform_settings.py
.
By default, both are set to groups
. This means
that EclecticIQ Intelligence Center:
Checks the contents of the
groups
claim. Each value in the groups claim is a security group on Azure AD.Because both
OAUTH_USER_GROUPS_CLAIM
andOAUTH_USER_ROLES_CLAIM
are set togroups
, EclecticIQ Intelligence Center looks for both groups and roles using those same values in thegroups
claim.Attempts to match each value in the claim to a role or group on EclecticIQ Intelligence Center.
If a value in the groups claim matches the name of a group or role on EclecticIQ Intelligence Center exactly, it assigns the signed-in user that group or role.
Use the roles
claim instead#
You can set OAUTH_USER_ROLES_CLAIM
to roles
instead if you configure application roles
on your Azure AD tenant.
Azure AD group OIDs and names#
By default, Azure AD only emits
OIDs (Azure AD object identifier) for security groups
in its groups
claim. On Azure AD cloud-only tenants,
you cannot emit security group names in tokens.
Security group OIDs look like this:
6cab8f93-8e22-4947-80c3-c6ed549cb47a
To synchronize security group assignments on your Azure AD tenant with Intelligence Center group assignments, you must create groups on the Intelligence Center that have the corresponding security group OID as its name.
For example: we have a security group named
“Restricted” with the OID 6cab8f93-8e22-4947-80c3-c6ed549cb47a
.
To be able to assign it to an Azure AD user and have
that assignment synchronize with EclecticIQ Intelligence Center,
you must create a group on EclecticIQ Intelligence Center named
6cab8f93-8e22-4947-80c3-c6ed549cb47a
.
If a group named
6cab8f93-8e22-4947-80c3-c6ed549cb47a
does not exist on EclecticIQ Intelligence Center, then
that claim value is ignored.
To get Azure AD to emit a groups
claim
containing group names instead, you must have:
An Azure AD tenant that is synchronized with an on-premises AD, and
Set your registered application to emit a groups claim that contains groups identified by
sAMAccountNAme
instead ofGroup ID
.
For more information on group claims, see the Azure AD documentation
Assign groups and roles to users using custom claims#
Instead of setting the
OAUTH_USER_GROUPS_CLAIM
and OAUTH_USER_ROLES_CLAIM
to use the default groups
and roles
claims respectively,
you can set up Azure AD application for EclecticIQ Intelligence Center to emit
custom claims that map groups on your Azure AD tenant to
matching roles and groups on EclecticIQ Intelligence Center.
To do this:
Set up the following custom claims using instructions from How to: Customize claims emitted in tokens for a specific app in a tenant:
eclecticiqGroups
: Custom claim mapped to a user’s Intelligence Center group assignment.eclecticiqRoles
: Custom claim mapped to a user’s Intelligence Center role assignments.
In
platform-settings.py
, set the following parameters:OAUTH_USER_GROUPS_CLAIM = "eclecticiqGroups" OAUTH_USER_ROLES_CLAIM = "eclecticiqRoles"
Test your OAuth 2.0 configuration#
You can test if your Intelligence Center is correctly set up
to authenticate users with your Azure AD tenant using OAuth 2.0
using the eiq-platform oauth test-access
command.
The eiq-platform oauth test-access
command runs a test script
that uses the OAuth 2.0 device code authorization grant flow
to retrieve a JWT token that allows you to access EclecticIQ Intelligence Center API.
Requirements:
Root access on Intelligence Center host.
An Azure AD tenant.
Permissions to register applications on your Azure AD tenant.
Existing users on your Azure AD tenant.
First, register an application for the test script on your Azure AD tenant:
Register an application with the Microsoft identity platform.
When registering the application:
Leave Redirect URL empty.
Under Authentication > Advanced Settings, set Allow public client flows to Yes.
Get the Application (client) ID for the application you just registered.
Open the terminal on your Intelligence Center host and edit
/etc/eclecticiq/platform_settings.py
.Set
CLIENT_APPLICATION_ID
to the Application (client) ID from earlier.Restart Intelligence Center services.
Run as root:
systemctl restart eclecticiq-platform-backend-services
Once done:
Open the terminal on your Intelligence Center host.
Run
sudo -i
to gain root access.Run:
# Where ``https://platform.example.com`` is your Intelligence Center API URL eiq-platform oauth test-access --client-application-id=<CLIENT_APPLICATION_ID> --platform-api-url=https://platform.example.com