Skip to main content

Home

Enabling Azure Active Directory (AAD) authentication

You can integrate Unravel with Azure Active Directory (AAD) to use this authentication service of Azure for Databricks. To integrate Unravel with AAD, you must first register Unravel services at the AAD website and then update Unravel configuration with AAD details.

Registering Unravel in AAD

  1. Sign in to the Azure portal.

  2. Select Azure Active Directory > App registrations.

  3. Click New registration and enter the following details:

    Item

    Description

    Name

    Specify any name to identify the application.

    Supported Account Types

    Select a supported account type option.

  4. Click Register.

  5. Go to the application and select Manage > Authentication.

  6. Click Add a platform > Web and enter the following details:

    Item

    Description

    Redirect URIs

    The URIs, that are accepted as destinations when returning authentication responses after successfully authenticating or signing out users.

    https://<Unravel URL>)>:3000/aad/consume

    Logout URL

    The URIs where the request is sent to have the application clear the user's session data.

    https://<Unravel URL>:3000/aad/logout-consume

  7. Click Configure and go back to the application.

  8. Select Certificates & Secrets > Client Secrets > New client secret.

  9. Enter a description and select an expiry duration.

    Note

    Copy the client secret as soon as it is displayed since this gets masked immediately.

  10. Go to the application and capture the following details for use in the Unravel configuration for AAD:

    Item

    Description

    Client ID

    Copy the details from Overview > Essentials > Application (client) ID.

    Client secret

    The client secret, which is copied as mentioned in #9

    tenantID

    Refer to tenantID.

  11. Set API permissions to fetch AAD groups.

    1. Go to the application and select > API Permissions tab.

    2. Click Add a permission. The Request API permissions dialog box is displayed.

    3. Select Microsoft APIs > Microsoft Graph.

    4. Add the following permissions:

      • Click Delegated Permissions and select User.Read. This is required for AAD login.

      • Click Application Permissions and select Directory.Read.All or User.Read.All. This is required for User Group Name / Group ID.

        Note

        • With User.Read.All permission, you can configure login and RBAC using User Group IDs only. For example: com.unraveldata.rbac.role.admin.groups=76098a29-c93d-4eb3-9923-1ce1d3da646c

        • With Directory.Read.All permission, you can configure login and RBAC using User Group Display Name. For example: com.unraveldata.rbac.role.admin.groups=UD-EMEA-DEV

    5. Click Add Permissions.

    6. Click Grant admin consent for Unravel Data button. The Grant admin consent confirmation is displayed.

    7. Click Yes.

Updating Unravel configuration with AAD

The AAD configurations can be added into a JSON file and set properties to provide the path to the JSON file.

  1. Create aad.json file with the following configurations and add the file to <Installation directory>/unravel/data/conf.

    {
    "clientID": "<clientID>",
    "tenantID": "<tenantID>",
    "clientSecret": "<clientSecret>",
    "callbackURL": "https://<Unravel URL>:3000/aad/consume",
    "logoutCallbackURL": "https://<Unravel URL>:3000/aad/logout-consume",
    "logoutEnabled": <true|false>,
    "unravel_mapping": {
        "username": "<user name attribute>",
        "group": "<group name attribute>"
    }
}

    For example:

    {
  "clientID": "701c561b-xxx-xxx-xxx-xxx-xxx",
  "tenantID": "bc745a0d-xxx-xxx-xxx-xxx-xxx",
  "clientSecret": "xxx_xxx.xxx~xxx_",
  "callbackURL": "https://demo.unraveldata.com:3000/aad/consume",
  "logoutCallbackURL": "https://demo.unraveldata.com:3000/aad/logout-consume",
  "logoutEnabled": false,
  "unravel_mapping": {
    "username": "upn",
    "group": "name"
  }
}

    Item

    Description

    clientID

    Client ID from Overview > Essentials > Application (client) ID.

    tenantID

    tenantID value depends on the App’s Supported account types field under App > Authentication > Supported account types.

    • If your application supports accounts in this organizational directory, replace this value with the Tenant ID, which is found under App > Overview > Essentials > Directory (tenant) ID value.

    • If your application supports accounts in any organizational directory, replace this value with organizations.

    • If your application supports accounts in any organizational directory and personal Microsoft accounts, replace this value with common.

    clientSecret

    The client secret.

    callbackURL

    Redirect URL to consume login response from AAD. This should be the same as the Redirect URI.

    logoutCallbackURL

    Redirect URL to consume logout response from AAD. This should be the same as the Logout URL.

    logoutEnabled

    Enable/Disable AAD account logout when the user logs out from Unravel.

    unravel_mapping

    Maps the AAD attributes to Unravel attributes.

    • username

      Any username attribute to use. Example: upn.

    • group

      Group name. This can be either name or id only.

      • name: if this is given, all the property values associated with the group will be group displayNames. The case can be ignored.

      • id: If ID is provided, then all the property values associated with the group will be either group GUIDs or Objectids.

  2. Stop Unravel.

    <Unravel installation directory>/unravel/manager stop

  3. Set the properties to specify the login mode and the path to the <Installation directory>/unravel/data/conf/aad.json file. 

    <Unravel installation directory>/unravel/manager config properties set com.unraveldata.login.mode=aad
<Unravel installation directory>/unravel/manager config properties set com.unraveldata.login.aad.config=<Installation directory>/unravel/data/conf/aad.json

  4. Set the following properties to allow only specific users to log in based on their usernames or groups. This is optional.

    Property/Description

    Set by user

    Unit

    Default

    com.unraveldata.login.userFilter

    Restricts login to a few selected usernames.

    For example:

    user1@teamunraveldata.onmicrosoft.com,USER2@teamunraveldata.onmicrosoft.com

    Optional

    CSL

    All usernames are allowed.

    com.unraveldata.login.groupFilter

    Restricts login to a few selected groups.

    For example: secs-lab-admins,secs-lab-users.

    Optional

    CSL

    All groups are allowed. 

    <Unravel installation directory>/unravel/manager config properties set com.unraveldata.login.userFilter=<user1@email.com>,<user2@email.com>
<Unravel installation directory>/unravel/manager config properties set com.unraveldata.login.groupFilter=<group1@email.com>,<group2@email.com>

  5. Assign admin and read-only admin roles to users by setting the corresponding properties. Refer to configuring roles in RBAC.

    Notice

    • By default, logged-in users assume read-only admin roles when RBAC is turned off and user roles when RBAC is turned on.

    • You can also provide custom AAD groups using a script that overwrites real AAD groups. Refer to Configuring custom user groups

  6. Apply changes. 

    <Unravel installation directory>/unravel/manager config apply

  7. Start Unravel.

    <Unravel installation directory>/unravel/manager start
In this section: