The Access Policy object
Attributes
Each item in
apps:
A write body that includes
label on an app or entitlement returns 400.
Grants
Each grant is an entitlement ID inapps[].entitlements[].id. It’s the same ID that
Get Entitlement takes. To grant access to the app
itself rather than to specific entitlements, omit entitlements or send an empty list.
Migrate Access Policies covers moving existing grants to
entitlement IDs.
A policy needs at least one app, and an empty apps list returns 400. When you create or update
a policy, Lumos checks every ID in apps:
The
400 message calls grants “permissions”.
Conditions
Sendaccess_condition with the condition that identities must match, or send
"is_everyone_condition": true to apply the policy to everyone. Sending both returns 400 on every
write. The exception is the everyone condition that a
read returns: Lumos reads it as "is_everyone_condition": true, so you can send a read’s
access_condition back as is.
Lumos checks the condition when you save it.
What Lumos rejects lists what returns 400.
Reads set is_everyone_condition to true only for this exact condition, label included. Any other
condition that matches every identity reads back as is_everyone_condition: false.
Conditions documents the format, and the
stored form that a read returns.
Two published policies can’t have the same condition. If creating, publishing, or updating a policy
would give a published policy the same condition as another published policy, the call returns
400 with “An access policy with these conditions already exists.” Drafts can share a condition.
Expanding fields with expand
Reads return the base object. Pass expand to include fields that reads omit by default.
Separate values with commas. A value an endpoint doesn’t take returns
400 with code set to
validation_error. Unlike most expand fields, owners aren’t left out when you can’t read them:
any owners path needs permission to list users and groups, or the whole request returns 403, as
Who can do what on the Owners page
describes.
owners
owners is an Owners object. Without an owners path in expand,
the response leaves it out, so callers that don’t manage owners, such as Terraform, see no change.
A user that List Users treats as deleted isn’t listed.
GET /v1/access-policies/{access_policy_id}?expand=owners
Drafts, publishing, and enabling
A policy grants access only while it’s both published and enabled.- Create returns
201with the new policy. It makes a draft unless you send"status": "published", and it leaves the policy disabled unless you send"is_enabled": true. A draft can’t be enabled, so on create,"is_enabled": truereturns400unless you also send"status": "published". - Publish a draft by sending
"status": "published"on Update Access Policy. You can’t return a published policy to draft. Sending"status": "draft"for a published policy returns400. - Approval. When your organization requires approval before publishing, creating a policy with
"status": "published"returns400, and so does publishing a draft whose changes aren’t approved. Create a draft and submit it for approval in the Lumos UI. - Update a published policy with
PUT, which replaces every field, or withPATCH, where a field you omit keeps its value and no field can benull. The update takes effect immediately. If the policy also has a draft version saved in Lumos, either call returns400with “Access policy already has a draft version.” - Read returns the published version when there is one, and the draft version otherwise.
- Delete removes the policy and the pre-approval it gave its apps, and returns
204.
status takes only draft or published, so an uppercase value such as PUBLISHED returns 400.
Updating or deleting a policy doesn’t remove access that identities already received through it.
When an identity stops matching a policy, Lumos removes the access that the policy granted only if
your organization has enabled Auto Run in its Movers settings. Even then, Lumos keeps access
that the identity requested through the AppStore.
Setting owners
Owners belong to the policy, not to a version of it. Publishing a draft never changes them.
See The Owners object for how both lists are replaced
and which bodies return
400 or 404.
Create a policy with owners:
POST /v1/access-policies
groups is sent empty, so the policy’s group owners
are removed:
PATCH /v1/access-policies/{access_policy_id}
owners as {id} references.
A PATCH that sends other fields along with owners applies all of them or none. If the content
change fails, for example with “Access policy already has a draft version.”, the owners don’t
change either.
Listing
List Access Policies returns the policies you can read, newest first.name limits the list to policies whose name contains that
text, ignoring case. A page can be empty while later pages still hold policies, as
Short and empty pages describes.
Who can do what
The built-in roles can do the following:
A custom role can also allow these actions. On a
PUT or PATCH, Lumos checks permission for each
changed field on its own, so an owner can update a draft’s apps, but gets 403 for a change to
its name, justification, or condition.
Changing owners needs permission to manage access policies, which comes from your role in the
organization, such as Admin. Being a policy’s owner doesn’t give it. A caller without it gets 403.
On POST, a body without owners needs no extra permission. On PATCH, a body that sends only
owners needs no permission to edit the policy’s content.
A call you aren’t allowed to make returns 403.