Set up OAuth 2.0 and Azure AD

You can set up the 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 the Intelligence Center instance.

  • Manage credentials used by that third-party application on Azure AD, instead of on the Intelligence Center.

But does not allow you to sign in to the 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 the Intelligence Center

You must have:

  • Root access to the Intelligence Center host.

  • Permissions to register applications on the target Azure AD tenant.

Steps:

  1. Register an Azure AD application for the Intelligence Center

  2. Configure platform_settings.py

Register an Azure AD application for the Intelligence Center

  1. Register application on your Azure AD tenant for the 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 the 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 the 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 the Intelligence Center after authenticating with Azure AD.

OAUTH_USER_USERID_CLAIM

Yes

oid by default.

When an Azure AD user signs in on the Intelligence Center through OAuth 2.0, the 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.

the 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 the Intelligence Center exactly.

See Map Azure AD groups and roles to the 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.

the Intelligence Center assigns users to the roles contained in this claim.

By default, this parameter is set to groups so that the 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 the Intelligence Center exactly.

See Map Azure AD groups and roles to the 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 the Intelligence Center using OAuth 2.0.

  • A user must belong to at least one group.

    Setting this value tells the 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 the 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 the Intelligence Center.

  • This paramter is shared by all external authentication systems that interact with the 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 the Intelligence Center using OAuth 2.0.

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

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

OAUTH_CASE_SENSITIVE_MATCHING

No

True by default.

Do not change this value.

Tells the Intelligence Center to use case-sensitive matching when matching groups and roles names from your external authentication system to the 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 the 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 the Intelligence Center

the 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 the 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, the 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 the Intelligence Center.

    If a value in the groups claim matches the name of a group or role on the 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 the Intelligence Center, you must create a group on the Intelligence Center named 6cab8f93-8e22-4947-80c3-c6ed549cb47a.

If a group named 6cab8f93-8e22-4947-80c3-c6ed549cb47a does not exist on the 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 the Intelligence Center to emit custom claims that map groups on your Azure AD tenant to matching roles and groups on the 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 the 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