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:

  1. Register an Azure AD application for EclecticIQ Intelligence Center

  2. Configure platform_settings.py

Register an Azure AD application for EclecticIQ Intelligence Center#

  1. Register application on your Azure AD tenant for EclecticIQ Intelligence Center. Follow the instructions in Azure AD documentation to do so.

  2. Once done, select your registered app to configure it.

  3. Go to Expose an API and select Add a scope.

  4. 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.

  5. Select Add scope to save your changes.

Configure platform_settings.py#

Set the following parameters in /etc/eclecticiq/platform_settings.py:

Parameter

Required

Description

OAUTH_ENABLED

Yes

False by default.

Set to True to enable OAuth 2.0 on EclecticIQ Intelligence Center.

OAUTH_TENANT_ID

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.

OAUTH_APPLICATION_ID

Yes

Application (client) ID registered for your Intelligence Center instance

The ID of the application object registered for your EclecticIQ Intelligence Center instance.

OAUTH_CLIENT_APPLICATION_IDS

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.

OAUTH_USER_USERID_CLAIM

Yes

oid by default.

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.

OAUTH_USER_EMAIL_CLAIM

Yes

email by default.

This is used to set the email address of external users.

OAUTH_USER_GROUPS_CLAIM

Yes

groups by default.

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.

OAUTH_USER_ROLES_CLAIM

Yes

groups by default.

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 groups so that EclecticIQ Intelligence Center looks for roles to assign to the user in the contens of this claim.

Set this to roles if you have set up Application roles. For more information, see the Azure AD documentation.

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.

EXTERNAL_USER_DEFAULT_GROUPS

No

[] by default.

A list of groups that are assigned to external users who sign in on EclecticIQ Intelligence Center using OAuth 2.0.

  • A user must belong to at least one group.

    Setting this value tells EclecticIQ Intelligence Center to automatically assign external users created when they sign in using OAuth 2.0 to these groups. Otherwise, assign these external users to groups on EclecticIQ Intelligence Center or use a custom claim with OAUTH_USER_GROUPS_CLAIM.

  • <group_name> is case-sensitive; it must match exactly an existing group name on EclecticIQ Intelligence Center.

  • This paramter is shared by all external authentication systems that interact with EclecticIQ Intelligence Center, and may already be set.

EXTERNAL_USER_DEFAULT_ROLES

No

[] by default.

A list of roles that are assigned to external users who sign in on EclecticIQ Intelligence Center using OAuth 2.0.

  • <role_name> is case-sensitive; must match exactly an existing role name on EclecticIQ Intelligence Center.

  • This paramter is shared by all external authentication systems that interact with EclecticIQ Intelligence Center, and may already be set.

OAUTH_CASE_SENSITIVE_MATCHING

No

True by default.

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.

OAUTH_DEBUG

No

False by default.

Set this to True to log OAuth 2.0 authentication errors in the web server logs.

OAUTH_USER_FIRSTNAME_CLAIM

No

given_name by default.

This is used to set the First name of external users.

OAUTH_USER_LASTNAME_CLAIM

No

family_name by default.

This is used to set the Last name of external users.

OAUTH_USER_IS_ADMIN_CLAIM

No

isEclecticIQAdmin by default.

When this parameter is set, you can assign a user administrator rights by setting the value of this claim to "is_admin".

OAUTH_ADMIN_ROLE_NAME

No

EclecticIQAdminsGroup by default.

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:

  1. 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 and OAUTH_USER_ROLES_CLAIM are set to groups, EclecticIQ Intelligence Center looks for both groups and roles using those same values in the groups claim.

  2. 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 of Group 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:

  1. Register an application with the Microsoft identity platform.

  2. When registering the application:

    • Leave Redirect URL empty.

    • Under Authentication > Advanced Settings, set Allow public client flows to Yes.

  3. Get the Application (client) ID for the application you just registered.

  4. Open the terminal on your Intelligence Center host and edit /etc/eclecticiq/platform_settings.py.

  5. Set CLIENT_APPLICATION_ID to the Application (client) ID from earlier.

  6. Restart Intelligence Center services.

    Run as root:

    systemctl restart eclecticiq-platform-backend-services

Once done:

  1. Open the terminal on your Intelligence Center host.

  2. Run sudo -i to gain root access.

  3. 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