Authentication Overview

User Management

All users are created just-in-time the first time that they authenticate using single sign-on (SSO) with Open ID Connect (OIDC).

We do not currently support SCIM provisioning and deprovisioning.

In an future release, Authentication Users and Directory Users will be linked. This will allow us to automate creating Auth Users automatically when they are provisioned in the Directory Source (ex. Okta). With tightly integrated features with Directory Users, we will be able to deprovision the Auth User as well as many other resources and user accounts that have been provisioned over time.

Single Sign On

Access Control uses your single sign-on (SSO) provider for all human user authentication. When signing in, the SSO provider ID, first and last name, and email address is received in the SSO authentication response and is encrypted and saved in the Access Control database.

You can choose any of the following vendors when installing Access Control:

GitLab
Google
Microsoft Azure AD
Microsoft Entra ID
Okta Customer Identity (formerly Auth0)
Okta Workforce Identity

Additional vendors may be added in the future if they are a supported provider.

If your SSO provider is not supported, you should sign up for a free Okta Customer Identity (Auth0) account that supports native integrations with a wider range of vendors.

See the SSO docs to learn more.

Password Management

We rely on your SSO provider for authentication. No passwords are managed or stored in Access Control.

You can configure password policies in your SSO provider. You can also configure passkey support in your SSO provider for a streamlined user experience.

Two Factor Authentication

We rely on your SSO provider for authentication. You can configure two factor policies and assign them to the Access Control application configuration in your SSO provider.

User Roles and Permissions

Access Control has fine grained access control using roles and permissions that are assigned to human users and service accounts.

See the roles and permissions docs to learn more or see which roles and permissions that your user account has and has not been assigned at /user/permissions.

API Authentication

The API endpoints are authenticated using access tokens and refresh tokens that are associated with a service account or user account.

Each endpoint is associated with a permission that the service or user must be granted to be able to use the endpoint.

See the API Authentication Architecture docs or API Credentials docs to learn more.

Command Line Interface (CLI) Client

The accessctl CLI client can be installed on a user’s device for accessing and managing the same data that is available in the Web UI. We consider the CLI to be a first class citizen and first party package since we come from a system administration background and understand the needs of our power users.

Each user can generate an activation token in the UI after authenticating with SSO that can be redeemed in the CLI client. During the activation process, the device’s machine metadata is sent to the server and saved as an Auth Device and used for device trust verification.

As a user, you only need to copy and paste one time to your terminal and do not need to manually save any token(s) in your password or secrets manager.

If device trust verification succeeds, a API refresh token is created that is associated with the Auth Device. The refresh token is valid for 90 days (configurable) before the user will need to reauthenticate with SSO and generate a new activation token. The reactivation experience is painless and takes less than 30 seconds.

The CLI client will fetch the refresh token from the server during the activation process and store it securely at $HOME/.config/accessctl/connections.json.

You will need an access token each time you run a command that gets data from the API. The CLI client automatically uses the refresh token to generate an access token that is valid for 60 minutes (configurable) to follow API Security best practices of short-lived tokens.

As a user, you will never need to manage, see, or use the refresh or access tokens after you activate the CLI client using accessctl login.

See the CLI docs to learn more or visit /user/cli to get started.

Personal Access Tokens (PAT)

API authentication and testing an API endpoint can be daunting when trying to use refresh tokens or an SDK.

When you simply need to test a GET, POST, PATCH, or DELETE endpoint, you can use a personal access token that is created in the UI at /user/pat.

In the software and security industry, PATs are usually long lived or have expiration dates 90-365 days in the future. Access Control PATs are only valid for 60 minutes since they are designed for testing, not perpetual access with the full level of permissions that your user account has. This prevents the bad practice behavior of an engineer using a PAT in their script or service that should use Service Accounts instead.

Service Accounts

Access Control uses a secure by design approach with non-human (machine to machine) access to the API using Service Accounts with granular permissions.

A Service Account is similar to a User Account, however it can only be authenticated with API tokens and there is no UI experience or SSO for service accounts.

Service Accounts are for inbound requests to the Access Control API from scripts or vendor services. See the Providers for each respective namespace (ex. Directory Provider, Infrastructure Provider, Workflow Provider, etc) for outbound API requests.

The default permissions of a service account only include the ability to perform an authentication test and generate an access token using the service account’s refresh token.

Each URL endpoint has a near 1:1 permission mapping that allows service accounts to only be granted access to the endpoints they actively use. If you are familiar with Oauth scopes, we take this to a much deeper level.

Each Service Account has a lot more features than just a name, description, and expiration date. Each service account has users associated that have permission to manage the service account. We refer to these as Service Account Managers and support least privilege and separation of duties.

admin: Can create/rotate tokens and grant permissions
permissions: Can grant permissions but cannot create/rotate/view tokens
tokens: Can create/rotate/view tokens but cannot edit permissions
audit: Has read-only access to see the metadata about the service account and the permissions, but cannot make any changes or create/rotate/view tokens.

We only supported named users for service account managers. This allows us to ensure that we have positive identification of who is responsible for the service account and have fine grained permissions that is harder to do with groups or teams.

Since API vendors and integrations come in all shapes and sizes, each service account can be configured to use the token strategy that makes the most sense:

Refresh token with up to 365 day expiration (configurable) with short lived access tokens that last 60 minutes (configurable)
Access token with up to 365 day expiration

Advanced Settings

IP and Network Access Control List (ACL)

This does not apply if you host Access Control in a private subnet in your cloud provider (AWS, GCP, etc) or inside your corporate network.

Access Control is usually hosted on the public Internet as a SaaS application. Your application is secure enough if you have two factor authentication enabled on your SSO provider.

For additional security, you can configure allowed and denied IP addresses using CIDR ranges. This is useful if your users are using a VPN or connecting from locations with known IP addresses.

All UI endpoints share the same list of allowed or denied IPs that apply to all users.

All API endpoints are protected based on each service account’s configured settings that allow access from 0.0.0.0/0 by default and can be restricted to a specific IP address or CIDR range of the 3rd party service (ex. their NAT gateway address or array of published addresses).

See the Network docs to learn more.