How to configure Auth0 as login method for the LXD UI and CLI¶

Auth0 is a flexible, drop-in solution to add authentication and authorization services to your applications. Auth0 supports OIDC and can be used to authenticate users for the LXD UI and CLI. This guide shows you how to set up Auth0.com as the login method for the LXD UI and CLI.

Using Auth0.com to access LXD¶

Open a free account on Auth0.com.
Once logged into the Auth0 web interface, select Applications > Applications in the side panel.
- You need to create two applications. One is for the LXD UI and the other is for the LXD CLI.
First, create an application that will be used for authentication in the LXD UI by selecting + Create Application.
- Give the application a name, e.g. LXD UI.
- Select Regular Web Application.
- Click Create.
Go to the Settings tab of your new application.
- Scroll to the Allowed Callback URLs field in this tab and enter your LXD UI address, followed by /oidc/callback.
  - Example: https://example.com:8443/oidc/callback
  - An IP address can be used instead of a domain name.
    - Note :8443 is the default listening port for the LXD server. It might differ for your setup. You can verify the LXD configuration value core.https_address to find the correct port for your LXD server.
- Enable Allow Refresh Token Rotation.
- Scroll down to Advanced Settings and select the Grant Types tab.
- Enable Authorization code and Refresh Token. Other grant types can be disabled.
- Select Save.
Navigate to Basic Information near the top of the Settings tab.
- Locate the Domain field. Copy the value and add the https:// prefix and the / suffix as in the example below. This is your OIDC issuer for LXD. Set this value in your LXD server configuration with the command:
```
lxc config set oidc.issuer=https://dev-example.us.auth0.com/
```
- Locate the Client ID and Client Secret fields. Copy the values and use them in your LXD server configuration:
```
lxc config set oidc.client.id=<Client ID>
lxc config set oidc.client.secret=<Client Secret>
```
- Now you can access the LXD UI with any browser and use SSO login. Enter the credentials for Auth0.
Now create an application to be used by the LXD CLI. To do this, go back to Applications > Applications in the side panel and click + Create Application.
- Give the application a name, e.g. LXD CLI.
- Select the default Native application type.
- Click Create.
Go to the Settings tab of your new application.
- Enable Allow Refresh Token Rotation.
- Scroll down to Advanced Settings and select the Grant Types tab.
- Enable Device Code and Refresh Token. Other grant types can be disabled.
- Select Save.
Navigate to Basic Information near the top of the Settings tab.
- Locate the Client ID field and use it in your LXD server configuration:
```
lxc config set oidc.device.client.id=<Client ID>
```
- You can now access LXD using the CLI with
```
lxc remote add <remote-name> <LXD-address> --auth-type oidc
```
  This will open a browser where you must confirm the device code displayed in the terminal window, and log in with the credentials for Auth0.

Users will have no permissions by default. You must set up LXD authorization groups to grant access to projects and instances. For connecting the LXD authorization groups to a user you have two options:

Map a LXD authorization group to the user directly. Note, that the user object in LXD will only be created on the first login of that user to LXD.
Configure roles in Auth0 and use automatic mapping to LXD authorization groups as described below.

Set up automatic group mappings¶

An admin can set up multiple users in Auth0 and allocate roles to those users. When a user logs in via OIDC, their allocated Auth0 roles can be mapped to LXD authorization groups through custom claims. This section details the steps for configuring roles in Auth0 and setting up a custom claim so that LXD can map those roles to its authorization groups.

In the left panel of the Auth0 interface, select User Management > Roles, create some roles with suitable names. Note that these roles are global for the Auth0 tenant.
Under User Management > Users, click Create User. Provide an email and password and create the user.
Select on the Roles tab in the user detail page, then click the Assign Roles button. Select the roles you created in step 1.
You must set up a custom action on Auth0 to set the custom claim on both the id_token and access_token during the OIDC login flow.
- In the main navigation, under Actions > Library, click the Create Action button. Select Create Custom Action.
  - Name: Give the action a suitable name like roles-in-id-token.
  - Trigger: Login / Post Login
  - Runtime: The recommended default
- Click Create. This causes a code editor to open.
- In the code editor, insert the code snippet shown below:
```
exports.onExecutePostLogin = async (event, api) => {
  if (event.authorization) {
    api.idToken.setCustomClaim(`global-roles`, event.authorization.roles);
    api.accessToken.setCustomClaim(`global-roles`, event.authorization.roles);
  }
};
```
- Select Deploy.
- Once the action is deployed, go to Actions > Triggers > post-login. Under the Add Action > Custom tab, drag the action you just created and drop it in between the Start and Complete nodes of the Login flow. Select Apply to save the changes.
Navigate to the LXD UI. First authenticate with the UI using a trusted certificate so that you can configure server settings without permission issues.
In the LXD UI, under settings, find oidc.groups.claim. Set it to the custom claim configured in step 4. Using the current example, the custom claim is global-roles. Alternatively, use the command line: lxc config set oidc.groups.claim=global-roles.
Continuing in the LXD UI, navigate to Permissions > IDP groups and click Create IDP Group. Here you can map roles from Auth0 to LXD authorization groups. For each identity provider group created in LXD, the name of the identity provider group must match a role you have created in Auth0, and it should also map to one or more LXD authorization groups. Alternatively, use the command line:
```
lxc auth identity-provider-group create <auth0-role-name>
lxc auth identity-provider-group group add <auth0-role-name> <LXD-group-name>
```
Lastly, you log in as a user with roles assigned in Auth0. During the OIDC flow, LXD extracts the roles set by Auth0 based on the LXD oidc.groups.claim configuration value. The extracted custom claim is an array of roles for your user from Auth0. Those roles are then mapped to LXD authorization groups using the identity provider group created in step 7.