Skip to main content

OAuth2 rights

Izanami allow to setup an OAuth2 provider.

Configuration of provider is documented here.

This page focuses on attributing rights to user coming from external auth provider.

Map provider roles to rights​

To attribute default rights to external users, you'll have to define app.openid.right-by-roles.

This property is a map, whose keys are roles, and value are rights that should be given to external users with these roles.

Role​

Role are provided by OAuth2 provider. You must specify claim that contains roles in token sent by OAuth2 provider in app.openid.role-claim.

Role claim must contain either a string containing a single role, or a json array containing a list of roles

Right format​

Each role is associated with a set of rights.

Here is a complete set of rights:

{
  "admin": <true|false>, // Wether user is global admin
  "tenants": {
    "my-tenant": {
      "level": "<read|write|admin>", // Right level for tenant "my-tenant"
      "default-project-right": "<read|update|write|admin>", // default project right for "my-tenant"
      "default-key-right": "<read|write|admin>", // default key right for "my-tenant"
      "default-webhook-right": "<read|write|admin>", // default webhook right for "my-tenant"
      "projects": {
        "my-project": "<read|update|write|admin>", // Specific right level for project "my-project"
        "another-project": "<read|update|write|admin>" // Specific right level for project "another-project"
      },
      "keys": {
        "my-key": "<read|write|admin>" // Specific right level for key "my-key"
      },
      "webhooks": {
        "my-hook": "<read|write|admin>" // Specific right level for webhook "my-hook"
      }
    }
  }
}

To know more about rights and what they allow, see this page.

Default rights​

To specify default rights for any oidc user, you'll need to define rights for a role "".

{
  "": {
    "tenants": {
      "my-tenant": {
        "level": "read",
        "default-project-right": "read"
      }
    }
  },
  "another-role": {
    // ...
  }
}

Role merge​

When a user has multiple role, or when he has one role and default rights, Izanami merges rights from different roles and default rights to keep only higher rights.

For instance, with the following configuration, a user with roles foo and bar will have:

  • global admin rights
  • admin right on my-tenant
  • default project right of update for my-tenant
  • default key right of read for my-tenant
{
  "": {
    "tenants": {
      "my-tenant": {
        "level": "read",
        "default-project-right": "read",
        "default-key-right": "read"
      }
    }
  },
  "foo": {
    "admin": true,
    "my-tenant": {
      "level": "write",
      "default-project-right": "update"
    }
  },
  "bar": {
    "my-tenant": {
      "level": "admin",
      "default-project-right": "read"
    }
  }
}

Rights modes​

Role synchronisation between external authentication provider and Izanami can be done using two different strategies:

  • initial: this strategy assigns rights to external user at first connection, user rights are not updated thereafter. In this mode, external user rights can be updated directly from Izanami as for a normal user.
  • supervised: as for internal strategy, this one assigns rights at first connection. This mode also "reset" rights at every login, allowing update of roles or right by role to be taken into account. In this mode, external use rights can't be updated from Izanami, to update one user rights you'll have to add / remove him roles in external authentication provider or to update right-by-roles configuration.

Max rights​

Max rights are available for Izanami 2.19.0 and above.

You can associate max rights to any external role.

Max rights act as an upper bound for user rights. This means that Izanami will prevent users to have rights above their defined max rights.

Defining max rights​

As for default rights, max rights are defined using app.openid.right-by-roles property.

{
  "": { // Max rights for user without roles
    "admin-allowed": false, // User without roles can't become admin of this izanami instance
    "tenants": {
      "super-corp": {
        "max-tenant-right": "read", // User without without roles can't have more than read right on tenant "super-corp"
        "max-project-right": "read",  // User without roles can't have more than read rights on "super-corp" projects
        "max-key-right": "none", // User without roles can't have any rights on "super-corp" keys
        "max-webhook-right": "none" // User without roles can't have any rights on "super-corp" webhooks
      },
      "secret-corp": {
        "max-tenant-right": "none" // User without without roles can't have any rights on "secret-corp" tenant, nor on its projects / keys / webhooks
      }
    }
  },
  "dev": { // Max rights for dev role
    "admin-allowed": false, // Dev can't become admin of this izanami instance
    "tenants": {
      "super-corp": {
        "max-tenant-right": "read", // Devs can't have more than read right on tenant "super-corp"
        "max-project-right": "write",  // Devs can't have more than write rights on "super-corp" projects
        "max-key-right": "read", // Devs can't have more than read rights on "super-corp" keys
        "max-webhook-right": "read" // Devs can't have more than read rights on "super-corp" webhooks
      },
      "secret-corp": {
        "max-tenant-right": "read", // User without without roles can't have any rights on "secret-corp" tenant, nor on its projects / keys / webhooks
        "max-project-right": "read",  // Devs can't have more than write rights on "secret-corp" projects
        "max-key-right": "none", // Devs can't have any rights on "secret-corp" keys
        "max-webhook-right": "none" // Devs can't have any rights on "secret-corp" webhooks
      }
    }
  },
  "superuser": {
    "admin-allowed": true // Dev can't become admin of this izanami instance
    //  every non listed item has a default value of "admin", therefore superuser doesn't have any max right limitation
  }
}

Max rights can also be setup from global settings page. As for the rest of OAuth2 configuration, it can't be changed from UI if set through env variables.

Merging max rights​

If a user has several roles, Izanami will merge max rights for these roles and keep only higher allowed right.

Keep in mind that if a roles does not define max rights for a given tenant, max rights are considered admin for this tenant.

Max right update​

When max rights are updated from UI, impacted users will be logged out. Their rights will be updated to max new max right at login.

Users that didn't log in since a long time may have stale rights (rights that are not up-to-date with max rights configuration). For these users, Izanami will apply max-rights to their rights on the fly when reading them, displaying a projection of their updated rights.